@ziggs-ai/agent-sdk 0.38.17 → 0.39.0

package/dist/checkout/boxClient.js

@@ -0,0 +1,320 @@
+import { laneHeader } from '@ziggs-ai/api-client';
+import { runtimeLog } from '../shared/runtimeLog.js';
+/** Headers git sends that the door needs to see; anything else stays behind. */
+const GIT_REQUEST_HEADERS = ['content-type', 'content-encoding', 'accept', 'git-protocol'];
+/** Headers the door answers with that git needs to see. */
+const GIT_RESPONSE_HEADERS = ['content-type', 'cache-control', 'content-encoding', 'www-authenticate'];
+const BOX_PATH = /^\/([^/]+)\/([^/]+?)(?:\.git)?\/(info\/refs|git-upload-pack|git-receive-pack)(\?.*)?$/;
+/** The door path for one of the box's git requests, or null when the request names another repository. */
+export function doorPathFor(boxPath, door) {
+    const m = BOX_PATH.exec(boxPath);
+    if (!m)
+        return null;
+    const [, owner, name, tail, query] = m;
+    if (owner.toLowerCase() !== door.repository.owner.toLowerCase() || name.toLowerCase() !== door.repository.name.toLowerCase()) {
+        return null;
+    }
+    return `/connections/${encodeURIComponent(door.connectionId)}/git/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/${tail}${query ?? ''}`;
+}
+export function doorHeaders(door, gitHeaders) {
+    const out = {
+        authorization: `Bearer ${door.operatorKey}`,
+        'x-agent-id': door.agentId,
+        'x-grant-id': door.grantId,
+        'x-ziggs-task-id': door.taskId,
+    };
+    for (const [key, value] of Object.entries(laneHeader(door.laneId)))
+        out[key.toLowerCase()] = value;
+    for (const [k, v] of Object.entries(gitHeaders)) {
+        if (GIT_REQUEST_HEADERS.includes(k.toLowerCase()))
+            out[k.toLowerCase()] = v;
+    }
+    return out;
+}
+export class CheckoutBoxError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'CheckoutBoxError';
+    }
+}
+/**
+ * The host's end of the channel. One per box. Every call carries the box's
+ * secret; the box answers nothing without it.
+ */
+export class CheckoutBoxClient {
+    endpoint;
+    fetchFn;
+    relayStopped = false;
+    relayLoop = null;
+    relayAbort = new AbortController();
+    forwarding = new Set();
+    mutation = Promise.resolve();
+    closing = false;
+    onMutation;
+    checkpointWarning;
+    warnCheckpoint(message) {
+        this.checkpointWarning = message;
+        runtimeLog.warn('checkout', message);
+    }
+    withCheckpointWarning(result) {
+        return this.checkpointWarning ? { ...result, checkpointWarning: this.checkpointWarning } : result;
+    }
+    mutate(operation) {
+        const pending = this.mutation.catch(() => { }).then(async () => {
+            if (this.closing)
+                throw new CheckoutBoxError('checkout is closing');
+            let result;
+            try {
+                result = await operation();
+            }
+            catch (error) {
+                // A lost HTTP response does not prove the command stopped. Quiesce
+                // before snapshotting; otherwise a retry could restore a torn archive.
+                await this.call('/cancel', {}, 5_000).catch(() => { });
+                throw error;
+            }
+            finally {
+                try {
+                    await this.onMutation?.();
+                }
+                catch (error) {
+                    this.warnCheckpoint(`Private checkpoint save failed: ${error.message}. Only previously saved or pushed work can be recovered.`);
+                }
+            }
+            return this.withCheckpointWarning(result);
+        });
+        this.mutation = pending;
+        return pending;
+    }
+    async quiesce() {
+        this.closing = true;
+        await this.call('/cancel', {}, 5_000).catch(() => { });
+        await this.mutation.catch(() => { });
+    }
+    async checkpoint() {
+        const res = await this.fetchFn(`${this.endpoint.url}/checkpoint`, {
+            method: 'POST', headers: this.auth(), signal: AbortSignal.timeout(130_000),
+        });
+        if (!res.ok)
+            throw new CheckoutBoxError(`checkpoint failed: ${await res.text()}`, res.status);
+        const reader = res.body?.getReader();
+        if (!reader)
+            throw new CheckoutBoxError('checkpoint has no body');
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > 64 * 1024 * 1024)
+                    throw new CheckoutBoxError('checkpoint exceeds 64 MiB');
+                chunks.push(value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+        return Buffer.concat(chunks);
+    }
+    async restore(data) {
+        const res = await this.fetchFn(`${this.endpoint.url}/restore`, {
+            method: 'POST', headers: { ...this.auth(), 'content-type': 'application/gzip' },
+            body: Buffer.from(data), signal: AbortSignal.timeout(130_000),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new CheckoutBoxError(`restore failed: ${text}`, res.status);
+    }
+    constructor(endpoint, fetchFn = fetch) {
+        this.endpoint = endpoint;
+        this.fetchFn = fetchFn;
+    }
+    auth() {
+        return { authorization: `Bearer ${this.endpoint.secret}` };
+    }
+    async call(path, body, timeoutMs = 60_000) {
+        const res = await this.fetchFn(`${this.endpoint.url}${path}`, {
+            method: 'POST',
+            headers: { ...this.auth(), 'content-type': 'application/json' },
+            body: JSON.stringify(body ?? {}),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = { error: text };
+        }
+        if (!res.ok) {
+            const error = parsed?.error ?? text ?? `HTTP ${res.status}`;
+            throw new CheckoutBoxError(`box ${path} failed: ${error}`, res.status);
+        }
+        return parsed;
+    }
+    /** Poll the box until it answers, or give up. */
+    async waitReady(timeoutMs) {
+        const until = Date.now() + timeoutMs;
+        let lastError = 'no answer';
+        while (Date.now() < until) {
+            try {
+                const res = await this.fetchFn(`${this.endpoint.url}/health`, {
+                    headers: this.auth(),
+                    signal: AbortSignal.timeout(3_000),
+                });
+                if (res.ok) {
+                    await res.text();
+                    return;
+                }
+                lastError = `HTTP ${res.status}`;
+            }
+            catch (err) {
+                lastError = err.message;
+            }
+            await new Promise((r) => setTimeout(r, 1_000));
+        }
+        throw new CheckoutBoxError(`box did not come up within ${Math.round(timeoutMs / 1000)}s (${lastError})`);
+    }
+    /**
+     * Forward the box's git requests to the door, one at a time as git makes
+     * them, until {@link stopRelay}. The box queues what git asks; this end
+     * long-polls, performs each request against the door under the hire's
+     * grant, and posts the answer back for git to read.
+     */
+    startRelay(door) {
+        if (this.relayLoop)
+            return;
+        this.relayStopped = false;
+        this.relayAbort = new AbortController();
+        this.relayLoop = this.relay(door).catch((err) => {
+            runtimeLog.warn('checkout', `git relay stopped: ${err.message}`);
+        });
+    }
+    async stopRelay() {
+        this.relayStopped = true;
+        this.relayAbort.abort();
+        await Promise.allSettled(this.forwarding);
+        await this.relayLoop?.catch(() => { });
+        this.relayLoop = null;
+    }
+    async relay(door) {
+        while (!this.relayStopped) {
+            let next;
+            try {
+                next = await this.fetchFn(`${this.endpoint.url}/relay/next`, {
+                    headers: this.auth(),
+                    signal: AbortSignal.any([this.relayAbort.signal, AbortSignal.timeout(40_000)]),
+                });
+            }
+            catch {
+                if (this.relayStopped)
+                    return;
+                await new Promise((r) => setTimeout(r, 500));
+                continue;
+            }
+            if (next.status === 204) {
+                await next.text().catch(() => { });
+                continue;
+            }
+            if (!next.ok) {
+                await next.text().catch(() => { });
+                if (next.status === 401)
+                    throw new CheckoutBoxError('box refused the channel secret', 401);
+                await new Promise((r) => setTimeout(r, 500));
+                continue;
+            }
+            const forwarding = this.forward(next, door).catch((err) => {
+                if (!this.relayStopped)
+                    runtimeLog.warn('checkout', `git relay request failed: ${err.message}`);
+            });
+            this.forwarding.add(forwarding);
+            void forwarding.finally(() => this.forwarding.delete(forwarding));
+        }
+    }
+    async forward(next, door) {
+        const id = next.headers.get('x-relay-id') ?? '';
+        const method = (next.headers.get('x-relay-method') ?? 'GET').toUpperCase();
+        const boxPath = next.headers.get('x-relay-path') ?? '/';
+        let gitHeaders = {};
+        try {
+            gitHeaders = JSON.parse(next.headers.get('x-relay-headers') ?? '{}');
+        }
+        catch {
+            gitHeaders = {};
+        }
+        const reply = async (status, headers, body) => {
+            const res = await this.fetchFn(`${this.endpoint.url}/relay/${encodeURIComponent(id)}`, {
+                method: 'POST',
+                headers: {
+                    ...this.auth(),
+                    'x-relay-status': String(status),
+                    'x-relay-headers': JSON.stringify(headers),
+                    'content-type': 'application/octet-stream',
+                },
+                body,
+                // Streaming request bodies need half duplex in Node's fetch.
+                ...{ duplex: 'half' },
+                signal: AbortSignal.any([this.relayAbort.signal, AbortSignal.timeout(10 * 60_000)]),
+            });
+            await res.text().catch(() => { });
+        };
+        const doorPath = doorPathFor(boxPath, door);
+        if (!doorPath) {
+            await next.body?.cancel().catch(() => { });
+            await reply(403, { 'content-type': 'text/plain' }, `this box is checked out for ${door.repository.owner}/${door.repository.name} only`);
+            return;
+        }
+        let upstream;
+        try {
+            upstream = await this.fetchFn(`${door.backendUrl}${doorPath}`, {
+                method,
+                headers: doorHeaders(door, gitHeaders),
+                body: method === 'POST' ? next.body : undefined,
+                ...{ duplex: 'half' },
+                redirect: 'manual',
+                signal: AbortSignal.any([this.relayAbort.signal, AbortSignal.timeout(10 * 60_000)]),
+            });
+        }
+        catch (err) {
+            await reply(502, { 'content-type': 'text/plain' }, `git door unreachable: ${err.message}`);
+            return;
+        }
+        const headers = {};
+        for (const name of GIT_RESPONSE_HEADERS) {
+            const v = upstream.headers.get(name);
+            if (v)
+                headers[name] = v;
+        }
+        await reply(upstream.status, headers, upstream.body);
+    }
+    setup(spec) {
+        return this.call('/setup', spec, 15 * 60_000);
+    }
+    async read(path) {
+        return this.withCheckpointWarning(await this.call('/read', { path }));
+    }
+    write(path, content) {
+        return this.mutate(() => this.call('/write', { path, content }));
+    }
+    run(command, timeoutSeconds) {
+        const seconds = Math.max(1, Math.min(timeoutSeconds ?? 600, 1_800));
+        return this.mutate(() => this.call('/run', { command, timeoutSeconds: seconds }, (seconds + 30) * 1000));
+    }
+    push(message) {
+        return this.mutate(() => this.call('/push', { message }, 10 * 60_000));
+    }
+    /** Ask the box to exit. Best effort: a box that is already gone is the goal. */
+    async stop() {
+        try {
+            await this.call('/stop', {}, 5_000);
+        }
+        catch {
+            /* already gone, or never came up */
+        }
+    }
+}

package/dist/checkout/index.d.ts

@@ -0,0 +1,10 @@
+export type { CheckoutBox, CheckoutBoxEndpoint, CheckoutBoxSpec, CheckoutProvider, CheckoutCheckpointStore, CheckoutTarget, CheckoutRunResult, CheckoutPushResult, } from './types.js';
+export { CheckoutBoxClient, CheckoutBoxError, doorPathFor, doorHeaders, type GitDoorTarget } from './boxClient.js';
+export { checkoutTargetFromText, checkoutTargetFromTask, checkoutBranchForTask } from './intake.js';
+export { CHECKOUT_TOOLS, checkoutReadTool, checkoutWriteTool, checkoutRunTool, checkoutPushTool, type CheckoutSession, } from './tools.js';
+export { openCheckout, closeCheckout, type OpenCheckout, type OpenCheckoutDeps } from './open.js';
+/**
+ * The box server, as a file a host can run with Node, or embed as a task's
+ * command. It depends on nothing but Node and git.
+ */
+export declare function checkoutBoxServerPath(): string;

package/dist/checkout/index.js

@@ -0,0 +1,12 @@
+import { fileURLToPath } from 'node:url';
+export { CheckoutBoxClient, CheckoutBoxError, doorPathFor, doorHeaders } from './boxClient.js';
+export { checkoutTargetFromText, checkoutTargetFromTask, checkoutBranchForTask } from './intake.js';
+export { CHECKOUT_TOOLS, checkoutReadTool, checkoutWriteTool, checkoutRunTool, checkoutPushTool, } from './tools.js';
+export { openCheckout, closeCheckout } from './open.js';
+/**
+ * The box server, as a file a host can run with Node, or embed as a task's
+ * command. It depends on nothing but Node and git.
+ */
+export function checkoutBoxServerPath() {
+    return fileURLToPath(new URL('./box/server.js', import.meta.url));
+}

package/dist/checkout/intake.d.ts

@@ -0,0 +1,15 @@
+import type { CheckoutTarget } from './types.js';
+/**
+ * What the task names. A task for a checkout agent names a repository as
+ * `owner/name` (a GitHub URL counts) and may name a base branch; when it does
+ * not, the repository's default branch is used. Nothing is guessed: a task
+ * naming no repository is refused with that said, not pointed at a likely one.
+ */
+export declare function checkoutTargetFromText(text: string): CheckoutTarget | null;
+/** The task's own words: title first, then the description. */
+export declare function checkoutTargetFromTask(task: {
+    title?: string | null;
+    description?: string | null;
+}): CheckoutTarget | null;
+/** The branch a task's change lands on: one per task, never the default branch. */
+export declare function checkoutBranchForTask(taskId: string): string;

package/dist/checkout/intake.js

@@ -0,0 +1,65 @@
+/** `owner/name`, the way GitHub spells it. */
+const REPOSITORY = /(?<![\w./-])([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9_.-]{1,100})(?![\w./-])/g;
+/** Words that look like `a/b` in prose but are never a repository. */
+const NOT_REPOSITORIES = new Set(['and/or', 'yes/no', 'on/off', 'read/write', 'i/o', 'he/she', 'his/her', 'src/']);
+const BASE_BRANCH = /\b(?:base|target|from|off|onto|against)\s+(?:the\s+)?branch\s+[`"']?([A-Za-z0-9._\/-]+)[`"']?|\bbranch\s*(?::|=)\s*[`"']?([A-Za-z0-9._\/-]+)[`"']?|\bbase\s*(?::|=)\s*[`"']?([A-Za-z0-9._\/-]+)[`"']?/i;
+/**
+ * What the task names. A task for a checkout agent names a repository as
+ * `owner/name` (a GitHub URL counts) and may name a base branch; when it does
+ * not, the repository's default branch is used. Nothing is guessed: a task
+ * naming no repository is refused with that said, not pointed at a likely one.
+ */
+export function checkoutTargetFromText(text) {
+    if (!text)
+        return null;
+    const fromUrl = /github\.com[/:]([A-Za-z0-9-]+)\/([A-Za-z0-9_.-]+)(?:[/\s)>,]|$)/.exec(text);
+    let owner;
+    let name;
+    if (fromUrl) {
+        owner = fromUrl[1];
+        name = fromUrl[2];
+    }
+    else {
+        for (const match of text.matchAll(REPOSITORY)) {
+            const candidate = `${match[1]}/${match[2]}`;
+            if (NOT_REPOSITORIES.has(candidate.toLowerCase()))
+                continue;
+            // A path like `src/pages` reads as a repository to the regex; a repository
+            // owner is an account, which never contains a dot, and the name never a
+            // second slash. The first `owner/name` the task mentions wins.
+            if (/^[a-z]+$/.test(match[1]) && /^(src|app|lib|pages|components|docs|test|tests|scripts|public|assets|dist|build|node_modules|packages|api|config|styles|utils|hooks|types)$/.test(match[1]))
+                continue;
+            owner = match[1];
+            name = match[2];
+            break;
+        }
+    }
+    if (!owner || !name)
+        return null;
+    name = name.replace(/[.,;:]+$/, '').replace(/\.git$/, '');
+    if (!name || name === '.' || name === '..')
+        return null;
+    const base = BASE_BRANCH.exec(text);
+    const baseBranch = (base?.[1] ?? base?.[2] ?? base?.[3] ?? null)?.replace(/[.,;:]+$/, "") || null;
+    return {
+        repository: `${owner}/${name}`,
+        owner,
+        name,
+        baseBranch: baseBranch && baseBranch !== owner ? baseBranch : null,
+    };
+}
+/** The task's own words: title first, then the description. */
+export function checkoutTargetFromTask(task) {
+    const title = String(task.title ?? '');
+    const description = String(task.description ?? '');
+    const target = checkoutTargetFromText(title) ?? checkoutTargetFromText(description);
+    if (!target)
+        return null;
+    const base = BASE_BRANCH.exec(`${title}\n${description}`);
+    target.baseBranch = (base?.[1] ?? base?.[2] ?? '').replace(/[.,;:]+$/, '') || null;
+    return target;
+}
+/** The branch a task's change lands on: one per task, never the default branch. */
+export function checkoutBranchForTask(taskId) {
+    return `agent/${String(taskId).trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-')}`;
+}

package/dist/checkout/open.d.ts

@@ -0,0 +1,49 @@
+import type { ConnectionWithGrants } from '@ziggs-ai/api-client';
+import { type GitDoorTarget } from './boxClient.js';
+import type { CheckoutSession } from './tools.js';
+import type { CheckoutBox, CheckoutProvider } from './types.js';
+import { type AgentNeed } from '../tools/needs.js';
+/** A box that is open for one wake, and when it started, for the cost line. */
+export interface OpenCheckout {
+    session: CheckoutSession;
+    box: CheckoutBox;
+    startedAt: number;
+    saveCheckpoint: () => Promise<void>;
+}
+export interface OpenCheckoutDeps {
+    provider: CheckoutProvider | undefined;
+    needs: AgentNeed[];
+    /** The task this wake is for; no task, no checkout. */
+    taskId: string | undefined;
+    getTask(taskId: string): Promise<{
+        title?: string | null;
+        description?: string | null;
+    }>;
+    /** The agent's live connection grants, grouped by connection. */
+    listConnections(): Promise<ConnectionWithGrants[]>;
+    door: Pick<GitDoorTarget, 'backendUrl' | 'operatorKey' | 'agentId' | 'laneId'>;
+    /** Close the task with the reason, the way the needs gate does. */
+    failTask(taskId: string, reason: string): Promise<void>;
+    log: (message: string) => void;
+    fetchFn?: typeof fetch;
+    /** Hard cap for the box, seconds. Default one hour. */
+    ttlSeconds?: number;
+    /** How long to wait for the box to answer. Default five minutes. */
+    readyTimeoutMs?: number;
+}
+/**
+ * Open the checkout a wake needs, or refuse the task by name.
+ *
+ * Returns null when this wake needs no checkout (the agent declares none, or
+ * the wake carries no task), `'refused'` when the task was failed here with
+ * the reason, and the open box otherwise. The caller destroys the box when
+ * the wake ends ({@link closeCheckout}).
+ */
+export declare function openCheckout(deps: OpenCheckoutDeps): Promise<OpenCheckout | null | 'refused'>;
+/** Destroy the box. Returns how long it lived, for the cost line. */
+export declare function closeCheckout(open: OpenCheckout): Promise<{
+    kind: string;
+    seconds: number;
+    vcpu?: number;
+    memoryMb?: number;
+}>;

package/dist/checkout/open.js

@@ -0,0 +1,190 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { CheckoutBoxClient, doorHeaders } from './boxClient.js';
+import { checkoutBranchForTask, checkoutTargetFromTask } from './intake.js';
+import { isCheckoutNeed, unmetNeedsMessage } from '../tools/needs.js';
+/** Connection providers whose grant can back a checkout. */
+function canBackCheckout(provider) {
+    const p = String(provider ?? '').split('—')[0].trim().toLowerCase();
+    return p === 'github' || p === 'mcp';
+}
+/**
+ * Open the checkout a wake needs, or refuse the task by name.
+ *
+ * Returns null when this wake needs no checkout (the agent declares none, or
+ * the wake carries no task), `'refused'` when the task was failed here with
+ * the reason, and the open box otherwise. The caller destroys the box when
+ * the wake ends ({@link closeCheckout}).
+ */
+export async function openCheckout(deps) {
+    if (!deps.needs.some(isCheckoutNeed))
+        return null;
+    const taskId = deps.taskId;
+    if (!taskId)
+        return null;
+    const fetchFn = deps.fetchFn ?? fetch;
+    const refuse = async (reason) => {
+        deps.log(`refusing task ${taskId} — ${reason}`);
+        try {
+            await deps.failTask(taskId, reason);
+        }
+        catch (err) {
+            deps.log(`could not fail task ${taskId}: ${err.message}`);
+        }
+        return 'refused';
+    };
+    let task;
+    try {
+        task = await deps.getTask(taskId);
+    }
+    catch (err) {
+        // Reading failed before any effect: let the host retry, without failing the task.
+        throw new Error(`Checkout task ${taskId} could not be read: ${err.message}`, { cause: err });
+    }
+    const target = checkoutTargetFromTask(task);
+    if (!target) {
+        return refuse('Cannot start this task: it names no repository. Name it as owner/name (a GitHub URL also works), and the base branch if it is not the default branch.');
+    }
+    if (!deps.provider) {
+        return refuse(`Cannot start this task: it needs a checkout of ${target.repository} and this host provides none.`);
+    }
+    let groups;
+    try {
+        groups = await deps.listConnections();
+    }
+    catch (err) {
+        return refuse(`Cannot start this task: the connection grants could not be read (${err.message}).`);
+    }
+    const candidates = groups.filter((g) => (g.grants ?? []).length > 0 && canBackCheckout(g.provider));
+    if (!candidates.length)
+        return refuse(unmetNeedsMessage([{ checkout: 'git' }]));
+    // The grant that can actually see the repository: asked of the door, which
+    // answers for the connection it fronts. A grant on another MCP server, or a
+    // GitHub account that cannot see this repository, is named rather than tried.
+    let door = null;
+    const tried = [];
+    candidatesLoop: for (const group of candidates) {
+        for (const grant of group.grants ?? []) {
+            const grantId = String(grant.grantId ?? '');
+            if (!grantId)
+                continue;
+            const candidate = {
+                ...deps.door,
+                connectionId: group.connectionId,
+                grantId,
+                taskId,
+                repository: { owner: target.owner, name: target.name },
+            };
+            try {
+                const probe = await fetchFn(`${deps.door.backendUrl}/connections/${encodeURIComponent(group.connectionId)}/git/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.name)}/info/refs?service=git-upload-pack`, { headers: doorHeaders(candidate, {}), signal: AbortSignal.timeout(30_000) });
+                const text = await probe.text();
+                if (probe.ok) {
+                    door = candidate;
+                    break candidatesLoop;
+                }
+                tried.push(`${group.connectionId}: ${probe.status} ${text.slice(0, 160).replace(/\s+/g, ' ')}`);
+            }
+            catch (err) {
+                tried.push(`${group.connectionId}: ${err.message}`);
+            }
+        }
+    }
+    if (!door) {
+        return refuse(`Cannot start this task: no GitHub connection grant on this hire can read ${target.repository} (${tried.join('; ')}). ` +
+            'Ask the connection owner to grant a GitHub connection that can see the repository, then re-assign the task.');
+    }
+    const branch = checkoutBranchForTask(taskId);
+    const secret = randomBytes(32).toString('hex');
+    const startedAt = Date.now();
+    let box;
+    try {
+        box = await deps.provider.start({
+            secret,
+            ttlSeconds: deps.ttlSeconds ?? 3600,
+            label: { agentId: deps.door.agentId, taskId, repository: target.repository },
+        });
+    }
+    catch (err) {
+        return refuse(`Cannot start this task: the host could not start a box for the checkout (${err.message}).`);
+    }
+    const client = new CheckoutBoxClient(box.endpoint, fetchFn);
+    try {
+        await client.waitReady(deps.readyTimeoutMs ?? 5 * 60_000);
+        client.startRelay(door);
+        const ready = await client.setup({ repository: target.repository, baseBranch: target.baseBranch, branch });
+        const key = createHash('sha256').update(JSON.stringify([
+            deps.door.agentId, deps.door.laneId ?? null, taskId,
+            target.repository.toLowerCase(), ready.baseBranch,
+        ])).digest('hex');
+        const store = deps.provider.checkpoints;
+        const saved = await store?.load(key);
+        if (saved)
+            await client.restore(saved);
+        let checkpointFailed = false;
+        const saveCheckpoint = async () => {
+            if (!store || checkpointFailed)
+                return;
+            try {
+                await store.save(key, await client.checkpoint());
+            }
+            catch (error) {
+                // Do not replace a tool result, retry a completed wake, or repeatedly
+                // archive an oversized repository. Keep the last recoverable snapshot.
+                checkpointFailed = true;
+                client.warnCheckpoint(`Private checkpoint save failed: ${error.message}. Checkpoints are disabled for this wake; push the task branch to preserve current work.`);
+            }
+        };
+        if (store)
+            client.onMutation = saveCheckpoint;
+        else
+            client.warnCheckpoint('Private checkpoints are disabled. Only work pushed to the task branch survives this wake.');
+        deps.log(`checkout open: ${target.repository} at ${ready.baseBranch} (${ready.head.slice(0, 10)}) on ${branch}` +
+            `${saved ? ', restored private task checkpoint' : ready.resumed ? ', continuing the branch an earlier wake pushed' : ''}, ${box.kind} box`);
+        return {
+            box,
+            startedAt,
+            saveCheckpoint,
+            session: {
+                client,
+                target,
+                baseBranch: ready.baseBranch,
+                branch,
+                taskId,
+                boxKind: box.kind,
+            },
+        };
+    }
+    catch (err) {
+        await client.stopRelay();
+        await box.stop();
+        // A storage/readiness/clone outage must not permanently fail the task.
+        // In particular, never continue from a fresh clone if loading a configured
+        // checkpoint failed: doing so could overwrite recoverable work.
+        throw new Error(`Could not open checkout of ${target.repository}: ${err.message}`, { cause: err });
+    }
+}
+/** Destroy the box. Returns how long it lived, for the cost line. */
+export async function closeCheckout(open) {
+    try {
+        await open.session.client.quiesce();
+        await open.saveCheckpoint();
+    }
+    finally {
+        try {
+            await open.session.client.stop();
+        }
+        finally {
+            try {
+                await open.session.client.stopRelay();
+            }
+            finally {
+                await open.box.stop();
+            }
+        }
+    }
+    return {
+        kind: open.box.kind,
+        seconds: Math.max(1, Math.round((Date.now() - open.startedAt) / 1000)),
+        ...(open.box.resources?.vcpu !== undefined ? { vcpu: open.box.resources.vcpu } : {}),
+        ...(open.box.resources?.memoryMb !== undefined ? { memoryMb: open.box.resources.memoryMb } : {}),
+    };
+}