@cargo-ai/cli 1.0.94 → 1.0.95

package/build/commands/ask/harness/instructions.d.ts

@@ -0,0 +1,13 @@
+import type { Ai } from "@cargo-ai/api";
+/**
+ * Always-on local-copy rails, plus CDK rails only when `dir` is a CDK project.
+ * Exported for tests.
+ */
+export declare function localHarnessInstructions(dir: string, release?: Ai.Release): string;
+/** Exported for tests. */
+export declare function localHarnessSkills(dir: string): Array<{
+    name: string;
+    description: string;
+    content: string;
+}>;
+//# sourceMappingURL=instructions.d.ts.map

package/build/commands/ask/harness/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,eAAe,CAAC;AAsBxC;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,GACnB,MAAM,CAkBR;AAED,0BAA0B;AAC1B,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GACV,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAM/D"}

package/build/commands/ask/harness/instructions.js

@@ -0,0 +1,41 @@
+import { cdkProjectRoot } from "@cargo-ai/cdk/cli";
+import { buildReleaseInstructionAppendix } from "./release.js";
+const LOCAL_WORKING_COPY_INSTRUCTIONS = `You are working in the user's local working copy, not a sandbox. Prefer plan over deploy.
+
+The user confirms each Bash, Write, Edit and NotebookEdit call, and can only answer one at a time. Ask for a single one of those per step and wait for its result before asking for the next; two in one step leaves the second waiting on a confirmation it will never be offered. Reads (Read, Glob, Grep) and the Cargo \`mcp__cargo__*\` tools need no confirmation — batch those freely.
+
+Prefer minimal, focused diffs; match the existing code style; run the project's own checks when they exist. End each task with a short summary of what changed and how it was validated.`;
+const CDK_RAILS_INSTRUCTIONS = `This directory is a Cargo CDK project.
+- Never edit cargo.state.json, cargo.state.lock, or .cargo-ai/ by hand — they are generated. Repoint this project's deploy state with \`cargo-cdk state bind\`.
+- Validate your changes before declaring them done: run \`npx tsc --noEmit\` and \`npx cargo-cdk plan\` (plan only reads — it changes nothing).
+- Never run \`cargo-cdk deploy\`, \`destroy\`, \`import\`, or \`rollback\` unless the user explicitly asked.`;
+const LOCAL_CDK_RAILS_SKILL = {
+    name: "cdk-rails",
+    description: "Rails for working on a Cargo CDK project on this machine.",
+    content: CDK_RAILS_INSTRUCTIONS,
+};
+/**
+ * Always-on local-copy rails, plus CDK rails only when `dir` is a CDK project.
+ * Exported for tests.
+ */
+export function localHarnessInstructions(dir, release) {
+    const rails = cdkProjectRoot(dir) !== undefined
+        ? `${LOCAL_WORKING_COPY_INSTRUCTIONS}\n\n${CDK_RAILS_INSTRUCTIONS}`
+        : LOCAL_WORKING_COPY_INSTRUCTIONS;
+    if (release === undefined) {
+        return rails;
+    }
+    const parts = [release.systemPrompt, rails];
+    const appendix = buildReleaseInstructionAppendix(release);
+    if (appendix !== undefined) {
+        parts.push(appendix);
+    }
+    return parts.join("\n\n");
+}
+/** Exported for tests. */
+export function localHarnessSkills(dir) {
+    if (cdkProjectRoot(dir) !== undefined) {
+        return [LOCAL_CDK_RAILS_SKILL];
+    }
+    return [];
+}

package/build/commands/ask/harness/layout.d.ts

@@ -0,0 +1,23 @@
+export type WorkspaceLayout = {
+    sandboxCwd: string;
+    /** `undefined` leaves the harness its per-session default. */
+    workDir: string | undefined;
+};
+/**
+ * Where to root the sandbox, and which directory inside it the session works in.
+ *
+ * The harness gives every session a work directory under the sandbox root and
+ * starts Claude Code there — `cwd: workdir` in the bridge — and it refuses to
+ * use the root itself. Rooted at the project, that means the agent begins in an
+ * empty `claude-code-<sessionId>` directory one level below the working copy it
+ * was asked about. Rooting at the project's parent instead makes the session
+ * work directory *be* the project, so the agent starts where the user is, and
+ * the harness's own artifacts land beside the project rather than in it.
+ *
+ * Falls back to the project when the parent cannot serve — a project at a
+ * filesystem root has no usable name, and a parent we cannot write to would
+ * fail the session at startup. The per-session directory returns in that case,
+ * and `pruneHarnessArtifacts` sweeps it once it is cold.
+ */
+export declare function resolveWorkspaceLayout(dir: string): WorkspaceLayout;
+//# sourceMappingURL=layout.d.ts.map

package/build/commands/ask/harness/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/layout.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAenE"}

package/build/commands/ask/harness/layout.js

@@ -0,0 +1,32 @@
+import { accessSync, constants } from "node:fs";
+import { basename, dirname } from "node:path";
+/**
+ * Where to root the sandbox, and which directory inside it the session works in.
+ *
+ * The harness gives every session a work directory under the sandbox root and
+ * starts Claude Code there — `cwd: workdir` in the bridge — and it refuses to
+ * use the root itself. Rooted at the project, that means the agent begins in an
+ * empty `claude-code-<sessionId>` directory one level below the working copy it
+ * was asked about. Rooting at the project's parent instead makes the session
+ * work directory *be* the project, so the agent starts where the user is, and
+ * the harness's own artifacts land beside the project rather than in it.
+ *
+ * Falls back to the project when the parent cannot serve — a project at a
+ * filesystem root has no usable name, and a parent we cannot write to would
+ * fail the session at startup. The per-session directory returns in that case,
+ * and `pruneHarnessArtifacts` sweeps it once it is cold.
+ */
+export function resolveWorkspaceLayout(dir) {
+    const parent = dirname(dir);
+    const name = basename(dir);
+    if (parent === dir || name.length === 0) {
+        return { sandboxCwd: dir, workDir: undefined };
+    }
+    try {
+        accessSync(parent, constants.W_OK);
+    }
+    catch {
+        return { sandboxCwd: dir, workDir: undefined };
+    }
+    return { sandboxCwd: parent, workDir: name };
+}

package/build/commands/ask/harness/mcp.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What Claude Code mounts this server as, and so the `mcp__<server>__` prefix
+ * its tools carry. Read by `isAutoApproved`, which trusts this server and no
+ * other — see the note there.
+ *
+ * Exported for tests.
+ */
+export declare const CARGO_MCP_SERVER_NAME = "cargo";
+/**
+ * The workspace half of local Ask: the hosted Cargo MCP server, reached
+ * through this CLI's own `mcp` bridge.
+ *
+ * Going through the bridge rather than configuring the HTTP endpoint directly
+ * is what keeps a long chat working — the bridge rebuilds the `Authorization`
+ * header per request from the same credentials every other command uses, so an
+ * OAuth session that expires mid-session renews instead of 401ing. `CARGO_BASE_URL`
+ * is pinned so the bridge cannot end up on a different API than this session.
+ *
+ * Everything the workspace can do arrives this way: actions, runs, models and
+ * SQL, the context, usage. That includes `execute_action`, which spends credits
+ * and writes to connected systems — see the approval note on
+ * `isAutoApproved`.
+ */
+export declare function cargoMcpServer(apiBaseUrl: string): Record<string, unknown>;
+//# sourceMappingURL=mcp.d.ts.map

package/build/commands/ask/harness/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/mcp.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO1E"}

package/build/commands/ask/harness/mcp.js

@@ -0,0 +1,72 @@
+import { fileURLToPath } from "node:url";
+/**
+ * What Claude Code mounts this server as, and so the `mcp__<server>__` prefix
+ * its tools carry. Read by `isAutoApproved`, which trusts this server and no
+ * other — see the note there.
+ *
+ * Exported for tests.
+ */
+export const CARGO_MCP_SERVER_NAME = "cargo";
+/**
+ * The workspace half of local Ask: the hosted Cargo MCP server, reached
+ * through this CLI's own `mcp` bridge.
+ *
+ * Going through the bridge rather than configuring the HTTP endpoint directly
+ * is what keeps a long chat working — the bridge rebuilds the `Authorization`
+ * header per request from the same credentials every other command uses, so an
+ * OAuth session that expires mid-session renews instead of 401ing. `CARGO_BASE_URL`
+ * is pinned so the bridge cannot end up on a different API than this session.
+ *
+ * Everything the workspace can do arrives this way: actions, runs, models and
+ * SQL, the context, usage. That includes `execute_action`, which spends credits
+ * and writes to connected systems — see the approval note on
+ * `isAutoApproved`.
+ */
+export function cargoMcpServer(apiBaseUrl) {
+    return {
+        type: "stdio",
+        command: process.execPath,
+        args: [...loaderArgs(), cliEntryPath(), "mcp"],
+        env: { CARGO_BASE_URL: apiBaseUrl },
+    };
+}
+/**
+ * This CLI's own entry, so the bridge is the same code and version as the
+ * session that spawned it — not whatever `cargo-ai` happens to be on PATH.
+ */
+function cliEntryPath() {
+    const entry = process.argv[1];
+    return entry !== undefined && entry.length > 0
+        ? entry
+        : fileURLToPath(new URL("../../../index.js", import.meta.url));
+}
+/**
+ * Loader flags only. A dev run under `tsx` starts from a `.ts` entry that bare
+ * node cannot execute, so the child needs the same loader; the rest of
+ * `execArgv` (`--inspect` above all, which would fight over a port) must not
+ * be inherited.
+ */
+function loaderArgs() {
+    const flags = ["--import", "--loader", "--require"];
+    const args = [];
+    for (let index = 0; index < process.execArgv.length; index += 1) {
+        const arg = process.execArgv[index];
+        if (arg === undefined) {
+            continue;
+        }
+        // `--import=tsx` carries its value; `--import tsx` is two entries and the
+        // second one has to come along.
+        if (flags.some((flag) => arg.startsWith(`${flag}=`)) === true) {
+            args.push(arg);
+            continue;
+        }
+        if (flags.includes(arg) === true) {
+            const value = process.execArgv[index + 1];
+            if (value !== undefined) {
+                args.push(arg, value);
+                index += 1;
+            }
+        }
+    }
+    return args;
+}

package/build/commands/ask/harness/pnpmShim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pnpmShim.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/pnpmShim.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,8EAA8E;AAC9E,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAchD;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,IAAI,MAAM,CAI9C"}

package/build/commands/ask/harness/release.d.ts

@@ -0,0 +1,18 @@
+import type { Ai, Orchestration } from "@cargo-ai/api";
+import type { Api } from "../../../api.js";
+/** Mount prefix so agent MCP tools can be auto-approved without widening user MCP. */
+export declare const CARGO_AGENT_MCP_NAME_PREFIX = "cargoagent_";
+type HostTool = {
+    description?: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: true;
+    };
+    execute: (data: unknown) => Promise<unknown>;
+};
+export declare function buildReleaseInstructionAppendix(release: Ai.Release): string | undefined;
+export declare function buildReleaseMcpServers(mcpClients: Ai.McpClient[]): Record<string, unknown>;
+export declare function buildReleaseHostTools(api: Api, actions: Ai.Action[]): Record<string, HostTool>;
+export declare function toExecuteAction(action: Ai.Action): Orchestration.Api.ExecuteActionPayload["action"];
+export {};
+//# sourceMappingURL=release.d.ts.map

package/build/commands/ask/harness/release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/release.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE3C,sFAAsF;AACtF,eAAO,MAAM,2BAA2B,gBAAgB,CAAC;AAEzD,KAAK,QAAQ,GAAG;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,oBAAoB,EAAE,IAAI,CAAC;KAC5B,CAAC;IACF,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,EAAE,CAAC,OAAO,GAClB,MAAM,GAAG,SAAS,CAwCpB;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,EAAE,CAAC,SAAS,EAAE,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,GACnB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CA4B1B;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,EAAE,CAAC,MAAM,GAChB,aAAa,CAAC,GAAG,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAgClD"}

package/build/commands/ask/harness/release.js

@@ -0,0 +1,117 @@
+/** Mount prefix so agent MCP tools can be auto-approved without widening user MCP. */
+export const CARGO_AGENT_MCP_NAME_PREFIX = "cargoagent_";
+export function buildReleaseInstructionAppendix(release) {
+    const parts = [];
+    const resourceLines = release.resources.map((resource) => {
+        const title = resource.name !== undefined ? resource.name : resource.slug;
+        if (resource.description === undefined) {
+            return `- ${title} (${resource.kind})`;
+        }
+        return `- ${title} (${resource.kind}): ${resource.description}`;
+    });
+    if (resourceLines.length > 0) {
+        parts.push(["Workspace resources for this agent:", ...resourceLines].join("\n"));
+    }
+    const capabilityLines = release.capabilities
+        .filter((capability) => capability.slug !== "sandbox" && capability.slug !== "suggestedActions")
+        .map((capability) => `- ${capability.slug}`);
+    if (capabilityLines.length > 0) {
+        parts.push([
+            "This agent also has these Cargo capabilities; use the Cargo MCP tools for workspace data they cover:",
+            ...capabilityLines,
+        ].join("\n"));
+    }
+    if (parts.length === 0) {
+        return undefined;
+    }
+    return parts.join("\n\n");
+}
+export function buildReleaseMcpServers(mcpClients) {
+    const servers = {};
+    for (const client of mcpClients) {
+        if (client.kind !== "custom") {
+            continue;
+        }
+        const name = mcpServerName(client.name);
+        const headers = customMcpHeaders(client.authentication);
+        servers[name] =
+            headers === undefined
+                ? { type: "http", url: client.url }
+                : { type: "http", url: client.url, headers };
+    }
+    return servers;
+}
+export function buildReleaseHostTools(api, actions) {
+    const tools = {};
+    for (const action of actions) {
+        tools[action.slug] = {
+            description: action.description,
+            inputSchema: {
+                type: "object",
+                additionalProperties: true,
+            },
+            execute: async (data) => {
+                try {
+                    return await api.orchestration.action.execute({
+                        action: toExecuteAction(action),
+                        data,
+                        waitUntilFinished: true,
+                    });
+                }
+                catch (error) {
+                    return {
+                        error: error instanceof Error ? error.message : "Action failed to run",
+                    };
+                }
+            },
+        };
+    }
+    return tools;
+}
+export function toExecuteAction(action) {
+    if (action.kind === "tool") {
+        return {
+            kind: "tool",
+            toolUuid: action.toolUuid,
+            templateSlug: action.templateSlug,
+            waitUntilFinished: action.waitUntilFinished,
+        };
+    }
+    if (action.kind === "agent") {
+        return {
+            kind: "agent",
+            agentUuid: action.agentUuid,
+            templateSlug: action.templateSlug,
+            waitUntilFinished: action.waitUntilFinished,
+        };
+    }
+    if (action.kind === "connector") {
+        return {
+            kind: "connector",
+            integrationSlug: action.integrationSlug,
+            connectorUuid: action.connectorUuid,
+            actionSlug: action.actionSlug,
+        };
+    }
+    return {
+        kind: "native",
+        actionSlug: action.actionSlug,
+    };
+}
+function mcpServerName(name) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+    const trimmed = slug.replace(/^_+|_+$/g, "");
+    const body = trimmed.length > 0 ? trimmed : "mcp";
+    return `${CARGO_AGENT_MCP_NAME_PREFIX}${body}`;
+}
+function customMcpHeaders(authentication) {
+    if (authentication === undefined) {
+        return undefined;
+    }
+    const tokenType = authentication.tokenType !== undefined
+        ? authentication.tokenType
+        : "Bearer";
+    return {
+        Authorization: `${tokenType} ${authentication.accessToken}`,
+    };
+}

package/build/commands/ask/harness/sandbox.d.ts

@@ -0,0 +1,9 @@
+import type { HarnessV1SandboxProvider } from "@ai-sdk/harness";
+/**
+ * `ai-sdk-sandbox-local@0.1.2` still ships deprecated `getPortUrl` only.
+ * Claude Code's harness treats a session without `getPortEndpoint` as a basic
+ * sandbox and then demands an explicit port — wrap until the local provider
+ * catches up.
+ */
+export declare function withGetPortEndpoint(provider: HarnessV1SandboxProvider): HarnessV1SandboxProvider;
+//# sourceMappingURL=sandbox.d.ts.map

package/build/commands/ask/harness/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAShE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,wBAAwB,GACjC,wBAAwB,CAc1B"}

package/build/commands/ask/harness/sandbox.js

@@ -0,0 +1,27 @@
+/**
+ * `ai-sdk-sandbox-local@0.1.2` still ships deprecated `getPortUrl` only.
+ * Claude Code's harness treats a session without `getPortEndpoint` as a basic
+ * sandbox and then demands an explicit port — wrap until the local provider
+ * catches up.
+ */
+export function withGetPortEndpoint(provider) {
+    const resumeSession = provider.resumeSession;
+    return {
+        specificationVersion: provider.specificationVersion,
+        providerId: provider.providerId,
+        createSession: async (options) => ensureGetPortEndpoint(await provider.createSession(options)),
+        resumeSession: resumeSession === undefined
+            ? undefined
+            : async (options) => ensureGetPortEndpoint(await resumeSession(options)),
+    };
+}
+function ensureGetPortEndpoint(session) {
+    if ("getPortEndpoint" in session) {
+        return session;
+    }
+    const getPortEndpoint = async (options) => ({
+        url: await session.getPortUrl(options),
+    });
+    Object.assign(session, { getPortEndpoint });
+    return session;
+}

package/build/commands/ask/harness/timing.d.ts

@@ -0,0 +1,16 @@
+import type { StreamLike } from "./turn.js";
+export declare const ASK_TIMING_ENABLED: boolean;
+export type PhaseLog = (phase: string) => void;
+export declare function createPhaseLog(label: string): PhaseLog;
+/**
+ * The harness prints its own diagnostics without a clock, which is what the
+ * gap needs. Reprint them relative to process start instead.
+ */
+export declare function reportHarnessDiagnostic(event: {
+    level: string;
+    subsystem?: string | undefined;
+    message: string;
+}): void;
+/** Marks when each part of a turn's stream arrives, and when it ends. */
+export declare function timeStreamParts(stream: StreamLike, phase: PhaseLog): StreamLike;
+//# sourceMappingURL=timing.d.ts.map

package/build/commands/ask/harness/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/timing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAgB5C,eAAO,MAAM,kBAAkB,SAC2B,CAAC;AAG3D,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/C,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAkBtD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAMP;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,QAAQ,GACd,UAAU,CAMZ"}

package/build/commands/ask/harness/timing.js

@@ -0,0 +1,72 @@
+/**
+ * A local turn spends far longer getting the prompt into Claude Code than it
+ * spends generating the answer, and none of that is visible from the tree or
+ * from Claude Code's own transcript. `CARGO_ASK_TIMING=1` writes the phase
+ * boundaries — and the harness's own diagnostics — to stderr. Unset, every
+ * call below is a no-op and nothing is added to the stream.
+ *
+ * `CARGO_ASK_TIMING=parts` adds the whole of each stream part next to its
+ * type. Verbose, and the only way to see what the bridge actually sends: the
+ * part names alone say a tool call arrived, not that its result came back
+ * empty or that the field a reader is looking for is spelled differently here
+ * than in the bridge that emitted it.
+ */
+const ASK_TIMING_LEVEL = process.env["CARGO_ASK_TIMING"];
+export const ASK_TIMING_ENABLED = ASK_TIMING_LEVEL === "1" || ASK_TIMING_LEVEL === "parts";
+const ASK_TIMING_DUMPS_PARTS = ASK_TIMING_LEVEL === "parts";
+export function createPhaseLog(label) {
+    if (ASK_TIMING_ENABLED === false) {
+        return () => undefined;
+    }
+    const start = Date.now();
+    let previous = start;
+    return (phase) => {
+        const now = Date.now();
+        const total = ((now - start) / 1000).toFixed(2).padStart(6);
+        const step = ((now - previous) / 1000).toFixed(2).padStart(5);
+        previous = now;
+        process.stderr.write(`[ask:timing] ${label} ${total}s (+${step}s) ${phase}\n`);
+    };
+}
+/**
+ * The harness prints its own diagnostics without a clock, which is what the
+ * gap needs. Reprint them relative to process start instead.
+ */
+export function reportHarnessDiagnostic(event) {
+    const elapsed = process.uptime().toFixed(2).padStart(6);
+    process.stderr.write(`[ask:timing] harness ${elapsed}s ${event.level} ${event.subsystem ?? "-"} ${event.message}\n`);
+}
+/** Marks when each part of a turn's stream arrives, and when it ends. */
+export function timeStreamParts(stream, phase) {
+    if (ASK_TIMING_ENABLED === false) {
+        return stream;
+    }
+    return { text: stream.text, fullStream: timeParts(stream.fullStream, phase) };
+}
+async function* timeParts(parts, phase) {
+    let seen = 0;
+    for await (const part of parts) {
+        seen += 1;
+        const type = typeof part === "object" && part !== null && "type" in part
+            ? String(part.type)
+            : "unknown";
+        // Text arrives one delta per token, which would bury everything else.
+        if (type.startsWith("text-delta") === false) {
+            phase(ASK_TIMING_DUMPS_PARTS === true
+                ? `part ${String(seen)}: ${type} ${dumpPart(part)}`
+                : `part ${String(seen)}: ${type}`);
+        }
+        yield part;
+    }
+    phase(`stream ended after ${String(seen)} parts`);
+}
+/** One stream part, flattened onto its log line. Truncated: some are huge. */
+function dumpPart(part) {
+    try {
+        const json = JSON.stringify(part, (_key, value) => value instanceof Error ? `Error(${value.message})` : value);
+        return json === undefined ? "" : json.slice(0, 900);
+    }
+    catch {
+        return "<unserializable>";
+    }
+}

package/build/commands/ask/harness/turn.d.ts

@@ -0,0 +1,145 @@
+import { type LocalTurnAccumulator } from "./usage.js";
+/**
+ * A built-in tool Claude Code wants to run that `permissionMode` does not
+ * auto-approve (anything that writes or shells out under `allow-reads`).
+ */
+export type LocalToolApproval = {
+    approvalId: string;
+    toolCallId: string;
+    toolName: string;
+    /** Compact one-line rendering of the tool input, for the prompt. */
+    summary: string;
+    input: unknown;
+};
+/** A tool starting or finishing, so the caller can show what is happening. */
+export type LocalToolActivity = {
+    kind: "start";
+    toolCallId: string;
+    toolName: string;
+    summary: string;
+} | {
+    kind: "end";
+    toolCallId: string;
+    toolName: string;
+    isError: boolean;
+}
+/**
+ * Announced, then never run — a tool whose input stopped mid-stream, one
+ * that was refused, or a sibling whose approval request the harness lost.
+ * None of them report a result, so `end` never comes: a caller tracking
+ * what is live has to be told, or it shows that tool for the rest of the
+ * turn. `retractAbandonedCalls` decides which calls qualify and when.
+ */
+ | {
+    kind: "dropped";
+    toolCallId: string;
+    toolName: string;
+};
+export type LocalStreamHandlers = {
+    onTextDelta?: (delta: string) => void;
+    /**
+     * Decide whether the tool may run. Omitted (`--print`, non-interactive)
+     * means deny — the turn continues and the model reports what it could not
+     * do rather than silently running commands on the user's machine.
+     */
+    onApproval?: (approval: LocalToolApproval) => Promise<boolean>;
+    onActivity?: (activity: LocalToolActivity) => void;
+    /** Path of a file the turn wrote or edited, as the tool named it. */
+    onFileTouched?: (path: string) => void;
+    /** Something worth saying that is not part of the reply. */
+    onNotice?: (message: string) => void;
+};
+export type LocalStreamOptions = LocalStreamHandlers & {
+    /** Aborts the turn; the harness interrupts Claude Code gracefully. */
+    abortSignal?: AbortSignal;
+    /**
+     * Fired when the stall watchdog gives up, before the turn is rejected.
+     * Should abort `abortSignal` so Claude Code stops rather than being torn
+     * down out from under a still-open bridge.
+     */
+    onStall?: () => void;
+};
+export type StreamLike = {
+    fullStream: AsyncIterable<unknown>;
+    text: PromiseLike<string>;
+};
+export type ApprovalContinuation = {
+    approvalResponse: {
+        type: "tool-approval-response";
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+    };
+    toolCall: {
+        type: "tool-call";
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    };
+};
+/** The two harness calls a turn needs. Split out so tests can fake them. */
+export type TurnDriver = {
+    start: () => Promise<StreamLike>;
+    continueWithApprovals: (continuations: readonly ApprovalContinuation[]) => Promise<StreamLike>;
+};
+/**
+ * Run one turn to completion, answering approval requests along the way.
+ *
+ * A turn suspends whenever Claude Code wants a tool `permissionMode` does not
+ * cover: the stream ends with the approvals still pending, and the turn only
+ * finishes once decisions are fed back in. Exported for tests.
+ */
+export declare function runPromptTurn(input: {
+    driver: TurnDriver;
+    handlers: LocalStreamHandlers | undefined;
+    accumulator?: LocalTurnAccumulator;
+    /**
+     * Filled with approvals the harness asked about and drained as each is
+     * answered, so a turn that ends mid-question leaves the unanswered ones
+     * behind for the caller to deny.
+     */
+    unanswered?: LocalToolApproval[];
+    /** Overridden by tests; `Infinity` waits forever. */
+    stallTimeoutMs?: number;
+    /** The same, for the stream while a tool is executing. */
+    toolStallTimeoutMs?: number;
+    /**
+     * Called when the stall watchdog fires, before the turn is rejected — abort
+     * the harness stream so Claude Code does not keep running after we give up.
+     */
+    onStall?: () => void;
+}): Promise<string>;
+/**
+ * The previous turn could not be wound down, so this session cannot take
+ * another prompt. Raised rather than pressed on with: the harness would either
+ * refuse the prompt itself or run it alongside the turn we failed to finish.
+ *
+ * The caller's recovery is to replace the session — nothing about a wedged
+ * runtime gets better by asking it again.
+ */
+export declare class HarnessTurnStuck extends Error {
+    constructor();
+}
+/**
+ * The turn produced nothing for `TURN_STALL_TIMEOUT_MS` while no tool was in
+ * flight. Common causes: a step that asked to run several confirmable tools at
+ * once (the harness only surfaces one approval), or the Claude Code bridge
+ * going silent. Recoverable — replace the session and ask again.
+ */
+export declare class HarnessTurnStalled extends Error {
+    constructor(timeoutMs: number, whileToolRunning?: boolean);
+}
+/**
+ * The Claude Code bridge dropped mid-turn. Same recovery as a stall: the
+ * process behind the session is gone, so the next question needs a new one.
+ */
+export declare function isBridgeClosedError(error: unknown): boolean;
+/**
+ * Wait for `work`, but give up after `timeoutMs` rather than blocking a
+ * teardown forever. Resolves either way; the caller has already decided that
+ * an unfinished result is better than waiting.
+ *
+ * Exported for tests.
+ */
+export declare function settleWithin(work: Promise<unknown>, timeoutMs: number): Promise<void>;
+//# sourceMappingURL=turn.d.ts.map

package/build/commands/ask/harness/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../../src/commands/ask/harness/turn.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AACH;;;;;;GAMG;GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnD,qEAAqE;IACrE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG;IACrD,sEAAsE;IACtE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,gBAAgB,EAAE;QAChB,IAAI,EAAE,wBAAwB,CAAC;QAC/B,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,QAAQ,EAAE;QACR,IAAI,EAAE,WAAW,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;CACH,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,qBAAqB,EAAE,CACrB,aAAa,EAAE,SAAS,oBAAoB,EAAE,KAC3C,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1B,CAAC;AA8DF;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC1C,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACjC,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsIlB;AAgGD;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;;CAO1C;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,SAAS,EAAE,MAAM,EAAE,gBAAgB,UAAQ;CAUxD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK3D;AAsDD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,iBAe3E"}