agentfootprint 12.2.0 → 13.0.0

package/dist/esm/core/agent/scripts/rows.js

@@ -0,0 +1,211 @@
+/**
+ * scripts/rows — the `script` row: built from one call, filed through ONE
+ * writer, read back per turn, and bounded.
+ *
+ * Pattern: Map + one writer (the `findings/ledger.ts` · `recordFindings`
+ *          twin for this kind): `scriptRowFor` builds, `recordScriptRow` is
+ *          the only thing that writes a `script` row, `scriptRowsOfTurn` is
+ *          the one reader the match and the attachment share.
+ * Role:    core/ layer leaf. Called by the dispatch loop (`stages/toolCalls.ts`)
+ *          at each place a call of a declared code-running tool pauses or
+ *          settles; read by the Route decider's judge and the final branch.
+ * Emits:   N/A — the row is state; the runner's facts already rode
+ *          `agentfootprint.tools.code_run`, which never carries the code.
+ *
+ * ## One unit, and the bounds (design § 4.4)
+ *
+ * UTF-8 payload bytes of the program, measured at record time
+ * (`lib/utf8.ts` · `utf8Length`) — never characters: 32,768 characters of a
+ * 3-byte character are 98,304 bytes.
+ *
+ * - **Per script.** A program over {@link MAX_SCRIPT_BYTES} keeps a row with
+ *   `bytes`, `lines` and the outcome, and no `text`: it can be neither matched
+ *   nor attached.
+ * - **Per turn.** {@link MAX_SCRIPT_ROWS} calls keep a row; a further call of
+ *   the turn files none and is counted in `AgentState.scriptsDropped`.
+ * - **Eligible text.** A row's `text` lives for its own turn: the seed stage's
+ *   restore drops it from every earlier turn's row (`withoutEarlierScriptText`),
+ *   so the text the ledger holds is at most 16 × 32,768 bytes = 512 KiB before
+ *   serialization, whatever the conversation's length. That bounds eligible
+ *   text only — prior turns' metadata, history and the answers that carried an
+ *   attached script are outside it.
+ *
+ * ## Append only, last wins
+ *
+ * A call PAUSED before it settles (a check-in, a consent, an ask, a tool that
+ * asked a person) files a `submitted` row at the pause, WITHOUT its text: the
+ * settled row filed when the call resumes is the one that carries it, so a
+ * program is never held twice. A reader takes the LAST row per call of the
+ * turn (the ledger's own law). A row that never settles stays `submitted`.
+ */
+import { utf8Length } from '../../../lib/utf8.js';
+import { exitCodeFits, SCRIPT_LABELS, scriptLabelOf, } from './label.js';
+/** A program longer than this (UTF-8 bytes) keeps a row with no text. Design § 4.4. */
+export const MAX_SCRIPT_BYTES = 32_768;
+/** Calls per turn that keep a row; the rest are counted. Design § 4.4. */
+export const MAX_SCRIPT_ROWS = 16;
+/** Lines of a program: LF-separated, `0` for an empty one. */
+export function linesOf(program) {
+    if (program.length === 0)
+        return 0;
+    let lines = 1;
+    for (let i = 0; i < program.length; i++)
+        if (program.charCodeAt(i) === 0x0a)
+            lines++;
+    return program.charCodeAt(program.length - 1) === 0x0a ? lines - 1 : lines;
+}
+/**
+ * The declared argument's value in `args` — the one read a call's program is
+ * captured with. Read it at the boundary it names (as the call arrives; just
+ * before `execute`) and keep the value: never the arguments object, which app
+ * code may edit after it was handed over.
+ */
+export function programIn(script, args) {
+    return args === undefined ? undefined : args[script.argument];
+}
+/**
+ * The row for one call, or `undefined` when the call carried no program — the
+ * declared argument is not a string (an argument check refuses such a call;
+ * there is nothing to record as "the program submitted").
+ */
+export function scriptRowFor(call) {
+    const program = call.submitted !== undefined ? call.submitted : call.proposed;
+    if (typeof program !== 'string')
+        return undefined;
+    const bytes = utf8Length(program);
+    const outcome = call.paused
+        ? { label: 'submitted' }
+        : scriptLabelOf({
+            settlement: call.settlement,
+            ...(call.facts !== undefined && { facts: call.facts }),
+        });
+    const rewritten = call.submitted !== undefined && call.submitted !== call.proposed;
+    return {
+        kind: 'script',
+        toolCallId: call.toolCallId,
+        tool: call.tool,
+        argument: call.script.argument,
+        ...(call.script.language !== undefined && { language: call.script.language }),
+        bytes,
+        lines: linesOf(program),
+        ...(call.paused !== true && bytes <= MAX_SCRIPT_BYTES && { text: program }),
+        outcome: outcome.label,
+        ...(outcome.exitCode !== undefined && { exitCode: outcome.exitCode }),
+        ...(outcome.serviceError === true && { serviceError: true }),
+        ...(call.withheld === true && { resultWithheld: 'over-ceiling' }),
+        ...(rewritten && { rewritten: true }),
+        turn: call.turn,
+        iteration: call.iteration,
+    };
+}
+const isScriptRow = (row) => row !== null && typeof row === 'object' && row.kind === 'script';
+/**
+ * THE ONE WRITER of a `script` row, and the one place a call gets its
+ * DISPATCH identity: the 1-based order of the actual dispatch within its turn.
+ * A call is a dispatch, never a provider id: a later call that reuses an id is
+ * a new dispatch. `options.dispatch` names a dispatch that already has a row
+ * (a paused call, settling): its row joins that dispatch.
+ *
+ * Appended, unless the turn already holds {@link MAX_SCRIPT_ROWS} other
+ * dispatches — then the call files nothing and `scriptsDropped` counts it
+ * (value-conditional: absent until a call is dropped). A dispatch that already
+ * has a row is never dropped, and a PAUSE is never counted (`paused`): its call
+ * is counted once, when it settles. Returns the dispatch the row was filed
+ * under, `undefined` when it was dropped. Synchronous: one read, one write, no
+ * await between.
+ */
+export function recordScriptRow(scope, draft, options = {}) {
+    const prev = [...(scope.findingsLedger ?? [])];
+    const dispatches = new Set();
+    let highest = 0;
+    for (const r of prev) {
+        if (!isScriptRow(r) || r.turn !== draft.turn)
+            continue;
+        dispatches.add(r.dispatch);
+        if (r.dispatch > highest)
+            highest = r.dispatch;
+    }
+    const joins = options.dispatch !== undefined && dispatches.has(options.dispatch);
+    if (!joins && dispatches.size >= MAX_SCRIPT_ROWS) {
+        if (options.paused !== true) {
+            scope.scriptsDropped = (scope.scriptsDropped ?? 0) + 1;
+        }
+        return undefined;
+    }
+    const dispatch = joins ? options.dispatch : highest + 1;
+    const { kind, toolCallId, ...rest } = draft;
+    scope.findingsLedger = [...prev, { kind, toolCallId, dispatch, ...rest }];
+    return dispatch;
+}
+/**
+ * The one reader of a turn's script rows: the last row per DISPATCH wins, and
+ * a dispatch sits where its last row was filed — execution order, so a call
+ * that settles after a later one ran is read after it. Earlier turns counted.
+ */
+export function scriptRowsOfTurn(ledger, turn) {
+    const latest = new Map();
+    const earlier = new Set();
+    for (const row of ledger ?? []) {
+        if (!isScriptRow(row))
+            continue;
+        if (row.turn === turn) {
+            latest.delete(row.dispatch);
+            latest.set(row.dispatch, row);
+        }
+        else {
+            earlier.add(`${row.turn}\u001f${row.dispatch}`);
+        }
+    }
+    return { current: [...latest.values()], earlier: earlier.size };
+}
+/**
+ * The restore door's half of the bound (seed): every `script` row of a turn
+ * BEFORE `turn` keeps its facts — ids, counts, outcome — and loses its `text`.
+ * The same reference when there is nothing to drop, so a ledger without
+ * script text is restored byte for byte.
+ */
+export function withoutEarlierScriptText(ledger, turn) {
+    let changed = false;
+    const out = ledger.map((row) => {
+        if (!isScriptRow(row) || row.turn >= turn || row.text === undefined)
+            return row;
+        changed = true;
+        const { text: _text, ...facts } = row;
+        void _text;
+        return facts;
+    });
+    return changed ? out : ledger;
+}
+const isCount = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0;
+/**
+ * Whether a value read from a stored checkpoint is a `script` row this library
+ * could have written — the checkpoint door's arm (`core/runCheckpoint.ts`).
+ * An older runtime refuses a checkpoint carrying one.
+ */
+export function scriptRowIsWellFormed(r) {
+    const label = r.outcome;
+    return (r.kind === 'script' &&
+        typeof r.toolCallId === 'string' &&
+        Number.isInteger(r.dispatch) &&
+        r.dispatch >= 1 &&
+        typeof r.tool === 'string' &&
+        typeof r.argument === 'string' &&
+        (r.language === undefined || typeof r.language === 'string') &&
+        isCount(r.bytes) &&
+        isCount(r.lines) &&
+        // The text is the program the row measured, within the bound.
+        (r.text === undefined ||
+            (typeof r.text === 'string' &&
+                r.bytes === utf8Length(r.text) &&
+                r.bytes <= MAX_SCRIPT_BYTES)) &&
+        typeof label === 'string' &&
+        SCRIPT_LABELS.includes(label) &&
+        // An exit code rides exactly the two labels that one proves, as the label writes it.
+        exitCodeFits(label, r.exitCode) &&
+        (r.serviceError === undefined || (r.serviceError === true && label === 'outcome-unknown')) &&
+        (r.resultWithheld === undefined || r.resultWithheld === 'over-ceiling') &&
+        (r.rewritten === undefined || r.rewritten === true) &&
+        typeof r.turn === 'number' &&
+        typeof r.iteration === 'number');
+}
+//# sourceMappingURL=rows.js.map

package/dist/esm/core/agent/scripts/rows.js.map

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

package/dist/esm/core/agent/scripts/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * scripts/types — the row a call of a code-running tool files, and the
+ * attachment's options. The vocabulary the event payloads share (the label,
+ * the block verdict, the attached script) lives in `lib/scriptRecord.ts` and
+ * is re-exported here.
+ *
+ * Pattern: plain row and verdict types, no logic (`label.ts` decides a label,
+ *          `rows.ts` files a row, `match.ts` judges a block, `attachment.ts`
+ *          composes what travels).
+ * Role:    core/ layer leaf of the script record (design:
+ *          docs/design/2026-10-script-artifact.md).
+ * Emits:   N/A.
+ *
+ * FOUR FACTS, KEPT APART. F1 "this is the script submitted" and F2 "this
+ * script ran" are facts about a CALL, on one `script` row per call. F3 "a tool
+ * returned this value" is the evidence gate's verdict, from `role: 'tool'`
+ * results only — nothing here ever enters the evidence or exempt corpus. F4
+ * "this claim holds" has no row. No sentence joins them.
+ */
+import type { ScriptLabel } from '../../../lib/scriptRecord.js';
+export type { ScriptBlockVerdict, ScriptLabel, ScriptsVerdict, ShownScript, TurnEndScripts, UnmatchedReason, } from '../../../lib/scriptRecord.js';
+/**
+ * One call of a declared code-running tool (`Tool.script`), on the findings
+ * ledger — F1 (the program submitted) and F2 (what its execution record
+ * proves), and nothing about any value.
+ *
+ * Filed by the dispatch loop (`stages/toolCalls.ts`) while
+ * `.namesAndNumbersFromEvidence({ code: 'match' })` or
+ * `.scriptTravelsWithTheAnswer()` is on, through ONE writer (`rows.ts` ·
+ * `recordScriptRow`): the call's row is KEPT CURRENT — its outcome is written
+ * when the call settles, and a row that never settles stays `submitted`. At
+ * the next turn boundary (seed) the row keeps its facts and loses its `text`.
+ */
+export interface ScriptRow {
+    readonly kind: 'script';
+    /** The provider's id for the call — display only; two calls may share one. */
+    readonly toolCallId: string;
+    /**
+     * The library's identity for the call: the 1-based order of the actual
+     * dispatch within its turn (`rows.ts` · `recordScriptRow`). A pause and its
+     * settlement share it; a later call that reuses the provider id is a new
+     * dispatch. Rows are counted, read and matched by it.
+     */
+    readonly dispatch: number;
+    /** The name the model called. */
+    readonly tool: string;
+    /** The declared argument that carried the program. */
+    readonly argument: string;
+    /** The declared language, when the tool declared one. */
+    readonly language?: string;
+    /** UTF-8 bytes of the program submitted to the tool. */
+    readonly bytes: number;
+    /** Lines of that program (LF-separated; `0` for an empty program). */
+    readonly lines: number;
+    /**
+     * The program submitted to the tool, byte for byte. ABSENT over
+     * `MAX_SCRIPT_BYTES`, and after the row's turn ended.
+     */
+    readonly text?: string;
+    readonly outcome: ScriptLabel;
+    /** Exactly the runner's exit code, only when it supplied one. */
+    readonly exitCode?: number;
+    /** The runner's failure verdict was the service's, with no exit code. */
+    readonly serviceError?: true;
+    /** The tool's own `resultCeiling` replaced the delivered result. */
+    readonly resultWithheld?: 'over-ceiling';
+    /** A before-tool rule changed the program before dispatch; the earlier text is on no row. */
+    readonly rewritten?: true;
+    /** `AgentState.turnNumber` when the call was made. */
+    readonly turn: number;
+    readonly iteration: number;
+}
+/** `.scriptTravelsWithTheAnswer()` options. */
+export interface ScriptTravelOptions {
+    /**
+     * `'last'` (default) — the last call of the turn that reached the tool;
+     * `'all'` — every call of the turn that reached it, at most
+     * `MAX_ATTACHED_SCRIPTS`, the rest counted as `omitted`.
+     */
+    readonly which?: 'last' | 'all';
+    /**
+     * UTF-8 bytes of each program shown (default 4,000). A longer program is
+     * cut at a code-point boundary and says it is incomplete.
+     */
+    readonly maxBytes?: number;
+}
+/** The resolved arm the chart carries. @internal */
+export interface ResolvedScriptTravel {
+    readonly which: 'last' | 'all';
+    readonly maxBytes: number;
+}

package/dist/esm/core/agent/scripts/types.js

@@ -0,0 +1,21 @@
+/**
+ * scripts/types — the row a call of a code-running tool files, and the
+ * attachment's options. The vocabulary the event payloads share (the label,
+ * the block verdict, the attached script) lives in `lib/scriptRecord.ts` and
+ * is re-exported here.
+ *
+ * Pattern: plain row and verdict types, no logic (`label.ts` decides a label,
+ *          `rows.ts` files a row, `match.ts` judges a block, `attachment.ts`
+ *          composes what travels).
+ * Role:    core/ layer leaf of the script record (design:
+ *          docs/design/2026-10-script-artifact.md).
+ * Emits:   N/A.
+ *
+ * FOUR FACTS, KEPT APART. F1 "this is the script submitted" and F2 "this
+ * script ran" are facts about a CALL, on one `script` row per call. F3 "a tool
+ * returned this value" is the evidence gate's verdict, from `role: 'tool'`
+ * results only — nothing here ever enters the evidence or exempt corpus. F4
+ * "this claim holds" has no row. No sentence joins them.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/core/agent/scripts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/core/agent/scripts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/esm/core/agent/scripts/wrapper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * scripts/wrapper — the Markdown wrapper the library puts around a program,
+ * with both of its line terminators pinned.
+ *
+ * Pattern: pure leaf. The renderer half of the wrapper law; the reader half is
+ *          `../evidence/codeRegions.ts`, and the two agree byte for byte
+ *          (`test/core/agent/evidence/script-wrapper.test.ts`).
+ * Role:    core/ layer leaf, asked by the attachment (`attachment.ts`).
+ * Emits:   N/A.
+ *
+ * THE LAW (design § 4.2, § 5.2). The fence is `max(3, longestRun + 1)`
+ * backticks, where `longestRun` is the longest run of backticks inside the
+ * program (the CommonMark closing rule), so a program that holds ```` ``` ````
+ * cannot close the library's block early. The renderer writes the opening
+ * fence line, ONE LF, the program's bytes unchanged, ONE LF, then the closing
+ * fence line. The two LFs are the wrapper's; what sits between them is the
+ * program exactly — so a program ending in a line break shows an empty line
+ * before the closing fence, and a program ending in a lone CR, in LF or in
+ * CRLF reads back unchanged.
+ *
+ * @example
+ * ```ts
+ * wrapProgram('print(1)', 'python');      // '```python\nprint(1)\n```'
+ * fenceFor('s = "```"');                   // '````'
+ * codeRegionsOf(wrapProgram(p)).regions[0].content === p; // for every p
+ * ```
+ */
+/** The fence for `program`: `max(3, longestRun + 1)` backticks. */
+export declare function fenceFor(program: string): string;
+/**
+ * The program inside the library's fence: opening line (fence + `language` as
+ * the info string), LF, the program unchanged, LF, closing fence. `language`
+ * is a declared token (`tools/script.ts` refuses a backtick or line break in
+ * it), so the info string cannot end the opening line early.
+ */
+export declare function wrapProgram(program: string, language?: string): string;

package/dist/esm/core/agent/scripts/wrapper.js

@@ -0,0 +1,58 @@
+/**
+ * scripts/wrapper — the Markdown wrapper the library puts around a program,
+ * with both of its line terminators pinned.
+ *
+ * Pattern: pure leaf. The renderer half of the wrapper law; the reader half is
+ *          `../evidence/codeRegions.ts`, and the two agree byte for byte
+ *          (`test/core/agent/evidence/script-wrapper.test.ts`).
+ * Role:    core/ layer leaf, asked by the attachment (`attachment.ts`).
+ * Emits:   N/A.
+ *
+ * THE LAW (design § 4.2, § 5.2). The fence is `max(3, longestRun + 1)`
+ * backticks, where `longestRun` is the longest run of backticks inside the
+ * program (the CommonMark closing rule), so a program that holds ```` ``` ````
+ * cannot close the library's block early. The renderer writes the opening
+ * fence line, ONE LF, the program's bytes unchanged, ONE LF, then the closing
+ * fence line. The two LFs are the wrapper's; what sits between them is the
+ * program exactly — so a program ending in a line break shows an empty line
+ * before the closing fence, and a program ending in a lone CR, in LF or in
+ * CRLF reads back unchanged.
+ *
+ * @example
+ * ```ts
+ * wrapProgram('print(1)', 'python');      // '```python\nprint(1)\n```'
+ * fenceFor('s = "```"');                   // '````'
+ * codeRegionsOf(wrapProgram(p)).regions[0].content === p; // for every p
+ * ```
+ */
+/** The longest run of backticks in `text` — one linear pass. */
+function longestBacktickRun(text) {
+    let longest = 0;
+    let run = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 0x60) {
+            run += 1;
+            if (run > longest)
+                longest = run;
+        }
+        else {
+            run = 0;
+        }
+    }
+    return longest;
+}
+/** The fence for `program`: `max(3, longestRun + 1)` backticks. */
+export function fenceFor(program) {
+    return '`'.repeat(Math.max(3, longestBacktickRun(program) + 1));
+}
+/**
+ * The program inside the library's fence: opening line (fence + `language` as
+ * the info string), LF, the program unchanged, LF, closing fence. `language`
+ * is a declared token (`tools/script.ts` refuses a backtick or line break in
+ * it), so the info string cannot end the opening line early.
+ */
+export function wrapProgram(program, language) {
+    const fence = fenceFor(program);
+    return `${fence}${language ?? ''}\n${program}\n${fence}`;
+}
+//# sourceMappingURL=wrapper.js.map

package/dist/esm/core/agent/scripts/wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.js","sourceRoot":"","sources":["../../../../../src/core/agent/scripts/wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,gEAAgE;AAChE,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAChC,GAAG,IAAI,CAAC,CAAC;YACT,IAAI,GAAG,GAAG,OAAO;gBAAE,OAAO,GAAG,GAAG,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,GAAG,GAAG,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,QAAiB;IAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,GAAG,QAAQ,IAAI,EAAE,KAAK,OAAO,KAAK,KAAK,EAAE,CAAC;AAC3D,CAAC"}

package/dist/esm/core/agent/stages/argumentAsk.d.ts

@@ -39,13 +39,16 @@
  * again, and the call's own step pauses in that batch, which asked nothing.
  */
 import { type TypedScope } from 'footprintjs';
-import type { ArgumentResolution, ToolOf } from '../arguments/resolve.js';
+import { type ArgumentResolution, type ToolOf } from '../arguments/resolve.js';
 import type { AgentState } from '../types.js';
 import type { ZoneName } from '../../../time/zone.js';
 import type { TimeAskMessages } from '../../../time/ask.js';
 import type { TimePolicy } from '../../../time/resolve.js';
 /** What the dispatch stage hands the ask — closures, never scope. */
 export interface ArgumentAskDeps {
+    /** Already refused calls do not acquire new obligations. */
+    readonly excludedCallIds?: readonly string[];
+    readonly argumentSources?: true;
     /** The implementation that will answer a name — the shared dispatch resolver's. */
     readonly toolOf: ToolOf;
     /** The run id a stamped request id carries; absent → the turn's start time. */