@pentoshi/clai 3.5.1 → 3.7.2

package/dist/agent/tool-history.js

@@ -0,0 +1,200 @@
+/** Append assistant turn that requested tools (must precede tool results). */
+export function appendAssistantWithTools(messages, text, toolCalls) {
+    messages.push({
+        role: "assistant",
+        content: text ?? "",
+        ...(toolCalls.length ? { toolCalls } : {}),
+    });
+}
+/** Append a single tool result linked by tool_call_id. */
+export function appendToolResult(messages, toolCallId, content, name, ok) {
+    messages.push({
+        role: "tool",
+        content,
+        toolCallId,
+        ...(name ? { name } : {}),
+        ...(typeof ok === "boolean" ? { ok } : {}),
+    });
+}
+/**
+ * Whether the message list would orphan a tool result (result without a
+ * preceding assistant toolCalls entry that owns the id).
+ */
+export function hasOrphanToolMessages(messages) {
+    const openIds = new Set();
+    for (const msg of messages) {
+        if (msg.role === "assistant" && msg.toolCalls?.length) {
+            for (const tc of msg.toolCalls)
+                openIds.add(tc.id);
+        }
+        if (msg.role === "tool") {
+            const id = msg.toolCallId ?? "";
+            if (!id || !openIds.has(id))
+                return true;
+        }
+    }
+    return false;
+}
+/** Ids on the last assistant toolCalls message that lack a following tool result. */
+export function missingToolResultIds(messages) {
+    let lastAssistant;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m.role === "assistant" && m.toolCalls?.length) {
+            lastAssistant = m;
+            break;
+        }
+    }
+    if (!lastAssistant?.toolCalls?.length)
+        return [];
+    const needed = new Set(lastAssistant.toolCalls.map((tc) => tc.id));
+    // Only scan results after that assistant message.
+    const start = messages.lastIndexOf(lastAssistant);
+    for (let i = start + 1; i < messages.length; i += 1) {
+        const m = messages[i];
+        if (m.role === "tool" && m.toolCallId)
+            needed.delete(m.toolCallId);
+        // Stop at next non-tool (next turn).
+        if (m.role !== "tool")
+            break;
+    }
+    return [...needed];
+}
+/**
+ * Append synthetic failed tool results for any assistant toolCalls ids that
+ * still lack a role:tool reply (deferred, cancelled, sliced, abort).
+ */
+export function fillMissingToolResults(messages, toolCalls, reason = "Cancelled — not executed this turn.") {
+    if (!toolCalls.length)
+        return 0;
+    const have = new Set();
+    // Collect existing tool results after the last matching assistant.
+    let start = -1;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m.role === "assistant" &&
+            m.toolCalls?.some((tc) => toolCalls.some((t) => t.id === tc.id))) {
+            start = i;
+            break;
+        }
+    }
+    if (start < 0)
+        return 0;
+    for (let i = start + 1; i < messages.length; i += 1) {
+        const m = messages[i];
+        if (m.role === "tool" && m.toolCallId)
+            have.add(m.toolCallId);
+        else if (m.role !== "tool")
+            break;
+    }
+    let filled = 0;
+    for (const tc of toolCalls) {
+        if (have.has(tc.id))
+            continue;
+        appendToolResult(messages, tc.id, `Tool ${tc.name} result (exit=130, ok=false):\n${reason}`, tc.name, false);
+        have.add(tc.id);
+        filled += 1;
+    }
+    return filled;
+}
+/**
+ * True when every id on every assistant toolCalls has a matching tool result
+ * later in the list (no missing pairs). Used by tests and diagnostics.
+ */
+export function allToolCallsHaveResults(messages) {
+    const pending = new Set();
+    for (const msg of messages) {
+        if (msg.role === "assistant" && msg.toolCalls?.length) {
+            for (const tc of msg.toolCalls)
+                pending.add(tc.id);
+        }
+        if (msg.role === "tool" && msg.toolCallId) {
+            pending.delete(msg.toolCallId);
+        }
+    }
+    return pending.size === 0;
+}
+/**
+ * When compacting, never leave role:tool without its assistant toolCalls.
+ * Expand a keep-window start so tool pairs stay intact.
+ */
+export function expandKeepStartForToolPairs(messages, keepStart) {
+    let start = keepStart;
+    while (start > 0 && messages[start]?.role === "tool") {
+        start -= 1;
+    }
+    // If we landed mid-assistant-with-tools, include that assistant.
+    if (start > 0 &&
+        messages[start]?.role === "assistant" &&
+        messages[start].toolCalls?.length) {
+        // already includes assistant
+    }
+    else if (start > 0) {
+        // If first kept message is tool, walk back to assistant
+        while (start > 0 &&
+            messages[start - 1]?.role !== "system" &&
+            (messages[start]?.role === "tool" ||
+                (messages[start - 1]?.role === "assistant" &&
+                    messages[start - 1].toolCalls?.length &&
+                    messages[start]?.role === "tool"))) {
+            if (messages[start - 1]?.role === "assistant" &&
+                messages[start - 1].toolCalls?.length) {
+                start -= 1;
+                break;
+            }
+            start -= 1;
+        }
+    }
+    return Math.max(0, start);
+}
+/**
+ * Validate native assistant/tool groups immediately before provider dispatch.
+ * Every tool result must belong to the currently open assistant group, ids are
+ * unique, and no non-tool message may begin until the whole group is closed.
+ */
+export function validateToolProtocol(messages) {
+    const issues = [];
+    const seenIds = new Set();
+    let pending = new Set();
+    for (let index = 0; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message.role === "assistant" && message.toolCalls?.length) {
+            if (pending.size > 0) {
+                issues.push(`message ${index}: new assistant tool group before results for ${[...pending].join(", ")}`);
+            }
+            pending = new Set();
+            for (const call of message.toolCalls) {
+                if (!call.id)
+                    issues.push(`message ${index}: tool call has no id`);
+                if (seenIds.has(call.id))
+                    issues.push(`message ${index}: duplicate tool call id ${call.id}`);
+                seenIds.add(call.id);
+                pending.add(call.id);
+            }
+            continue;
+        }
+        if (message.role === "tool") {
+            const id = message.toolCallId ?? "";
+            if (!id || !pending.has(id)) {
+                issues.push(`message ${index}: orphan tool result${id ? ` ${id}` : ""}`);
+            }
+            else {
+                pending.delete(id);
+            }
+            continue;
+        }
+        if (pending.size > 0) {
+            issues.push(`message ${index}: non-tool message before results for ${[...pending].join(", ")}`);
+            pending.clear();
+        }
+    }
+    if (pending.size > 0)
+        issues.push(`end of history: missing results for ${[...pending].join(", ")}`);
+    return issues;
+}
+export function assertValidToolProtocol(messages) {
+    const issues = validateToolProtocol(messages);
+    if (issues.length > 0)
+        throw new Error(`invalid native tool protocol: ${issues.join("; ")}`);
+}
+//# sourceMappingURL=tool-history.js.map

package/dist/agent/tool-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-history.js","sourceRoot":"","sources":["../../src/agent/tool-history.ts"],"names":[],"mappings":"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"}

package/dist/agent/tool-output-formatting.d.ts

@@ -1,7 +1,19 @@
 import type { ToolCall, ToolResult } from "../types.js";
 export declare function saveToolOutput(call: ToolCall, output: string): Promise<string | undefined>;
-export declare function summarizeOutput(output: string, maxChars?: number): {
+/**
+ * Truncate long tool output for the model. When `preferErrors` is set (failed
+ * commands), keep error-bearing lines and a heavy tail so stack traces survive.
+ */
+export declare function summarizeOutput(output: string, maxChars?: number, opts?: {
+    preferErrors?: boolean;
+}): {
     text: string;
     truncated: boolean;
 };
+/** One-line failure cue prepended when a tool returns ok=false. */
+export declare function failureSummaryLine(result: {
+    ok: boolean;
+    exitCode?: number | undefined;
+    output?: string | undefined;
+}): string | undefined;
 export declare function formatToolContext(call: ToolCall, result: ToolResult): string;

package/dist/agent/tool-output-formatting.js

@@ -24,10 +24,47 @@ export async function saveToolOutput(call, output) {
         handlePermissionError(err);
     }
 }
-export function summarizeOutput(output, maxChars = 8_000) {
+const ERROR_LINE_RE = /\b(?:error|exception|failed|failure|fatal|traceback|panic|ECONNREFUSED|ENOENT|TypeError|SyntaxError|ReferenceError|Cannot find|not found|exit code)\b/i;
+/**
+ * Truncate long tool output for the model. When `preferErrors` is set (failed
+ * commands), keep error-bearing lines and a heavy tail so stack traces survive.
+ */
+export function summarizeOutput(output, maxChars = 8_000, opts) {
     if (output.length <= maxChars)
         return { text: output, truncated: false };
     const lines = output.split(/\r?\n/);
+    if (opts?.preferErrors) {
+        const errorLines = lines.filter((l) => ERROR_LINE_RE.test(l));
+        const tailBudget = Math.floor(maxChars * 0.55);
+        const errBudget = maxChars - tailBudget - 80;
+        const errBlock = [];
+        let used = 0;
+        for (const line of errorLines.slice(-80)) {
+            const cost = line.length + 1;
+            if (used + cost > errBudget)
+                break;
+            errBlock.push(line);
+            used += cost;
+        }
+        const tail = [];
+        used = 0;
+        for (let i = lines.length - 1; i >= 0; i -= 1) {
+            const line = lines[i];
+            const cost = line.length + 1;
+            if (used + cost > tailBudget)
+                break;
+            tail.unshift(line);
+            used += cost;
+        }
+        const body = [
+            ...(errBlock.length
+                ? ["[error-relevant lines]", ...errBlock, ""]
+                : []),
+            `... (${lines.length.toLocaleString()} lines truncated; tail kept) ...`,
+            ...tail,
+        ].join("\n");
+        return { text: body.slice(0, maxChars + 200), truncated: true };
+    }
     const head = [];
     const tail = [];
     let used = 0;
@@ -57,6 +94,17 @@ export function summarizeOutput(output, maxChars = 8_000) {
         truncated: true,
     };
 }
+/** One-line failure cue prepended when a tool returns ok=false. */
+export function failureSummaryLine(result) {
+    if (result.ok)
+        return undefined;
+    const exit = typeof result.exitCode === "number" ? `exit=${result.exitCode}` : "failed";
+    const head = (result.output ?? "").split(/\r?\n/).find((l) => l.trim()) ?? "";
+    const snippet = head.replace(/\s+/g, " ").trim().slice(0, 120);
+    return snippet
+        ? `FAILURE SUMMARY: ${exit}; ${snippet}`
+        : `FAILURE SUMMARY: ${exit}`;
+}
 // Tools whose output is the actual content the model needs verbatim (file
 // bodies, listings, search hits). Running these through the security-signal
 // `genericReducer` was wrong: it ranks lines by pentest keywords and drops
@@ -83,26 +131,33 @@ const PASSTHROUGH_CAP_CHARS = 400_000;
 const WEB_FETCH_CAP_CHARS = 20_000;
 export function formatToolContext(call, result) {
     const output = result.output.trim();
-    if (!output)
-        return "";
+    if (!output) {
+        const fail = failureSummaryLine(result);
+        return fail ?? "";
+    }
+    const preferErrors = !result.ok;
+    const failLine = failureSummaryLine(result);
     if (call.name === "web.fetch" || call.name === "http.fetch") {
-        const { text, truncated } = summarizeOutput(output, WEB_FETCH_CAP_CHARS);
-        if (!truncated)
-            return text;
-        const saved = result.outputPath
-            ? `\n\n[Response exceeds ${WEB_FETCH_CAP_CHARS.toLocaleString()} chars; showing the head and tail. The FULL response is saved at: ${result.outputPath} — re-fetch a narrower URL or read the saved file if you need the middle.]`
-            : `\n\n[Response exceeds ${WEB_FETCH_CAP_CHARS.toLocaleString()} chars; only head and tail shown.]`;
-        return `${text}${saved}`.trim();
+        const { text, truncated } = summarizeOutput(output, WEB_FETCH_CAP_CHARS, {
+            preferErrors,
+        });
+        const body = truncated
+            ? `${text}${result.outputPath
+                ? `\n\n[Response exceeds ${WEB_FETCH_CAP_CHARS.toLocaleString()} chars; head/tail shown. Full: ${result.outputPath}]`
+                : `\n\n[Response exceeds ${WEB_FETCH_CAP_CHARS.toLocaleString()} chars; only head and tail shown.]`}`
+            : text;
+        return [failLine, body].filter(Boolean).join("\n").trim();
     }
-    // Pass-through tools: never reduce — the model needs the real content.
     if (PASSTHROUGH_TOOLS.has(call.name)) {
-        const { text, truncated } = summarizeOutput(output, PASSTHROUGH_CAP_CHARS);
-        if (!truncated)
-            return text;
-        const saved = result.outputPath
-            ? `\n\n[File content exceeds ${PASSTHROUGH_CAP_CHARS.toLocaleString()} chars; showing the head and tail. The FULL content is saved at: ${result.outputPath} — re-read specific line ranges with fs.read if you need the middle.]`
-            : `\n\n[File content exceeds ${PASSTHROUGH_CAP_CHARS.toLocaleString()} chars; only head and tail shown. Read it in smaller chunks if the middle is needed.]`;
-        return `${text}${saved}`.trim();
+        const { text, truncated } = summarizeOutput(output, PASSTHROUGH_CAP_CHARS, {
+            preferErrors,
+        });
+        const body = truncated
+            ? `${text}${result.outputPath
+                ? `\n\n[File content exceeds ${PASSTHROUGH_CAP_CHARS.toLocaleString()} chars; head/tail shown. Full: ${result.outputPath}]`
+                : `\n\n[File content exceeds ${PASSTHROUGH_CAP_CHARS.toLocaleString()} chars; only head and tail shown.]`}`
+            : text;
+        return [failLine, body].filter(Boolean).join("\n").trim();
     }
     let reduced;
     try {
@@ -116,13 +171,11 @@ export function formatToolContext(call, result) {
     catch {
         reduced = undefined;
     }
-    // Hard cap on the reduced text — reducers should already be small, but
-    // never let one accidentally explode model context.
     const base = reduced && reduced.length > 0 ? reduced : output;
-    const summary = summarizeOutput(base, 8_000);
+    const summary = summarizeOutput(base, 8_000, { preferErrors });
     const saved = result.outputPath
         ? `\nFull output saved to: ${result.outputPath}`
         : "";
-    return `${summary.text}${saved}`.trim();
+    return [failLine, `${summary.text}${saved}`].filter(Boolean).join("\n").trim();
 }
 //# sourceMappingURL=tool-output-formatting.js.map

package/dist/agent/tool-output-formatting.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-output-formatting.js","sourceRoot":"","sources":["../../src/agent/tool-output-formatting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAGtE,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,CACL,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;QAC5D,aAAa,CACd,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAc,EACd,MAAc;IAEd,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtE,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,MAAM,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,QAAQ,GAAG,KAAK;IAEhB,IAAI,MAAM,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAEzE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC7B,IAAI,IAAI,GAAG,IAAI,GAAG,IAAI;YAAE,MAAM;QAC9B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,IAAI,IAAI,IAAI,CAAC;IACf,CAAC;IAED,IAAI,GAAG,CAAC,CAAC;IACT,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC7B,IAAI,IAAI,GAAG,IAAI,GAAG,IAAI;YAAE,MAAM;QAC9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnB,IAAI,IAAI,IAAI,CAAC;IACf,CAAC;IAED,OAAO;QACL,IAAI,EAAE;YACJ,GAAG,IAAI;YACP,QAAQ,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,8BAA8B;YACnE,GAAG,IAAI;SACR,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,iDAAiD;AACjD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS;IACxC,SAAS;IACT,SAAS;IACT,WAAW;IACX,SAAS;IACT,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AACH,MAAM,qBAAqB,GAAG,OAAO,CAAC;AACtC,8EAA8E;AAC9E,4EAA4E;AAC5E,uEAAuE;AACvE,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,mEAAmE;AACnE,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEnC,MAAM,UAAU,iBAAiB,CAAC,IAAc,EAAE,MAAkB;IAClE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC5D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,eAAe,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;QACzE,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU;YAC7B,CAAC,CAAC,yBAAyB,mBAAmB,CAAC,cAAc,EAAE,qEAAqE,MAAM,CAAC,UAAU,4EAA4E;YACjO,CAAC,CAAC,yBAAyB,mBAAmB,CAAC,cAAc,EAAE,oCAAoC,CAAC;QACtG,OAAO,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,uEAAuE;IACvE,IAAI,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,eAAe,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QAC3E,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU;YAC7B,CAAC,CAAC,6BAA6B,qBAAqB,CAAC,cAAc,EAAE,oEAAoE,MAAM,CAAC,UAAU,uEAAuE;YACjO,CAAC,CAAC,6BAA6B,qBAAqB,CAAC,cAAc,EAAE,uFAAuF,CAAC;QAC/J,OAAO,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,IAAI,OAA2B,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,GACX,IAAI,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3E,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,EAAE;YACtC,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,OAAO;SACR,CAAC,CAAC;QACH,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,SAAS,CAAC;IACtB,CAAC;IACD,uEAAuE;IACvE,oDAAoD;IACpD,MAAM,IAAI,GAAG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU;QAC7B,CAAC,CAAC,2BAA2B,MAAM,CAAC,UAAU,EAAE;QAChD,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"tool-output-formatting.js","sourceRoot":"","sources":["../../src/agent/tool-output-formatting.ts"],"names":[],"mappings":"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"}

package/dist/agent/turn-outcome.d.ts

@@ -0,0 +1,11 @@
+export type TurnOutcomeStatus = "succeeded" | "partial" | "blocked" | "failed" | "aborted" | "paused_budget";
+export interface TurnOutcome {
+    readonly schemaVersion: 1;
+    readonly status: TurnOutcomeStatus;
+    readonly answer: string;
+    readonly steps: number;
+    readonly remainingCriteria: readonly string[];
+    readonly reason?: string | undefined;
+}
+export declare function createTurnOutcome(input: Omit<TurnOutcome, "schemaVersion">): TurnOutcome;
+export declare function renderTurnOutcome(outcome: TurnOutcome): string;

package/dist/agent/turn-outcome.js

@@ -0,0 +1,17 @@
+export function createTurnOutcome(input) {
+    if (input.status === "succeeded" && input.remainingCriteria.length > 0) {
+        throw new Error("a succeeded turn cannot have remaining criteria");
+    }
+    return { schemaVersion: 1, ...input };
+}
+export function renderTurnOutcome(outcome) {
+    if (outcome.status === "succeeded" || outcome.status === "aborted")
+        return outcome.answer;
+    const status = outcome.status === "paused_budget" ? "paused" : outcome.status;
+    const remaining = outcome.remainingCriteria.length
+        ? `\n\nRemaining:\n${outcome.remainingCriteria.map((item) => `- ${item}`).join("\n")}`
+        : "";
+    const reason = outcome.reason ? `\n\nReason: ${outcome.reason}` : "";
+    return `${outcome.answer}${outcome.answer ? "\n\n" : ""}Status: ${status}${reason}${remaining}`;
+}
+//# sourceMappingURL=turn-outcome.js.map

package/dist/agent/turn-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-outcome.js","sourceRoot":"","sources":["../../src/agent/turn-outcome.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,iBAAiB,CAAC,KAAyC;IACzE,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAoB;IACpD,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC;IAC1F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,MAAM;QAChD,CAAC,CAAC,mBAAmB,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACtF,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,CAAC;AAClG,CAAC"}

package/dist/agent/turn-state.d.ts

@@ -0,0 +1,11 @@
+export type TurnState = "understanding" | "exploring" | "acting" | "verifying" | "succeeded" | "partial" | "blocked" | "failed" | "aborted" | "paused_budget";
+export interface TurnStateSnapshot {
+    readonly schemaVersion: 1;
+    readonly state: TurnState;
+    readonly revision: number;
+    readonly reason?: string | undefined;
+}
+export declare function createTurnState(initial?: TurnState): TurnStateSnapshot;
+export declare function canTransitionTurn(from: TurnState, to: TurnState): boolean;
+export declare function transitionTurn(snapshot: TurnStateSnapshot, to: TurnState, reason?: string): TurnStateSnapshot;
+export declare function isTerminalTurnState(state: TurnState): boolean;

package/dist/agent/turn-state.js

@@ -0,0 +1,28 @@
+const LEGAL_TRANSITIONS = {
+    understanding: ["exploring", "acting", "blocked", "failed", "aborted", "paused_budget"],
+    exploring: ["understanding", "acting", "verifying", "blocked", "failed", "aborted", "paused_budget"],
+    acting: ["exploring", "verifying", "blocked", "failed", "aborted", "paused_budget"],
+    verifying: ["exploring", "acting", "succeeded", "partial", "blocked", "failed", "aborted", "paused_budget"],
+    paused_budget: ["understanding", "exploring", "acting", "verifying", "aborted"],
+    succeeded: [],
+    partial: [],
+    blocked: [],
+    failed: [],
+    aborted: [],
+};
+export function createTurnState(initial = "understanding") {
+    return { schemaVersion: 1, state: initial, revision: 0 };
+}
+export function canTransitionTurn(from, to) {
+    return LEGAL_TRANSITIONS[from].includes(to);
+}
+export function transitionTurn(snapshot, to, reason) {
+    if (!canTransitionTurn(snapshot.state, to)) {
+        throw new Error(`illegal turn transition: ${snapshot.state} -> ${to}`);
+    }
+    return { schemaVersion: 1, state: to, revision: snapshot.revision + 1, reason };
+}
+export function isTerminalTurnState(state) {
+    return LEGAL_TRANSITIONS[state].length === 0;
+}
+//# sourceMappingURL=turn-state.js.map

package/dist/agent/turn-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-state.js","sourceRoot":"","sources":["../../src/agent/turn-state.ts"],"names":[],"mappings":"AAmBA,MAAM,iBAAiB,GAAsD;IAC3E,aAAa,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC;IACvF,SAAS,EAAE,CAAC,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC;IACpG,MAAM,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC;IACnF,SAAS,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC;IAC3G,aAAa,EAAE,CAAC,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC;IAC/E,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;CACZ,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,UAAqB,eAAe;IAClE,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAe,EAAE,EAAa;IAC9D,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,QAA2B,EAC3B,EAAa,EACb,MAAe;IAEf,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,KAAK,OAAO,EAAE,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/agent/workspace-orient.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Stack-agnostic workspace orientation for build turns.
+ *
+ * Weak models often skip fs.list/fs.read and plan against an imaginary empty
+ * destination — then re-scaffold into a non-empty folder ("Operation cancelled")
+ * or write into the agent package. This module snapshots the real cwd /
+ * destination / candidate project paths so the model always sees ground truth
+ * before plan.create or implement.
+ */
+/** Filenames that strongly suggest "this directory is already a software project". */
+export declare const PROJECT_MARKERS: readonly ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "Cargo.toml", "go.mod", "pyproject.toml", "requirements.txt", "Pipfile", "composer.json", "Gemfile", "pom.xml", "build.gradle", "build.gradle.kts", "CMakeLists.txt", "Makefile", "mix.exs", "pubspec.yaml", "Package.swift", "deno.json", "deno.jsonc", "tsconfig.json", "index.html", "setup.py", "manage.py", "Cargo.lock", ".git"];
+export declare function isBareParentDirectory(path: string): boolean;
+export declare function detectProjectMarkers(dir: string): string[];
+/**
+ * Infer package manager from lockfiles / markers present in a project dir.
+ * Prefer lockfile over bare package.json.
+ */
+export declare function detectPackageManager(dir: string): "npm" | "pnpm" | "yarn" | "bun" | "pip" | "poetry" | "cargo" | "go" | undefined;
+export declare function isExistingProjectDir(dir: string): boolean;
+/**
+ * Discover marker-bearing immediate children under a user-named destination.
+ * This is intentionally bounded and non-recursive: enough to resume an
+ * arbitrary existing Desktop project without crawling the user's filesystem.
+ */
+export declare function discoverImmediateProjectRoots(parent: string, maxEntries?: number): string[];
+export interface DirSnapshot {
+    path: string;
+    exists: boolean;
+    isDir: boolean;
+    entryCount: number;
+    /** Up to maxNames entry basenames. */
+    entries: string[];
+    markers: string[];
+    isProject: boolean;
+    emptyOrMissing: boolean;
+}
+export declare function snapshotDir(path: string, maxNames?: number): DirSnapshot;
+export interface WorkspaceOrientationInput {
+    cwd?: string;
+    /** User-named parent destination (e.g. Desktop). */
+    destinationHint?: string;
+    /** Candidate project path from plan/prompt (may not exist yet). */
+    candidateProject?: string;
+    /** Extra absolute paths to snapshot (e.g. Desktop/todo-app guessed from prompt). */
+    extraPaths?: string[];
+}
+/**
+ * Guess a likely project subfolder name from free text (todo-app, my-api, …).
+ * Stack-agnostic: any reasonable folder token after create/scaffold/in/on.
+ */
+export declare function guessProjectFolderName(text: string): string | undefined;
+/**
+ * Human + model-facing block injected into the system prompt for build turns.
+ */
+export declare function buildWorkspaceOrientation(input: WorkspaceOrientationInput): string;
+/**
+ * Extract the directory name a scaffolder would create (stack-agnostic).
+ * Returns undefined when the command is not a one-shot create into a named path.
+ */
+export declare function extractScaffoldTargetName(command: string): string | undefined;
+/**
+ * Resolve absolute path a scaffolder would write into.
+ */
+export declare function resolveScaffoldTargetPath(command: string, shellCwd?: string): string | undefined;
+/** Scaffold cancelled / refused without creating a usable tree. */
+export declare function isScaffoldCancelledOutput(output: string): boolean;
+/**
+ * True when the target path looks like a materialized project after scaffold.
+ */
+export declare function scaffoldLooksMaterialized(targetPath: string | undefined): boolean;
+/**
+ * Soft preflight: block scaffold into an existing non-empty project path.
+ * Returns an error message for the model, or undefined if OK to proceed.
+ */
+export declare function scaffoldTargetConflictMessage(command: string, shellCwd?: string): string | undefined;