@datename/fastcode-termux 0.1.6 → 0.1.8-beta.0

package/dist/agent/protocol.d.ts

@@ -1,4 +1,23 @@
-export declare function parseToolCalls(text: any): any[];
+export interface ToolCallRecord {
+    tool: string;
+    [key: string]: any;
+}
+export interface ToolCallParseResult {
+    calls: ToolCallRecord[];
+    /** End offset of the last complete construct that was consumed. */
+    consumedEnd: number;
+    /** True parse failures. Salvaged calls do not add an error. */
+    errors: string[];
+}
+/**
+ * Parse all complete tool calls, then salvage only the *remaining* text.
+ *
+ * Invariants (regression-tested):
+ * - a complete construct is consumed exactly once and never rescanned;
+ * - the salvage pass receives `raw.slice(consumedEnd)`, never the full text;
+ * - two adjacent normal calls plus a stray close tag stays at two calls.
+ */
+export declare function parseToolCalls(text: any): ToolCallParseResult;
 export declare function stripToolCalls(text: any): any;
 export declare function formatToolResults(results: any): string;
 export declare const AGENT_SYSTEM_PROMPT: string;

package/dist/agent/protocol.js

@@ -1,18 +1,68 @@
-const TOOL_RE = /<fastcode_tool>([\s\S]*?)<\/fastcode_tool>/g;
 // Some models (notably DeepSeek) emit their native "DSML" tool-call markup
 // instead of <fastcode_tool>. The markers look like `<｜DSML｜invoke ...>`
 // (U+FF5C fullwidth bar, sometimes doubled or spaced). We canonicalize those
 // markers back to plain angle-bracket tags and then parse the
 // calls -> invoke -> parameter structure as a second dialect.
+const FASTCODE_TOOL_OPEN = "<fastcode_tool>";
+const FASTCODE_TOOL_CLOSE_RE = /<\/\s*fastcode_tool\s*>/gi;
+const RESIDUAL_CLOSE_RE = /<\/\s*(?:fastcode_tool|parameter|invoke|calls)\s*>/i;
 const DSML_OPEN_RE = /<\s*(?:[|｜]\s*)+DSML\s*(?:[|｜]\s*)+/gi;
 const DSML_CLOSE_RE = /<\/\s*(?:[|｜]\s*)+DSML\s*(?:[|｜]\s*)+/gi;
-const DSML_BLOCK_RE = /<([a-z_]*calls?)>([\s\S]*?)<\/\1>/gi;
-const DSML_INVOKE_RE = /<invoke\s+name="([^"]+)"\s*>([\s\S]*?)<\/invoke>/gi;
-const DSML_PARAM_RE = /<parameter\s+name="([^"]+)"([^>]*)>([\s\S]*?)<\/parameter>/gi;
+const DSML_BLOCK_RE = /<([a-z_]*calls?)>([\s\S]*?)<\/\s*\1\s*>/gi;
+const DSML_INVOKE_RE = /<invoke\s+name="([^"]+)"\s*>([\s\S]*?)<\/\s*invoke\s*>/gi;
+const DSML_PARAM_RE = /<parameter\s+name="([^"]+)"([^>]*)>([\s\S]*?)<\/\s*parameter\s*>/gi;
+const INVOKE_OPEN_RE = /<invoke\s+name="([^"]+)"\s*>/gi;
 /** Turn the DSML glyph markers into ordinary `<tag>` / `</tag>` tags. */
 function canonicalizeDsml(text) {
     return text.replace(DSML_CLOSE_RE, "</").replace(DSML_OPEN_RE, "<");
 }
+function invokeToCall(invoke) {
+    const call = { tool: invoke[1] };
+    for (const param of (invoke[2] ?? "").matchAll(DSML_PARAM_RE))
+        call[param[1]] = coerceDsmlValue(param[2] ?? "", param[3] ?? "");
+    return call;
+}
+function insideSpan(start, spans) {
+    return spans.some((span) => start >= span.start && start < span.end);
+}
+function matchFrom(text, from, re) {
+    re.lastIndex = from;
+    const match = re.exec(text);
+    if (!match || match.index === undefined)
+        return undefined;
+    return { start: match.index, end: match.index + match[0].length };
+}
+function parseJsonCall(body) {
+    try {
+        const parsed = JSON.parse(body.trim());
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.tool === "string")
+            return parsed;
+    }
+    catch {
+        // Malformed JSON is reported by the caller.
+    }
+    return undefined;
+}
+/**
+ * Recover a JSON object that starts at the beginning of `text` but may be
+ * followed by more markup (for example a drifted close tag). Returns the
+ * consumed prefix length so the caller can continue after it.
+ */
+function salvageJsonPrefix(text) {
+    let searchFrom = 0;
+    while (searchFrom < text.length) {
+        const end = text.indexOf("}", searchFrom);
+        if (end < 0)
+            return undefined;
+        const call = parseJsonCall(text.slice(0, end + 1));
+        if (call) {
+            const close = matchFrom(text, end + 1, FASTCODE_TOOL_CLOSE_RE);
+            return { call, consumed: close ? close.end : end + 1 };
+        }
+        searchFrom = end + 1;
+    }
+    return undefined;
+}
 function coerceDsmlValue(attrs, raw) {
     const value = raw.replace(/^\n/, "").replace(/\n$/, "");
     if (/\bstring\s*=\s*"true"/i.test(attrs))
@@ -32,44 +82,119 @@ function coerceDsmlValue(attrs, raw) {
         return Number.isNaN(n) ? value : n;
     }
 }
-function parseDsmlCalls(text) {
-    const canonical = canonicalizeDsml(text);
-    const bodies = [];
-    for (const block of canonical.matchAll(DSML_BLOCK_RE))
-        bodies.push(block[2] ?? "");
-    if (bodies.length === 0)
-        bodies.push(canonical);
+/**
+ * Parse all complete tool calls, then salvage only the *remaining* text.
+ *
+ * Invariants (regression-tested):
+ * - a complete construct is consumed exactly once and never rescanned;
+ * - the salvage pass receives `raw.slice(consumedEnd)`, never the full text;
+ * - two adjacent normal calls plus a stray close tag stays at two calls.
+ */
+export function parseToolCalls(text) {
+    const raw = canonicalizeDsml(String(text ?? ""));
     const calls = [];
-    for (const body of bodies) {
-        for (const invoke of body.matchAll(DSML_INVOKE_RE)) {
-            const call = { tool: invoke[1] };
-            for (const param of (invoke[2] ?? "").matchAll(DSML_PARAM_RE))
-                call[param[1]] = coerceDsmlValue(param[2] ?? "", param[3] ?? "");
-            calls.push(call);
+    const errors = [];
+    const spans = [];
+    let cursor = 0;
+    while (cursor < raw.length) {
+        const open = raw.indexOf(FASTCODE_TOOL_OPEN, cursor);
+        if (open < 0)
+            break;
+        const innerStart = open + FASTCODE_TOOL_OPEN.length;
+        const close = matchFrom(raw, innerStart, FASTCODE_TOOL_CLOSE_RE);
+        if (!close) {
+            const salvaged = salvageJsonPrefix(raw.slice(innerStart));
+            if (salvaged) {
+                calls.push(salvaged.call);
+                cursor = innerStart + salvaged.consumed;
+                spans.push({ start: open, end: cursor });
+                continue;
+            }
+            errors.push("unclosed <fastcode_tool> block; re-emit a complete tool call");
+            break;
+        }
+        const body = raw.slice(innerStart, close.start);
+        const full = parseJsonCall(body);
+        if (full) {
+            calls.push(full);
+            spans.push({ start: open, end: close.end });
+            cursor = close.end;
+            continue;
+        }
+        // Closing drift: the JSON may be valid even when extra markup (or a
+        // second opener) sits before the matched close tag.
+        const prefix = salvageJsonPrefix(body);
+        if (prefix) {
+            calls.push(prefix.call);
+            cursor = innerStart + prefix.consumed;
+            spans.push({ start: open, end: cursor });
+            continue;
         }
+        errors.push("invalid JSON inside <fastcode_tool>; re-emit a complete tool call");
+        spans.push({ start: open, end: close.end });
+        cursor = close.end;
     }
-    return calls;
-}
-export function parseToolCalls(text) {
-    const calls = [];
-    for (const match of text.matchAll(TOOL_RE)) {
-        const raw = match[1]?.trim();
-        if (!raw)
+    // DSML dialect: parse each complete block once, then complete invokes that
+    // did not belong to a block. Spans prevent a second parse of the same text.
+    for (const block of raw.matchAll(DSML_BLOCK_RE)) {
+        const start = block.index ?? 0;
+        const end = start + block[0].length;
+        if (insideSpan(start, spans))
+            continue;
+        for (const invoke of (block[2] ?? "").matchAll(DSML_INVOKE_RE))
+            calls.push(invokeToCall(invoke));
+        spans.push({ start, end });
+    }
+    for (const invoke of raw.matchAll(DSML_INVOKE_RE)) {
+        const start = invoke.index ?? 0;
+        if (insideSpan(start, spans))
             continue;
-        try {
-            const parsed = JSON.parse(raw);
-            if (typeof parsed.tool === "string")
-                calls.push(parsed);
+        calls.push(invokeToCall(invoke));
+        spans.push({ start, end: start + invoke[0].length });
+    }
+    const consumedEnd = spans.reduce((max, span) => Math.max(max, span.end), 0);
+    salvageResidual(raw.slice(consumedEnd), calls, errors);
+    return { calls, consumedEnd, errors };
+}
+function salvageResidual(tail, calls, errors) {
+    if (!tail.trim())
+        return;
+    let salvaged = false;
+    const toolOpen = tail.indexOf(FASTCODE_TOOL_OPEN);
+    if (toolOpen >= 0) {
+        const recovered = salvageJsonPrefix(tail.slice(toolOpen + FASTCODE_TOOL_OPEN.length));
+        if (recovered) {
+            calls.push(recovered.call);
+            salvaged = true;
         }
-        catch {
-            // Ignore malformed tool blocks; the model can correct itself next turn.
+        else {
+            errors.push("unclosed <fastcode_tool> block; re-emit a complete tool call");
         }
     }
-    calls.push(...parseDsmlCalls(text));
-    return calls;
+    const openers = Array.from(tail.matchAll(INVOKE_OPEN_RE));
+    openers.forEach((opener, index) => {
+        const start = opener.index ?? 0;
+        const bodyStart = start + opener[0].length;
+        const nextStart = openers[index + 1]?.index ?? tail.length;
+        const call = invokeToCall({ 1: opener[1], 2: tail.slice(bodyStart, nextStart) });
+        if (Object.keys(call).length > 1) {
+            calls.push(call);
+            salvaged = true;
+        }
+        else {
+            errors.push(`incomplete invoke for "${opener[1]}"; re-emit a complete tool call`);
+        }
+    });
+    if (!salvaged && openers.length === 0 && toolOpen < 0 && RESIDUAL_CLOSE_RE.test(tail))
+        errors.push("stray closing tag without an opening tool call; re-emit a complete tool call");
 }
 export function stripToolCalls(text) {
-    return canonicalizeDsml(text).replace(TOOL_RE, "").replace(DSML_BLOCK_RE, "").trim();
+    return canonicalizeDsml(String(text ?? ""))
+        .replace(/<fastcode_tool>[\s\S]*?<\/\s*fastcode_tool\s*>/gi, "")
+        .replace(DSML_BLOCK_RE, "")
+        .replace(/<fastcode_tool>[\s\S]*$/i, "")
+        .replace(/<\/\s*(?:fastcode_tool|parameter|invoke|calls)\s*>/gi, "")
+        .trim();
 }
 export function formatToolResults(results) {
     const blocks = results.map((r, index) => {
@@ -97,20 +222,25 @@ You can inspect and change the user's machine by emitting exactly one or more to
 Available tools:
 - shell: {"tool":"shell","command":"command to run"}
 - shell with timeout: {"tool":"shell","command":"npm test","timeoutMs":120000}
+- shell poll (long commands return a session id): {"tool":"shell","session_id":"sh_..."}
+  Polling returns only new output; use waitMs to wait briefly for more.
 - pwd: {"tool":"pwd"}
 - read_file: {"tool":"read_file","path":"path/to/file"}
-- read_many: {"tool":"read_many","paths":["file1","file2"]}
+- read_file range: {"tool":"read_file","path":"large.ts","offset":800,"limit":50}
+  offset is 1-based; use it instead of reading a large file from the start.
+- read_many: {"tool":"read_many","paths":["file1","file2"],"maxBytes":300000}
 - write_file: {"tool":"write_file","path":"path/to/file","content":"full file contents"}
 - append_file: {"tool":"append_file","path":"path/to/file","content":"text to append"}
 - apply_patch: {"tool":"apply_patch","patch":"*** Begin Patch\\n*** Update File: path\\n@@\\n-old\\n+new\\n*** End Patch\\n"}
-- list_files: {"tool":"list_files","path":"optional/path","maxDepth":2}
-- grep: {"tool":"grep","pattern":"text or regex","path":"optional/path"}
-- replace_in_file: {"tool":"replace_in_file","path":"path/to/file","find":"exact text","replace":"replacement"}
+- list_files: {"tool":"list_files","path":"optional/path","maxDepth":2,"detail":false}
+- read_file is capped (default 200KB); grep skips files over 1MB. .fastcodeignore is honored.
+- grep: {"tool":"grep","pattern":"text or regex","path":"optional/path","caseSensitive":false,"glob":"*.ts","context":2,"maxResults":200}
+- replace_in_file: {"tool":"replace_in_file","path":"path/to/file","find":"exact text","replace":"replacement","expectedMatches":1}
 - stat_path: {"tool":"stat_path","path":"path/to/file"}
 - make_dir: {"tool":"make_dir","path":"path/to/dir"}
-- copy_file: {"tool":"copy_file","from":"src","to":"dest"}
+- copy_file: {"tool":"copy_file","from":"src","to":"dest","overwrite":false}
 - move_path: {"tool":"move_path","from":"src","to":"dest"}
-- delete_file: {"tool":"delete_file","path":"path/to/file"}
+- delete_file: {"tool":"delete_file","path":"path/to/file","recursive":false}
 
 Rules:
 - Prefer inspecting files before editing.

package/dist/agent/registry.d.ts

@@ -0,0 +1,19 @@
+import { type ApprovalDecision } from "./approval.js";
+import type { Tool, ToolCall, ToolCtx, ToolResult } from "./tools/types.js";
+export declare function assertToolContract(tools?: Tool[]): void;
+export declare function toolCatalogHash(tools?: Tool[]): string;
+export declare class ToolRegistry {
+    private readonly tools;
+    private readonly catalogHash;
+    constructor(tools?: Tool[]);
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+    approve(call: ToolCall, ctx: ToolCtx): ApprovalDecision;
+    execute(call: ToolCall, ctx: ToolCtx): Promise<ToolResult>;
+}
+export declare const registry: ToolRegistry;
+export declare function runAgentTool(call: ToolCall, cwd?: string, options?: {
+    signal?: AbortSignal;
+    turn?: number;
+    requestApproval?: import("./approval.js").ApprovalResolver;
+}): Promise<ToolResult>;

package/dist/agent/registry.js

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+import { isTrusted } from "../config/trust.js";
+import { DEFAULT_ALLOW_OPTIONS, approvalRequestId, } from "./approval.js";
+import { approvalKey, isPreApproved, rememberApproval } from "./approval-store.js";
+import { evaluateShellCommand } from "./guards.js";
+import { TOOLS } from "./tools/index.js";
+import { loadConfig } from "../config/store.js";
+import { egressAudit, evaluateEgressCall, evaluateEgressOutput, formatEgressDenial, normalizeEgressConfig, } from "./policy/egress.js";
+const STATE_SCOPES = new Set(["call", "turn", "session"]);
+const REVALIDATE_KEYS = new Set(["trust", "sandboxRoots", "schema", "modelCaps"]);
+const TOOL_ERROR_CODES = new Set([
+    "ENOENT", "EACCES", "EEXIST", "ENOTDIR", "EISDIR", "EXDEV", "INVALID_ARGS",
+    "SANDBOX_DENY", "APPROVAL_DENY", "EGRESS_DENY", "NOT_FOUND", "ABORTED", "UNKNOWN",
+]);
+function errorCode(error) {
+    const code = String(error?.code ?? "");
+    if (TOOL_ERROR_CODES.has(code))
+        return code;
+    const message = String(error?.message ?? error ?? "");
+    if (/outside sandbox/i.test(message))
+        return "SANDBOX_DENY";
+    if (/not trusted/i.test(message))
+        return "APPROVAL_DENY";
+    if (/aborted/i.test(message))
+        return "ABORTED";
+    return "UNKNOWN";
+}
+function unique(values) {
+    return Array.from(new Set((values ?? []).filter(Boolean)));
+}
+function normalizeSideEffects(sideEffects) {
+    if (!sideEffects)
+        return undefined;
+    const touched = unique(sideEffects.touched);
+    const created = unique(sideEffects.created);
+    const removed = unique(sideEffects.removed);
+    if (touched.length === 0 && created.length === 0 && removed.length === 0)
+        return undefined;
+    return {
+        ...(touched.length > 0 ? { touched } : {}),
+        ...(created.length > 0 ? { created } : {}),
+        ...(removed.length > 0 ? { removed } : {}),
+    };
+}
+export function assertToolContract(tools = TOOLS) {
+    const names = new Set();
+    for (const tool of tools) {
+        if (!tool.name || typeof tool.name !== "string")
+            throw new Error("tool contract: every tool needs a name");
+        if (names.has(tool.name))
+            throw new Error(`tool contract: duplicate tool name ${tool.name}`);
+        names.add(tool.name);
+        if (!STATE_SCOPES.has(tool.stateScope))
+            throw new Error(`tool contract: ${tool.name} has an invalid stateScope`);
+        for (const key of tool.revalidate ?? []) {
+            if (!REVALIDATE_KEYS.has(key))
+                throw new Error(`tool contract: ${tool.name} has an invalid revalidate key ${String(key)}`);
+        }
+        if (tool.requiresTrust && !(tool.revalidate ?? []).includes("trust")) {
+            throw new Error(`tool contract: ${tool.name} requiresTrust but does not revalidate "trust"`);
+        }
+    }
+}
+export function toolCatalogHash(tools = TOOLS) {
+    const catalog = tools
+        .map((tool) => ({
+        name: tool.name,
+        trust: Boolean(tool.requiresTrust),
+        scope: tool.stateScope,
+        revalidate: [...(tool.revalidate ?? [])].sort(),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return createHash("sha1").update(JSON.stringify(catalog)).digest("hex").slice(0, 8);
+}
+export class ToolRegistry {
+    tools = new Map();
+    catalogHash;
+    constructor(tools = TOOLS) {
+        assertToolContract(tools);
+        for (const tool of tools)
+            this.tools.set(tool.name, tool);
+        this.catalogHash = toolCatalogHash(tools);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    list() {
+        return Array.from(this.tools.values());
+    }
+    approve(call, ctx) {
+        const tool = this.get(call.tool);
+        if (!tool)
+            return { kind: "deny", reason: `unknown tool: ${String(call.tool)}` };
+        if (tool.name === "shell") {
+            const verdict = evaluateShellCommand(call.command);
+            if (verdict.action === "hard_block")
+                return { kind: "deny", reason: verdict.output, code: verdict.code, target: verdict.target };
+            if (verdict.action === "soft_gate") {
+                const key = approvalKey(tool.name, call, ctx.cwd);
+                if (isPreApproved(key, this.catalogHash))
+                    return { kind: "allow", scope: "once" };
+                return { kind: "pending", request: shellApprovalRequest(call, verdict) };
+            }
+            if (!verdict.allow)
+                return { kind: "deny", reason: verdict.output };
+        }
+        if ((tool.revalidate ?? []).includes("trust") && !isTrusted(ctx.cwd)) {
+            return {
+                kind: "deny",
+                reason: `project is not trusted: ${ctx.cwd}. Run \`fastcode trust ${ctx.cwd}\` or accept the trust prompt.`,
+            };
+        }
+        return { kind: "allow", scope: "once" };
+    }
+    async execute(call, ctx) {
+        const tool = this.get(call.tool);
+        if (!tool)
+            return { ok: false, output: `unknown tool: ${String(call.tool)}`, code: "INVALID_ARGS" };
+        const toolCtx = { ...ctx, catalogHash: this.catalogHash };
+        const prepared = tool.prepare(call, toolCtx);
+        if (prepared.ok === false)
+            return { ok: false, output: prepared.output, code: prepared.code ?? "INVALID_ARGS", hint: prepared.hint };
+        const egressConfig = normalizeEgressConfig(loadConfig().egress);
+        const preEgress = evaluateEgressCall(call, ctx.cwd, egressConfig);
+        if (preEgress.action === "deny") {
+            const egressDecision = preEgress.decision;
+            return {
+                ok: false,
+                output: formatEgressDenial(egressDecision),
+                code: "EGRESS_DENY",
+                hint: "Egress policy blocked this call before execution; no approval request was created.",
+                egress: egressAudit(egressDecision),
+            };
+        }
+        const preAudit = preEgress.decision ? egressAudit(preEgress.decision) : undefined;
+        const decision = this.approve(call, toolCtx);
+        if (decision.kind === "deny") {
+            const output = decision.reason ?? "denied by approval policy";
+            if (tool.name === "shell" && (decision.code === "sensitive_file_egress" || decision.code === "credential_read")) {
+                return {
+                    ok: false,
+                    output,
+                    code: "EGRESS_DENY",
+                    egress: {
+                        outlet: "shell.command",
+                        ...(decision.target ? { target: decision.target } : {}),
+                        rule: decision.code,
+                        mode: "block",
+                        wouldBlock: true,
+                        code: "EGRESS_DENY",
+                        reason: decision.code,
+                    },
+                };
+            }
+            return { ok: false, output, code: "APPROVAL_DENY" };
+        }
+        if (decision.kind === "pending") {
+            if (!ctx.requestApproval)
+                return { ok: false, output: "approval required, but no approval resolver is registered (fail closed)", code: "APPROVAL_DENY" };
+            let resolved;
+            try {
+                resolved = await ctx.requestApproval(decision.request);
+            }
+            catch (err) {
+                return { ok: false, output: `approval failed (fail closed): ${err?.message ?? String(err)}`, code: "APPROVAL_DENY" };
+            }
+            if (!resolved || resolved.kind === "pending")
+                return { ok: false, output: "approval unresolved; nothing was executed (fail closed)", code: "APPROVAL_DENY" };
+            if (resolved.kind !== "allow") {
+                const reason = resolved.kind === "deny" ? resolved.reason : resolved.kind === "feedback" ? resolved.text : `decision ${resolved.kind} requires a later batch`;
+                return { ok: false, output: `approval denied: ${reason ?? "no reason"}`, code: "APPROVAL_DENY" };
+            }
+            rememberApproval(approvalKey(tool.name, call, ctx.cwd), this.catalogHash, resolved.scope);
+        }
+        try {
+            let result = await tool.execute(call, toolCtx);
+            result = {
+                ...result,
+                sideEffects: normalizeSideEffects(result.sideEffects),
+                ...(preAudit && !result.egress ? { egress: preAudit } : {}),
+            };
+            const postEgress = evaluateEgressOutput(call.tool, result.output, egressConfig);
+            if (postEgress.action === "deny") {
+                const egressDecision = postEgress.decision;
+                return {
+                    ok: false,
+                    output: formatEgressDenial(egressDecision),
+                    code: "EGRESS_DENY",
+                    hint: "Egress policy blocked this tool output before it reached the model.",
+                    sideEffects: result.sideEffects,
+                    egress: egressAudit(egressDecision),
+                };
+            }
+            if (postEgress.decision)
+                result = { ...result, egress: egressAudit(postEgress.decision) };
+            return result;
+        }
+        catch (err) {
+            const output = err?.message ?? String(err);
+            const postEgress = evaluateEgressOutput(call.tool, output, egressConfig);
+            if (postEgress.action === "deny") {
+                const egressDecision = postEgress.decision;
+                return {
+                    ok: false,
+                    output: formatEgressDenial(egressDecision),
+                    code: "EGRESS_DENY",
+                    hint: "Egress policy blocked this error output before it reached the model.",
+                    egress: egressAudit(egressDecision),
+                };
+            }
+            return {
+                ok: false,
+                output,
+                code: errorCode(err),
+                ...(preAudit ? { egress: preAudit } : {}),
+                ...(postEgress.decision ? { egress: egressAudit(postEgress.decision) } : {}),
+            };
+        }
+    }
+}
+function shellApprovalRequest(call, verdict) {
+    const options = DEFAULT_ALLOW_OPTIONS.map((option) => ({ ...option }));
+    const denyIndex = options.findIndex((option) => option.kind === "deny");
+    const target = verdict.target ?? "";
+    const prompt = `Shell command needs approval: ${verdict.code}${target ? ` (${target})` : ""}`;
+    return {
+        id: approvalRequestId(),
+        tool: "shell",
+        args: call,
+        reason: "destructive",
+        options,
+        tier: 2,
+        prompt,
+        source: "system",
+        defaultIndex: denyIndex >= 0 ? denyIndex : 0,
+        timeoutMs: 60_000,
+    };
+}
+export const registry = new ToolRegistry();
+export async function runAgentTool(call, cwd = process.cwd(), options = {}) {
+    return registry.execute(call, {
+        cwd,
+        signal: options.signal,
+        turn: options.turn,
+        requestApproval: options.requestApproval,
+    });
+}

package/dist/agent/runner.d.ts

@@ -0,0 +1,127 @@
+import type { ChatChunk, ChatMessage, NativeToolCall, Provider, ReasoningEffort, ToolSchema } from "../types.js";
+import type { ActiveFile } from "../session/log.js";
+import type { SideEffects } from "./tools/types.js";
+import { type CompactionConfig } from "./compaction.js";
+import { type ToolProtocol } from "./protocol-mode.js";
+import type { ApprovalResolver } from "./approval.js";
+export interface ToolCall {
+    tool: string;
+    [key: string]: any;
+}
+export interface LoopDetectionOptions {
+    readOnlyThreshold?: number;
+    sideEffectThreshold?: number;
+    window?: number;
+    exemptReadOnly?: boolean;
+}
+export interface RunOptions {
+    provider: Provider;
+    apiKey?: string;
+    model: string;
+    messages?: ChatMessage[];
+    prompt: string;
+    system?: string;
+    maxTurns?: number;
+    allowTools?: boolean;
+    tokenBudget?: number;
+    costBudgetUsd?: number;
+    signal?: AbortSignal;
+    cwd?: string;
+    idleTimeoutMs?: number;
+    contextBudgetChars?: number;
+    compaction?: CompactionConfig;
+    contextWindow?: number;
+    serverOpaqueState?: string;
+    loopDetection?: LoopDetectionOptions;
+    reasoningEffort?: ReasoningEffort;
+    protocol?: ToolProtocol;
+    tools?: ToolSchema[];
+    onProtocolFallback?: (message: string) => void;
+    onNativeOk?: () => void;
+    takeSteering?: () => string[];
+    onDelta?: (delta: string, text: string) => void;
+    requestApproval?: ApprovalResolver;
+}
+export type AgentStopReason = "complete" | "max_turns" | "token_budget" | "cost_budget" | "loop_detected" | "aborted" | "incomplete" | "stream_error";
+export type AgentErrorKind = "token_budget" | "cost_budget" | "loop_detected" | "aborted" | "stream_error";
+export type AgentEvent = {
+    type: "compaction";
+    beforeChars: number;
+    afterChars: number;
+    beforeTokens: number;
+    afterTokens: number;
+    droppedMessages: number;
+    keptMessages: number;
+    reason: "threshold" | "heap";
+    source: "local" | "server";
+    summaryFile?: string;
+} | {
+    type: "assistant_raw";
+    text: string;
+    toolCalls?: NativeToolCall[];
+} | {
+    type: "assistant_text";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    call: ToolCall;
+    native?: boolean;
+} | {
+    type: "tool_result";
+    id: string;
+    call: ToolCall;
+    ok: boolean;
+    output: string;
+    sideEffects?: SideEffects;
+    code?: string;
+    hint?: string;
+    truncated?: boolean;
+    totalLines?: number;
+    returnedLines?: number;
+    totalBytes?: number;
+    returnedBytes?: number;
+    filesRead?: number;
+    filesSkipped?: number;
+    matches?: number;
+} | {
+    type: "egress_denied";
+    outlet: string;
+    target?: string;
+    rule: string;
+    mode: "audit" | "block";
+    wouldBlock: boolean;
+    code: "EGRESS_DENY";
+    reason: string;
+} | {
+    type: "usage";
+    usage: NonNullable<ChatChunk["usage"]>;
+} | {
+    type: "loop_detected";
+    fingerprint: string;
+    occurrences: number;
+    warned: boolean;
+} | {
+    type: "notice";
+    text: string;
+} | {
+    type: "error";
+    kind: AgentErrorKind;
+    message: string;
+    text?: string;
+    used?: number;
+} | {
+    type: "checkpoint";
+    turn: number;
+    cwd: string;
+    providerId: string;
+    model: string;
+    activeFiles: ActiveFile[];
+} | {
+    type: "done";
+    history: ChatMessage[];
+    finalText: string;
+    stopReason: AgentStopReason;
+};
+export declare const LOOP_WARNING: string;
+export declare function runAgent(options: RunOptions): AsyncGenerator<AgentEvent, void, void>;