@ziggs-ai/agent-sdk 0.38.17 → 0.39.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## Unreleased
+## 0.39.0
+
+- A manifest may declare `needs: [{ checkout: 'git' }]`. The host provides a throwaway box per wake (`checkout` option, a `CheckoutProvider`); the task names the repository as owner/name and may name a base branch; the brain gets `checkout_read`, `checkout_write`, `checkout_run` and `checkout_push`; the change is pushed to `agent/<task id>` for a pull request. Without a GitHub connection grant on the hire the task is refused by name, like a connection need. The box holds no credential: its git traffic is relayed by the host through the backend git door under the hire's grant. The box server ships as `dist/checkout/box/server.js` (`checkoutBoxServerPath()`).
+
+- Every repository subprocess, including Git filters, runs with the same box confinement. File reads preserve the beginning, report actual byte counts and truncation, and build output is bounded while it arrives.
+- Checkout providers may supply private checkpoint storage. Without it, later wakes resume the pushed task branch. Mutating tools and wake cleanup save staged, unstaged and untracked work; later wakes restore it without making or pushing a commit. Storage keys isolate agents, hire lanes, tasks, repositories and base branches. Save failures return warnings without replacing command results or failing completed wakes; task-read and checkout-open errors leave task status unchanged.
+- Task intake preserves dotted repository names and reads the explicit base branch from either title or description. Relay shutdown cancels outstanding requests and cleanup stops the box even when checkpoint storage fails.
 
 ## 0.38.17
 

package/README.md

@@ -120,6 +120,43 @@ capability bundles include `DISCOVERY_TOOLS`, `CONTEXT_TOOLS`, `CONNECTION_TOOLS
 Use `defineTool` for your own tools. Declared `needs` provide their access tools
 and enforce missing grants at task start.
 
+A need can also be a checkout: `needs: [{ checkout: 'git' }]`. The host
+provides a throwaway box per wake (the `checkout` option, a `CheckoutProvider`),
+the task names the repository as owner/name and may name a base branch, and
+the agent gets `checkout_read`, `checkout_write`, `checkout_run` and
+`checkout_push`. The change is pushed to `agent/<task id>` for a pull request;
+the default branch is never pushed. Without a GitHub connection grant the task
+is refused by name. The box holds no credential: its git traffic is relayed by
+the host through the backend under the grant. The box server ships as
+`dist/checkout/box/server.js` (`checkoutBoxServerPath()`) and needs only Node
+and git.
+
+A provider may supply `checkpoints: CheckoutCheckpointStore` with `load(key)`
+and atomic `save(key, bytes)` methods. Without storage, later wakes resume the
+pushed task branch; tool results explicitly warn that unpushed work is temporary.
+Checkpoints are private host storage, never a Git push. When configured, the SDK
+saves after mutating tools and during wake cleanup. Keys include agent, hire lane,
+task, repository and base branch. Archives are capped at 64 MiB compressed and
+omit `node_modules` and `.npm`; reinstall dependencies after a restore.
+
+A failed save preserves the tool's original result and adds `checkpointWarning`.
+Further saves are disabled for that wake, so an oversized repository or storage
+outage does not repeatedly delay every tool or fail an already completed wake.
+Only the last successful checkpoint or pushed branch is recoverable. Loading a
+configured store must succeed before work proceeds, to avoid overwriting saved
+work. A task-read or checkout-open error leaves task status unchanged.
+
+The reference Mac host retains local snapshots for seven days. The Fargate host
+has no checkpoint storage by default and this rollout provisions no S3 snapshot
+bucket. A production host can explicitly supply a store after establishing its
+own retention policy and dedicated access controls.
+
+All subprocesses, including Git and archive extraction, use `BOX_RUN_AS` or
+`BOX_EXEC_PREFIX`. Providers must enforce outbound isolation independently of
+proxy environment variables. The reference fleet uses subnets without an internet
+route and a package proxy; the local host allows only the Git relay and that proxy.
+
+
 Configure an alternate backend before constructing an agent:
 
 ```ts

package/dist/Agent.d.ts

@@ -30,6 +30,7 @@ import { ToolManager } from './tools/ToolManager.js';
 import { type ToolDefinition } from './tools/defineTool.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { type AgentNeed } from './tools/needs.js';
+import type { CheckoutProvider } from './checkout/types.js';
 /**
  * Given a normalized event, return the sessionId for this agent. Return
  * `null` to skip processing. Lets each Agent define what "session" means —
@@ -89,6 +90,12 @@ export interface AgentOptions {
      * missing access named, before the tick spends anything.
      */
     needs?: AgentNeed[];
+    /**
+     * Who provides the checkout a `{ checkout: 'git' }` need asks for: the host.
+     * A fleet starts a container per wake, a lab a confined local process. Left
+     * unset, a task that needs a checkout is refused naming this host.
+     */
+    checkout?: CheckoutProvider;
     taskTools?: 'all' | 'none' | string[];
     /**
      * Brain selection — preferred over legacy `cognition`.
@@ -265,6 +272,8 @@ export declare class Agent {
     private readonly outboundMessages;
     private readonly confirmedPlanVersions;
     private grantProviderCache;
+    /** The checkout box each lane holds while its wake runs. */
+    private checkoutByLane;
     constructor(options?: AgentOptions);
     private _validate;
     private _setup;
@@ -383,6 +392,13 @@ export declare class Agent {
      */
     private canAskForAccess;
     private _processEvent;
+    /**
+     * The checkout a wake needs, opened before the brain runs. Null when this
+     * wake needs none; `'refused'` when the task was failed here by name.
+     */
+    private _openCheckoutForWake;
+    /** Destroy the lane's box, if it still holds one, and say what it cost. */
+    private _closeCheckoutForWake;
     /**
      * Re-run one recorded wake against THIS agent, and nothing else.
      *

package/dist/Agent.js

@@ -33,7 +33,10 @@ import { marketplaceViewTool } from './platform/tools/tier2/marketplaceTools.js'
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
 import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, presentSendResult, } from '@ziggs-ai/api-client';
-import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
+import { isCheckoutNeed, normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
+import { openCheckout, closeCheckout } from './checkout/open.js';
+import { resolveBackendUrl } from './shared/backendUrl.js';
+import { laneUnderAgreement } from '@ziggs-ai/api-client';
 import { TaskService } from './platform/tasks/TaskService.js';
 import { AgreementService } from './platform/agreements/AgreementService.js';
 import { INBOX_STOP_TIMEOUT_MS, runInboxLoop } from './platform/inboxLoop.js';
@@ -69,6 +72,11 @@ export function laneSessionIdForTask(task) {
     }
     return 'default';
 }
+/**
+ * A wake that holds a checkout installs, builds and tests a repository, which
+ * takes longer than a conversation turn. Its watchdog is at least this.
+ */
+const CHECKOUT_TICK_TIMEOUT_MS = Number(process.env.CLAUDE_SDK_CHECKOUT_TICK_TIMEOUT_MS ?? 40 * 60_000);
 function createToolManager(options) {
     const toolManager = new ToolManager();
     const userTools = options.tools || options.services?.tools || [];
@@ -217,6 +225,8 @@ export class Agent {
     outboundMessages = new SeenMessages();
     confirmedPlanVersions = new SeenMessages();
     grantProviderCache = null;
+    /** The checkout box each lane holds while its wake runs. */
+    checkoutByLane = new Map();
     constructor(options = {}) {
         const resolved = applyBrainToAgentOptions(options);
         this.options = {
@@ -238,6 +248,7 @@ export class Agent {
             // agents — the declaration existed and nothing carried it. Same for
             // `requestMatchTags` (always undefined at triage) and `telemetryIngest`.
             needs: resolved.needs,
+            checkout: resolved.checkout,
             taskTools: resolved.taskTools,
             states: resolved.states,
             initial: resolved.initial,
@@ -894,7 +905,7 @@ export class Agent {
         if (this.canAskForAccess() && !this.askedForAccessLanes.has(_laneKey)) {
             this.askedForAccessLanes.add(_laneKey);
             this.unmetTasksPendingAsk.set(_laneKey, mine.map((t) => String(t.taskId)));
-            runtimeLog.info(this.options.name || 'agent', `no access for ${unmet.map((n) => n.connection).join('/')} on ${_laneKey} — letting this wake run once so it can ask, then failing whatever it leaves`);
+            runtimeLog.info(this.options.name || 'agent', `no access for ${unmet.map((n) => ('connection' in n ? n.connection : 'checkout')).join('/')} on ${_laneKey} — letting this wake run once so it can ask, then failing whatever it leaves`);
             return false;
         }
         for (const task of mine) {
@@ -1057,6 +1068,13 @@ export class Agent {
             frame = runnable.length === 1 ? runnable[0] : { type: 'batch', events: runnable };
         const memory = this.memoryForWake(session, frame);
         const wakeTaskId = workScopeFromWake(frame, session.sessionId).taskId;
+        // A checkout agent gets its box before the brain runs: the task names the
+        // repository, the hire's GitHub grant backs the clone, and a task that
+        // names nothing or holds no grant is refused here by name, like the needs
+        // gate above.
+        const checkout = await this._openCheckoutForWake(laneKey, session.sessionId, frame, wakeTaskId);
+        if (checkout === 'refused')
+            return;
         // Recorded here rather than after the tick: this is the last point where the
         // input is still exactly what the brain will see, and a wake that goes on to
         // throw is the one most worth replaying.
@@ -1182,19 +1200,24 @@ export class Agent {
         };
         try {
             await checkpoint();
-            tickWork = this.wakeEffects.run(marks, () => this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal }));
+            tickWork = this.wakeEffects.run(marks, () => this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal, ...(checkout ? { checkout: checkout.session } : {}) }));
             const result = await Promise.race([
                 tickWork,
                 new Promise((_, reject) => {
                     tickWatchdog = setTimeout(() => {
                         tickAbort.abort(new Error('tick timeout'));
                         reject(new Error('tick timeout'));
-                    }, this.tickTimeoutMs);
+                    }, checkout ? Math.max(this.tickTimeoutMs, CHECKOUT_TICK_TIMEOUT_MS) : this.tickTimeoutMs);
                 }),
             ]);
             session.ctx = result.ctx;
             session.state = result.state;
             this.sessions.set(laneKey, session);
+            // The box dies with the wake, and what it cost rides the same cost line
+            // as the wake's tokens.
+            const boxCost = await this._closeCheckoutForWake(laneKey);
+            if (boxCost && result.metrics)
+                result.metrics = { ...result.metrics, box: boxCost };
             this.recordWakeOutcome(session, classifyWakeOutcome({
                 skippedReason: result.skippedReason,
                 llmCalls: result.metrics?.llmCalls ?? 0,
@@ -1328,6 +1351,53 @@ export class Agent {
             // work it was refused for sitting active.
             if (!heldTask)
                 await this.settleUnmetAfterAsk(laneKey).catch(() => { });
+            // A tick that threw still must not leave its box running.
+            await this._closeCheckoutForWake(laneKey).catch(() => { });
+        }
+    }
+    /**
+     * The checkout a wake needs, opened before the brain runs. Null when this
+     * wake needs none; `'refused'` when the task was failed here by name.
+     */
+    async _openCheckoutForWake(laneKey, sessionId, frame, taskId) {
+        const needs = normalizeNeeds(this.options.needs);
+        if (!needs.some(isCheckoutNeed) || !taskId)
+            return null;
+        const operatorKey = this.options.operatorKey;
+        const agentId = this.options.agentId;
+        if (!operatorKey || !agentId || !this.taskService)
+            return null;
+        const laneId = laneUnderAgreement(sessionId, workScopeFromWake(frame, sessionId).agreementId);
+        const open = await openCheckout({
+            provider: this.options.checkout,
+            needs,
+            taskId,
+            getTask: (id) => this.taskService.getTask(id),
+            listConnections: () => new ConnectionsClient(operatorKey, agentId, undefined, laneId).listForHolder(),
+            door: { backendUrl: resolveBackendUrl(), operatorKey, agentId, laneId },
+            failTask: async (id, reason) => {
+                await this.taskService.updateState(id, 'failed', { summary: reason, status: 'failed' });
+            },
+            log: (message) => runtimeLog.info(this.options.name || 'agent', message),
+        });
+        if (open && open !== 'refused')
+            this.checkoutByLane.set(laneKey, open);
+        return open;
+    }
+    /** Destroy the lane's box, if it still holds one, and say what it cost. */
+    async _closeCheckoutForWake(laneKey) {
+        const open = this.checkoutByLane.get(laneKey);
+        if (!open)
+            return null;
+        this.checkoutByLane.delete(laneKey);
+        try {
+            const cost = await closeCheckout(open);
+            runtimeLog.info(this.options.name || 'agent', `checkout closed: ${cost.kind} box held ${cost.seconds}s`);
+            return cost;
+        }
+        catch (err) {
+            runtimeLog.warn(this.options.name || 'agent', `could not save/close the checkout box: ${err?.message ?? err}`);
+            throw err;
         }
     }
     /**

package/dist/brain/ClaudeBrain.d.ts

@@ -84,6 +84,12 @@ export declare function isMissingSessionError(err: unknown): boolean;
  * the loop: instead of the FSM + `runTurn`, a wake drives a headless Claude
  * `query()` (see "host is the product; the brain is how it decides").
  */
+/**
+ * The agreement every delivery in this wake is under, or undefined when none
+ * names one or they disagree. A batch across agreements names nothing, and the
+ * backend holds that wake to its room.
+ */
+export declare function wakeAgreementOf(event: RawEvent | undefined): string | undefined;
 export declare class ClaudeBrain implements Brain {
     readonly kind: "claude";
     workflow: Workflow;
@@ -110,5 +116,5 @@ export declare class ClaudeBrain implements Brain {
     private toolContextByLane;
     private sdkMcpByLane;
     constructor(opts: ClaudeBrainOptions);
-    tick({ event, ctx, state, identity, eff, memory, signal }: TickInput): Promise<TickOutput>;
+    tick({ event, ctx, state, identity, eff, memory, signal, checkout }: TickInput): Promise<TickOutput>;
 }

package/dist/brain/ClaudeBrain.js

@@ -177,6 +177,23 @@ function extractMetrics(message) {
  * the loop: instead of the FSM + `runTurn`, a wake drives a headless Claude
  * `query()` (see "host is the product; the brain is how it decides").
  */
+/**
+ * The agreement every delivery in this wake is under, or undefined when none
+ * names one or they disagree. A batch across agreements names nothing, and the
+ * backend holds that wake to its room.
+ */
+export function wakeAgreementOf(event) {
+    if (!event)
+        return undefined;
+    const items = Array.isArray(event.events) && event.events.length > 0 ? event.events : [event];
+    const ids = new Set(items.map((item) => {
+        const id = item.resource?.agreementId;
+        return typeof id === 'string' && id ? id : null;
+    }));
+    if (ids.size !== 1)
+        return undefined;
+    return [...ids][0] ?? undefined;
+}
 export class ClaudeBrain {
     kind = 'claude';
     workflow;
@@ -230,7 +247,7 @@ export class ClaudeBrain {
         this.actsOnHireActivation = opts.actsOnHireActivation === true;
         this.askWakeGate = opts.askWakeGate ?? null;
     }
-    async tick({ event, ctx, state, identity, eff, memory, signal }) {
+    async tick({ event, ctx, state, identity, eff, memory, signal, checkout }) {
         if (!identity?.sessionId)
             throw new Error('ClaudeBrain.tick: identity.sessionId is required');
         if (!eff)
@@ -397,6 +414,9 @@ export class ClaudeBrain {
             eff,
             senderId: rawEvent?.senderId != null ? String(rawEvent.senderId) : undefined,
             senderType: rawEvent?.senderType != null ? String(rawEvent.senderType) : undefined,
+            // The agreement the delivery itself is under, so the backend scopes this
+            // wake to it. Read off the delivery, never a lane's remembered agreement.
+            wakeAgreementId: wakeAgreementOf(rawEvent),
             ///832: agreement this wake acts under → lets a delegated per-user
             // MCP call resolve the originating end-user (payer) rather than the
             // delegating agent (senderId). Resolved from every reliable wire source,
@@ -412,6 +432,9 @@ export class ClaudeBrain {
             // Hire-partitioned store. The host already scoped this wake;
             // Claude tools that persist notes must use this, not a process-wide bag.
             memory,
+            // The wake's checkout, when the host opened one: the checkout_* tools
+            // read it here and refuse on a wake that has none.
+            ...(checkout ? { checkout } : {}),
         };
         const lane = identity.laneKey;
         this.toolContextByLane.set(lane, toolContext);

package/dist/brain/ZiggsBrain.d.ts

@@ -27,6 +27,8 @@ export interface TickInput {
      * the agent's choice — `counterparty:<id>`, `agreement:<id>:notes`, etc.
      */
     memory?: MemoryStore;
+    /** The checkout the host opened for this wake, when the agent declares the need and the task names a repository. */
+    checkout?: import('../checkout/tools.js').CheckoutSession;
     /** Optional tap for FSM transition events. */
     transitionTap?: (event: TransitionEvent) => void;
     /**
@@ -63,6 +65,13 @@ export interface TickOutput {
             cacheRead?: number;
             cacheCreation?: number;
         };
+        /** The checkout box this wake held, when it held one: what kind, for how long, how big. */
+        box?: {
+            kind: string;
+            seconds: number;
+            vcpu?: number;
+            memoryMb?: number;
+        };
     };
     /** Tick skipped the model; host records a no-op naming why. */
     skippedReason?: string;

package/dist/brain/toolManagerToSdkMcp.js

@@ -132,6 +132,7 @@ alwaysLoad = () => true) {
                         onBehalfOfAgreementId: ctx.onBehalfOfAgreementId,
                         runId: ctx.runId,
                         writeKeys: ctx.writeKeys,
+                        ...(ctx.checkout ? { checkout: ctx.checkout } : {}),
                     });
                     if (r.ok)
                         return toCallToolResult(r.result);

package/dist/checkout/box/server.d.ts

@@ -0,0 +1 @@
+export {};