@alisio/core 0.5.1 → 0.6.0

package/dist/core/runner.js

@@ -1,4 +1,8 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
+import { createNestedDispatcher } from "../forge/nested.js";
+import { hasScratchEstimator, scratchIncomingBytes } from "../forge/scratch-quota.js";
+import { decideEffect, effectAskable } from "../permissions/decide.js";
+import { bindCallInternals } from "./call-internals.js";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
 import { HumanWaits } from "./human-wait.js";
 import { EXIT_PLAN_TOOL, optInAllows } from "./opt-in.js";
@@ -48,11 +52,6 @@ const MIN_MESSAGE_BUDGET_FLOOR = 4_000;
  * would pay for a summarizer call. The hard-limit last-chance compaction ignores it.
  */
 const RECOMPACT_GROWTH_MARGIN = 0.1;
-const allowed = (policy, effect) => effect === "read" ||
-    effect === "internal" ||
-    ((effect === "write" || effect === "process" || effect === "external") && !!policy[effect]);
-/** A tool's capability is pre-allowed by the policy alone (`--allow-analysis`). */
-const capabilityAllowed = (policy, tool) => tool.capability === "analysis.run" && !!policy.analysis;
 /** First 40 lines of a script input, for capability approvals. */
 const scriptPreview = (input) => typeof input.code === "string" ? input.code.split(/\r?\n/).slice(0, 40).join("\n") : undefined;
 /** A short id for a tool call the user started from a UI (alphanumeric, 9 characters). */
@@ -164,16 +163,13 @@ export class AgentRunner {
                 return false;
             if (!optInAllows(t.name, run.optInTools))
                 return false;
-            const effect = t.effect ?? "external";
-            if (allowed(policy, effect))
-                return true;
-            if (t.capability) {
-                if (capabilityAllowed(policy, t))
-                    return true;
-                if (sessionId && o.capabilities?.granted(t.capability, sessionId))
-                    return true;
-            }
-            return approvals && (effect === "write" || effect === "process" || effect === "external");
+            // Offered when the call would run or could be asked: anything but a denial.
+            return (decideEffect(policy, t, {
+                approvals,
+                capabilityGranted: !!(t.capability &&
+                    sessionId &&
+                    o.capabilities?.granted(t.capability, sessionId)),
+            }).kind !== "deny");
         });
     }
     /** Abort signal of the session's active run, if any (used to cascade cancellation). */
@@ -415,6 +411,11 @@ export class AgentRunner {
         const { call } = p;
         let result;
         const started = Date.now();
+        /** Set by the call itself (see `CallInternals`): it may have left effects. */
+        let effectful = false;
+        let dispatcher;
+        /** Held from the scratchpad quota check until the write is done (L1). */
+        let releaseScratch;
         // `effect` rides along so the TUI can group consecutive calls by capability kind
         // (read batches, write batches, commands…) without a name heuristic. Additive field.
         emit("tool_started", {
@@ -436,6 +437,7 @@ export class AgentRunner {
             // resolved map keeps "allow once" scoped to this one call, with no shared mutable
             // state that parallel read batches could race on.
             const resolved = new Map();
+            const targets = [];
             if (pathAccess)
                 for (const declared of p.tool.paths?.(p.input) ?? [])
                     if (!resolved.has(declared)) {
@@ -450,6 +452,7 @@ export class AgentRunner {
                         // ask a second time for an "allow once" decision.
                         resolved.set(declared, target);
                         resolved.set(target, target);
+                        targets.push(target);
                     }
             scope.guard?.(effect);
             if ((options.toolFilter && !options.toolFilter(p.tool)) ||
@@ -457,26 +460,62 @@ export class AgentRunner {
                 throw new Error(`Tool ${call.name} is not available in this session`);
             const capability = p.tool.capability;
             const gate = o.capabilities;
-            if (capability && (allowed(policy, effect) || capabilityAllowed(policy, p.tool))) {
-                // A broad process grant or --allow-analysis: allowed, audited as a flag decision.
-                gate?.record({
-                    capability,
-                    sessionId,
-                    scope: "once",
-                    decision: "allow",
-                    source: "flag",
-                    callId: call.id,
-                    runId,
-                    ...(options.correlationId !== undefined ? { correlationId: options.correlationId } : {}),
-                });
+            let decision = decideEffect(policy, p.tool, {
+                approvals: !!o.approve && approvals,
+                capabilityGranted: !!capability && !!gate?.granted(capability, sessionId),
+            });
+            // The session's scratchpad is an authorized write root (Forja, spec §9.4): a write confined
+            // to it needs no approval in any mode, headless runs included. What is lifted is a call that
+            // WOULD ask a person; a run locked down on purpose (`--read-only`, which has no scratchpad
+            // root, or a child run with approvals turned off) keeps its denial.
+            if (decision.kind !== "allow" &&
+                effect === "write" &&
+                !capability &&
+                options.approvals !== false &&
+                hasScratchEstimator(p.tool.name) &&
+                pathAccess &&
+                targets.length > 0 &&
+                decideEffect(policy, p.tool, { approvals: true, capabilityGranted: false }).kind ===
+                    "ask" &&
+                (await Promise.all(targets.map((t) => pathAccess.isScratchPath(t, sessionId)))).every(Boolean))
+                decision = { kind: "allow", via: "effect" };
+            // A write into the scratchpad also has a quota (FJ-AC-34), whatever allowed it: a full
+            // scratchpad refuses new writes with a plain error and deletes nothing.
+            if (decision.kind === "allow" &&
+                effect === "write" &&
+                !capability &&
+                pathAccess &&
+                targets.length > 0 &&
+                (await Promise.all(targets.map((t) => pathAccess.isScratchPath(t, sessionId)))).every(Boolean)) {
+                releaseScratch = await pathAccess.lockScratch(sessionId);
+                const problem = await pathAccess.scratchQuotaProblem(sessionId, await scratchIncomingBytes(p.tool.name, p.input, targets), targets);
+                if (problem)
+                    throw new Error(problem);
+            }
+            if (decision.kind === "allow") {
+                // A broad process grant or --allow-analysis is audited as a flag decision; a plain effect
+                // and a persisted "allow for this session" grant of the root session leave no record here.
+                if (capability && decision.via === "flag")
+                    gate?.record({
+                        capability,
+                        sessionId,
+                        scope: "once",
+                        decision: "allow",
+                        source: "flag",
+                        callId: call.id,
+                        runId,
+                        ...(options.correlationId !== undefined
+                            ? { correlationId: options.correlationId }
+                            : {}),
+                    });
             }
-            else if (capability && gate?.granted(capability, sessionId)) {
-                // A persisted "allow for this session" grant of the root session.
+            else if (decision.kind === "deny") {
+                throw new Error(`Capability denied: ${capability ?? effect}`);
             }
-            else if (!allowed(policy, effect)) {
-                if (!o.approve ||
-                    !approvals ||
-                    (effect !== "write" && effect !== "process" && effect !== "external"))
+            else {
+                const approve = o.approve;
+                // `ask` is only ever decided for an askable effect with a handler (see `decideEffect`).
+                if (!approve || !effectAskable(effect))
                     throw new Error(`Capability denied: ${capability ?? effect}`);
                 const preview = capability
                     ? (scriptPreview(p.input) ?? (await gate?.preview?.(p.input, sessionId)))
@@ -488,7 +527,6 @@ export class AgentRunner {
                     ...(options.label ? { label: options.label } : {}),
                     ...(capability ? { capability } : {}),
                 });
-                const approve = o.approve;
                 const callInput = p.input;
                 // Waiting for the person is not work: the run's time limit does not count it.
                 const decision = await this.humanWaits.track(sessionId, () => approve({
@@ -593,7 +631,7 @@ export class AgentRunner {
                 });
                 return allowedNow ? "once" : "deny";
             };
-            result = await p.tool.execute(p.input, {
+            const toolContext = {
                 signal: combined,
                 workspace,
                 session: sessionId,
@@ -625,7 +663,35 @@ export class AgentRunner {
                         },
                     }
                     : {}),
+            };
+            // Only the core's own tools can find these (see `CallInternals`); the SDK context is unchanged.
+            bindCallInternals(toolContext, {
+                markEffectful: () => {
+                    effectful = true;
+                },
+                nested: () => (dispatcher ??= createNestedDispatcher({
+                    registry: o.registry,
+                    policy,
+                    approvals: !!o.approve && approvals,
+                    scratchWrites: options.approvals !== false,
+                    ...(options.toolFilter ? { toolFilter: options.toolFilter } : {}),
+                    ...(options.optInTools ? { optInTools: options.optInTools } : {}),
+                    workspace,
+                    session: sessionId,
+                    ...(options.label ? { label: options.label } : {}),
+                    runId,
+                    parentCallId: call.id,
+                    signal: combined,
+                    ...(pathAccess ? { pathAccess } : {}),
+                    ...(publisher ? { artifacts: publisher } : {}),
+                    ...(decisions ? { decisions } : {}),
+                    ...(scope.guard ? { guard: scope.guard } : {}),
+                    markEffectful: () => {
+                        effectful = true;
+                    },
+                })),
             });
+            result = await p.tool.execute(p.input, toolContext);
             // The bound applies to what the model sees (the text projection): display-only
             // ui/image parts are bounded by their producers and must not push text over it.
             const projected = textProjection(result);
@@ -640,10 +706,14 @@ export class AgentRunner {
             // the user to inspect. A `read` call cannot have left any (and `exit_plan`, which is one,
             // is exactly what a stop or the run limit interrupts while a person decides): it is closed
             // with the cancellation, so the next message continues normally instead of asking to
-            // "recover" a call nobody needs to inspect.
-            if (!combined.aborted || p.tool?.effect === "read")
+            // "recover" a call nobody needs to inspect. A read that flagged itself `effectful` (js_run
+            // after a nested write) is the exception: it stays pending like any other effectful call.
+            if (!combined.aborted || (p.tool?.effect === "read" && !effectful))
                 o.store.endCall(sessionId, call, result);
         }
+        finally {
+            releaseScratch?.();
+        }
         emit("tool_completed", {
             id: call.id,
             name: call.name,
@@ -1262,7 +1332,10 @@ export class AgentRunner {
                 const execute = (p) => this.executeCall(scope, p);
                 const results = [];
                 // Bounded parallel batches for consecutive read or explicitly concurrent tools.
-                const parallel = (p) => !!p?.tool && (p.tool.effect === "read" || p.tool.concurrent === true);
+                // `concurrent: false` keeps a tool out of the batch even when it is a read (js_run).
+                const parallel = (p) => !!p?.tool &&
+                    p.tool.concurrent !== false &&
+                    (p.tool.effect === "read" || p.tool.concurrent === true);
                 for (let i = 0; i < prepared.length;) {
                     const current = prepared[i];
                     if (!current)

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;