@ziggs-ai/agent-sdk 0.38.16 → 0.39.0

package/dist/checkout/tools.d.ts

@@ -0,0 +1,24 @@
+import { type ToolDefinition } from '../tools/defineTool.js';
+import type { CheckoutBoxClient } from './boxClient.js';
+import type { CheckoutTarget } from './types.js';
+/**
+ * What one wake holds once its checkout is open: the box, the repository it
+ * cloned, the branch its change lands on. Put on the tool context by the host
+ * for the wake, taken off it when the box is destroyed.
+ */
+export interface CheckoutSession {
+    client: CheckoutBoxClient;
+    target: CheckoutTarget;
+    /** The base branch actually checked out (the task's, or the default branch). */
+    baseBranch: string;
+    /** `agent/<task id>`: the only branch the way out pushes to. */
+    branch: string;
+    taskId: string;
+    /** The box's kind, for the pull request body and the cost line. */
+    boxKind: string;
+}
+export declare const checkoutReadTool: ToolDefinition;
+export declare const checkoutWriteTool: ToolDefinition;
+export declare const checkoutRunTool: ToolDefinition;
+export declare const checkoutPushTool: ToolDefinition;
+export declare const CHECKOUT_TOOLS: ToolDefinition[];

package/dist/checkout/tools.js

@@ -0,0 +1,65 @@
+import { defineTool } from '../tools/defineTool.js';
+function sessionOf(ctx, tool) {
+    const session = ctx['checkout'];
+    if (!session?.client) {
+        throw new Error(`${tool}: no checkout is open on this wake. A checkout opens when a task assigned to you names a repository (owner/name); this wake carries none.`);
+    }
+    return session;
+}
+const CHECKOUT_LOCATION = 'Paths are relative to the root of the checkout, which is the repository the task named, cloned at its base branch.';
+export const checkoutReadTool = defineTool('checkout_read', {
+    path: { type: 'string', required: true, description: 'File to read, relative to the checkout root.' },
+}, async (args, ctx) => {
+    const s = sessionOf(ctx, 'checkout_read');
+    return s.client.read(String(args.path));
+}, { description: `Read one file from the checkout. ${CHECKOUT_LOCATION} Large files come back truncated with truncated=true; read a narrower file or use checkout_run with sed to read a range.` });
+export const checkoutWriteTool = defineTool('checkout_write', {
+    path: { type: 'string', required: true, description: 'File to write, relative to the checkout root. Folders are created as needed.' },
+    content: { type: 'string', required: true, description: 'The complete new content of the file.' },
+}, async (args, ctx) => {
+    const s = sessionOf(ctx, 'checkout_write');
+    return s.client.write(String(args.path), String(args.content));
+}, { description: `Write one whole file in the checkout, creating or replacing it. ${CHECKOUT_LOCATION} Write complete files, never placeholders.` });
+export const checkoutRunTool = defineTool('checkout_run', {
+    command: { type: 'string', required: true, description: 'A shell command, run from the checkout root inside the box (e.g. "npm ci", "npm test", "grep -rn Foo src", "git status").' },
+    timeoutSeconds: { type: 'number', description: 'Give up after this many seconds (default 600, max 1800).' },
+}, async (args, ctx) => {
+    const s = sessionOf(ctx, 'checkout_run');
+    return s.client.run(String(args.command), args.timeoutSeconds != null ? Number(args.timeoutSeconds) : undefined);
+}, { description: `Run a shell command in the checkout and get its exit code, stdout and stderr (tails, capped). Use it to search the code, install dependencies, and run the build or tests the repository defines before you push. ${CHECKOUT_LOCATION} The box has no credentials and no network into Ziggs; package registries are reachable.` });
+export const checkoutPushTool = defineTool('checkout_push', {
+    message: { type: 'string', required: true, description: 'One-line commit message saying what changed.' },
+}, async (args, ctx) => {
+    const s = sessionOf(ctx, 'checkout_push');
+    const result = await s.client.push(String(args.message));
+    const agreementId = ctx['serviceAgreementId'] ??
+        ctx['wakeAgreementId'] ??
+        ctx['onBehalfOfAgreementId'] ??
+        null;
+    const ran = result.ran.length
+        ? result.ran.map((r) => `\`${r.command}\` (exit ${r.exitCode ?? 'killed'})`).join(', ')
+        : 'nothing';
+    return {
+        ...result,
+        baseBranch: s.baseBranch,
+        repository: s.target.repository,
+        pullRequest: {
+            head: result.branch,
+            base: s.baseBranch,
+            draft: true,
+            /** Paste these lines into the pull request body, verbatim. */
+            bodyLines: [
+                `Opened by a Ziggs agent${agreementId ? ` under hire ${agreementId}` : ''}, task ${s.taskId}.`,
+                `Ran in the checkout (${s.boxKind} box): ${ran}.`,
+            ],
+        },
+    };
+}, {
+    description: 'Commit every change in the checkout as one commit and push it to the task\'s branch agent/<task id>. Never the base branch. Returns the branch, the commit, the files changed, what was run, and the lines to put in the pull request body. Call it once, after the build or tests you ran pass or you have decided to say they did not; then open the draft pull request with your GitHub tool.',
+});
+export const CHECKOUT_TOOLS = [
+    checkoutReadTool,
+    checkoutWriteTool,
+    checkoutRunTool,
+    checkoutPushTool,
+];

package/dist/checkout/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The checkout need, host side.
+ *
+ * An agent declares `{ checkout: 'git' }`; whoever hosts it provides a box. A
+ * box is a throwaway isolated unit (its own container) that holds a clone of
+ * the task's repository and nothing of the host's: no host environment, no
+ * credentials, no network into the host's services. The host talks to it over
+ * one narrow channel (read a file, write a file, run a command, push the
+ * branch) and the box's git traffic comes back over that same channel, so the
+ * box never holds a credential at all.
+ */
+/** Where the host finds a box it started. */
+export interface CheckoutBoxEndpoint {
+    /** Base URL of the box's channel, e.g. `http://10.0.11.4:7777`. */
+    url: string;
+    /** Per-box bearer the host minted and passed into the box at start. */
+    secret: string;
+}
+export interface CheckoutBoxSpec {
+    /** Per-box channel secret, minted by the SDK; the provider passes it in as `BOX_SECRET`. */
+    secret: string;
+    /** Hard time cap for the box, in seconds; the box exits when it is reached. */
+    ttlSeconds: number;
+    /** For logs and task tags; never a credential. */
+    label: {
+        agentId: string;
+        taskId: string;
+        repository: string;
+    };
+}
+export interface CheckoutBox {
+    endpoint: CheckoutBoxEndpoint;
+    /** What kind of unit this is, for the cost line (`fargate`, `sandbox`, ...). */
+    kind: string;
+    /** The box's size, when the provider knows it, for the cost line. */
+    resources?: {
+        vcpu?: number;
+        memoryMb?: number;
+    };
+    /** Destroy the box. Idempotent; never throws. */
+    stop(): Promise<void>;
+}
+/**
+ * Whoever hosts the agent implements this: the fleet starts a Fargate task,
+ * a lab starts a confined local process, a person's own runner could hand out
+ * a container of its own. The SDK never knows which.
+ */
+/** Host-owned private storage, keyed by agent, hire lane, task, repository and base. */
+export interface CheckoutCheckpointStore {
+    load(key: string): Promise<Uint8Array | null>;
+    save(key: string, data: Uint8Array): Promise<void>;
+}
+export interface CheckoutProvider {
+    /** Optional. Without storage, later wakes resume only the pushed task branch. */
+    checkpoints?: CheckoutCheckpointStore;
+    start(spec: CheckoutBoxSpec): Promise<CheckoutBox>;
+}
+/** What a task has to name for a checkout to exist. */
+export interface CheckoutTarget {
+    /** `owner/name` on GitHub. */
+    repository: string;
+    owner: string;
+    name: string;
+    /** Named by the task, or null to use the repository's default branch. */
+    baseBranch: string | null;
+}
+/** How a command ran in the box. */
+export interface CheckoutRunResult {
+    checkpointWarning?: string;
+    command: string;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+export interface CheckoutPushResult {
+    checkpointWarning?: string;
+    branch: string;
+    commit: string | null;
+    filesChanged: string[];
+    pushed: boolean;
+    /** Every command the brain ran in this box, with its exit code, for the pull request body. */
+    ran: Array<{
+        command: string;
+        exitCode: number | null;
+    }>;
+}

package/dist/checkout/types.js

@@ -0,0 +1,12 @@
+/**
+ * The checkout need, host side.
+ *
+ * An agent declares `{ checkout: 'git' }`; whoever hosts it provides a box. A
+ * box is a throwaway isolated unit (its own container) that holds a clone of
+ * the task's repository and nothing of the host's: no host environment, no
+ * credentials, no network into the host's services. The host talks to it over
+ * one narrow channel (read a file, write a file, run a command, push the
+ * branch) and the box's git traffic comes back over that same channel, so the
+ * box never holds a credential at all.
+ */
+export {};

package/dist/index.d.ts

@@ -60,7 +60,9 @@ export { recordReport } from './tools/recordReport.js';
 export { credsFromToolContext, laneFromToolContext } from './tools/toolCreds.js';
 export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
 export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
-export type { AgentNeed, ConnectionNeed } from './tools/needs.js';
+export type { AgentNeed, ConnectionNeed, CheckoutNeed } from './tools/needs.js';
+export { isCheckoutNeed } from './tools/needs.js';
+export { CHECKOUT_TOOLS, checkoutReadTool, checkoutWriteTool, checkoutRunTool, checkoutPushTool, CheckoutBoxClient, CheckoutBoxError, checkoutTargetFromText, checkoutTargetFromTask, checkoutBranchForTask, checkoutBoxServerPath, openCheckout, closeCheckout, doorPathFor, doorHeaders, type CheckoutProvider, type CheckoutCheckpointStore, type CheckoutBox, type CheckoutBoxSpec, type CheckoutBoxEndpoint, type CheckoutTarget, type CheckoutSession, type CheckoutRunResult, type CheckoutPushResult, type GitDoorTarget, type OpenCheckout, type OpenCheckoutDeps, } from './checkout/index.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';

package/dist/index.js

@@ -61,6 +61,8 @@ export { credsFromToolContext, laneFromToolContext } from './tools/toolCreds.js'
 // An agent declares the access it cannot work without, and the declaration
 // produces the tools for it.
 export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
+export { isCheckoutNeed } from './tools/needs.js';
+export { CHECKOUT_TOOLS, checkoutReadTool, checkoutWriteTool, checkoutRunTool, checkoutPushTool, CheckoutBoxClient, CheckoutBoxError, checkoutTargetFromText, checkoutTargetFromTask, checkoutBranchForTask, checkoutBoxServerPath, openCheckout, closeCheckout, doorPathFor, doorHeaders, } from './checkout/index.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';

package/dist/platform/ZiggsEffectHandler.js

@@ -169,6 +169,8 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             serviceAgreementId: effect.serviceAgreementId,
             memory: effect.memory,
             writeKeys: effect.writeKeys,
+            // The wake's checkout, when the host opened one.
+            ...(effect.checkout ? { checkout: effect.checkout } : {}),
             // `wake_at` reads this off the tool context.
             wakeScheduler: deps.wakeScheduler,
             reportUsage,

package/dist/tools/needs.d.ts

@@ -17,16 +17,23 @@ import { type ToolDefinition } from './defineTool.js';
  * "Unknown provider: mcp" — the second wall linear-janitor hit.
  */
 export declare const MCP_PROVIDER = "mcp";
-/**
- * One shape for now, the one we have actually hit. A second kind means a case in
- * {@link toolsForNeed}: a need nothing derives tools from is a need nothing
- * enforces.
- */
 export interface ConnectionNeed {
     /** Provider, e.g. 'mcp' or a named connector like 'github'. */
     connection: string;
 }
-export type AgentNeed = ConnectionNeed;
+/**
+ * A checkout of a git repository, provided by whoever hosts the agent. The
+ * task names the repository (owner/name) and a base branch; the host clones it
+ * into a throwaway box under the hire's GitHub connection grant, the brain works
+ * in that box with file and shell tools, and the way out is a branch
+ * `agent/<task id>` for a pull request. Without the GitHub grant the task is
+ * refused by name, like a connection need.
+ */
+export interface CheckoutNeed {
+    checkout: 'git';
+}
+export type AgentNeed = ConnectionNeed | CheckoutNeed;
+export declare function isCheckoutNeed(need: AgentNeed): need is CheckoutNeed;
 /** Reads a manifest's `needs` field defensively — it crosses a package edge. */
 export declare function normalizeNeeds(input: unknown): AgentNeed[];
 /**

package/dist/tools/needs.js

@@ -13,12 +13,18 @@
 import { toolName } from './defineTool.js';
 import { connectionListGrantsTool, connectionProxyTool } from '../platform/tools/tier2/connectionTools.js';
 import { MCP_CONNECTION_TOOLS } from '../platform/tools/tier2/mcpConnectionTools.js';
+import { CHECKOUT_TOOLS } from '../checkout/tools.js';
 /**
  * A remote MCP server is stored as `provider: 'mcp'` and goes through the
  * gateway. `connection_proxy` resolves a NAMED connector and refuses it with
  * "Unknown provider: mcp" — the second wall linear-janitor hit.
  */
 export const MCP_PROVIDER = 'mcp';
+export function isCheckoutNeed(need) {
+    return need.checkout === 'git';
+}
+/** Providers whose connection grant can back a git checkout. */
+const CHECKOUT_PROVIDERS = new Set(['github', MCP_PROVIDER]);
 /** Reads a manifest's `needs` field defensively — it crosses a package edge. */
 export function normalizeNeeds(input) {
     if (!Array.isArray(input))
@@ -28,6 +34,11 @@ export function normalizeNeeds(input) {
         const connection = raw?.connection;
         if (typeof connection === 'string' && connection.trim()) {
             out.push({ connection: connection.trim() });
+            continue;
+        }
+        const checkout = raw?.checkout;
+        if (typeof checkout === 'string' && checkout.trim().toLowerCase() === 'git') {
+            out.push({ checkout: 'git' });
         }
     }
     return out;
@@ -38,6 +49,8 @@ export function normalizeNeeds(input) {
  * an agent that held a Linear grant and had no way to notice.
  */
 export function toolsForNeed(need) {
+    if (isCheckoutNeed(need))
+        return [connectionListGrantsTool, ...CHECKOUT_TOOLS];
     return need.connection === MCP_PROVIDER
         ? [connectionListGrantsTool, ...MCP_CONNECTION_TOOLS]
         : [connectionListGrantsTool, connectionProxyTool];
@@ -56,6 +69,8 @@ export function toolsForNeeds(needs) {
 }
 /** One line naming what is missing, for a refusal a human can act on. */
 export function describeNeed(need) {
+    if (isCheckoutNeed(need))
+        return 'a GitHub connection (for the checkout)';
     return need.connection === MCP_PROVIDER
         ? 'a connection to an MCP server'
         : `a ${need.connection} connection`;
@@ -71,7 +86,9 @@ export function unmetNeeds(needs, providers) {
     const held = new Set(providers
         .map((p) => String(p ?? '').split('—')[0].trim().toLowerCase())
         .filter(Boolean));
-    return needs.filter((n) => !held.has(n.connection.toLowerCase()));
+    return needs.filter((n) => isCheckoutNeed(n)
+        ? ![...CHECKOUT_PROVIDERS].some((p) => held.has(p))
+        : !held.has(n.connection.toLowerCase()));
 }
 /**
  * The refusal itself. Names the missing access and who can fix it, because the

package/dist/tools/toolCreds.d.ts

@@ -19,7 +19,7 @@
  * remember. Omitting the lane can only narrow reach, never widen it, which is
  * why forgetting it never fails loudly.
  */
-import type { Creds } from '@ziggs-ai/api-client';
+import { type Creds } from '@ziggs-ai/api-client';
 /** The loose bag `defineTool` hands a handler. */
 type ToolContext = Record<string, unknown> | undefined | null;
 /**
@@ -27,6 +27,10 @@ type ToolContext = Record<string, unknown> | undefined | null;
  * `agrn-<agreementId>` for an agreement lane. Undefined when the tool is
  * running outside any lane (a bootstrap sweep, a test), which the fence reads
  * as "own org only".
+ *
+ * A room wake that handles mail under an agreement (`wakeAgreementId`, taken
+ * from the delivery itself) names it too, so the backend scopes the wake to
+ * that agreement rather than inferring it from the room's mail.
  */
 export declare function laneFromToolContext(ctx: ToolContext): string | undefined;
 /**

package/dist/tools/toolCreds.js

@@ -19,6 +19,7 @@
  * remember. Omitting the lane can only narrow reach, never widen it, which is
  * why forgetting it never fails loudly.
  */
+import { laneUnderAgreement } from '@ziggs-ai/api-client';
 const str = (ctx, key) => {
     const value = ctx?.[key];
     return typeof value === 'string' && value.trim() ? value : undefined;
@@ -28,9 +29,14 @@ const str = (ctx, key) => {
  * `agrn-<agreementId>` for an agreement lane. Undefined when the tool is
  * running outside any lane (a bootstrap sweep, a test), which the fence reads
  * as "own org only".
+ *
+ * A room wake that handles mail under an agreement (`wakeAgreementId`, taken
+ * from the delivery itself) names it too, so the backend scopes the wake to
+ * that agreement rather than inferring it from the room's mail.
  */
 export function laneFromToolContext(ctx) {
-    return str(ctx, 'chatId') ?? str(ctx, 'sessionId');
+    const lane = str(ctx, 'chatId') ?? str(ctx, 'sessionId');
+    return lane ? laneUnderAgreement(lane, str(ctx, 'wakeAgreementId')) : undefined;
 }
 /**
  * The creds a tool should act under. Throws when the context is missing what a

package/dist/types.d.ts

@@ -504,6 +504,8 @@ export type Effect = {
     stateId?: string;
     /** Replay-stable write keys for this wake — write-capable tools derive their idempotency key from here, never from the LLM. */
     writeKeys?: DeliveryWriteKeys;
+    /** The checkout the host opened for this wake; the checkout_* tools read it off their context. */
+    checkout?: import('./checkout/tools.js').CheckoutSession;
 }
 /**
  * `receiverId` is optional: in a room with one other participant the backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.38.16",
+  "version": "0.39.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -30,7 +30,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.19",
+    "@ziggs-ai/api-client": "0.37.21",
     "@ziggs-ai/contracts": "^0.23.3",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",