@alisio/core 0.5.2 → 0.7.0

package/dist/config.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { z } from "zod";
 import { DEFAULT_DECISIONS_CONFIG } from "./decisions/service.js";
+import { DEFAULT_FORGE_LIMITS, MAX_FORGE_LIMITS } from "./forge/limits.js";
 import { exists, readJson } from "./runtime/fs.js";
 import { isPathSpec } from "./runtime/modules.js";
 const providerSchema = z
@@ -82,7 +83,42 @@ const serversSchema = (value) => z.record(z.string(), value).superRefine((server
  */
 export const OCI_IMAGE_PATTERN = /^[a-zA-Z0-9][^\s@]*@sha256:[a-f0-9]{64}$/;
 /** Analysis keys only the user (global) layer decides; a project layer cannot set them. */
-const GLOBAL_ONLY_ANALYSIS = ["runtime", "oci", "retention"];
+const GLOBAL_ONLY_ANALYSIS = ["runtime", "isolation", "oci", "wasm", "retention"];
+/**
+ * Forja keys only the user (global) layer decides (spec §10). A project may still lower
+ * `timeoutMs`, `maxToolCalls`, `maxConcurrency` and `maxOutputChars` and switch a feature off.
+ */
+const GLOBAL_ONLY_FORGE = [
+    "javascript.host",
+    "javascript.memoryBytes",
+    "javascript.stackBytes",
+    "state.maxTotalBytes",
+    "scratch",
+];
+/** The limits a project layer may lower: the same list `mergeLimits` honours. */
+const FORGE_PROJECT_LOWERABLE = [
+    "timeoutMs",
+    "maxToolCalls",
+    "maxConcurrency",
+    "maxOutputChars",
+];
+/** A Forja limit: a positive integer up to its hard global maximum, with the spec default. */
+const forgeLimit = (key) => z.number().int().min(1).max(MAX_FORGE_LIMITS[key]).default(DEFAULT_FORGE_LIMITS[key]);
+const FORGE_DEFAULTS = {
+    javascript: {
+        enabled: true,
+        host: "auto",
+        timeoutMs: DEFAULT_FORGE_LIMITS.timeoutMs,
+        memoryBytes: DEFAULT_FORGE_LIMITS.memoryBytes,
+        stackBytes: DEFAULT_FORGE_LIMITS.stackBytes,
+        maxToolCalls: DEFAULT_FORGE_LIMITS.maxToolCalls,
+        maxConcurrency: DEFAULT_FORGE_LIMITS.maxConcurrency,
+        maxOutputChars: DEFAULT_FORGE_LIMITS.maxOutputChars,
+    },
+    state: { enabled: true, maxTotalBytes: 512 * 1024 },
+    scratch: { enabled: true, root: null, retentionDays: 7, maxBytes: 256 * 1024 * 1024 },
+    guides: { enabled: true },
+};
 /** Decision Intelligence keys only the user (global) layer decides: the provider and telemetry. */
 const GLOBAL_ONLY_DECISIONS = ["provider", "telemetry"];
 /** Web UI keys only the user (global) layer decides: the server picks which theme it serves. */
@@ -289,11 +325,43 @@ const configObjectSchema = z
          */
         smartDashboard: z.boolean().default(true),
         /**
-         * Where `python_run` executes. `managed` is the discovered Python (not a sandbox); `oci`
-         * is a Docker or Podman container started from a pinned image. GLOBAL ONLY: a project
+         * Where `python_run` executes. `auto` (default) picks the most isolated backend that is
+         * ready: `oci`, then `wasm`, then `managed` (the last only under `isolation: preferred`).
+         * `managed` is the discovered Python (not a sandbox); `oci` is a Docker or Podman
+         * container started from a pinned image; `wasm` is Pyodide in a restricted Node child
+         * process. An explicit value is honored or fails, never replaced. GLOBAL ONLY: a project
          * layer cannot choose the runtime or the image (it is ignored with a diagnostic).
          */
-        runtime: z.enum(["managed", "oci"]).default("managed"),
+        runtime: z.enum(["auto", "managed", "oci", "wasm"]).default("auto"),
+        /**
+         * What `auto` may use: `preferred` falls back to the host when no isolated backend is
+         * ready, `required` never runs on the host, `strict` admits only backends whose network
+         * the OS denies (global only).
+         */
+        isolation: z.enum(["preferred", "required", "strict"]).default("preferred"),
+        /** Pyodide backend settings (global only). Read by `wasm`, and by `auto` when it is ready. */
+        wasm: z
+            .object({
+            /** Soft limit: the parent samples the child's RSS and kills it above this. */
+            memoryMb: z.number().int().min(256).max(65_536).default(3072),
+            /** Margin for loading Pyodide, added to the run's own deadline and reported apart. */
+            startupMs: z.number().int().min(1000).max(300_000).default(30_000),
+            /** Inputs above this many bytes keep `auto` away from wasm. */
+            maxInputBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(100 * 1024 * 1024),
+            /** A `node` >= 22.22 / 24.13 / 25.3 for the child (needed under Bun; the running Node otherwise). */
+            nodePath: z.string().min(1).nullable().default(null),
+        })
+            .strict()
+            .default(() => ({
+            memoryMb: 3072,
+            startupMs: 30_000,
+            maxInputBytes: 100 * 1024 * 1024,
+            nodePath: null,
+        })),
         /** Container runtime settings (global only). Used when `runtime` is `oci`. */
         oci: z
             .object({
@@ -383,7 +451,14 @@ const configObjectSchema = z
         .default(() => ({
         enabled: true,
         smartDashboard: true,
-        runtime: "managed",
+        runtime: "auto",
+        isolation: "preferred",
+        wasm: {
+            memoryMb: 3072,
+            startupMs: 30_000,
+            maxInputBytes: 100 * 1024 * 1024,
+            nodePath: null,
+        },
         oci: { engine: "docker", memoryMb: 2048, cpus: 2 },
         retention: { jobsDays: 30, intermediateDays: 7, artifactsDays: 0 },
         limits: {
@@ -505,6 +580,58 @@ const configObjectSchema = z
     })
         .strict()
         .default(() => ({ active: "build" })),
+    /**
+     * Forja: isolated code execution (spec §10). `javascript.enabled` is `true` since the
+     * JavaScript engine passed its gate (Phase 3b): `js_run` replaces `execute`; `false` brings
+     * `execute` and the previous system prompt back. `javascript.host`, `memoryBytes`, `stackBytes`,
+     * `state.maxTotalBytes` and `scratch.*` are GLOBAL ONLY; a project may only lower
+     * `timeoutMs`, `maxToolCalls`, `maxConcurrency` and `maxOutputChars` and switch a feature off.
+     */
+    forge: z
+        .object({
+        javascript: z
+            .object({
+            enabled: z.boolean().default(FORGE_DEFAULTS.javascript.enabled),
+            host: z.enum(["auto", "worker", "process"]).default("auto"),
+            timeoutMs: forgeLimit("timeoutMs"),
+            memoryBytes: forgeLimit("memoryBytes"),
+            stackBytes: forgeLimit("stackBytes"),
+            maxToolCalls: forgeLimit("maxToolCalls"),
+            maxConcurrency: forgeLimit("maxConcurrency"),
+            maxOutputChars: forgeLimit("maxOutputChars"),
+        })
+            .strict()
+            .default(() => ({ ...FORGE_DEFAULTS.javascript })),
+        state: z
+            .object({
+            enabled: z.boolean().default(true),
+            maxTotalBytes: z
+                .number()
+                .int()
+                .min(1)
+                .max(8 * 1024 * 1024)
+                .default(FORGE_DEFAULTS.state.maxTotalBytes),
+        })
+            .strict()
+            .default(() => ({ ...FORGE_DEFAULTS.state })),
+        scratch: z
+            .object({
+            enabled: z.boolean().default(true),
+            /** Base of the volatile session directories; `ALISIO_TMPDIR` wins over it. */
+            root: z.string().min(1).nullable().default(null),
+            /** Days without activity before a session folder goes; `0` disables the cleanup. */
+            retentionDays: z.number().int().min(0).max(3650).default(7),
+            maxBytes: z.number().int().min(1).default(FORGE_DEFAULTS.scratch.maxBytes),
+        })
+            .strict()
+            .default(() => ({ ...FORGE_DEFAULTS.scratch })),
+        guides: z
+            .object({ enabled: z.boolean().default(true) })
+            .strict()
+            .default(() => ({ ...FORGE_DEFAULTS.guides })),
+    })
+        .strict()
+        .default(() => structuredClone(FORGE_DEFAULTS)),
     /**
      * Web UI preferences. `iconTheme` names the active `icon-theme` extension point provider
      * (`"none"` keeps the built-in inline icons). GLOBAL ONLY: the server decides which theme its
@@ -572,6 +699,44 @@ async function canonicalDirectory(path) {
 export function overridesSavedProviderProfile(provenance, hasEndpointOverride) {
     return hasEndpointOverride || !!provenance.selectedLayer?.hasLegacyProvider;
 }
+/** Whether a dotted path (`javascript.host`) is written in a raw `forge` block. */
+function forgeHas(raw, path) {
+    let current = raw;
+    for (const part of path.split(".")) {
+        if (!current || typeof current !== "object" || !(part in current))
+            return false;
+        current = current[part];
+    }
+    return true;
+}
+/**
+ * The project layer over the global one for `forge`: global-only keys always come from the global
+ * layer, a lowerable limit takes the smaller value when the project wrote it, and a feature switch
+ * the project wrote can only turn the feature off (a defaulted value never changes the global one).
+ */
+function overlayForge(global, project, raw) {
+    const javascript = { ...global.javascript };
+    for (const key of FORGE_PROJECT_LOWERABLE)
+        if (forgeHas(raw, `javascript.${key}`))
+            javascript[key] = Math.min(global.javascript[key], project.javascript[key]);
+    if (forgeHas(raw, "javascript.enabled"))
+        javascript.enabled = global.javascript.enabled && project.javascript.enabled;
+    return {
+        javascript,
+        state: {
+            ...global.state,
+            enabled: forgeHas(raw, "state.enabled")
+                ? global.state.enabled && project.state.enabled
+                : global.state.enabled,
+        },
+        scratch: global.scratch,
+        guides: {
+            enabled: forgeHas(raw, "guides.enabled")
+                ? global.guides.enabled && project.guides.enabled
+                : global.guides.enabled,
+        },
+    };
+}
 export const configHome = () => process.env.ALISIO_CONFIG_HOME ??
     join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "alisio");
 export const stateHome = () => process.env.ALISIO_STATE_HOME ??
@@ -625,6 +790,9 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
         const analysisRaw = object.analysis && typeof object.analysis === "object" && !Array.isArray(object.analysis)
             ? object.analysis
             : {};
+        const forgeRaw = object.forge && typeof object.forge === "object" && !Array.isArray(object.forge)
+            ? object.forge
+            : {};
         const tasksRaw = object.tasks && typeof object.tasks === "object" && !Array.isArray(object.tasks)
             ? object.tasks
             : {};
@@ -641,6 +809,7 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
             : {};
         const ignored = [
             ...GLOBAL_ONLY_ANALYSIS.filter((key) => key in analysisRaw).map((key) => `analysis.${key}`),
+            ...GLOBAL_ONLY_FORGE.filter((path) => forgeHas(forgeRaw, path)).map((path) => `forge.${path}`),
             ...GLOBAL_ONLY_DECISIONS.filter((key) => key in decisionsRaw).map((key) => `decisions.${key}`),
             ...GLOBAL_ONLY_WEB.filter((key) => key in webRaw).map((key) => `web.${key}`),
             ...Object.entries(overridesRaw)
@@ -653,6 +822,8 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
             keys: new Set(Object.keys(object)),
             /** Raw keys of the layer's `analysis` block (a defaulted key is not an expressed one). */
             analysisKeys: new Set(Object.keys(analysisRaw)),
+            /** Raw `forge` block of the layer, to tell a written key from a defaulted one. */
+            forgeRaw,
             sources,
             ignored,
             file,
@@ -723,11 +894,13 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                 continue;
             }
             if (key === "analysis") {
-                // `runtime`, `oci` and `retention` are global-only (a repository must not pick the binary
+                // `runtime`, `isolation`, `oci`, `wasm` and `retention` are global-only (a repository must not pick the binary
                 // that runs scripts, nor shorten the retention of every workspace's data).
                 overlaid.analysis = {
                     ...selected.config.analysis,
                     runtime: global.config.analysis.runtime,
+                    isolation: global.config.analysis.isolation,
+                    wasm: global.config.analysis.wasm,
                     oci: global.config.analysis.oci,
                     retention: global.config.analysis.retention,
                     // A defaulted `true` must not undo the global `false`: only a key the layer wrote wins.
@@ -737,6 +910,10 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                 };
                 continue;
             }
+            if (key === "forge") {
+                overlaid.forge = overlayForge(global.config.forge, selected.config.forge, selected.forgeRaw);
+                continue;
+            }
             if (key === "decisions") {
                 // `provider` and `telemetry` are global-only (a repository cannot pick the decision
                 // engine nor its telemetry policy); the rest follows the selected layer.
@@ -912,7 +1089,10 @@ const SETTABLE_SECTIONS = {
     goal: configObjectSchema.shape.goal.removeDefault(),
     plan: configObjectSchema.shape.plan.removeDefault(),
     web: configObjectSchema.shape.web.removeDefault(),
+    forge: configObjectSchema.shape.forge.removeDefault(),
 };
+const FORGE_JAVASCRIPT = SETTABLE_SECTIONS.forge.shape.javascript.removeDefault();
+const FORGE_GUIDES = SETTABLE_SECTIONS.forge.shape.guides.removeDefault();
 const ANALYSIS_LIMITS = SETTABLE_SECTIONS.analysis.shape.limits.removeDefault();
 const ANALYSIS_RETENTION = SETTABLE_SECTIONS.analysis.shape.retention.removeDefault();
 const SETTABLE_KEYS = {
@@ -962,6 +1142,8 @@ const SETTABLE_KEYS = {
     "plan.diagrams": SETTABLE_SECTIONS.plan.shape.diagrams,
     "plan.maxDiagrams": SETTABLE_SECTIONS.plan.shape.maxDiagrams,
     "web.iconTheme": SETTABLE_SECTIONS.web.shape.iconTheme,
+    "forge.javascript.enabled": FORGE_JAVASCRIPT.shape.enabled,
+    "forge.guides.enabled": FORGE_GUIDES.shape.enabled,
 };
 export function isSettableSettingKey(key) {
     return Object.prototype.hasOwnProperty.call(SETTABLE_KEYS, key);

package/dist/core/call-internals.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What only the core's own tools may do from inside a call (spec D-23, D-24): flag the running
+ * call as `effectful` and reach the run's nested-call dispatcher. It is NOT part of the SDK
+ * `ToolContext`: the runner binds it to the context object of a call in a module-private
+ * `WeakMap`, so a plugin tool, which sees only the SDK type, has no property to find and no module
+ * to import.
+ */
+import type { ToolContext } from "@alisio/sdk";
+import type { NestedCallDispatcher } from "../forge/nested.ts";
+export interface CallInternals {
+    /**
+     * Flags the running call: it may have left effects, so a cancellation must leave it pending for
+     * recovery even though its own effect is `read`. Idempotent.
+     */
+    markEffectful(): void;
+    /** The dispatcher for tool calls made from inside this call (built on first use). */
+    nested(): NestedCallDispatcher;
+}
+/** The runner binds the internals of a call to the context it hands the tool. */
+export declare function bindCallInternals(context: ToolContext, internals: CallInternals): void;
+/** The internals of the call this context belongs to; undefined for any other context. */
+export declare function callInternals(context: ToolContext): CallInternals | undefined;

package/dist/core/call-internals.js

@@ -0,0 +1,9 @@
+const bound = new WeakMap();
+/** The runner binds the internals of a call to the context it hands the tool. */
+export function bindCallInternals(context, internals) {
+    bound.set(context, internals);
+}
+/** The internals of the call this context belongs to; undefined for any other context. */
+export function callInternals(context) {
+    return bound.get(context);
+}

package/dist/core/contracts.d.ts

@@ -209,7 +209,7 @@ export interface ApprovalRequest {
     /** Capability approvals: the first 40 lines of the script. */
     preview?: string;
     /** Capability approvals: how the code runs (`managed` is not sandboxed). */
-    runtime?: "managed" | "oci";
+    runtime?: "auto" | "managed" | "oci" | "wasm";
     /** `analysis.install`: the packages, the size estimate and the network need (once or deny). */
     install?: InstallPreview;
 }
@@ -233,7 +233,7 @@ export interface CapabilityGate {
     /** Recorded as the source of interactive decisions (`tui` or `web`). */
     source?: "tui" | "web";
     /** Runtime mode shown with `analysis.run` approvals (read live: the configuration can change). */
-    runtime?: "managed" | "oci";
+    runtime?: "auto" | "managed" | "oci" | "wasm";
     /**
      * The script to show in an approval whose input does not carry it (a rerun runs a saved script).
      * Absent or undefined: the preview is taken from `input.code`.

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/eval/canonical.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonical JSON of the reliability lab (specs/010 D10): equal values give equal text, so the same
+ * text can be hashed for the configuration hash, argument keys and cassette fingerprints.
+ *
+ * Rules: object keys sorted by UTF-16 code unit (the default string order), `undefined` members
+ * dropped (in arrays they become `null`, as `JSON.stringify` does), `null` kept, `-0` written as
+ * `0`, non-finite numbers rejected (JSON cannot carry them), string VALUES normalized to NFC
+ * (keys are left as written).
+ */
+/** JSON text with the canonical rules above. */
+export declare function canonicalJson(value: unknown): string;
+export declare const sha256Hex: (data: string | Buffer) => string;
+/** `sha256:<64 hex>` of the canonical JSON of `value`. */
+export declare function hashCanonical(value: unknown): string;

package/dist/eval/canonical.js

@@ -0,0 +1,40 @@
+/**
+ * Canonical JSON of the reliability lab (specs/010 D10): equal values give equal text, so the same
+ * text can be hashed for the configuration hash, argument keys and cassette fingerprints.
+ *
+ * Rules: object keys sorted by UTF-16 code unit (the default string order), `undefined` members
+ * dropped (in arrays they become `null`, as `JSON.stringify` does), `null` kept, `-0` written as
+ * `0`, non-finite numbers rejected (JSON cannot carry them), string VALUES normalized to NFC
+ * (keys are left as written).
+ */
+import { createHash } from "node:crypto";
+function normalize(value) {
+    if (typeof value === "string")
+        return value.normalize("NFC");
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`Cannot canonicalize a non-finite number (${value}).`);
+        return value === 0 ? 0 : value;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => (item === undefined ? null : normalize(item)));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const member = value[key];
+            if (member !== undefined)
+                out[key] = normalize(member);
+        }
+        return out;
+    }
+    return value;
+}
+/** JSON text with the canonical rules above. */
+export function canonicalJson(value) {
+    return JSON.stringify(normalize(value));
+}
+export const sha256Hex = (data) => createHash("sha256").update(data).digest("hex");
+/** `sha256:<64 hex>` of the canonical JSON of `value`. */
+export function hashCanonical(value) {
+    return `sha256:${sha256Hex(canonicalJson(value))}`;
+}