@alisio/core 0.5.2 → 0.6.0

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,338 @@
+/**
+ * `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, randomUUID } from "node:crypto";
+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_${randomUUID()}`))();
+        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">;

package/dist/forge/limits.js

@@ -0,0 +1,73 @@
+/**
+ * Forja limit merging: global ∩ project ∩ request. Pure: no I/O.
+ *
+ * The global layer (user config) picks values up to the hard maxima; project and request layers can
+ * only lower them (spec D16). Projects may lower only a subset (§10); a request may lower any limit.
+ */
+import { ForgeError } from "./errors.js";
+import { MAX_MESSAGE_BYTES } from "./protocol.js";
+const KiB = 1024;
+const MiB = 1024 * KiB;
+/**
+ * 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 const MAX_CALL_INPUT_BYTES = MAX_MESSAGE_BYTES - 4 * KiB;
+/** Defaults of the spec's §6.5 table. */
+export const DEFAULT_FORGE_LIMITS = {
+    maxSourceBytes: 64 * KiB,
+    timeoutMs: 30_000,
+    memoryBytes: 32 * MiB,
+    stackBytes: 256 * KiB,
+    maxToolCalls: 50,
+    maxConcurrency: 4,
+    maxCallInputBytes: 256 * KiB,
+    maxCallResponseBytes: 512 * KiB,
+    maxRetainedOutputBytes: 1 * MiB,
+    maxOutputChars: 16_000,
+};
+/** Hard global maxima of the same table. */
+export const MAX_FORGE_LIMITS = {
+    maxSourceBytes: 64 * KiB,
+    timeoutMs: 300_000,
+    memoryBytes: 128 * MiB,
+    stackBytes: 512 * KiB,
+    maxToolCalls: 500,
+    maxConcurrency: 16,
+    maxCallInputBytes: 1 * MiB,
+    maxCallResponseBytes: 2 * MiB,
+    maxRetainedOutputBytes: 4 * MiB,
+    maxOutputChars: 48_000,
+};
+/** The limits a project config may lower; the rest is global-only. */
+export const PROJECT_LOWERABLE_LIMITS = [
+    "timeoutMs",
+    "maxToolCalls",
+    "maxConcurrency",
+    "maxOutputChars",
+];
+const KEYS = Object.keys(DEFAULT_FORGE_LIMITS);
+function checked(layer, key, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new ForgeError("INVALID_INPUT", `${layer} limit ${key} must be a positive integer`);
+    }
+    return value;
+}
+export function mergeLimits(layers) {
+    const merged = { ...DEFAULT_FORGE_LIMITS };
+    for (const key of KEYS) {
+        const configured = layers.global?.[key];
+        if (configured !== undefined) {
+            merged[key] = Math.min(checked("global", key, configured), MAX_FORGE_LIMITS[key]);
+        }
+        const project = PROJECT_LOWERABLE_LIMITS.includes(key) ? layers.project?.[key] : undefined;
+        if (project !== undefined)
+            merged[key] = Math.min(merged[key], checked("project", key, project));
+        const request = layers.request?.[key];
+        if (request !== undefined)
+            merged[key] = Math.min(merged[key], checked("request", key, request));
+    }
+    merged.maxCallInputBytes = Math.min(merged.maxCallInputBytes, MAX_CALL_INPUT_BYTES);
+    return merged;
+}

package/dist/forge/nested.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The nested-call port of Forja (spec D-24, D-29, §6.4): how a script running inside a `js_run`
+ * call reaches other tools. A nested call is NOT a second permission system: it passes the same
+ * gate a direct call of the run passes (the run's `toolFilter`, opt-in tools, the LIVE run policy
+ * and `decideEffect`), with two differences that follow from "never open a new approval":
+ * approvals and stored grants do not exist for it, and the answer to "would need to ask" is a
+ * structured error instead of a prompt.
+ *
+ * The runner builds one dispatcher per tool call (`core/call-internals.ts`); the broker of Phase 3b
+ * is its only consumer. Nothing here knows QuickJS.
+ */
+import type { ArtifactPublisher, ToolDecisions, ToolDefinition, ToolResult } from "@alisio/sdk";
+import type { Policy } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+import type { PathAccess } from "../runtime/access.ts";
+import { type ForgeErrorCode } from "./errors.ts";
+/**
+ * Tools no script can reach in v1: Forja's own tools and `execute` (no recursion), the guide
+ * (a model-facing tool), and the subagent tools (`task`, `task_wait` and `send_message` can wait
+ * on a child session that is waiting for this very call: D-29), and `ask_user_question` (the only
+ * tool that opens an interactive prompt; approvals and installs are already refused). Opt-in tools (`OPT_IN_TOOLS`) are
+ * excluded as well.
+ */
+export declare const FORGE_EXCLUDED_TOOLS: ReadonlySet<string>;
+export interface NestedCallStart {
+    /** `${parentCallId}:forge:${n}`: the journal id of this call; never a `tool_calls` row. */
+    nestedCallId: string;
+    name: string;
+    effect: string;
+    /** Resolved absolute paths the tool declared (journaled for `write` calls, D-31). */
+    paths: string[];
+}
+export interface NestedCallRequest {
+    name: unknown;
+    input?: unknown;
+    /** Cancels this call; combined with the signal of the parent call. */
+    signal?: AbortSignal;
+    /** Runs once the call passed the gate, right before the tool executes. */
+    onStart?: (start: NestedCallStart) => void;
+}
+export type NestedCallOutcome = {
+    ok: true;
+    nestedCallId: string;
+    effect: string;
+    /** Text parts of the result, joined. */
+    text: string;
+    /** The text parsed as JSON when it is JSON, else the text. */
+    value: unknown;
+    result: ToolResult;
+} | {
+    ok: false;
+    nestedCallId: string;
+    code: ForgeErrorCode;
+    message: string;
+    /** Known once the tool was found; lets the caller journal the failed attempt. */
+    effect?: string;
+};
+export interface NestedCallDispatcher {
+    /** The tools a nested call can reach right now (what `catalog.search` lists). */
+    catalog(): ToolDefinition[];
+    /**
+     * Whether the registry has a tool of this name, reachable or not. The only names a record or a
+     * broadcast may carry: a name a script invented is never stored.
+     */
+    knows(name: string): boolean;
+    call(request: NestedCallRequest): Promise<NestedCallOutcome>;
+}
+export interface NestedDispatcherDeps {
+    registry: ToolRegistry;
+    /** The run's live policy object; read at every call (a session approval widens it). */
+    policy: Policy;
+    /** Whether the run could open an approval for a direct call (only to tell the error apart). */
+    approvals: boolean;
+    /**
+     * Whether a write confined to the scratchpad may run without an approval (default true). It is
+     * false only for a run locked down on purpose (a child run with approvals turned off).
+     */
+    scratchWrites?: boolean;
+    toolFilter?: (tool: ToolDefinition) => boolean;
+    optInTools?: readonly string[];
+    workspace: string;
+    session: string;
+    label?: string;
+    runId?: string;
+    /** The id of the parent tool call; artifacts and decisions are bound to it. */
+    parentCallId: string;
+    signal: AbortSignal;
+    pathAccess?: PathAccess;
+    artifacts?: ArtifactPublisher;
+    decisions?: ToolDecisions;
+    /** The run's guard (context changed, token budget spent): throws to refuse the call. */
+    guard?: (effect: string) => void;
+    /** Flags the parent call effectful; called when a non-read, non-internal call starts. */
+    markEffectful: () => void;
+}
+export declare function createNestedDispatcher(deps: NestedDispatcherDeps): NestedCallDispatcher;