Capture Agent 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_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.

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

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

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

const branch = await repo.createBranch({
  baseRef: repo.defaultBranch,
  targetIsEphemeral: true,
});

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

const sessionBranch = branch.targetBranch;
let headSha = branch.commitSha;

import os

from pierre_storage import GitStorage

storage_client = GitStorage({
    "key": os.environ["PIERRE_PRIVATE_KEY"],
    "name": os.environ["PIERRE_ORG"],
})

repository_id = "acme/storefront"
repo = await storage_client.find_one(id=repository_id)

branch = await repo.create_branch(
    base_ref=repo.default_branch,
    target_is_ephemeral=True,
)

if not branch["commit_sha"]:
    raise RuntimeError("The session branch has no base commit")

session_branch = branch["target_branch"]
head_sha = branch["commit_sha"]

import "os"

client, err := storage.NewClient(storage.Options{
	Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
	Name: os.Getenv("PIERRE_ORG"),
})

ctx := context.Background()
repositoryID := "acme/storefront"
repo, err := client.FindOne(ctx, storage.FindOneOptions{ID: repositoryID})

branch, err := repo.CreateBranch(ctx, storage.CreateBranchOptions{
	BaseRef:           repo.DefaultBranch,
	TargetIsEphemeral: true,
})

if branch.CommitSHA == "" {
	panic("the session branch has no base commit")
}

sessionBranch := branch.TargetBranch
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.

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;

import json
from pathlib import Path

previous_head_sha = head_sha
updated_auth_source = Path("src/auth.ts").read_text()
task_state = {"status": "in_progress"}

snapshot = await (
    repo.create_commit(
        author={"email": "agent@example.com", "name": "Agent"},
        commit_message="Save session state",
        ephemeral=True,
        expected_head_sha=head_sha,
        target_branch=session_branch,
    )
    .add_file_from_string("src/auth.ts", updated_auth_source)
    .add_file_from_string(".agent/task.json", json.dumps(task_state))
    .send()
)

head_sha = snapshot["commit_sha"]

previousHeadSHA := headSHA
updatedAuthSource, err := os.ReadFile("src/auth.ts")
taskState, err := json.Marshal(map[string]string{"status": "in_progress"})

builder, err := repo.CreateCommit(storage.CommitOptions{
	Author:          storage.CommitSignature{Email: "agent@example.com", Name: "Agent"},
	CommitMessage:   "Save session state",
	Ephemeral:       true,
	ExpectedHeadSHA: headSHA,
	TargetBranch:    sessionBranch,
})

snapshot, err := builder.
	AddFileFromString("src/auth.ts", string(updatedAuthSource), nil).
	AddFileFromString(".agent/task.json", string(taskState), nil).
	Send(ctx)

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.

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);

pointer = {
    "path": "src/auth.ts",
    "repository_id": repo.id,
    "sha": head_sha,
}

pointer_repo = await storage_client.find_one(id=pointer["repository_id"])

response = await pointer_repo.get_file_stream(
    path=pointer["path"],
    ref=pointer["sha"],
)
source = (await response.aread()).decode()

diff = await pointer_repo.get_commit_diff(
    base_sha=previous_head_sha,
    sha=pointer["sha"],
)

print(source, diff["stats"])

pointer := struct {
	Path         string
	RepositoryID string
	SHA          string
}{
	Path:         "src/auth.ts",
	RepositoryID: repo.ID,
	SHA:          headSHA,
}

pointerRepo, err := client.FindOne(ctx, storage.FindOneOptions{ID: pointer.RepositoryID})

response, err := pointerRepo.FileStream(ctx, storage.GetFileOptions{
	Path: pointer.Path,
	Ref:  pointer.SHA,
})
defer response.Body.Close()
source, err := io.ReadAll(response.Body)

diff, err := pointerRepo.GetCommitDiff(ctx, storage.GetCommitDiffOptions{
	BaseSHA: previousHeadSHA,
	SHA:     pointer.SHA,
})

fmt.Println(string(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. External Sandbox Integration shows the URLs and the Git setup. See Ephemeral Namespace for namespace details and Ref Policies for refPolicies rules.

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.

Getting Started

Platform

Workflows

Libraries

API 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