@vextlabs/theron-cli 0.2.1 → 0.4.0

package/dist/tools/task.js

@@ -0,0 +1,166 @@
+// Task tool — bounded read-only subagent over fetch to /api/cli/chat.
+// Allows only Read/Grep/Glob/LS. Aggregate AbortController timeout (default 300s).
+// No agent_type param (CLI version).
+import { execRead } from "./read.js";
+import { execGrep } from "./grep.js";
+import { execGlob } from "./glob.js";
+import { execLs } from "./ls.js";
+import { buildLocalToolSchemas } from "@vextlabs/theron-agent-sdk";
+const MAX_TURNS = 10;
+const DEFAULT_TIMEOUT_SECONDS = 300;
+// Read-only tool schemas for the sub-agent.
+const READ_ONLY_SCHEMAS = buildLocalToolSchemas({
+    Read: "Read a file from the workspace.",
+    Grep: "Search file contents with a regex.",
+    Glob: "Find files by glob pattern.",
+    LS: "List files and directories in a path.",
+});
+const READ_ONLY_NAMES = new Set(["Read", "Grep", "Glob", "LS"]);
+const READ_ONLY_TOOL_SCHEMAS = READ_ONLY_SCHEMAS.filter((s) => READ_ONLY_NAMES.has(s.function.name));
+export async function execTask(args, ctx) {
+    if (!args.prompt || !args.prompt.trim()) {
+        return "[error] prompt must be a non-empty string.";
+    }
+    if (!ctx.apiUrl) {
+        return "[error] apiUrl not configured — cannot spawn subagent.";
+    }
+    const timeoutMs = Math.max(10_000, (args.timeout_seconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000);
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(new Error(`Task timed out after ${timeoutMs / 1000}s`)), timeoutMs);
+    try {
+        return await runTask(args, ctx, abort.signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function runTask(args, ctx, signal) {
+    const messages = [
+        { role: "user", content: args.prompt.trim() },
+    ];
+    const accumulatedText = [];
+    const label = args.description ? `[Task: ${args.description}]` : "[Task]";
+    for (let turn = 0; turn < MAX_TURNS; turn++) {
+        if (signal.aborted) {
+            return `${label}\n[error] Task timed out.\n${accumulatedText.join("")}`;
+        }
+        let response;
+        try {
+            const turnSignal = AbortSignal.any
+                ? AbortSignal.any([signal, AbortSignal.timeout(60_000)])
+                : signal;
+            response = await fetch(`${ctx.apiUrl.replace(/\/$/, "")}/api/cli/chat`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(ctx.apiKey ? { authorization: `Bearer ${ctx.apiKey}` } : {}),
+                    accept: "application/x-ndjson",
+                },
+                body: JSON.stringify({
+                    messages,
+                    tools: READ_ONLY_TOOL_SCHEMAS,
+                    surface: "cli",
+                }),
+                signal: turnSignal,
+            });
+        }
+        catch (err) {
+            return `${label}\n[error] Network error on turn ${turn + 1}: ${err instanceof Error ? err.message : String(err)}\n${accumulatedText.join("")}`;
+        }
+        if (!response.ok || !response.body) {
+            let detail = "";
+            try {
+                detail = (await response.text()).slice(0, 300);
+            }
+            catch { /* ignore */ }
+            return `${label}\n[error] HTTP ${response.status} on turn ${turn + 1}: ${detail}\n${accumulatedText.join("")}`;
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        let turnText = "";
+        const toolCalls = [];
+        let stopReason = "end_turn";
+        try {
+            outer: while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buf += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buf.indexOf("\n")) >= 0) {
+                    const line = buf.slice(0, idx).trim();
+                    buf = buf.slice(idx + 1);
+                    if (!line)
+                        continue;
+                    let frame;
+                    try {
+                        frame = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (frame.type === "text_delta" && frame.delta) {
+                        turnText += frame.delta;
+                    }
+                    else if (frame.type === "tool_call" && frame.id && frame.name && frame.args) {
+                        toolCalls.push({ id: frame.id, name: frame.name, args: frame.args });
+                    }
+                    else if (frame.type === "turn_end" && frame.stop_reason) {
+                        stopReason = frame.stop_reason;
+                        break outer;
+                    }
+                    else if (frame.type === "error" && frame.message) {
+                        return `${label}\n[error] Subagent error: ${frame.message}\n${accumulatedText.join("")}`;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            return `${label}\n[error] Stream error on turn ${turn + 1}: ${err instanceof Error ? err.message : String(err)}\n${accumulatedText.join("")}`;
+        }
+        if (turnText)
+            accumulatedText.push(turnText);
+        messages.push({ role: "assistant", content: turnText, tool_calls: toolCalls });
+        if (stopReason !== "tool_use" || toolCalls.length === 0)
+            break;
+        for (const call of toolCalls) {
+            if (!READ_ONLY_NAMES.has(call.name)) {
+                messages.push({
+                    role: "tool",
+                    tool_call_id: call.id,
+                    content: `[error] Tool "${call.name}" is not available in a read-only subagent.`,
+                });
+                continue;
+            }
+            let result;
+            try {
+                switch (call.name) {
+                    case "Read":
+                        result = await execRead(call.args, ctx);
+                        break;
+                    case "Grep":
+                        result = await execGrep(call.args, ctx);
+                        break;
+                    case "Glob":
+                        result = await execGlob(call.args, ctx);
+                        break;
+                    case "LS":
+                        result = await execLs(call.args, ctx);
+                        break;
+                    default:
+                        result = `[error] Unknown read-only tool: ${call.name}`;
+                }
+            }
+            catch (err) {
+                result = `[error] ${call.name} threw: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            messages.push({ role: "tool", tool_call_id: call.id, content: result });
+        }
+    }
+    const finalText = accumulatedText.join("").trim();
+    if (!finalText)
+        return `${label}\n[subagent returned no text]`;
+    return `${label}\n${finalText}`;
+}
+//# sourceMappingURL=task.js.map

package/dist/tools/task.js.map

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

package/dist/tools/todowrite.d.ts

@@ -0,0 +1,12 @@
+import type { ToolContext } from "./index.js";
+export interface TodoItem {
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm?: string;
+}
+interface TodoWriteArgs {
+    todos: TodoItem[];
+}
+export declare function execTodoWrite(args: TodoWriteArgs, _ctx: ToolContext): Promise<string>;
+export declare function describeCurrentList(): string;
+export {};

package/dist/tools/todowrite.js

@@ -0,0 +1,38 @@
+// TodoWrite tool — structured task list for the current session.
+// Module-level state persists across tool calls within one CLI session.
+// Module-level state — persists for the CLI session.
+let todoList = [];
+export async function execTodoWrite(args, _ctx) {
+    if (!Array.isArray(args.todos)) {
+        return "[error] todos must be an array.";
+    }
+    for (const item of args.todos) {
+        if (typeof item.content !== "string" || !item.content.trim()) {
+            return "[error] Each todo must have a non-empty string content field.";
+        }
+        if (!["pending", "in_progress", "completed"].includes(item.status)) {
+            return `[error] Invalid status "${item.status}" — must be pending, in_progress, or completed.`;
+        }
+    }
+    todoList = args.todos.map((t) => ({
+        content: t.content,
+        status: t.status,
+        activeForm: t.activeForm ?? "",
+    }));
+    return renderList(todoList);
+}
+function renderList(list) {
+    if (list.length === 0)
+        return "Todo list is empty.";
+    const lines = list.map((item) => {
+        const mark = item.status === "completed" ? "[x]" :
+            item.status === "in_progress" ? "[~]" :
+                "[ ]";
+        return `${mark} ${item.content}`;
+    });
+    return lines.join("\n");
+}
+export function describeCurrentList() {
+    return renderList(todoList);
+}
+//# sourceMappingURL=todowrite.js.map

package/dist/tools/todowrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todowrite.js","sourceRoot":"","sources":["../../src/tools/todowrite.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,wEAAwE;AAUxE,qDAAqD;AACrD,IAAI,QAAQ,GAAe,EAAE,CAAC;AAM9B,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAmB,EAAE,IAAiB;IACxE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,iCAAiC,CAAC;IAC3C,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YAC7D,OAAO,+DAA+D,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACnE,OAAO,2BAA2B,IAAI,CAAC,MAAM,iDAAiD,CAAC;QACjG,CAAC;IACH,CAAC;IACD,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChC,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,EAAE;KAC/B,CAAC,CAAC,CAAC;IACJ,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,UAAU,CAAC,IAAgB;IAClC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,qBAAqB,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC9B,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACrC,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;gBACvC,KAAK,CAAC;QACR,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/webfetch.d.ts

@@ -0,0 +1,6 @@
+import type { ToolContext } from "./index.js";
+interface WebFetchArgs {
+    url: string;
+}
+export declare function execWebFetch(args: WebFetchArgs, ctx: ToolContext): Promise<string>;
+export {};

package/dist/tools/webfetch.js

@@ -0,0 +1,98 @@
+// WebFetch tool — fetches a URL, strips HTML to readable text, 15s timeout,
+// truncates to ctx.maxBytes. SSRF guard rejects file://, loopback, and
+// private IP ranges.
+// Patterns to strip from HTML before returning to the model.
+const SCRIPT_STYLE_RE = /<(script|style)[^>]*>[\s\S]*?<\/\1>/gi;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const HTML_TAG_RE = /<[^>]+>/g;
+const MULTI_BLANK_RE = /\n{3,}/g;
+/** Returns an error string if the URL should be rejected, else null. */
+function ssrfCheck(parsed) {
+    if (parsed.protocol === "file:")
+        return "file: protocol is not allowed.";
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return `protocol "${parsed.protocol}" is not allowed; only http: and https: are permitted.`;
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") {
+        return `host "${host}" is a loopback address and is not allowed.`;
+    }
+    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const [, a, b] = v4.map(Number);
+        if (a === 10)
+            return `host "${host}" is in a private IP range and is not allowed.`;
+        if (a === 172 && b >= 16 && b <= 31)
+            return `host "${host}" is in a private IP range and is not allowed.`;
+        if (a === 192 && b === 168)
+            return `host "${host}" is in a private IP range and is not allowed.`;
+        if (a === 169 && b === 254)
+            return `host "${host}" is a link-local address and is not allowed.`;
+    }
+    return null;
+}
+export async function execWebFetch(args, ctx) {
+    let parsed;
+    try {
+        parsed = new URL(args.url);
+    }
+    catch {
+        return `[error] Invalid URL: ${args.url}`;
+    }
+    const ssrfErr = ssrfCheck(parsed);
+    if (ssrfErr)
+        return `[error] SSRF guard: ${ssrfErr}`;
+    const url = parsed.toString();
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: {
+                "user-agent": "Mozilla/5.0 (compatible; TheronCLI/1.0; +https://itstheron.com)",
+                "accept": "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8",
+            },
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (err) {
+        return `[error] Fetch failed for ${url}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (!response.ok) {
+        return `[error] HTTP ${response.status} ${response.statusText} for ${url}`;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    let body;
+    try {
+        body = await response.text();
+    }
+    catch (err) {
+        return `[error] Could not read response body: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    let text;
+    if (contentType.includes("html")) {
+        text = body
+            .replace(SCRIPT_STYLE_RE, " ")
+            .replace(HTML_COMMENT_RE, " ")
+            .replace(HTML_TAG_RE, " ")
+            .replace(/&nbsp;/g, " ")
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .replace(/[ \t]+/g, " ")
+            .replace(/^ +/gm, "")
+            .replace(MULTI_BLANK_RE, "\n\n")
+            .trim();
+    }
+    else {
+        text = body;
+    }
+    const cap = ctx.maxBytes;
+    const note = Buffer.byteLength(text, "utf-8") > cap ? "\n[content truncated to maxBytes]" : "";
+    if (Buffer.byteLength(text, "utf-8") > cap) {
+        const buf = Buffer.from(text, "utf-8");
+        text = buf.slice(0, cap).toString("utf-8");
+    }
+    return `${url}\n${text}${note}`;
+}
+//# sourceMappingURL=webfetch.js.map

package/dist/tools/webfetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webfetch.js","sourceRoot":"","sources":["../../src/tools/webfetch.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,uEAAuE;AACvE,qBAAqB;AAQrB,6DAA6D;AAC7D,MAAM,eAAe,GAAG,uCAAuC,CAAC;AAChE,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,MAAM,WAAW,GAAG,UAAU,CAAC;AAC/B,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,wEAAwE;AACxE,SAAS,SAAS,CAAC,MAAW;IAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,gCAAgC,CAAC;IACzE,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,aAAa,MAAM,CAAC,QAAQ,wDAAwD,CAAC;IAC9F,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACvF,OAAO,SAAS,IAAI,6CAA6C,CAAC;IACpE,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;IACtE,IAAI,EAAE,EAAE,CAAC;QACP,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,SAAS,IAAI,gDAAgD,CAAC;QACnF,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO,SAAS,IAAI,gDAAgD,CAAC;QAC1G,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,SAAS,IAAI,gDAAgD,CAAC;QACjG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,SAAS,IAAI,+CAA+C,CAAC;IAClG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAkB,EAAE,GAAgB;IACrE,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,wBAAwB,IAAI,CAAC,GAAG,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,OAAO;QAAE,OAAO,uBAAuB,OAAO,EAAE,CAAC;IAErD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC9B,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,OAAO,EAAE;gBACP,YAAY,EAAE,iEAAiE;gBAC/E,QAAQ,EAAE,4DAA4D;aACvE;YACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;SACpC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,4BAA4B,GAAG,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAChG,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,gBAAgB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,QAAQ,GAAG,EAAE,CAAC;IAC7E,CAAC;IAED,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC/D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,yCAAyC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACrG,CAAC;IAED,IAAI,IAAY,CAAC;IACjB,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,IAAI,GAAG,IAAI;aACR,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;aAC7B,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;aAC7B,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC;aACzB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;aACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;aACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;aACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;aACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;aACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;aACtB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;aACvB,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;aACpB,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC;aAC/B,IAAI,EAAE,CAAC;IACZ,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/F,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,GAAG,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,GAAG,GAAG,KAAK,IAAI,GAAG,IAAI,EAAE,CAAC;AAClC,CAAC"}

package/dist/tools/websearch.d.ts

@@ -0,0 +1,7 @@
+import type { ToolContext } from "./index.js";
+interface WebSearchArgs {
+    query: string;
+    max_results?: number;
+}
+export declare function execWebSearch(args: WebSearchArgs, _ctx: ToolContext): Promise<string>;
+export {};

package/dist/tools/websearch.js

@@ -0,0 +1,83 @@
+// WebSearch tool — DuckDuckGo HTML scrape returning title + URL + snippet.
+// No API key required.
+const MAX_RESULTS_CAP = 20;
+const DEFAULT_MAX = 10;
+const RESULT_LINK_RE = /<a[^>]+class="[^"]*result__a[^"]*"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+const HTML_ENTITY_RE = /&[a-z]+;|&#\d+;/gi;
+const HTML_TAG_INLINE_RE = /<[^>]+>/g;
+function decodeEntities(s) {
+    return s
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, " ")
+        .replace(HTML_ENTITY_RE, " ");
+}
+function stripTags(s) {
+    return s.replace(HTML_TAG_INLINE_RE, "").trim();
+}
+export async function execWebSearch(args, _ctx) {
+    if (!args.query || !args.query.trim()) {
+        return "[error] query must be a non-empty string.";
+    }
+    const maxResults = Math.min(args.max_results && args.max_results > 0 ? args.max_results : DEFAULT_MAX, MAX_RESULTS_CAP);
+    const encoded = encodeURIComponent(args.query.trim());
+    const searchUrl = `https://html.duckduckgo.com/html/?q=${encoded}`;
+    let response;
+    try {
+        response = await fetch(searchUrl, {
+            headers: {
+                "user-agent": "Mozilla/5.0 (compatible; TheronCLI/1.0; +https://itstheron.com)",
+                "accept": "text/html,*/*;q=0.8",
+                "accept-language": "en-US,en;q=0.9",
+            },
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (err) {
+        return `[error] Search request failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (!response.ok) {
+        return `[error] DuckDuckGo returned HTTP ${response.status} for "${args.query}"`;
+    }
+    let html;
+    try {
+        html = await response.text();
+    }
+    catch (err) {
+        return `[error] Could not read search response: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const results = [];
+    let match;
+    RESULT_LINK_RE.lastIndex = 0;
+    while ((match = RESULT_LINK_RE.exec(html)) !== null && results.length < maxResults) {
+        const rawHref = match[1];
+        const rawTitle = match[2];
+        const title = decodeEntities(stripTags(rawTitle)).replace(/\s+/g, " ").trim();
+        if (!title)
+            continue;
+        let url = rawHref;
+        try {
+            const hrefUrl = new URL(rawHref, "https://html.duckduckgo.com");
+            const uddg = hrefUrl.searchParams.get("uddg");
+            if (uddg) {
+                url = decodeURIComponent(uddg);
+            }
+            else {
+                url = hrefUrl.toString();
+            }
+        }
+        catch { /* keep rawHref */ }
+        if (!url || url.startsWith("https://duckduckgo.com"))
+            continue;
+        results.push({ title, url });
+    }
+    if (results.length === 0) {
+        return `[no results found for "${args.query}"]`;
+    }
+    const lines = results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}`);
+    return `Web search: "${args.query}" (${results.length} result${results.length === 1 ? "" : "s"})\n\n${lines.join("\n\n")}`;
+}
+//# sourceMappingURL=websearch.js.map

package/dist/tools/websearch.js.map

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

package/dist/tools/write.js

@@ -3,13 +3,29 @@
 // already passed.
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { sha256Hex, receiptLocalAction } from "../receipt.js";
+import { snapshot } from "../checkpoints.js";
 export async function execWrite(args, ctx) {
     const target = path.isAbsolute(args.file_path)
         ? args.file_path
         : path.resolve(ctx.cwd, args.file_path);
+    // Snapshot the file's current content BEFORE overwriting so /rewind can
+    // restore it.  Fail-safe: a read error (file missing, permission denied)
+    // is swallowed — the write still proceeds normally.
+    await snapshot(target).catch(() => undefined);
     await fs.mkdir(path.dirname(target), { recursive: true });
     await fs.writeFile(target, args.content, "utf-8");
+    const byteLen = Buffer.byteLength(args.content, "utf-8");
     const lineCount = args.content.split(/\r?\n/).length;
-    return `Wrote ${target} (${lineCount} lines, ${Buffer.byteLength(args.content, "utf-8")} bytes)`;
+    const baseResult = `Wrote ${target} (${lineCount} lines, ${byteLen} bytes)`;
+    // Mint a STOA receipt for this write. Fail-open: if the receipt POST
+    // fails, the base result is returned unmodified.
+    const postSha256 = sha256Hex(args.content);
+    const verifyUrl = await receiptLocalAction(ctx.apiUrl, ctx.apiKey, "local_write", {
+        path: target,
+        bytes: byteLen,
+        post_sha256: postSha256,
+    }).catch(() => null);
+    return verifyUrl ? baseResult + "\nsigned -- verify: " + verifyUrl : baseResult;
 }
 //# sourceMappingURL=write.js.map

package/dist/tools/write.js.map

@@ -1 +1 @@
-{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qEAAqE;AACrE,kBAAkB;AAElB,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAe,EAAE,GAAgB;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;QAC5C,CAAC,CAAC,IAAI,CAAC,SAAS;QAChB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAE1C,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACrD,OAAO,SAAS,MAAM,KAAK,SAAS,WAAW,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC;AACnG,CAAC"}
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qEAAqE;AACrE,kBAAkB;AAElB,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAO7C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAe,EAAE,GAAgB;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;QAC5C,CAAC,CAAC,IAAI,CAAC,SAAS;QAChB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAE1C,wEAAwE;IACxE,yEAAyE;IACzE,oDAAoD;IACpD,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAE9C,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACrD,MAAM,UAAU,GAAG,SAAS,MAAM,KAAK,SAAS,WAAW,OAAO,SAAS,CAAC;IAE5E,qEAAqE;IACrE,iDAAiD;IACjD,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,kBAAkB,CACxC,GAAG,CAAC,MAAM,EACV,GAAG,CAAC,MAAM,EACV,aAAa,EACb;QACE,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,OAAO;QACd,WAAW,EAAE,UAAU;KACxB,CACF,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAEpB,OAAO,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG,sBAAsB,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;AAClF,CAAC"}

package/dist/verifiers/calc_gate.d.ts

@@ -0,0 +1,2 @@
+import type { Verifier } from "./types.js";
+export declare const calcGateKernel: Verifier;

package/dist/verifiers/calc_gate.js

@@ -0,0 +1,112 @@
+// Calc-gate verifier — the deterministic teeth behind the numeric
+// methodology's "show the work" invariant.
+//
+// The throughline for finance / data / math (and the numeric trades —
+// trader / engineer / realtor) is: a number you COMPUTED must arrive with
+// the computation that produced it. A bare asserted result figure — "the
+// IRR is 14.3%", "the LTV/CAC is 3.2x", "the NPV is $1.24M", "the deflection
+// is 4.7mm" — with no derivation is the failure mode this gate catches. It
+// runs on the numeric profiles only.
+//
+// How it differs from arithmetic_recheck (the existing numeric kernel):
+//   - arithmetic_recheck takes an explicit "X op Y = Z" line and re-evaluates
+//     it — it catches WRONG math that's already shown.
+//   - calc_gate catches MISSING math: a derived headline figure asserted with
+//     no visible derivation at all. The two are complementary — recheck
+//     proves shown work is right; calc_gate proves the work was shown.
+//
+// How it works:
+//   1. Scan the output for a COMPUTED-RESULT assertion: a named computed
+//      quantity (IRR, NPV, ROI, LTV/CAC, margin, CAGR, payback, deflection,
+//      stress, mean, median, std dev, p-value, total, etc.) stated as a
+//      concrete value ("= 14.3%", "is $1.24M", "comes to 3.2x").
+//   2. If such a claim is present, check for DERIVATION evidence anywhere in
+//      the output: an arithmetic line (a + b = c), a formula, a fenced code/
+//      calc block, a python calculator call, a stated set of inputs, or a
+//      worked table. Any of these proves the number wasn't conjured.
+//   3. A computed figure asserted with NO derivation is a BLOCK — fed back so
+//      the model shows the steps before the number stands.
+//
+// Conservative by design: it only fires when a RESULT-NAMED quantity is
+// stated as a hard value. Round-number context ("we have ~10 customers"),
+// inputs the user gave ("at a 10% discount rate"), questions, and figures the
+// model explicitly flags as estimates/assumptions all pass. The guard below
+// keeps it off honest "rough estimate" language.
+const APPLIES_TO_PROFILES = new Set([
+    "finance",
+    "data",
+    "math",
+    "trader",
+    "engineer",
+    "realtor",
+]);
+// Only gate substantive outputs — a one-line "the total is 5" aside isn't a
+// derivation-worthy result.
+const MIN_LENGTH_TO_GATE = 160;
+// COMPUTED-RESULT assertion: a named, derived quantity stated as a concrete
+// value. The quantity name is what marks it as COMPUTED (you don't "measure"
+// an IRR, you compute it), so a bare value next to one of these names implies
+// a calculation must exist.
+const NAMED_RESULT = "irr|npv|roi|roic|roe|cagr|ltv\\s*/?\\s*cac|ltv|cac|payback(?:\\s+period)?|gross\\s+margin|net\\s+margin|ebitda|arr|mrr|burn\\s+rate|runway|wacc|dcf|cap\\s+rate|cash[- ]on[- ]cash|dscr|noi|break[- ]even|deflection|bending\\s+(?:moment|stress)|shear|torque|stress|strain|moment\\s+of\\s+inertia|resistance|voltage|current|the\\s+mean|the\\s+median|the\\s+average|std(?:\\.|\\s+dev)?|standard\\s+deviation|variance|p[- ]value|correlation|r\\^?2|r[- ]squared|the\\s+total|the\\s+sum|the\\s+result|the\\s+(?:projected|expected)\\s+\\w+";
+// A concrete value token: a number with optional currency/unit/percent/x.
+const VALUE = "[\\$€£]?-?\\d[\\d,]*(?:\\.\\d+)?\\s*(?:%|x|bps|mm|cm|m|kg|n|nm|kn|mpa|psi|v|a|ω|ohm|years?|months?|days?|k|m|b|bn|mn)?";
+const CLAIM_PATTERNS = [
+    // "the IRR is 14.3%", "NPV = $1.24M", "LTV/CAC comes to 3.2x"
+    new RegExp(`\\b(?:${NAMED_RESULT})\\b[^.\\n]{0,30}\\b(?:is|=|comes?\\s+(?:to|out\\s+to)|works?\\s+out\\s+to|equals?|totals?|of)\\b\\s*(?:approximately\\s+|roughly\\s+|about\\s+|~)?${VALUE}`, "i"),
+    // "= 14.3%" immediately following a named result within a tight window
+    new RegExp(`\\b(?:${NAMED_RESULT})\\b[^=\\n]{0,20}=\\s*${VALUE}`, "i"),
+];
+// GUARD: the model being honest that a figure is a rough estimate / placeholder
+// / illustrative, or asking for inputs, doesn't need a full derivation shown —
+// that's honest uncertainty, which we reward. Also guards values the user
+// themselves supplied as an input ("at your stated 10% rate").
+const GUARD = /\b(?:rough(?:ly)?\s+estimate|ballpark|placeholder|illustrative|for\s+example|let'?s\s+(?:say|assume)|hypothetical|order\s+of\s+magnitude|i\s+don'?t\s+have|i\s+can'?t\s+(?:compute|calculate)|need\s+(?:the|more)\s+(?:inputs?|data|numbers?)|what\s+(?:is|are)\s+your|you\s+(?:said|gave|specified|provided)|as\s+you\s+(?:stated|noted))\b/i;
+// DERIVATION evidence — proof the number came from a calculation.
+const DERIVATION_EVIDENCE = [
+    /[\$€£]?-?\d[\d,]*(?:\.\d+)?\s*[+\-*/×÷]\s*[\$€£]?-?\d[\d,]*(?:\.\d+)?/, // an arithmetic expression a op b
+    /=\s*[\$€£]?-?\d[\d,]*(?:\.\d+)?\s*[+\-*/×÷]/, // = a op b ...
+    /```[\s\S]*?```/, // a fenced calc / code block
+    /\bpython3?\b[^.\n]{0,40}\b(?:-c|print|=)/i, // a python calculator call
+    /\b(?:formula|equation|derivation|calculation|computed\s+as|worked\s+out|step\s*\d|step[- ]by[- ]step)\b/i,
+    /\b(?:where|given|inputs?|assumptions?)\b\s*[:\-][^.\n]{0,40}=/i, // a "given: x = ..., y = ..." inputs block
+    /\|\s*[-:]+\s*\|/, // a markdown table separator (a worked table)
+    /\b(?:sum|total|mean|average)\s*(?:of)?\s*\([^)]*[+,][^)]*\)/i, // sum(a, b, c) / mean(...)
+    /\(\s*[\$€£]?-?\d[\d,]*(?:\.\d+)?[^)]*[+\-*/×÷][^)]*\)/, // a parenthesized expression (a + b)
+];
+function anyMatch(patterns, text) {
+    return patterns.some((re) => re.test(text));
+}
+export const calcGateKernel = {
+    slug: "calc_gate",
+    describe: "Numeric domains: a computed result figure (IRR, NPV, margin, deflection, mean, …) must show the calculation/derivation, not just assert the number",
+    async run(ctx) {
+        if (!APPLIES_TO_PROFILES.has(ctx.profile))
+            return [];
+        const text = ctx.assistantText;
+        if (text.length < MIN_LENGTH_TO_GATE)
+            return [];
+        // Is there a named computed-result assertion at all?
+        const claimMatch = CLAIM_PATTERNS.map((re) => re.exec(text)).find(Boolean);
+        if (!claimMatch)
+            return [];
+        // Guard: rough estimate / user-supplied input / "I can't compute" — these
+        // don't need a derivation shown. Inspect a window around the match.
+        const idx = claimMatch.index ?? 0;
+        const window = text.slice(Math.max(0, idx - 90), idx + (claimMatch[0]?.length ?? 0) + 90);
+        if (GUARD.test(window))
+            return [];
+        // Does the output show the work anywhere?
+        if (anyMatch(DERIVATION_EVIDENCE, text))
+            return [];
+        return [
+            {
+                severity: "block",
+                kernel: "calc_gate",
+                message: `A computed figure ("${claimMatch[0].slice(0, 60).trim()}…") is asserted with no visible calculation. ` +
+                    `Per the methodology for numeric work: show the work — the arithmetic, formula, inputs, or a worked table that produces the number. ` +
+                    `A bare result the reader can't reproduce is a hypothesis, not an answer.`,
+            },
+        ];
+    },
+};
+//# sourceMappingURL=calc_gate.js.map

package/dist/verifiers/calc_gate.js.map

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

package/dist/verifiers/citation_gate.d.ts

@@ -0,0 +1,2 @@
+import type { Verifier } from "./types.js";
+export declare const citationGateKernel: Verifier;