Capture Agent State

Capture agent state as ephemeral commits, exchange commit pointers, and keep normal branches unchanged.

Use one ephemeral branch for each agent session. Write one commit for each durable state, and pass commit pointers between sandboxes and services.

This pattern keeps intermediate work out of normal branches. It also makes each prior state available after its sandbox stops.

Create the session ID in your backend. Pass it to the worker as SESSION_ID. Keep the repository name, branch name, and current commit SHA in the same session record.

​

Create the session branch

Create an ephemeral branch from the repository’s normal default branch. One session branch holds every state of one session.

Run this code in a trusted backend service. Set PIERRE_ORG to your organization slug. Set PIERRE_PRIVATE_KEY to the private key in PEM format from the Code Storage dashboard. Do not give this key to a sandbox.

TypeScript

import { Pierre } from '@pierre/sdk';

const pierre = new Pierre(); // reads PIERRE_ORG and PIERRE_PRIVATE_KEY

const repoName = 'acme/storefront';
const sessionId = process.env.SESSION_ID!;
const repo = await pierre.repos.get({ repo_name: repoName });

const branch = await pierre.repos.branches.create({
  repo_name: repoName,
  base_ref: repo.default_branch,
  target_branch: `sessions/${sessionId}`,
  target_is_ephemeral: true,
});

if (!branch.commit_sha) {
  throw new Error('The session branch has no base commit');
}

const sessionBranch = branch.target_branch;
let headSha = branch.commit_sha;

base_ref can also be a full commit SHA. Use a full SHA when the session must start from an exact state.

​

Save each state

Add one commit for each state that another process must read or restore. Each commit inherits unchanged files from the prior state, so send only changed or deleted paths.

TypeScript

import { readFile } from 'node:fs/promises';

const previousHeadSha = headSha;
const updatedAuthSource = await readFile('src/auth.ts', 'utf8');
const taskState = { status: 'in_progress' };

const snapshot = await pierre.repos.commits.create({
  repo_name: repoName,
  author: { email: '[e-mail]', name: 'Agent' },
  commit_message: 'Save session state',
  expected_target_sha: headSha,
  target_branch: sessionBranch,
  target_is_ephemeral: true,
  files: [
    { path: 'src/auth.ts', content: updatedAuthSource },
    { path: '.agent/task.json', content: JSON.stringify(taskState) },
  ],
});

headSha = snapshot.commit.commit_sha;

expected_target_sha lets the write succeed only if the branch still points to headSha. If another writer changed the branch, the write fails with a RefGuardError. Stop the old writer and reload the session record.

Store headSha in the backend session record after each successful write. See repos.commits.create for file and stream inputs.

​

Exchange commit pointers

Pass a pointer instead of file contents. We recommend a repository name, a commit SHA, and an optional path.

TypeScript

const pointer = {
  path: 'src/auth.ts',
  repoName,
  sha: headSha,
};

const response = await pierre.repos.files.get({
  repo_name: pointer.repoName,
  path: pointer.path,
  ref: pointer.sha,
});
const source = await response.text();

const diff = await pierre.repos.diff.get({
  repo_name: pointer.repoName,
  base_ref: previousHeadSha,
  ref: pointer.sha,
});

console.log(source, diff.stats);

A full commit SHA stays readable while any repository ref can reach it. Keep the session branch until no reader needs its commits.

Use repos.files.get for files and repos.diff.get for changes.

​

Confine a sandbox to its own session

A sandbox never holds your private key. Give each sandbox a credential with a short TTL. Use ref_policies to confine that credential to the session’s own ref. The sandbox can then fast-forward its own session branch only. It cannot change a normal branch or another session branch.

A backend service that writes states through the API needs none of this. It signs each request with the private key and never hands a credential out.

External Sandbox Integration shows the URLs and the Git setup. See Ephemeral Namespace for namespace details and Ref Policies for the rules of ref_policies.

​

Next steps

• Restore Agent State restores the latest state after a sandbox stops.
• Run Parallel Attempts creates several isolated branches from one state.
• Show Live Diffs renders the state as it changes.