@alisio/core 0.5.2 → 0.7.0

package/dist/eval/verifiers.js

@@ -0,0 +1,264 @@
+/**
+ * Deterministic, local verifiers of the reliability lab (specs/010 D4). A verifier answers
+ * `pass`, `fail` or `error`; `error` means it could not run (bad path, missing input, command that
+ * cannot start) and is never folded into `fail`. Details never echo file contents.
+ *
+ * `command` runs a subprocess with a clean environment and a timeout. A subprocess is NOT a
+ * sandbox: suites are trusted repository code and the command runs with the user's privileges.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { EvalPathError, resolveInside, unsafeRelativeReason } from "./paths.js";
+const IGNORED_DIRS = new Set([".git", "node_modules"]);
+const MAX_COMMAND_OUTPUT = 1_000_000;
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+/**
+ * Hashes every file under `dir` (symlinks by their target text, never followed). `.git` and
+ * `node_modules` are skipped at any depth: they are tooling state, not task output.
+ */
+export function snapshotTree(dir) {
+    const files = {};
+    const walk = (current, prefix) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const full = join(current, entry.name);
+            if (entry.isSymbolicLink())
+                files[rel] = sha256(`symlink:${readlinkSync(full)}`);
+            else if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name))
+                    walk(full, rel);
+            }
+            else if (entry.isFile())
+                files[rel] = sha256(readFileSync(full));
+        }
+    };
+    walk(dir, "");
+    const hash = sha256(Object.keys(files)
+        .sort()
+        .map((path) => `${path}\0${files[path]}`)
+        .join("\n"));
+    return { files, hash };
+}
+const result = (v, status, detail) => ({
+    id: v.id,
+    status,
+    ...(detail === undefined ? {} : { detail }),
+});
+function isMissing(error) {
+    return error?.code === "ENOENT";
+}
+function runCommand(v, cwd, tmpDir) {
+    return new Promise((resolve) => {
+        const [bin, ...args] = v.command;
+        if (bin === undefined)
+            return resolve(result(v, "error", "command is empty."));
+        if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+            return resolve(result(v, "error", "working directory does not exist."));
+        const env = { PATH: process.env.PATH ?? "", NODE_NO_WARNINGS: "1" };
+        if (process.env.SystemRoot)
+            env.SystemRoot = process.env.SystemRoot;
+        if (tmpDir) {
+            env.HOME = tmpDir;
+            env.TMPDIR = tmpDir;
+        }
+        let stdout = "";
+        let timedOut = false;
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        // The child leads its own process group (POSIX) so a timeout can stop grandchildren too.
+        const detached = process.platform !== "win32";
+        const child = spawn(bin, args, {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "ignore"],
+            shell: false,
+            detached,
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (detached && child.pid !== undefined)
+                    process.kill(-child.pid, "SIGKILL");
+                else
+                    child.kill("SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        }, v.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            if (stdout.length < MAX_COMMAND_OUTPUT)
+                stdout += chunk.toString("utf8");
+        });
+        child.on("error", (error) => done(result(v, "error", `command could not start: ${error.message}`)));
+        child.on("close", (code, signal) => {
+            // The command is the task's own check running agent-written code: a hang is the agent's
+            // failure, not an infrastructure error (a command that cannot start stays `error`).
+            if (timedOut)
+                return done(result(v, "fail", `command timed out after ${v.timeoutMs} ms.`));
+            const expected = v.expectExit ?? 0;
+            if (code !== expected)
+                return done(result(v, "fail", signal ? `terminated by ${signal}.` : `exit ${code}, expected exit ${expected}.`));
+            if (v.expectStdoutIncludes !== undefined && !stdout.includes(v.expectStdoutIncludes))
+                return done(result(v, "fail", "stdout does not include the expected text."));
+            done(result(v, "pass"));
+        });
+    });
+}
+function readTarget(path) {
+    try {
+        return { data: readFileSync(path) };
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { missing: true };
+        throw error;
+    }
+}
+function diffTree(baseline, current) {
+    const added = [];
+    const deleted = [];
+    const modified = [];
+    for (const [path, hash] of Object.entries(current.files)) {
+        const before = baseline.files[path];
+        if (before === undefined)
+            added.push(path);
+        else if (before !== hash)
+            modified.push(path);
+    }
+    for (const path of Object.keys(baseline.files))
+        if (!(path in current.files))
+            deleted.push(path);
+    return { added, deleted, modified };
+}
+/** `a/b.ts` allows exactly that file; `a/` allows everything below the directory `a`. */
+const isAllowed = (path, allowed) => allowed.some((entry) => (entry.endsWith("/") ? path.startsWith(entry) : path === entry));
+function checkSequence(rule, events) {
+    switch (rule.type) {
+        case "before": {
+            const firstAt = events.findIndex((e) => e.tool === rule.first);
+            const thenAt = events.findIndex((e) => e.tool === rule.then);
+            if (thenAt === -1)
+                return { ok: true };
+            return firstAt !== -1 && firstAt < thenAt
+                ? { ok: true }
+                : { ok: false, detail: `"${rule.then}" was called without a prior "${rule.first}".` };
+        }
+        case "never":
+            return events.some((e) => e.tool === rule.tool)
+                ? { ok: false, detail: `"${rule.tool}" must never be called.` }
+                : { ok: true };
+        case "max-calls": {
+            const calls = events.filter((e) => e.tool === rule.tool).length;
+            return calls > rule.max
+                ? { ok: false, detail: `"${rule.tool}" was called ${calls} times, maximum ${rule.max}.` }
+                : { ok: true };
+        }
+        case "no-repeat-failure": {
+            const failed = new Set();
+            for (const e of events) {
+                if (e.tool !== rule.tool)
+                    continue;
+                const key = e.argsKey ?? "";
+                if (failed.has(key))
+                    return {
+                        ok: false,
+                        detail: `"${rule.tool}" repeated an identical call that had failed.`,
+                    };
+                if (!e.ok)
+                    failed.add(key);
+            }
+            return { ok: true };
+        }
+    }
+}
+async function evaluate(v, ctx) {
+    switch (v.kind) {
+        case "command":
+            return runCommand(v, ctx.cwd, ctx.tmpDir);
+        case "file-equals": {
+            const target = readTarget(resolveInside(ctx.cwd, v.path, "path"));
+            if ("missing" in target)
+                return result(v, "fail", `${v.path} does not exist.`);
+            return sha256(target.data) === v.sha256.toLowerCase()
+                ? result(v, "pass")
+                : result(v, "fail", `${v.path} sha256 differs from the expected value.`);
+        }
+        case "file-contains": {
+            const target = readTarget(resolveInside(ctx.cwd, v.path, "path"));
+            if ("missing" in target)
+                return result(v, "fail", `${v.path} does not exist.`);
+            return target.data.toString("utf8").includes(v.text)
+                ? result(v, "pass")
+                : result(v, "fail", `${v.path} does not contain the expected text.`);
+        }
+        case "file-absent": {
+            const absolute = resolveInside(ctx.cwd, v.path, "path");
+            try {
+                lstatSync(absolute);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return result(v, "pass");
+                throw error;
+            }
+            return result(v, "fail", `${v.path} exists.`);
+        }
+        case "tree-diff-within": {
+            if (!ctx.baseline)
+                return result(v, "error", "no fixture snapshot was provided to compare against.");
+            for (const entry of v.allowed) {
+                const reason = unsafeRelativeReason(entry);
+                if (reason)
+                    return result(v, "error", `allowed entry "${entry}" ${reason}.`);
+            }
+            const { added, deleted, modified } = diffTree(ctx.baseline, snapshotTree(ctx.cwd));
+            const outside = (paths) => paths.filter((p) => !isAllowed(p, v.allowed)).sort();
+            const parts = [
+                ["modified", outside(modified)],
+                ["added", outside(added)],
+                ["deleted", outside(deleted)],
+            ]
+                .filter(([, paths]) => paths.length > 0)
+                .map(([label, paths]) => `${label}: ${paths.join(", ")}`);
+            return parts.length === 0
+                ? result(v, "pass")
+                : result(v, "fail", `changes outside the allowed list (${parts.join("; ")}).`);
+        }
+        case "tool-sequence": {
+            if (!ctx.toolEvents)
+                return result(v, "error", "no tool events were recorded for this run.");
+            const checked = checkSequence(v.rule, ctx.toolEvents);
+            return checked.ok ? result(v, "pass") : result(v, "fail", checked.detail);
+        }
+        default:
+            return result(v, "error", `unknown verifier kind "${v.kind}".`);
+    }
+}
+/** Runs one verifier; anything that prevents a verdict (including exceptions) is `error`. */
+export async function runVerifier(v, ctx) {
+    try {
+        return await evaluate(v, ctx);
+    }
+    catch (error) {
+        const detail = error instanceof EvalPathError
+            ? error.message
+            : `verifier could not run: ${error.code ?? error.message}`;
+        return result(v, "error", detail);
+    }
+}
+/** Runs the verifiers in order (sequentially: `command` verifiers may share the working directory). */
+export async function runVerifiers(verifiers, ctx) {
+    const results = [];
+    for (const v of verifiers)
+        results.push(await runVerifier(v, ctx));
+    return results;
+}

package/dist/forge/broker.d.ts

@@ -0,0 +1,51 @@
+import type { ForgeProgress } from "@alisio/sdk";
+import type { BudgetLedger } from "./budget.ts";
+import type { SqliteExecutionJournal } from "./journal.ts";
+import type { ForgeLimits } from "./limits.ts";
+import type { NestedCallDispatcher } from "./nested.ts";
+import type { HostReply } from "./ports.ts";
+import type { ForgeOutputItem, GuestMessage } from "./protocol.ts";
+import type { StateDelta } from "./state-delta.ts";
+/** Maximum catalog lookups per execution; they are cheap but not free. */
+export declare const MAX_CATALOG_REQUESTS = 200;
+/** Progress messages one execution may report; the rest is dropped (counted, not stored). */
+export declare const MAX_PROGRESS_MESSAGES = 10000;
+/** Characters of one progress message the host keeps. */
+export declare const MAX_PROGRESS_CHARS = 500;
+/** Bytes of state operations one execution may queue (the commit enforces the stored total). */
+export declare const MAX_STATE_DELTA_BYTES: number;
+export interface BrokerDeps {
+    dispatcher: NestedCallDispatcher;
+    ledger: BudgetLedger;
+    limits: ForgeLimits;
+    journal: Pick<SqliteExecutionJournal, "startCall" | "endCall">;
+    executionId: string;
+    /** Aborts every nested call when the execution is stopped. */
+    signal: AbortSignal;
+    /** `undefined` when the stored state is switched off. */
+    state: StateDelta | undefined;
+    /** Coalesced, droppable progress (script progress, a call starting). */
+    update(progress: ForgeProgress): void;
+    /** Never dropped (a call ended). */
+    terminal(progress: ForgeProgress): void;
+    engine: ForgeProgress["engine"];
+    log(line: string): void;
+    now?: () => number;
+}
+export interface CallStats {
+    total: number;
+    failed: number;
+    denied: number;
+}
+export declare class CapabilityBroker {
+    #private;
+    readonly output: ForgeOutputItem[];
+    readonly stats: CallStats;
+    /** Progress messages dropped past `MAX_PROGRESS_MESSAGES` (reported in the journal metrics). */
+    progressDropped: number;
+    constructor(deps: BrokerDeps);
+    bind(send: (reply: HostReply) => void): void;
+    /** Resolves when every call the guest started has finished (or the timeout passed). */
+    drain(timeoutMs: number): Promise<void>;
+    receive(message: GuestMessage): Promise<HostReply | undefined>;
+}

package/dist/forge/broker.js

@@ -0,0 +1,244 @@
+/**
+ * The capability broker (spec §4.2, §6.4): the kernel's side of the guest's messages. A script sees
+ * proxy functions; every real decision happens here, with the numbers the HOST keeps:
+ *
+ *  - nested calls go through the run's nested-call dispatcher (the same gate as a direct call, no
+ *    new approvals, D7/D-24), paced by the `BudgetLedger` (total, concurrent, credits);
+ *  - sizes, output and state are bounded again no matter what the prelude checked;
+ *  - every nested call is journaled and reported as `ForgeProgress`.
+ *
+ * Errors that mean "the guest broke a limit" are thrown as `ForgeError`: the engine ends the
+ * execution with that code. Errors of one tool call are answered to the guest as `ok: false`.
+ */
+import { createHash } from "node:crypto";
+import { describeTool, searchCatalog } from "./catalog-view.js";
+import { ForgeError } from "./errors.js";
+import { clipText } from "./result.js";
+/** Maximum catalog lookups per execution; they are cheap but not free. */
+export const MAX_CATALOG_REQUESTS = 200;
+/** Progress messages one execution may report; the rest is dropped (counted, not stored). */
+export const MAX_PROGRESS_MESSAGES = 10_000;
+/** Characters of one progress message the host keeps. */
+export const MAX_PROGRESS_CHARS = 500;
+/** Bytes of state operations one execution may queue (the commit enforces the stored total). */
+export const MAX_STATE_DELTA_BYTES = 1024 * 1024;
+const DENIED = new Set(["PERMISSION_DENIED", "APPROVAL_REQUIRED"]);
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const positionOf = (nestedCallId) => Number(nestedCallId.slice(nestedCallId.lastIndexOf(":") + 1));
+export class CapabilityBroker {
+    #deps;
+    #now;
+    output = [];
+    stats = { total: 0, failed: 0, denied: 0 };
+    #inflight = new Set();
+    #send = () => { };
+    /** Progress messages dropped past `MAX_PROGRESS_MESSAGES` (reported in the journal metrics). */
+    progressDropped = 0;
+    #progressSeen = 0;
+    #catalogRequests = 0;
+    #stateBytes = 0;
+    constructor(deps) {
+        this.#deps = deps;
+        this.#now = deps.now ?? Date.now;
+    }
+    bind(send) {
+        this.#send = send;
+    }
+    /** Resolves when every call the guest started has finished (or the timeout passed). */
+    async drain(timeoutMs) {
+        if (this.#inflight.size === 0)
+            return;
+        await Promise.race([
+            Promise.allSettled([...this.#inflight]),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs).unref?.()),
+        ]);
+    }
+    async receive(message) {
+        switch (message.type) {
+            case "ready":
+                return { type: "grant", payload: this.#deps.ledger.grant() };
+            case "progress": {
+                if (++this.#progressSeen > MAX_PROGRESS_MESSAGES) {
+                    if (this.progressDropped++ === 0)
+                        this.#deps.log(`progress: more than ${MAX_PROGRESS_MESSAGES} messages; the rest is dropped`);
+                    return undefined;
+                }
+                const text = clipText(message.payload.message, MAX_PROGRESS_CHARS).text;
+                this.#deps.log(`progress: ${text}`);
+                this.#deps.update({
+                    kind: "forge",
+                    executionId: this.#deps.executionId,
+                    engine: this.#deps.engine,
+                    phase: "running",
+                    message: text,
+                    ...(message.payload.completed !== undefined
+                        ? { completed: message.payload.completed }
+                        : {}),
+                    ...(message.payload.total !== undefined ? { total: message.payload.total } : {}),
+                });
+                return undefined;
+            }
+            case "output":
+                this.#recordOutput(message.payload);
+                return undefined;
+            case "state.set":
+                this.#state().set(message.payload.key, message.payload.value);
+                this.#countState(message.payload.key, message.payload.value);
+                return undefined;
+            case "state.delete":
+                this.#state().delete(message.payload.key);
+                this.#countState(message.payload.key, null);
+                return undefined;
+            case "catalog":
+                return this.#catalog(message.payload);
+            case "call": {
+                // Not awaited by the engine's dispatch: calls of one script run concurrently.
+                const job = this.#call(message.payload);
+                this.#inflight.add(job);
+                const settled = () => this.#inflight.delete(job);
+                job.then(settled, settled);
+                await job;
+                return undefined;
+            }
+            default:
+                return undefined;
+        }
+    }
+    #state() {
+        const state = this.#deps.state;
+        if (!state)
+            throw new ForgeError("INVALID_INPUT", "stored state is switched off (forge.state.enabled)");
+        return state;
+    }
+    #countState(key, value) {
+        this.#stateBytes += key.length + JSON.stringify(value).length;
+        if (this.#stateBytes > MAX_STATE_DELTA_BYTES)
+            throw new ForgeError("BUDGET_EXCEEDED", "this execution changed too much stored state");
+    }
+    #recordOutput(item) {
+        const bytes = Buffer.byteLength(JSON.stringify(item), "utf8");
+        this.#deps.ledger.recordOutput(bytes);
+        this.output.push(item);
+        if (item.type === "text")
+            this.#deps.log(item.text.replace(/\n$/, ""));
+    }
+    #catalog(payload) {
+        if (++this.#catalogRequests > MAX_CATALOG_REQUESTS)
+            throw new ForgeError("BUDGET_EXCEEDED", `catalog lookups are limited to ${MAX_CATALOG_REQUESTS} per execution`);
+        const tools = this.#deps.dispatcher.catalog();
+        const entries = payload.op === "search"
+            ? searchCatalog(tools, payload.query, payload.limit)
+            : [describeTool(tools, payload.query)].filter((entry) => entry !== undefined);
+        return { type: "catalog.result", payload: { requestId: payload.requestId, entries } };
+    }
+    async #call(payload) {
+        const { ledger, journal, executionId, limits } = this.#deps;
+        // Only names the registry has are ever recorded or broadcast; anything else is a placeholder.
+        const tool = this.#deps.dispatcher.knows(payload.tool)
+            ? payload.tool
+            : `unknown:${sha256(payload.tool).slice(0, 12)}`;
+        // The host's own count: a call without a credit, or past the total, ends the execution.
+        ledger.startCall();
+        this.stats.total++;
+        const startedAt = this.#now();
+        const progress = (status, extra = {}) => ({
+            kind: "forge",
+            executionId,
+            engine: this.#deps.engine,
+            phase: "call",
+            call: { callId: payload.callId, tool, status, ...extra },
+        });
+        let journalId;
+        let ended = false;
+        const end = (status, errorCode) => {
+            if (journalId && !ended) {
+                ended = true;
+                journal.endCall(executionId, journalId, {
+                    status,
+                    durationMs: this.#now() - startedAt,
+                    ...(errorCode ? { errorCode } : {}),
+                });
+            }
+        };
+        let reply;
+        try {
+            const inputJson = JSON.stringify(payload.input ?? {});
+            if (Buffer.byteLength(inputJson, "utf8") > limits.maxCallInputBytes) {
+                reply = this.#error(payload.callId, "TOOL_INPUT_INVALID", `tool input is larger than ${limits.maxCallInputBytes} bytes`);
+                this.stats.failed++;
+                this.#deps.terminal(progress("failed"));
+            }
+            else {
+                this.#deps.log(`call ${tool}`);
+                this.#deps.update(progress("started"));
+                const outcome = await this.#deps.dispatcher.call({
+                    name: payload.tool,
+                    input: payload.input,
+                    signal: this.#deps.signal,
+                    onStart: (start) => {
+                        journalId = journal.startCall({
+                            executionId,
+                            n: positionOf(start.nestedCallId),
+                            toolName: start.name,
+                            effect: start.effect,
+                            inputSha256: sha256(inputJson),
+                            paths: start.paths,
+                        });
+                    },
+                });
+                if (outcome.ok) {
+                    const valueJson = JSON.stringify(outcome.value) ?? "null";
+                    if (Buffer.byteLength(valueJson, "utf8") > limits.maxCallResponseBytes) {
+                        reply = this.#error(payload.callId, "OUTPUT_LIMIT", `${payload.tool} returned ${Buffer.byteLength(valueJson, "utf8")} bytes, over the ${limits.maxCallResponseBytes} byte limit; ask for less (a smaller range, a filter, a page)`);
+                        this.stats.failed++;
+                        end("failed", "OUTPUT_LIMIT");
+                        this.#deps.terminal(progress("failed", { durationMs: this.#now() - startedAt }));
+                    }
+                    else {
+                        reply = {
+                            type: "result",
+                            payload: { callId: payload.callId, ok: true, value: outcome.value ?? null },
+                        };
+                        end("succeeded");
+                        this.#deps.terminal(progress("succeeded", { durationMs: this.#now() - startedAt }));
+                    }
+                }
+                else {
+                    if (!journalId) {
+                        // Refused before it started (denied, unknown, invalid): still on the record.
+                        journalId = journal.startCall({
+                            executionId,
+                            n: positionOf(outcome.nestedCallId),
+                            toolName: tool,
+                            effect: (outcome.effect ?? "external"),
+                            inputSha256: sha256(inputJson),
+                        });
+                    }
+                    const denied = DENIED.has(outcome.code);
+                    if (denied)
+                        this.stats.denied++;
+                    else
+                        this.stats.failed++;
+                    end("failed", outcome.code);
+                    this.#deps.log(`call ${tool} failed: ${outcome.code}`);
+                    this.#deps.terminal(progress(denied ? "denied" : "failed", { durationMs: this.#now() - startedAt }));
+                    reply = this.#error(payload.callId, outcome.code, outcome.message);
+                }
+            }
+        }
+        catch (error) {
+            end("failed", "TOOL_FAILED");
+            this.stats.failed++;
+            this.#deps.terminal(progress("failed", { durationMs: this.#now() - startedAt }));
+            reply = this.#error(payload.callId, "TOOL_FAILED", error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            ledger.finishCall();
+        }
+        this.#send(reply);
+        this.#send({ type: "grant", payload: ledger.grant() });
+    }
+    #error(callId, code, message) {
+        return { type: "result", payload: { callId, ok: false, error: { code, message } } };
+    }
+}

package/dist/forge/budget.d.ts

@@ -0,0 +1,27 @@
+export interface BudgetLimits {
+    maxToolCalls: number;
+    maxConcurrency: number;
+    maxRetainedOutputBytes: number;
+}
+export declare class BudgetLedger {
+    #private;
+    constructor(limits: BudgetLimits);
+    get stats(): {
+        started: number;
+        active: number;
+        outputBytes: number;
+    };
+    /**
+     * Tops the guest's credits up to what it may still use and returns the increment to send in a
+     * `grant` message. Call credits never exceed the free concurrency slots or the remaining total.
+     */
+    grant(): {
+        calls: number;
+        bytes: number;
+    };
+    /** Spends a credit for a new nested call or throws `BUDGET_EXCEEDED` without changing state. */
+    startCall(): void;
+    finishCall(): void;
+    /** Accounts output bytes, or throws `OUTPUT_LIMIT` without partial accounting. */
+    recordOutput(bytes: number): void;
+}

package/dist/forge/budget.js

@@ -0,0 +1,60 @@
+/**
+ * Per-execution budget: total and concurrent nested calls, the credits granted to the guest
+ * (backpressure, spec §5.4) and retained output bytes. The host enforces these numbers even when
+ * the guest prelude checks them too. Pure: no I/O.
+ */
+import { ForgeError } from "./errors.js";
+export class BudgetLedger {
+    #limits;
+    #started = 0;
+    #active = 0;
+    #outputBytes = 0;
+    #callCredits = 0;
+    #byteCredits = 0;
+    constructor(limits) {
+        this.#limits = limits;
+    }
+    get stats() {
+        return { started: this.#started, active: this.#active, outputBytes: this.#outputBytes };
+    }
+    /**
+     * Tops the guest's credits up to what it may still use and returns the increment to send in a
+     * `grant` message. Call credits never exceed the free concurrency slots or the remaining total.
+     */
+    grant() {
+        const callTarget = Math.max(0, Math.min(this.#limits.maxConcurrency - this.#active, this.#limits.maxToolCalls - this.#started));
+        const calls = Math.max(0, callTarget - this.#callCredits);
+        this.#callCredits += calls;
+        const bytes = this.#limits.maxRetainedOutputBytes - this.#outputBytes - this.#byteCredits;
+        this.#byteCredits += bytes;
+        return { calls, bytes };
+    }
+    /** Spends a credit for a new nested call or throws `BUDGET_EXCEEDED` without changing state. */
+    startCall() {
+        if (this.#started >= this.#limits.maxToolCalls) {
+            throw new ForgeError("BUDGET_EXCEEDED", `Tool call limit reached (${this.#limits.maxToolCalls})`);
+        }
+        if (this.#active >= this.#limits.maxConcurrency) {
+            throw new ForgeError("BUDGET_EXCEEDED", `Concurrent tool call limit reached (${this.#limits.maxConcurrency})`);
+        }
+        if (this.#callCredits <= 0) {
+            throw new ForgeError("BUDGET_EXCEEDED", "Tool call without a granted credit");
+        }
+        this.#callCredits--;
+        this.#started++;
+        this.#active++;
+    }
+    finishCall() {
+        if (this.#active <= 0)
+            throw new Error("finishCall without an active call");
+        this.#active--;
+    }
+    /** Accounts output bytes, or throws `OUTPUT_LIMIT` without partial accounting. */
+    recordOutput(bytes) {
+        if (this.#outputBytes + bytes > this.#limits.maxRetainedOutputBytes) {
+            throw new ForgeError("OUTPUT_LIMIT", `Retained output limit reached (${this.#limits.maxRetainedOutputBytes} bytes)`);
+        }
+        this.#outputBytes += bytes;
+        this.#byteCredits = Math.max(0, this.#byteCredits - bytes);
+    }
+}

package/dist/forge/catalog-view.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What `catalog.search` and `catalog.describe` show a script (spec §6.2, D13): the tools the run
+ * lets it call right now, found by name or description, never the whole prompt-sized catalog.
+ * Pure over the tool definitions.
+ */
+import type { ToolDefinition } from "@alisio/sdk";
+export declare const CATALOG_DEFAULT_LIMIT = 10;
+export declare const CATALOG_MAX_LIMIT = 25;
+export interface CatalogEntry {
+    name: string;
+    effect: string;
+    summary: string;
+}
+export interface CatalogDetail {
+    name: string;
+    effect: string;
+    description: string;
+    inputSchema: unknown;
+}
+/** The first sentence of a description, bounded. */
+export declare function summarize(description: string): string;
+/** Tools whose name or description holds every term of the query (all of them for an empty query). */
+export declare function searchCatalog(tools: readonly ToolDefinition[], query: string, limit?: number): CatalogEntry[];
+export declare function describeTool(tools: readonly ToolDefinition[], name: string): CatalogDetail | undefined;