Agent branch lease

Claim a scoped branch and token in one call. The branch and token both expire when the TTL ends—no cleanup logic required.

import { PerSQL } from "@persql/sdk";

const parent = new PerSQL({ token: process.env.PERSQL_TOKEN! });
const db = parent.database("acme", "main");

const lease = await db.branches.claim({
  purpose: "ingestion-agent",
  ttlSec: 3600,
  role: "write",
});

const sandbox = new PerSQL({ token: lease.token });
const branch = sandbox.database(lease.namespaceSlug, lease.databaseSlug);

await branch.query(
  "CREATE TABLE IF NOT EXISTS staging (id INTEGER PRIMARY KEY, payload TEXT)"
);
await branch.query(
  "INSERT INTO staging (payload) VALUES (?)",
  [JSON.stringify({ source: "s3", key: "uploads/2024.csv" })]
);

await db.branches.merge(lease.branchRef, { mode: "schema" });

The leased token is scoped to one branch and one role. When the TTL expires both the branch and the token are reclaimed automatically.

Next step

Sub-agent handoff