@alisio/core 0.5.2 → 0.7.0

package/dist/forge/journal.js

@@ -0,0 +1,174 @@
+import { isProcessAlive } from "../runtime/process.js";
+import { canTransition, InvalidTransitionError } from "./state-machine.js";
+const TERMINAL = ["succeeded", "failed", "cancelled", "timed_out"];
+const isTerminal = (state) => TERMINAL.includes(state);
+/** The id of the n-th nested call of a tool call (D-24). It never enters `tool_calls`. */
+export const forgeCallId = (toolCallId, n) => `${toolCallId}:forge:${n}`;
+function toRecord(row) {
+    return {
+        id: String(row.id),
+        rootSessionId: String(row.root_session_id),
+        sessionId: String(row.session_id),
+        toolCallId: String(row.tool_call_id),
+        engine: row.engine,
+        isolation: row.isolation,
+        selectionReason: String(row.selection_reason),
+        status: row.status,
+        codeSha256: String(row.code_sha256),
+        startedAt: Number(row.started_at),
+        ...(row.ended_at != null ? { endedAt: Number(row.ended_at) } : {}),
+        ...(row.metrics_json != null
+            ? { metrics: JSON.parse(String(row.metrics_json)) }
+            : {}),
+        ...(row.error_code != null ? { errorCode: row.error_code } : {}),
+        terminationUnconfirmed: Number(row.termination_unconfirmed) === 1,
+        ...(row.analysis_execution_id != null
+            ? { analysisExecutionId: String(row.analysis_execution_id) }
+            : {}),
+        ...(row.owner_pid != null ? { ownerPid: Number(row.owner_pid) } : {}),
+    };
+}
+function toCall(row) {
+    return {
+        executionId: String(row.execution_id),
+        callId: String(row.call_id),
+        toolName: String(row.tool_name),
+        effect: row.effect,
+        status: row.status,
+        ...(row.duration_ms != null ? { durationMs: Number(row.duration_ms) } : {}),
+        inputSha256: String(row.input_sha256),
+        ...(row.error_code != null ? { errorCode: row.error_code } : {}),
+        ...(row.paths_json != null ? { paths: JSON.parse(String(row.paths_json)) } : {}),
+    };
+}
+export class SqliteExecutionJournal {
+    #db;
+    #now;
+    #ownerPid;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#now = options.now ?? Date.now;
+        this.#ownerPid = options.ownerPid ?? process.pid;
+    }
+    /** Records a new execution in `validating`. */
+    open(input) {
+        this.#db
+            .prepare(`INSERT INTO forge_executions(id,root_session_id,session_id,tool_call_id,engine,isolation,
+           selection_reason,status,code_sha256,started_at,analysis_execution_id,owner_pid)
+         VALUES(?,?,?,?,?,?,?,'validating',?,?,?,?)`)
+            .run(input.id, input.rootSessionId, input.sessionId, input.toolCallId, input.engine, input.isolation, input.selectionReason, input.codeSha256, this.#now(), input.analysisExecutionId ?? null, this.#ownerPid);
+        return this.#required(input.id);
+    }
+    /** Links the execution to the `analysis_executions` row its engine created while preparing. */
+    linkAnalysisExecution(id, analysisExecutionId) {
+        const result = this.#db
+            .prepare("UPDATE forge_executions SET analysis_execution_id=? WHERE id=?")
+            .run(analysisExecutionId, id);
+        if (Number(result.changes) === 0)
+            throw new Error(`Unknown Forja execution: ${id}`);
+    }
+    get(id) {
+        const row = this.#db.prepare("SELECT * FROM forge_executions WHERE id=?").get(id);
+        return row ? toRecord(row) : undefined;
+    }
+    listByRoot(rootSessionId) {
+        return this.#db
+            .prepare("SELECT * FROM forge_executions WHERE root_session_id=? ORDER BY started_at, id")
+            .all(rootSessionId).map(toRecord);
+    }
+    /** Moves to a non-terminal state the diagram allows. Terminal states go through `close()`. */
+    transition(id, to) {
+        if (isTerminal(to))
+            throw new Error(`Terminal state ${to} is reached through close(), not transition()`);
+        this.#advance(id, to, {});
+    }
+    /** Reaches a terminal state, once. A second close throws and changes nothing. */
+    close(id, outcome) {
+        if (!isTerminal(outcome.status))
+            throw new Error(`close() needs a terminal state, got ${String(outcome.status)}`);
+        this.#advance(id, outcome.status, {
+            endedAt: this.#now(),
+            errorCode: outcome.errorCode ?? null,
+            metrics: outcome.metrics ? JSON.stringify(outcome.metrics) : null,
+            unconfirmed: outcome.terminationUnconfirmed ? 1 : 0,
+        });
+    }
+    #advance(id, to, terminal) {
+        this.#db.transaction(() => {
+            const row = this.#db.prepare("SELECT status FROM forge_executions WHERE id=?").get(id);
+            if (!row)
+                throw new Error(`Unknown Forja execution: ${id}`);
+            if (!canTransition(row.status, to))
+                throw new InvalidTransitionError(row.status, to);
+            if (terminal.endedAt === undefined) {
+                this.#db
+                    .prepare("UPDATE forge_executions SET status=? WHERE id=? AND status=?")
+                    .run(to, id, row.status);
+                return;
+            }
+            this.#db
+                .prepare(`UPDATE forge_executions SET status=?, ended_at=?, error_code=?, metrics_json=?,
+             termination_unconfirmed=? WHERE id=? AND status=?`)
+                .run(to, terminal.endedAt, terminal.errorCode ?? null, terminal.metrics ?? null, terminal.unconfirmed ?? 0, id, row.status);
+        });
+    }
+    /** Records the start of a nested call and returns its id. */
+    startCall(input) {
+        const execution = this.#required(input.executionId);
+        const callId = forgeCallId(execution.toolCallId, input.n);
+        this.#db
+            .prepare(`INSERT INTO forge_calls(execution_id,call_id,tool_name,effect,status,input_sha256,paths_json)
+         VALUES(?,?,?,?,'started',?,?)`)
+            .run(input.executionId, callId, input.toolName, input.effect, input.inputSha256, input.effect === "write" && input.paths ? JSON.stringify(input.paths) : null);
+        return callId;
+    }
+    /** Ends a call that is still `started`; false when it already ended (or does not exist). */
+    endCall(executionId, callId, outcome) {
+        const result = this.#db
+            .prepare(`UPDATE forge_calls SET status=?, duration_ms=?, error_code=?
+         WHERE execution_id=? AND call_id=? AND status='started'`)
+            .run(outcome.status, outcome.durationMs ?? null, outcome.errorCode ?? null, executionId, callId);
+        return Number(result.changes) > 0;
+    }
+    calls(executionId) {
+        const rows = this.#db
+            .prepare("SELECT * FROM forge_calls WHERE execution_id=?")
+            .all(executionId);
+        const position = (callId) => Number(callId.slice(callId.lastIndexOf(":") + 1));
+        return rows.map(toCall).sort((a, b) => position(a.callId) - position(b.callId));
+    }
+    #required(id) {
+        const record = this.get(id);
+        if (!record)
+            throw new Error(`Unknown Forja execution: ${id}`);
+        return record;
+    }
+}
+/**
+ * Restart reconciliation (§9.3, FJ-AC-25): every non-terminal execution whose owner process is
+ * gone (or unknown) becomes `failed` with `ISOLATE_FAILURE` and reason `interrupted`. Nothing is
+ * relaunched. Executions of another live process are left alone. Returns the rows reconciled.
+ *
+ * Call it once when the application opens the store (Phase 3 wires it next to the runner).
+ */
+export function reconcileInterruptedExecutions(db, options = {}) {
+    const now = (options.now ?? Date.now)();
+    const isAlive = options.isAlive ?? isProcessAlive;
+    return db.transaction(() => {
+        const rows = db
+            .prepare(`SELECT id, status, owner_pid FROM forge_executions
+         WHERE status NOT IN ('succeeded','failed','cancelled','timed_out')`)
+            .all();
+        const update = db.prepare(`UPDATE forge_executions SET status='failed', error_code='ISOLATE_FAILURE', ended_at=?,
+         metrics_json=? WHERE id=? AND status=?`);
+        let reconciled = 0;
+        for (const row of rows) {
+            if (row.owner_pid != null && isAlive(row.owner_pid))
+                continue;
+            const result = update.run(now, JSON.stringify({ reason: "interrupted" }), row.id, row.status);
+            if (Number(result.changes) > 0)
+                reconciled++;
+        }
+        return reconciled;
+    });
+}

package/dist/forge/kernel.d.ts

@@ -0,0 +1,76 @@
+import type { EngineId, EngineLanguage, ForgeProgress, PermissionMode } from "@alisio/sdk";
+import type { SqliteExecutionJournal } from "./journal.ts";
+import { type ForgeLimits } from "./limits.ts";
+import type { NestedCallDispatcher } from "./nested.ts";
+import type { EngineRegistry } from "./registry.ts";
+import { type ForgeResult } from "./result.ts";
+import { type EngineSelector, type JavaScriptSelectionContext, type Selection } from "./selector.ts";
+import type { SlotTable } from "./slots.ts";
+import type { SqliteStateStore } from "./state-store.ts";
+export interface KernelConfig {
+    /** `forge.javascript.enabled`. */
+    enabled: boolean;
+    /** The configured limits (the global layer; project config only ever lowered them already). */
+    limits: Partial<ForgeLimits>;
+    /** `forge.state.enabled`. */
+    stateEnabled: boolean;
+}
+export interface KernelDeps {
+    engines: EngineRegistry;
+    selector: EngineSelector<JavaScriptSelectionContext, EngineId>;
+    journal: SqliteExecutionJournal;
+    state?: SqliteStateStore;
+    slots: SlotTable;
+    config: () => KernelConfig;
+    now?: () => number;
+    newId?: () => string;
+    /** How long the end of an execution waits for nested calls the script left running. */
+    drainMs?: number;
+}
+/** Everything the core knows about the call that asks for the execution; the model controls none of it. */
+export interface KernelCallContext {
+    toolCallId: string;
+    session: string;
+    rootSessionId: string;
+    workspace: string;
+    signal: AbortSignal;
+    permissionMode: PermissionMode;
+    allowAnalysis: boolean;
+    allowProcess: boolean;
+    /** Absent for an engine that cannot call tools (Python): the kernel then offers none. */
+    dispatcher?: NestedCallDispatcher;
+    /** Delivers `ForgeProgress` to the run (already coalesced to 4 per second). */
+    emit: (progress: ForgeProgress) => void;
+    /** `<sessionDir>/tasks/<executionId>.log` is written under this folder when given. */
+    tasksDir?: string;
+}
+export interface KernelInvocation {
+    source: string;
+    title?: string;
+    requestedLimits?: Partial<ForgeLimits>;
+    call: KernelCallContext;
+    /** Language of `source`; JavaScript when omitted. */
+    language?: EngineLanguage;
+    /**
+     * A selection the caller already made (Python's backend selector). It replaces the JavaScript
+     * chain; the engine must be registered. The model never provides it.
+     */
+    selection?: Selection<EngineId>;
+    /** Per-engine request extensions, handed to `prepare` next to the state snapshot. */
+    payload?: Record<string, unknown>;
+    /**
+     * Limits set by the core after the merge (Python's own timeout and source size, which the
+     * JavaScript maxima do not describe). Never built from model input.
+     */
+    limitOverrides?: Partial<ForgeLimits>;
+}
+/** The result plus the bound on what the model sees of it (the effective `maxOutputChars`). */
+export interface KernelOutcome {
+    result: ForgeResult;
+    maxOutputChars: number;
+}
+export declare class ExecutionKernel {
+    #private;
+    constructor(deps: KernelDeps);
+    execute(invocation: KernelInvocation): Promise<KernelOutcome>;
+}

package/dist/forge/kernel.js

@@ -0,0 +1,339 @@
+/**
+ * `ExecutionKernel` (spec D1, §5.2): the fixed lifecycle every Forja execution follows, whatever the
+ * engine. Template Method:
+ *
+ *   validate -> admit -> select -> prepare -> run (with deadline) -> collect -> cleanup (always)
+ *
+ * The kernel owns what must not depend on an engine: limits, the concurrency slots, the journal
+ * (every transition and nested call), the cross-execution state (committed only on success), the
+ * deadline and cancellation with the host's OWN clock, the output bound and the single terminal
+ * state. The engine only knows how to run code in an isolate.
+ */
+import { createHash } from "node:crypto";
+import { newUuid } from "../runtime/ids.js";
+import { CapabilityBroker } from "./broker.js";
+import { BudgetLedger } from "./budget.js";
+import { ForgeError, isForgeError } from "./errors.js";
+import { DEFAULT_FORGE_LIMITS, mergeLimits } from "./limits.js";
+import { ProgressCoalescer } from "./progress.js";
+import { hintFor } from "./result.js";
+import { StateDelta } from "./state-delta.js";
+import { ExecutionStateMachine } from "./state-machine.js";
+import { TaskLog } from "./task-log.js";
+import { verdictOf } from "./verdict.js";
+/** What an engine without tool calls sees as its nested-call port: nothing. */
+const NO_NESTED_CALLS = {
+    catalog: () => [],
+    knows: () => false,
+    call: async () => ({
+        ok: false,
+        nestedCallId: "",
+        code: "TOOL_UNAVAILABLE",
+        message: "this engine cannot call tools",
+    }),
+};
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+export class ExecutionKernel {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    async execute(invocation) {
+        const deps = this.#deps;
+        const now = deps.now ?? Date.now;
+        const call = invocation.call;
+        const startedAt = now();
+        const id = (deps.newId ?? (() => `fx_${newUuid()}`))();
+        const config = deps.config();
+        const descriptors = deps.engines.descriptors();
+        const language = invocation.language ?? "javascript";
+        const dispatcher = call.dispatcher ?? NO_NESTED_CALLS;
+        // select (cheap and pure, so it precedes the journal row, which needs the engine and the reason)
+        let selection;
+        let selectionError;
+        try {
+            selection =
+                invocation.selection ??
+                    deps.selector.select({
+                        language,
+                        javascriptEnabled: config.enabled,
+                        descriptors,
+                    });
+        }
+        catch (error) {
+            selectionError = isForgeError(error)
+                ? error
+                : new ForgeError("ENGINE_UNAVAILABLE", error instanceof Error ? error.message : String(error));
+        }
+        const engineId = selection?.engine ?? "javascript-quickjs";
+        const isolation = descriptors[engineId]?.isolation ?? "none";
+        const selectionReason = selection?.reason ?? selectionError?.message ?? "no engine";
+        deps.journal.open({
+            id,
+            rootSessionId: call.rootSessionId,
+            sessionId: call.session,
+            toolCallId: call.toolCallId,
+            engine: engineId,
+            isolation,
+            selectionReason,
+            codeSha256: sha256(invocation.source),
+        });
+        const machine = new ExecutionStateMachine();
+        const advance = (to) => {
+            machine.transition(to);
+            deps.journal.transition(id, to);
+        };
+        const log = call.tasksDir ? new TaskLog(`${call.tasksDir}/${id}.log`) : undefined;
+        const progress = new ProgressCoalescer(call.emit);
+        const base = { kind: "forge", executionId: id, engine: engineId };
+        const phase = (name, message) => progress.terminal({ ...base, phase: name, ...(message ? { message } : {}) });
+        let limits;
+        let release;
+        let engine;
+        let prepared;
+        let broker;
+        let verdict = {
+            status: "failed",
+            error: { code: "ISOLATE_FAILURE", message: "execution did not finish" },
+        };
+        let report;
+        let queueMs = 0;
+        const abort = new AbortController();
+        let stop;
+        let running = false;
+        let timer;
+        let termination;
+        const requestStop = (reason) => {
+            if (!running || stop)
+                return;
+            stop = reason;
+            // Nested calls hear it first: a guest waiting on one executes no bytecode and cannot notice.
+            abort.abort(new Error(reason === "timeout" ? "deadline" : "cancelled"));
+            const why = reason === "timeout" ? "timeout" : "cancelled";
+            if (engine && prepared)
+                termination = engine.terminate(prepared, why);
+        };
+        const onUserAbort = () => requestStop("cancelled");
+        try {
+            // validate
+            if (selectionError)
+                throw selectionError;
+            const layers = {
+                global: config.limits,
+                ...(invocation.requestedLimits ? { request: invocation.requestedLimits } : {}),
+            };
+            limits = { ...mergeLimits(layers), ...invocation.limitOverrides };
+            if (Buffer.byteLength(invocation.source, "utf8") > limits.maxSourceBytes)
+                throw new ForgeError("INVALID_INPUT", `the script is larger than ${limits.maxSourceBytes} bytes`);
+            if (invocation.source.trim() === "")
+                throw new ForgeError("INVALID_INPUT", "the script is empty");
+            // admit (the slots are the JavaScript engine's: Python runs are not Forja script hosts, and a
+            // `js_run` that calls `python_run` holds its session's slot while the Python run starts)
+            if (language === "javascript")
+                release = deps.slots.acquire(call.session);
+            advance("preparing");
+            phase("preparing");
+            const snapshot = config.stateEnabled && deps.state
+                ? deps.state.snapshot(call.rootSessionId)
+                : { values: {}, revisions: {} };
+            const delta = config.stateEnabled && deps.state ? new StateDelta(snapshot) : undefined;
+            // prepare
+            engine = deps.engines.get(engineId);
+            const request = {
+                language,
+                source: invocation.source,
+                ...(invocation.title ? { title: invocation.title } : {}),
+                engineHint: engineId,
+                payload: {
+                    ...invocation.payload,
+                    state: snapshot.values,
+                    catalogSize: dispatcher.catalog().length,
+                },
+            };
+            prepared = await engine.prepare(request, {
+                executionId: id,
+                toolCallId: call.toolCallId,
+                rootSessionId: call.rootSessionId,
+                workspace: call.workspace,
+                permissionMode: call.permissionMode,
+                allowAnalysis: call.allowAnalysis,
+                allowProcess: call.allowProcess,
+                signal: call.signal,
+                limits,
+            });
+            if (prepared.analysisExecutionId)
+                deps.journal.linkAnalysisExecution(id, prepared.analysisExecutionId);
+            broker = new CapabilityBroker({
+                dispatcher,
+                ledger: new BudgetLedger(limits),
+                limits,
+                journal: deps.journal,
+                executionId: id,
+                signal: abort.signal,
+                state: delta,
+                update: (event) => progress.update(event),
+                terminal: (event) => progress.terminal(event),
+                engine: engineId,
+                log: (line) => log?.write(line),
+                now,
+            });
+            const activeBroker = broker;
+            let send = () => { };
+            activeBroker.bind((reply) => send(reply));
+            // run (the deadline starts here and covers compute and nested calls)
+            let outcome;
+            if (call.signal.aborted) {
+                // Cancelled before it ever ran: preparing -> cancelled.
+                outcome = { kind: "failed", code: "CANCELLED", message: "cancelled" };
+                verdict = verdictOf(outcome, "cancelled", limits.timeoutMs);
+            }
+            else {
+                advance("running");
+                running = true;
+                queueMs = now() - startedAt;
+                phase("running");
+                log?.write(`started ${id} (${selectionReason})`);
+                call.signal.addEventListener("abort", onUserAbort, { once: true });
+                timer = setTimeout(() => requestStop("timeout"), limits.timeoutMs);
+                outcome = await engine.run(prepared, {
+                    receive: (message) => activeBroker.receive(message),
+                    bind: (next) => {
+                        send = next;
+                    },
+                    signal: abort.signal,
+                });
+                running = false;
+                // The engine's own collection (artifacts to publish) comes before the state commit, and
+                // only for an execution the host did not stop.
+                let collecting = false;
+                if (!stop && engine.collect) {
+                    if (outcome.kind === "completed") {
+                        advance("collecting");
+                        phase("collecting");
+                        collecting = true;
+                    }
+                    outcome = await engine.collect(prepared, outcome);
+                }
+                verdict = verdictOf(outcome, stop, limits.timeoutMs);
+                if (stop) {
+                    // The host's own stop decides the terminal state; wait until the guest is confirmed gone.
+                    report = await (termination ??
+                        engine.terminate(prepared, stop === "timeout" ? "timeout" : "cancelled"));
+                }
+                else if (outcome.kind === "failed") {
+                    report = await engine.terminate(prepared, "limit_exceeded");
+                }
+                abort.abort(new Error("execution ended"));
+                await activeBroker.drain(deps.drainMs ?? 2_000);
+                if (verdict.status === "succeeded") {
+                    if (!collecting) {
+                        advance("collecting");
+                        phase("collecting");
+                    }
+                    try {
+                        if (delta && deps.state)
+                            deps.state.commit(call.rootSessionId, snapshot, delta.ops());
+                    }
+                    catch (error) {
+                        if (isForgeError(error))
+                            verdict = { status: "failed", error: { code: error.code, message: error.message } };
+                        else
+                            throw error;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            running = false;
+            const forge = isForgeError(error) ? error : undefined;
+            verdict = {
+                status: "failed",
+                error: {
+                    code: forge?.code ?? "ISOLATE_FAILURE",
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+        finally {
+            clearTimeout(timer);
+            call.signal.removeEventListener("abort", onUserAbort);
+            abort.abort(new Error("execution ended"));
+            if (broker)
+                await broker.drain(deps.drainMs ?? 2_000);
+            if (engine && prepared) {
+                try {
+                    await engine.dispose(prepared);
+                }
+                catch {
+                    /* The isolate is already stopped or unreachable; nothing more to do from here. */
+                }
+            }
+            progress.close();
+        }
+        // The terminal state is reached exactly once, with the state machine's blessing.
+        const unconfirmed = report ? !report.confirmed : false;
+        const stats = broker?.stats ?? { total: 0, failed: 0, denied: 0 };
+        const output = broker?.output ?? [];
+        const outputBytes = output.reduce((sum, item) => sum + Buffer.byteLength(JSON.stringify(item)), 0);
+        const wallMs = now() - startedAt;
+        try {
+            if (verdict.status === "cancelled" && machine.state === "running")
+                advance("cancelling");
+            if (verdict.status === "timed_out" && machine.state === "running")
+                advance("timed_out_pending");
+            deps.journal.close(id, {
+                status: verdict.status,
+                ...(verdict.error ? { errorCode: verdict.error.code } : {}),
+                metrics: {
+                    wallMs,
+                    queueMs,
+                    calls: stats,
+                    outputBytes,
+                    ...(broker?.progressDropped ? { progressDropped: broker.progressDropped } : {}),
+                },
+                terminationUnconfirmed: unconfirmed,
+            });
+        }
+        catch (error) {
+            // The row is already terminal (a reconciliation raced us); the result still goes back.
+            log?.write(`journal: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        log?.write(`${verdict.status}${verdict.error ? `: ${verdict.error.code}` : ""} (${wallMs} ms)`);
+        await log?.flush();
+        // A guest that could not be confirmed gone keeps its slot until it is (or the process ends).
+        if (unconfirmed && report?.settled)
+            void report.settled.then(() => release?.());
+        else
+            release?.();
+        const result = {
+            schemaVersion: 1,
+            executionId: id,
+            engine: engineId,
+            isolation,
+            selectionReason,
+            status: verdict.status,
+            output,
+            ...(verdict.value !== undefined ? { value: verdict.value } : {}),
+            ...(verdict.error
+                ? {
+                    error: {
+                        ...verdict.error,
+                        ...(() => {
+                            const hint = language === "javascript"
+                                ? hintFor(verdict.error.code, verdict.error.message, invocation.source)
+                                : undefined;
+                            return hint ? { hint } : {};
+                        })(),
+                    },
+                }
+                : {}),
+            calls: stats,
+            truncated: false,
+            metrics: { wallMs, queueMs, outputBytes },
+        };
+        return {
+            result,
+            maxOutputChars: limits?.maxOutputChars ?? DEFAULT_FORGE_LIMITS.maxOutputChars,
+        };
+    }
+}

package/dist/forge/limits.d.ts

@@ -0,0 +1,38 @@
+export interface ForgeLimits {
+    maxSourceBytes: number;
+    timeoutMs: number;
+    /** QuickJS heap. */
+    memoryBytes: number;
+    /** QuickJS stack. */
+    stackBytes: number;
+    /** Nested tool calls per execution. */
+    maxToolCalls: number;
+    /** Simultaneous nested tool calls. */
+    maxConcurrency: number;
+    maxCallInputBytes: number;
+    maxCallResponseBytes: number;
+    maxRetainedOutputBytes: number;
+    /** Characters of output returned to the model. */
+    maxOutputChars: number;
+}
+export type ForgeLimitKey = keyof ForgeLimits;
+/**
+ * The most a tool input may weigh: the protocol message that carries it (envelope, ids, tool name)
+ * must fit in `MAX_MESSAGE_BYTES`, so the effective limit stays a little below it whatever the
+ * configuration says. Over this a call is refused as `TOOL_INPUT_INVALID` before it is sent.
+ */
+export declare const MAX_CALL_INPUT_BYTES: number;
+/** Defaults of the spec's §6.5 table. */
+export declare const DEFAULT_FORGE_LIMITS: Readonly<ForgeLimits>;
+/** Hard global maxima of the same table. */
+export declare const MAX_FORGE_LIMITS: Readonly<ForgeLimits>;
+/** The limits a project config may lower; the rest is global-only. */
+export declare const PROJECT_LOWERABLE_LIMITS: readonly ForgeLimitKey[];
+export interface LimitLayers {
+    global?: Partial<ForgeLimits>;
+    project?: Partial<ForgeLimits>;
+    request?: Partial<ForgeLimits>;
+}
+export declare function mergeLimits(layers: LimitLayers): ForgeLimits;
+/** The limits the guest is told about in `start`; the host enforces them regardless. */
+export type GuestLimits = Pick<ForgeLimits, "timeoutMs" | "memoryBytes" | "stackBytes" | "maxToolCalls" | "maxConcurrency" | "maxCallInputBytes" | "maxCallResponseBytes" | "maxRetainedOutputBytes">;