Show Live Diffs

Render an agent branch as a live diff and refresh the view when a new state arrives.

Render an agent’s work from its ephemeral branch while the agent runs. Your product can show current and prior states without a second file store or diff service.

This guide uses the branch layout from Store Session State.

Read the current diff

Compare the session branch with its normal base branch.

TypeScript

import { GitStorage } from '@pierre/storage';

const sessionId = process.env.SESSION_ID;

const store = new GitStorage({
  key: process.env.PIERRE_PRIVATE_KEY,
  name: 'acme',
});

const repositoryId = 'acme/storefront';
const repo = await store.findOne({ id: repositoryId });

const sessionBranch = `sessions/${sessionId}`;

const view = await repo.getBranchDiff({
  base: repo.defaultBranch,
  branch: sessionBranch,
  ephemeral: true,
});

console.log(view.stats);
console.log(view.files);

view.files contains the file changes and diff text. view.stats contains the file, line, and change totals.

Use getBranchDiff() to filter the response to selected paths.

Read one file

Use the session branch for the latest content, or use a commit SHA for a fixed view.

TypeScript

const response = await repo.getFileStream({
  ephemeral: true,
  path: 'src/auth.ts',
  ref: sessionBranch,
});

const source = await response.text();
console.log(source);

For a fixed review link, store the state SHA and pass it as ref. The same SHA can also select a commit diff.

TypeScript

const stateSha = '4f53cda18c2baa0c0354bb5f9a3ecbe5f6b3f858';
const baseSha = '081b0449cdb51a6fd5c495e7fa329119b3a5dc26';

const fixedDiff = await repo.getCommitDiff({
  baseSha,
  sha: stateSha,
});

console.log(fixedDiff.stats);

Refresh after each state

Use either of these refresh signals:

1. Poll the session branch tip, then reload the diff when the SHA changes.
2. Subscribe to push webhooks, validate each delivery, and reload the diff for the same repository and branch.

Treat the webhook as a signal. Read the branch again after each event. Do not use the event as your state store.

See Webhooks for subscriptions, signatures, and retries.

Keep credentials on the server

Call Code Storage from your backend. Do not send your organization private key or a write token to the browser.

Cache a diff by its head SHA when many viewers request the same state. A new state gets a new SHA and a new cache key.