Run Parallel Attempts

Create several ephemeral branches from one commit when you want multiple agents to solve the same task. Each branch starts from the same files without a repository copy. This guide uses the session branch from Store Session State.

Pin the start state

Read the current tip SHA from your backend session record. Use the same SHA for every attempt.

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

const baseSha = process.env.TIP_SHA;
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 });

import os

from pierre_storage import GitStorage

base_sha = os.environ["TIP_SHA"]
session_id = os.environ["SESSION_ID"]

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

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

baseSHA := os.Getenv("TIP_SHA")
sessionID := os.Getenv("SESSION_ID")

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

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

Create the attempt branches

Create each attempt from the same SHA. Branch creation writes refs only and does not copy Git objects.

const attemptBranches = Array.from(
  { length: 4 },
  (_, index) => `sessions/${sessionId}/attempt/${index + 1}`,
);

await Promise.all(
  attemptBranches.map((attemptBranch) =>
    repo.createBranch({
      baseRef: baseSha,
      targetBranch: attemptBranch,
      targetIsEphemeral: true,
    }),
  ),
);

import asyncio

attempt_branches = [
    f"sessions/{session_id}/attempt/{index + 1}"
    for index in range(4)
]

await asyncio.gather(
    *(
        repo.create_branch(
            base_ref=base_sha,
            target_branch=attempt_branch,
            target_is_ephemeral=True,
        )
        for attempt_branch in attempt_branches
    )
)

attemptBranches := make([]string, 4)
for index := range attemptBranches {
	attemptBranch := fmt.Sprintf("sessions/%s/attempt/%d", sessionID, index+1)
	attemptBranches[index] = attemptBranch

	_, err = repo.CreateBranch(ctx, storage.CreateBranchOptions{
		BaseRef:           baseSHA,
		TargetBranch:      attemptBranch,
		TargetIsEphemeral: true,
	})
}

Give each sandbox one branch and one credential. Use expectedHeadSha: baseSha for its first commit, then use each returned commit SHA for the next write.

const attemptSource = 'export const authEnabled = true;\n';

const attempt = await repo
  .createCommit({
    author: { email: 'agent-1@example.com', name: 'Agent 1' },
    commitMessage: 'Attempt 1',
    ephemeral: true,
    expectedHeadSha: baseSha,
    targetBranch: attemptBranches[0],
  })
  .addFileFromString('src/auth.ts', attemptSource)
  .send();

console.log(attempt.commitSha);

attempt_source = "export const authEnabled = true;\n"

attempt = await (
    repo.create_commit(
        author={"email": "agent-1@example.com", "name": "Agent 1"},
        commit_message="Attempt 1",
        ephemeral=True,
        expected_head_sha=base_sha,
        target_branch=attempt_branches[0],
    )
    .add_file_from_string("src/auth.ts", attempt_source)
    .send()
)

print(attempt["commit_sha"])

attemptSource := "export const authEnabled = true;\n"

builder, err := repo.CreateCommit(storage.CommitOptions{
	Author:          storage.CommitSignature{Email: "agent-1@example.com", Name: "Agent 1"},
	CommitMessage:   "Attempt 1",
	Ephemeral:       true,
	ExpectedHeadSHA: baseSHA,
	TargetBranch:    attemptBranches[0],
})

attempt, err := builder.
	AddFileFromString("src/auth.ts", attemptSource, nil).
	Send(ctx)

fmt.Println(attempt.CommitSHA)

Compare the results

Read each attempt tip as a commit diff from the pinned start state. Evaluate each diff with tests, code review, or your own evaluation method.

const currentBranches = await repo.listBranches({ ephemeral: true, limit: 100 });

const results = await Promise.all(
  attemptBranches.map(async (attemptBranch) => {
    const current = currentBranches.branches.find((item) => item.name === attemptBranch);
    if (!current) throw new Error(`No branch exists for ${attemptBranch}`);

    return {
      branch: attemptBranch,
      diff: await repo.getCommitDiff({ baseSha, sha: current.headSha }),
    };
  }),
);

for (const result of results) {
  console.log(result.branch, result.diff.stats);
}

current_branches = await repo.list_branches(ephemeral=True, limit=100)

async def get_attempt_result(attempt_branch: str):
    current = next(
        (item for item in current_branches["branches"] if item["name"] == attempt_branch),
        None,
    )
    if current is None:
        raise RuntimeError(f"No branch exists for {attempt_branch}")

    return {
        "branch": attempt_branch,
        "diff": await repo.get_commit_diff(
            base_sha=base_sha,
            sha=current["head_sha"],
        ),
    }

results = await asyncio.gather(
    *(
        get_attempt_result(attempt_branch)
        for attempt_branch in attempt_branches
    )
)

for result in results:
    print(result["branch"], result["diff"]["stats"])

ephemeral := true
currentBranches, err := repo.ListBranches(ctx, storage.ListBranchesOptions{
	Ephemeral: &ephemeral,
	Limit:     100,
})

for _, attemptBranch := range attemptBranches {
	var headSHA string
	for _, current := range currentBranches.Branches {
		if current.Name == attemptBranch {
			headSHA = current.HeadSHA
			break
		}
	}
	if headSHA == "" {
		panic(fmt.Sprintf("no branch exists for %s", attemptBranch))
	}

	diff, err := repo.GetCommitDiff(ctx, storage.GetCommitDiffOptions{
		BaseSHA: baseSHA,
		SHA:     headSHA,
	})
	fmt.Println(attemptBranch, diff.Stats)
}

See getCommitDiff() for path filters and response fields.

Promote the winner

Promote the best ephemeral branch to a normal branch. You can then review and merge the normal branch.

const winner = attemptBranches[2];

await repo.createBranch({
  baseIsEphemeral: true,
  baseRef: winner,
  targetBranch: 'agent/fix-auth',
});

winner = attempt_branches[2]

await repo.create_branch(
    base_is_ephemeral=True,
    base_ref=winner,
    target_branch="agent/fix-auth",
)

winner := attemptBranches[2]

_, err = repo.CreateBranch(ctx, storage.CreateBranchOptions{
	BaseIsEphemeral: true,
	BaseRef:         winner,
	TargetBranch:    "agent/fix-auth",
})

Delete the other refs after you no longer need their states.

await Promise.all(
  attemptBranches
    .filter((attemptBranch) => attemptBranch !== winner)
    .map((attemptBranch) => repo.deleteBranch({ ephemeral: true, name: attemptBranch })),
);

await asyncio.gather(
    *(
        repo.delete_branch(ephemeral=True, name=attempt_branch)
        for attempt_branch in attempt_branches
        if attempt_branch != winner
    )
)

for _, attemptBranch := range attemptBranches {
	if attemptBranch == winner {
		continue
	}

	_, err = repo.DeleteBranch(ctx, storage.DeleteBranchOptions{
		Ephemeral: &ephemeral,
		Name:      attemptBranch,
	})
}

Deletion removes the refs. Git objects remain available while another ref can reach them. See Ephemeral Namespace for promotion details and Ref Policies for per-attempt credentials.

Getting Started

Features

Workflows

Reference

Pin the start state

Create the attempt branches

Compare the results

Promote the winner

​Pin the start state

​Create the attempt branches

​Compare the results

​Promote the winner

Pin the start state

Create the attempt branches

Compare the results

Promote the winner