@inflexa-ai/harness 0.46.2 → 0.48.0

package/dist/lib/markdown-pdf.js

@@ -0,0 +1,236 @@
+/**
+ * A PDF from markdown, on `marked` and `pdfmake`, with no browser.
+ *
+ * `marked` gives the token tree, and each token maps to a `pdfmake` node: a heading, a paragraph, a list, a GFM table,
+ * a code block, a quote, a rule, and an image. An SVG image, for example a chart of `render_chart`, lands as vector
+ * graphics. The text font is the Roboto that `pdfmake` ships, which holds the Greek letters and the common math signs.
+ *
+ * `pdfmake` resolves a font by a file path, also inside an SVG, thus the fonts land one time in a private temporary
+ * directory. Each URL is refused, and a local path is refused unless it is one of those font files, thus a document
+ * reads nothing that the caller did not give it.
+ */
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { lexer } from "marked";
+import { z } from "zod";
+/** The token kinds of the lexer of `marked`. */
+const MARKED_KINDS = new Set([
+    "blockquote",
+    "br",
+    "checkbox",
+    "code",
+    "codespan",
+    "def",
+    "del",
+    "em",
+    "escape",
+    "heading",
+    "hr",
+    "html",
+    "image",
+    "link",
+    "list",
+    "list_item",
+    "paragraph",
+    "space",
+    "strong",
+    "table",
+    "tag",
+    "text",
+]);
+/**
+ * A token of one of the kinds of the lexer. No extension of `marked` is registered, thus a token with one of these
+ * kinds has the shape of that kind.
+ */
+function isMarkedToken(token) {
+    return MARKED_KINDS.has(token.type);
+}
+/** The tokens of the lexer as its own kinds. */
+function tokensOf(tokens) {
+    return (tokens ?? []).filter(isMarkedToken);
+}
+const FontFilesSchema = z.record(z.string(), z.string());
+/** The width of the text block of an A4 page with the margins of {@link documentOf}, in points. */
+const TEXT_WIDTH = 515;
+const FONT_FILES = {
+    normal: "Roboto-Regular.ttf",
+    bold: "Roboto-Medium.ttf",
+    italics: "Roboto-Italic.ttf",
+    bolditalics: "Roboto-MediumItalic.ttf",
+};
+let ready;
+/** The `pdfmake` instance with the fonts on disk and the access policies set. It is set up one time for each process. */
+function pdfmakeOf() {
+    ready ??= (async () => {
+        const { default: pdfmake } = await import("pdfmake");
+        const vfsModule = await import("pdfmake/build/vfs_fonts.js");
+        const vfs = FontFilesSchema.parse(Reflect.get(Object(vfsModule), "default"));
+        const dir = await mkdtemp(join(tmpdir(), "pdf-fonts-"));
+        const paths = {};
+        for (const [style, file] of Object.entries(FONT_FILES)) {
+            const data = vfs[file];
+            if (data === undefined)
+                throw new Error(`pdfmake ships no font file ${file}`);
+            paths[style] = join(dir, file);
+            await writeFile(join(dir, file), Buffer.from(data, "base64"));
+        }
+        const fontPaths = new Set(Object.values(paths));
+        pdfmake.setFonts({ Roboto: paths });
+        pdfmake.setUrlAccessPolicy(() => false);
+        pdfmake.setLocalAccessPolicy((path) => fontPaths.has(path));
+        return pdfmake;
+    })();
+    return ready;
+}
+/** The text runs of inline tokens, with the styles of the marks that hold them. */
+function inline(tokens, images) {
+    const out = [];
+    for (const token of tokensOf(tokens)) {
+        switch (token.type) {
+            case "strong":
+                out.push({ text: inline(token.tokens, images), bold: true });
+                break;
+            case "em":
+                out.push({ text: inline(token.tokens, images), italics: true });
+                break;
+            case "del":
+                out.push({ text: inline(token.tokens, images), decoration: "lineThrough" });
+                break;
+            case "codespan":
+                out.push({ text: token.text, background: "#f2f2f2" });
+                break;
+            case "link":
+                out.push({ text: inline(token.tokens, images), link: token.href, color: "#1a5fb4", decoration: "underline" });
+                break;
+            case "br":
+                out.push({ text: "\n" });
+                break;
+            case "image":
+                out.push({ text: token.text, italics: true });
+                break;
+            case "text":
+                out.push(token.tokens === undefined ? { text: token.text } : { text: inline(token.tokens, images) });
+                break;
+            case "escape":
+                out.push({ text: token.text });
+                break;
+            default:
+                out.push({ text: token.raw });
+        }
+    }
+    return out;
+}
+/** An image of a paragraph that holds one image alone, with its alt text as the caption. */
+function imageNode(token, images) {
+    const image = images.get(token.href);
+    const caption = token.text.length > 0 ? [{ text: token.text, style: "caption" }] : [];
+    if (image === undefined)
+        return [{ text: `[${token.text || token.href}]`, italics: true }];
+    if (image.kind === "svg")
+        return [{ svg: image.svg, width: TEXT_WIDTH, margin: [0, 6, 0, 2] }, ...caption];
+    const data = `data:image/${image.kind};base64,${Buffer.from(image.bytes).toString("base64")}`;
+    return [{ image: data, fit: [TEXT_WIDTH, 600], margin: [0, 6, 0, 2] }, ...caption];
+}
+function blocks(tokens, images) {
+    const out = [];
+    for (const token of tokensOf(tokens)) {
+        switch (token.type) {
+            case "heading":
+                out.push({ text: inline(token.tokens, images), style: `h${String(Math.min(token.depth, 4))}` });
+                break;
+            case "paragraph": {
+                const parts = tokensOf(token.tokens);
+                const only = parts.length === 1 ? parts[0] : undefined;
+                if (only?.type === "image")
+                    out.push(...imageNode(only, images));
+                else
+                    out.push({ text: inline(token.tokens, images), style: "paragraph" });
+                break;
+            }
+            case "list":
+                out.push({
+                    [token.ordered ? "ol" : "ul"]: token.items.map((item) => ({ stack: blocks(item.tokens, images) })),
+                    style: "list",
+                });
+                break;
+            case "table":
+                out.push({
+                    table: {
+                        headerRows: 1,
+                        widths: token.header.map(() => "*"),
+                        body: [
+                            token.header.map((cell) => ({ text: inline(cell.tokens, images), bold: true })),
+                            ...token.rows.map((row) => row.map((cell) => ({ text: inline(cell.tokens, images) }))),
+                        ],
+                    },
+                    layout: "lightHorizontalLines",
+                    style: "table",
+                });
+                break;
+            case "code":
+                out.push({ text: token.text, style: "code", preserveLeadingSpaces: true });
+                break;
+            case "blockquote":
+                out.push({ stack: blocks(token.tokens, images), style: "quote" });
+                break;
+            case "hr":
+                out.push({ canvas: [{ type: "line", x1: 0, y1: 0, x2: TEXT_WIDTH, y2: 0, lineWidth: 0.5, lineColor: "#999999" }], margin: [0, 8, 0, 8] });
+                break;
+            case "text":
+                out.push({ text: inline(token.tokens, images), style: "paragraph" });
+                break;
+            default:
+                // A space, an HTML block, or a link definition prints nothing.
+                break;
+        }
+    }
+    return out;
+}
+/** The source of each image of a markdown text, in the order of the text. */
+export function markdownImageSources(markdown) {
+    const sources = [];
+    const walk = (tokens) => {
+        for (const token of tokensOf(tokens)) {
+            if (token.type === "image")
+                sources.push(token.href);
+            if (token.type === "list")
+                for (const item of token.items)
+                    walk(item.tokens);
+            else if (token.type === "table")
+                for (const cell of [...token.header, ...token.rows.flat()])
+                    walk(cell.tokens);
+            else if ("tokens" in token)
+                walk(token.tokens);
+        }
+    };
+    walk(lexer(markdown));
+    return [...new Set(sources)];
+}
+function documentOf(markdown, title, images) {
+    return {
+        info: title === undefined ? {} : { title },
+        pageSize: "A4",
+        pageMargins: [40, 48, 40, 48],
+        content: [...(title === undefined ? [] : [{ text: title, style: "title" }]), ...blocks(lexer(markdown), images)],
+        defaultStyle: { font: "Roboto", fontSize: 10, lineHeight: 1.25 },
+        styles: {
+            title: { fontSize: 20, bold: true, margin: [0, 0, 0, 12] },
+            h1: { fontSize: 16, bold: true, margin: [0, 12, 0, 6] },
+            h2: { fontSize: 13, bold: true, margin: [0, 10, 0, 4] },
+            h3: { fontSize: 11, bold: true, margin: [0, 8, 0, 4] },
+            h4: { fontSize: 10, bold: true, margin: [0, 6, 0, 2] },
+            paragraph: { margin: [0, 0, 0, 6] },
+            list: { margin: [0, 0, 0, 6] },
+            table: { fontSize: 9, margin: [0, 4, 0, 8] },
+            code: { fontSize: 8.5, background: "#f2f2f2", margin: [0, 2, 0, 8] },
+            quote: { color: "#555555", italics: true, margin: [12, 0, 0, 6] },
+            caption: { fontSize: 8.5, italics: true, color: "#555555", alignment: "center", margin: [0, 0, 0, 8] },
+        },
+    };
+}
+/** The PDF of a markdown text. `images` holds each image that the text names, by its source. */
+export async function markdownToPdf(args) {
+    const pdfmake = await pdfmakeOf();
+    return pdfmake.createPdf(documentOf(args.markdown, args.title, args.images)).getBuffer();
+}

package/dist/lib/metrics.d.ts

@@ -10,6 +10,9 @@
  *   - cortex.sandbox.exec.duration{outcome}       — histogram, the runtime the sandbox reported for that exec
  *   - cortex.sandbox.exec.peak_memory_bytes{outcome} — histogram, the peak resident set of that exec
  *   - cortex.sandbox.exec.cpu_seconds{outcome}    — histogram, the CPU time of that exec
+ *   - cortex.sandbox.lease.wait{backend}          — histogram, from a lease request to its grant
+ *   - cortex.sandbox.machine.start{backend}       — histogram, from a spawn to the health of the machine
+ *   - cortex.sandbox.machine.replaced{cause}      — counter, one per machine of a lease that went away
  *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
@@ -31,6 +34,7 @@
  * proxy: a meter taken at module load, before `initOtel` runs, would stay
  * on the no-op provider for the life of the process.
  */
+import type { WorkKind } from "../contracts/chat-parts.js";
 import type { StepExecutionStatus } from "../state/schema.js";
 /** Terminal status of a run, the same as the run ledger. */
 export type RunOutcome = "completed" | "partial" | "failed" | "canceled";
@@ -71,6 +75,13 @@ export declare const SANDBOX_PEAK_MEMORY_BOUNDS_BYTES: readonly number[];
  * granting.
  */
 export declare const SANDBOX_CPU_SECONDS_BOUNDS: readonly number[];
+/**
+ * Bucket bounds for a cold start and for a wait in the lease queue: 1, 5, 15, 30 s, then 1, 2, 5, 10, 30, 60 min.
+ * A machine on a ready node starts in seconds, and a new node or a full local budget takes minutes.
+ */
+export declare const SANDBOX_WAIT_BOUNDS_MS: readonly number[];
+/** Why a machine of a lease went away. */
+export type MachineReplacementCause = "idle" | "dead" | "oom" | "release";
 /**
  * Record one run that reached a terminal status. Call it inside the DBOS step
  * that persists that status, or behind the ledger compare-and-set that accepted
@@ -122,6 +133,26 @@ export declare function recordSandboxExec(args: {
     readonly peakMemoryBytes?: number | undefined;
     readonly cpuMillis?: number | undefined;
 }): void;
+/** Record the wait of one lease from its request to its grant. Call it in the step that took the grant. */
+export declare function recordLeaseWait(args: {
+    readonly backend: string;
+    readonly waitMs: number;
+}): void;
+/** Record the time from one spawn to the health of the machine. Call it in the step of the spawn. */
+export declare function recordMachineStart(args: {
+    readonly backend: string;
+    readonly startMs: number;
+}): void;
+/** Record one machine of a lease that went away. Call it in the step that removed it. */
+export declare function recordMachineReplaced(args: {
+    readonly cause: MachineReplacementCause;
+}): void;
+/** Count one lease workflow that runs in this process, until the returned function runs. */
+export declare function trackLeaseWorkflow(): () => void;
+/** Count one workflow body that waits in a pause in this process, until the returned function runs. */
+export declare function trackWorkPaused(args: {
+    readonly workKind: WorkKind;
+}): () => void;
 /** Record one manifest entry dropped at reconcile. */
 export declare function recordArtifactReconcileDropped(args: {
     readonly agentId: string;

package/dist/lib/metrics.js

@@ -10,6 +10,9 @@
  *   - cortex.sandbox.exec.duration{outcome}       — histogram, the runtime the sandbox reported for that exec
  *   - cortex.sandbox.exec.peak_memory_bytes{outcome} — histogram, the peak resident set of that exec
  *   - cortex.sandbox.exec.cpu_seconds{outcome}    — histogram, the CPU time of that exec
+ *   - cortex.sandbox.lease.wait{backend}          — histogram, from a lease request to its grant
+ *   - cortex.sandbox.machine.start{backend}       — histogram, from a spawn to the health of the machine
+ *   - cortex.sandbox.machine.replaced{cause}      — counter, one per machine of a lease that went away
  *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
@@ -60,6 +63,11 @@ export const SANDBOX_PEAK_MEMORY_BOUNDS_BYTES = [
  * granting.
  */
 export const SANDBOX_CPU_SECONDS_BOUNDS = [0.5, 1, 5, 15, 60, 300, 900, 1_800, 3_600, 14_400];
+/**
+ * Bucket bounds for a cold start and for a wait in the lease queue: 1, 5, 15, 30 s, then 1, 2, 5, 10, 30, 60 min.
+ * A machine on a ready node starts in seconds, and a new node or a full local budget takes minutes.
+ */
+export const SANDBOX_WAIT_BOUNDS_MS = [1_000, 5_000, 15_000, 30_000, 60_000, 120_000, 300_000, 600_000, 1_800_000, 3_600_000];
 let instruments;
 function getInstruments() {
     if (instruments === undefined) {
@@ -103,6 +111,28 @@ function getInstruments() {
                 unit: "s",
                 advice: { explicitBucketBoundaries: [...SANDBOX_CPU_SECONDS_BOUNDS] },
             }),
+            sandboxLeaseWait: meter.createHistogram("cortex.sandbox.lease.wait", {
+                description: "Wait of a sandbox lease from its request to its grant. Tagged by backend.",
+                unit: "ms",
+                advice: { explicitBucketBoundaries: [...SANDBOX_WAIT_BOUNDS_MS] },
+            }),
+            sandboxMachineStart: meter.createHistogram("cortex.sandbox.machine.start", {
+                description: "Time from the spawn of a sandbox machine to its health. Tagged by backend.",
+                unit: "ms",
+                advice: { explicitBucketBoundaries: [...SANDBOX_WAIT_BOUNDS_MS] },
+            }),
+            sandboxMachineReplaced: meter.createCounter("cortex.sandbox.machine.replaced", {
+                description: "Machines of a lease that went away. Tagged by cause.",
+                unit: "{machine}",
+            }),
+            sandboxLeaseWorkflows: meter.createUpDownCounter("cortex.sandbox.lease.workflows", {
+                description: "Lease workflows that run in this process. Each one waits in memory for the life of its lease.",
+                unit: "{workflow}",
+            }),
+            workPaused: meter.createUpDownCounter("cortex.work.paused", {
+                description: "Workflow bodies that wait in a pause in this process. Tagged by work_kind.",
+                unit: "{workflow}",
+            }),
             artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
                 description: "Manifest entries dropped because their on-disk file was missing at " +
                     "registration time (writes-then-deletes, renames). Tagged by agent_id.",
@@ -227,6 +257,40 @@ export function recordSandboxExec(args) {
     if (args.cpuMillis !== undefined)
         sandboxExecCpuSeconds.record(Math.max(0, args.cpuMillis) / 1000, attributes);
 }
+/** Record the wait of one lease from its request to its grant. Call it in the step that took the grant. */
+export function recordLeaseWait(args) {
+    getInstruments().sandboxLeaseWait.record(Math.max(0, args.waitMs), { backend: args.backend });
+}
+/** Record the time from one spawn to the health of the machine. Call it in the step of the spawn. */
+export function recordMachineStart(args) {
+    getInstruments().sandboxMachineStart.record(Math.max(0, args.startMs), { backend: args.backend });
+}
+/** Record one machine of a lease that went away. Call it in the step that removed it. */
+export function recordMachineReplaced(args) {
+    getInstruments().sandboxMachineReplaced.add(1, { cause: args.cause });
+}
+/**
+ * Count one value in this process until the returned function runs. The count is of this process only, thus a
+ * dashboard can put it beside the memory of the same process. A second call of the returned function does nothing.
+ */
+function track(counter, attributes) {
+    counter.add(1, attributes);
+    let open = true;
+    return () => {
+        if (!open)
+            return;
+        open = false;
+        counter.add(-1, attributes);
+    };
+}
+/** Count one lease workflow that runs in this process, until the returned function runs. */
+export function trackLeaseWorkflow() {
+    return track(getInstruments().sandboxLeaseWorkflows);
+}
+/** Count one workflow body that waits in a pause in this process, until the returned function runs. */
+export function trackWorkPaused(args) {
+    return track(getInstruments().workPaused, { work_kind: args.workKind });
+}
 /** Record one manifest entry dropped at reconcile. */
 export function recordArtifactReconcileDropped(args) {
     getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });

package/dist/lib/pdf-text.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The text of a PDF, for each page, on `unpdf`: the serverless build of PDF.js, with no native part and no worker
+ * file. Thus it runs under Node, under Bun, and in a Bun single-file binary.
+ */
+/** The text of one page. */
+export type PdfPageText = {
+    readonly page: number;
+    readonly text: string;
+};
+/** The pages that a read gave, and the page count of the whole document. */
+export type PdfText = {
+    readonly totalPages: number;
+    readonly pages: readonly PdfPageText[];
+};
+/**
+ * Read the text of the pages `first` to `last` of a PDF, both inclusive and 1-based, clamped to the document. The
+ * whole document is never decoded: PDF.js parses a page when the read asks for it. A PDF that PDF.js cannot open
+ * throws, and the caller maps the throw.
+ */
+export declare function readPdfText(bytes: Uint8Array, range: {
+    readonly first: number;
+    readonly last: number;
+}): Promise<PdfText>;

package/dist/lib/pdf-text.js

@@ -0,0 +1,34 @@
+/**
+ * The text of a PDF, for each page, on `unpdf`: the serverless build of PDF.js, with no native part and no worker
+ * file. Thus it runs under Node, under Bun, and in a Bun single-file binary.
+ */
+import { getDocumentProxy } from "unpdf";
+/** The text of the items of a page, with the line ends that PDF.js marks. A marked-content item carries no text. */
+function pageText(items) {
+    return items
+        .map((item) => ("str" in item && typeof item.str === "string" ? `${item.str}${"hasEOL" in item && item.hasEOL === true ? "\n" : ""}` : ""))
+        .join("")
+        .trim();
+}
+/**
+ * Read the text of the pages `first` to `last` of a PDF, both inclusive and 1-based, clamped to the document. The
+ * whole document is never decoded: PDF.js parses a page when the read asks for it. A PDF that PDF.js cannot open
+ * throws, and the caller maps the throw.
+ */
+export async function readPdfText(bytes, range) {
+    // The verbosity 0 keeps the warnings of PDF.js off the console of the host.
+    const pdf = await getDocumentProxy(new Uint8Array(bytes), { verbosity: 0 });
+    try {
+        const first = Math.max(1, range.first);
+        const last = Math.min(pdf.numPages, range.last);
+        const pages = [];
+        for (let page = first; page <= last; page++) {
+            const content = await (await pdf.getPage(page)).getTextContent();
+            pages.push({ page, text: pageText(content.items) });
+        }
+        return { totalPages: pdf.numPages, pages };
+    }
+    finally {
+        await pdf.cleanup();
+    }
+}

package/dist/lib/regulatory-corpus/fetch-fda-guidance.js

@@ -1,5 +1,5 @@
 import { load } from "cheerio";
-import { PDFParse } from "pdf-parse";
+import { readPdfText } from "../pdf-text.js";
 import { normalizeWhitespace } from "./normalize-whitespace.js";
 /**
  * Curated catalog of FDA guidance documents to index into the corpus.
@@ -77,10 +77,8 @@ export async function fetchAndExtractFdaDoc(stub) {
     const ct = (res.headers.get("content-type") ?? "").toLowerCase();
     let text;
     if (ct.includes("pdf") || stub.doc_url.toLowerCase().endsWith(".pdf")) {
-        const parser = new PDFParse({ data: buf });
-        const result = await parser.getText();
-        await parser.destroy();
-        text = result.text;
+        const result = await readPdfText(buf, { first: 1, last: Number.MAX_SAFE_INTEGER });
+        text = result.pages.map((page) => page.text).join("\n\n");
     }
     else {
         const $ = load(buf.toString("utf-8"));

package/dist/lib/regulatory-corpus/fetch-ich.js

@@ -11,7 +11,7 @@
  * Codes look like S7A, E14, M3(R2), Q1A. The doc_id we emit is
  * `ich-<code>` with non-word chars sanitized.
  */
-import { PDFParse } from "pdf-parse";
+import { readPdfText } from "../pdf-text.js";
 import { normalizeWhitespace } from "./normalize-whitespace.js";
 /**
  * Curated catalog of ICH guidelines to index into the corpus.
@@ -144,14 +144,12 @@ export async function fetchAndExtractIchDoc(stub) {
         throw new Error(`fetch ${stub.doc_url}: ${res.status} ${res.statusText}`);
     }
     const buf = Buffer.from(await res.arrayBuffer());
-    const parser = new PDFParse({ data: buf });
-    const result = await parser.getText();
-    await parser.destroy();
+    const result = await readPdfText(buf, { first: 1, last: Number.MAX_SAFE_INTEGER });
     return {
         doc_id: stub.doc_id,
         doc_title: stub.doc_title,
         doc_url: stub.doc_url,
-        text: normalizeWhitespace(result.text),
+        text: normalizeWhitespace(result.pages.map((page) => page.text).join("\n\n")),
         metadata: {
             code: stub.code,
             series: stub.series,

package/dist/loop/chat-stream.js

@@ -116,7 +116,8 @@ export function createTurnStreamWriter(rootSource, observe) {
             return;
         // A tool step gives its frames to the library, which checkpoints each one that is not progress.
         if (DBOS.isInStep()) {
-            toolWriter().write(chunkOfFrame(frame, isProgressFrame(frame)));
+            const liveOnly = "transient" in event && event.transient === true;
+            toolWriter().write(chunkOfFrame(frame, liveOnly || isProgressFrame(frame)));
             return;
         }
         await write(frame);

package/dist/loop/run-loop.d.ts

@@ -231,3 +231,8 @@ export type SalvagedResult = LoopResult & {
  */
 export declare function runWithSalvage(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: LoopOptions, salvage: TerminalSalvage): Promise<SalvagedResult>;
 export declare function finalText(messages: readonly LoopMessage[]): string;
+/**
+ * The agent with the `run_script` tool over its script tools, after its own tools. The tool is a pure function of
+ * the script tools, thus each request of a conversation declares the same tool, and the prompt cache holds.
+ */
+export declare function withRunScript(agent: AgentDefinition, logger?: Logger): AgentDefinition;

package/dist/loop/run-loop.js

@@ -16,7 +16,7 @@
 import { randomUUID } from "node:crypto";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { durableCalls } from "@dbos-inc/vercel-ai";
-import { streamText, wrapLanguageModel, } from "ai";
+import { NoSuchToolError, streamText, wrapLanguageModel, } from "ai";
 import { forSubAgent } from "../auth/types.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -25,11 +25,13 @@ import { errorNameOf } from "../lib/thrown.js";
 import { contextRecordOf, markCompactionExchange, markInterruptedMessage, summaryMarkerMessage, syntheticUserMessage, withRequestInputTokens, } from "../memory/ai-sdk-message-storage.js";
 import { conversationView, lastRequestInputTokens, withoutReasoning } from "../memory/conversation-view.js";
 import { answerUnansweredToolCalls } from "../memory/tool-call-integrity.js";
+import { aliasedToolName } from "./tool-name-repair.js";
 import { fallbackModelOf } from "../providers/ai-sdk.js";
 import { extractStatus, findProviderError } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, withPromptCacheBreakpoint, withSystemPromptBreakpoint } from "../providers/prompt-cache.js";
 import { accountingMiddleware, rollupMiddleware } from "./accounting.js";
 import { createCallPolicy } from "./call-policy.js";
+import { createRunScriptTool } from "../tools/script/run-script.js";
 import { COMPACTION_MAX_REQUESTS } from "./compaction.js";
 import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
 import { adaptTools, deniedReason, foldCallRecords, isFatalToolError, modelViewOf, recordedInputOf, ToolCallOutputSchema, } from "./tool-adapter.js";
@@ -133,11 +135,28 @@ export function finalText(messages) {
         .map((block) => block.text)
         .join("");
 }
+/**
+ * The agent with the `run_script` tool over its script tools, after its own tools. The tool is a pure function of
+ * the script tools, thus each request of a conversation declares the same tool, and the prompt cache holds.
+ */
+export function withRunScript(agent, logger) {
+    const scriptTools = agent.scriptTools ?? [];
+    if (scriptTools.length === 0)
+        return agent;
+    const asking = scriptTools.find((tool) => tool.approval !== undefined || tool.startsWorkflow === true);
+    if (asking !== undefined)
+        throw new Error(`the script tool ${asking.id} of agent ${agent.id} asks an approval or starts a workflow`);
+    const ownStep = scriptTools.find((tool) => tool.ownStep === true);
+    if (ownStep !== undefined)
+        throw new Error(`the script tool ${ownStep.id} of agent ${agent.id} must run as its own durable step`);
+    return { ...agent, tools: [...agent.tools, createRunScriptTool(scriptTools, agent.scriptRuntime, { scratch: agent.scriptScratch, logger })] };
+}
 /**
  * Open the loop over one conversation. `metricAgentId` is the id that usage
  * and run metrics count under, which is not always `agent.id`.
  */
-function openConversation(agent, initial, session, opts, metricAgentId) {
+function openConversation(declared, initial, session, opts, metricAgentId) {
+    const agent = withRunScript(declared, opts.logger);
     const { provider, emit } = opts;
     if (agent.tools.length > 0 && !provider.capabilities.toolCalling) {
         throw new Error(`Provider/model cannot run tool-required agent "${agent.id}"`);
@@ -516,6 +535,15 @@ async function runSeries(agent, opts, calls, log, target, spec) {
         maxRetries: 0,
         abortSignal: AbortSignal.any([opts.signal, fatalController.signal]),
         telemetry: bound.telemetry,
+        repairToolCall: ({ toolCall, tools: declared, error }) => {
+            if (!NoSuchToolError.isInstance(error))
+                return Promise.resolve(null);
+            const tool = aliasedToolName(toolCall.toolName, new Set(Object.keys(declared)));
+            if (tool === undefined)
+                return Promise.resolve(null);
+            log.warn("a tool call named a proxy alias of a declared tool", { alias: toolCall.toolName, tool });
+            return Promise.resolve({ ...toolCall, toolName: tool });
+        },
         toolApproval: async ({ toolCall }) => {
             const refusal = calls.refusalOf({ toolName: toolCall.toolName, input: toolCall.input }, spec.mask);
             if (refusal !== undefined) {

package/dist/loop/tool-name-repair.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The repair of a tool name that a proxy alias left behind.
+ *
+ * The Claude cloak of CLIProxyAPI renames each client tool to `mcp__<server>__<word>_<tool>`, and it maps the name
+ * back on the response. The model sometimes drops the `mcp__<server>__` part. Then the proxy maps nothing back, and
+ * the loop gets `<word>_<tool>`, for example `art_read_file` (router-for-me/CLIProxyAPI#6848, which upstream closed as
+ * not planned). A name of one lowercase word, an underscore, and a declared tool id is such an alias. The repair
+ * applies only to a name that no tool declares, thus a declared tool always keeps its own name.
+ */
+/** The declared tool that an alias names, or `undefined` for a name that is not an alias of one. */
+export declare function aliasedToolName(name: string, declared: ReadonlySet<string>): string | undefined;

package/dist/loop/tool-name-repair.js

@@ -0,0 +1,23 @@
+/**
+ * The repair of a tool name that a proxy alias left behind.
+ *
+ * The Claude cloak of CLIProxyAPI renames each client tool to `mcp__<server>__<word>_<tool>`, and it maps the name
+ * back on the response. The model sometimes drops the `mcp__<server>__` part. Then the proxy maps nothing back, and
+ * the loop gets `<word>_<tool>`, for example `art_read_file` (router-for-me/CLIProxyAPI#6848, which upstream closed as
+ * not planned). A name of one lowercase word, an underscore, and a declared tool id is such an alias. The repair
+ * applies only to a name that no tool declares, thus a declared tool always keeps its own name.
+ */
+/** The declared tool that an alias names, or `undefined` for a name that is not an alias of one. */
+export function aliasedToolName(name, declared) {
+    if (declared.has(name))
+        return undefined;
+    const split = name.indexOf("_");
+    if (split <= 0)
+        return undefined;
+    const word = name.slice(0, split);
+    const tool = name.slice(split + 1);
+    for (const char of word)
+        if (char < "a" || char > "z")
+            return undefined;
+    return declared.has(tool) ? tool : undefined;
+}

package/dist/loop/types.d.ts

@@ -7,6 +7,8 @@ import type { ToolCallDetail, ToolOutcome } from "../contracts/chat-events.js";
 import type { ChatStreamEvent, ProviderOptions } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
 import type { CompactionRules } from "./compaction.js";
+import type { ScriptRuntime } from "../tools/script/run-script.js";
+import type { ScriptScratch } from "../tools/script/scratch.js";
 /**
  * A loop message. The harness's working message array is AI SDK-shaped
  * `ModelMessage`.
@@ -22,6 +24,18 @@ export type AgentDefinition = {
     readonly systemPrompt: string;
     readonly model: string;
     readonly tools: readonly Tool[];
+    /**
+     * The tools that the agent calls from a script, through the one `run_script` tool that the loop adds. A request
+     * declares only `run_script`, with one catalog line for each of them, thus their full descriptions stay out of
+     * the context until a script asks for one. Each must ask no approval and start no workflow, because a script runs
+     * as one step. A step that did not complete runs its script again, thus a tool that writes must accept the same
+     * write again. Absent or empty: the agent has no `run_script`.
+     */
+    readonly scriptTools?: readonly Tool[];
+    /** Where the VM of `run_script` comes from. Absent: the VM loads from `node_modules`. */
+    readonly scriptRuntime?: ScriptRuntime;
+    /** The scratch directory of the scripts of the agent. Absent: no script is saved, and no script writes a file. */
+    readonly scriptScratch?: ScriptScratch;
     /** Runaway guard: the cap of model requests of one run. The run ends at the cap. */
     readonly maxIterations: number;
     /** The compaction rules of an agent that a chat thread runs. Absent: the conversation never compacts. */
@@ -116,6 +130,11 @@ export type ChatDataPart = {
      * routing envelopes).
      */
     readonly source?: EventSource;
+    /**
+     * Live only. Inside a tool step the chat stream writes the part as progress: a live reader gets it, and the step
+     * does not checkpoint it. Give it to a copy that a later part of the same reconciling id replaces.
+     */
+    readonly transient?: boolean;
 };
 /**
  * The flat event sink. One function reference flows unchanged through