Store Session State

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 ID, 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_PRIVATE_KEY to the private key in PEM format from the Code Storage dashboard. Do not give this key to a sandbox.

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 branch = await repo.createBranch({
  baseRef: repo.defaultBranch,
  targetBranch: sessionBranch,
  targetIsEphemeral: true,
});

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

let headSha = branch.commitSha;

baseRef 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 repo
  .createCommit({
    author: { email: 'agent@example.com', name: 'Agent' },
    commitMessage: 'Save session state',
    ephemeral: true,
    expectedHeadSha: headSha,
    targetBranch: sessionBranch,
  })
  .addFileFromString('src/auth.ts', updatedAuthSource)
  .addFileFromString('.agent/task.json', JSON.stringify(taskState))
  .send();

headSha = snapshot.commitSha;

expectedHeadSha lets the write succeed only if the branch still points to headSha. If another writer changed the branch, the write fails with the precondition_failed reason. Stop the old writer and reload the session record. Store headSha in the backend session record after each successful write. See createCommit() for file and stream inputs.

Exchange commit pointers

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

TypeScript

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

const pointerRepo = await store.findOne({ id: pointer.repositoryId });

const response = await pointerRepo.getFileStream({
  path: pointer.path,
  ref: pointer.sha,
});
const source = await response.text();

const diff = await pointerRepo.getCommitDiff({
  baseSha: previousHeadSha,
  sha: 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 getFileStream() for files and getCommitDiff() 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 refPolicies 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. Connect a Sandbox shows the URLs and the Git setup. See Ephemeral Namespace for namespace details and Branch Protection for refPolicies rules.

On GitHub App sync repositories, Git LFS uploads from an ephemeral URL still pass through to GitHub. Keep LFS-tracked files out of session states for now. See GitHub Sync.

Next steps

Resume Sandbox Work 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.

Getting Started

Features

Workflows

Reference

Create the session branch

Save each state

Exchange commit pointers

Confine a sandbox to its own session

Next steps

​Create the session branch

​Save each state

​Exchange commit pointers

​Confine a sandbox to its own session

​Next steps

Create the session branch

Save each state

Exchange commit pointers

Confine a sandbox to its own session

Next steps