@zackbart/connecta 0.25.0 → 0.26.1

package/dist/execute.js

@@ -1,4 +1,4 @@
-import { Cause, Duration, Effect, Exit } from "effect";
+import { Cause, Deferred, Duration, Effect, Exit } from "effect";
 import { z } from "zod";
 import { advertisedSchema } from "./advertised-schema.js";
 import { boundedDiscoveryText, CatalogService, DiscoveryPolicyError, flatSearchResult, } from "./catalog-service.js";
@@ -7,12 +7,18 @@ import { guardExecuteResultValue, MAX_EXECUTE_LOG_CHARS, truncateExecuteText, }
 import { ExecutorAdmissionError, ExecutorExecutionError, isAdmittingExecutor, } from "./executor-admission.js";
 import { boundedEchoText, msg } from "./errors.js";
 import { InvocationFailure, InvocationService, timed, } from "./invocation.js";
-import { withoutProgramTerminator } from "./program-source.js";
+import { normalizeProgramSource } from "./program-source.js";
+import { DEFAULT_MAX_WRITES, ExemptWrites, MIN_STORAGE_TIMEOUT_MS, RunState, writeStateOf, } from "./resumable.js";
+import { journalKey } from "./run-journal.js";
+import { underAnySignal } from "./timeout.js";
+import { isApprovalExempt, NO_EXEMPTIONS, } from "./tool-safety.js";
 import { fromSignal, runEdge } from "./runtime/run.js";
 import { connectorGuide, connectorGuideRequired, connectorSkillName, hasConnectorGuides, } from "./skills.js";
 /** Keep one model-written program from amplifying into an unbounded fan-out. */
 const EXECUTE_MAX_HOST_CALLS = 20;
 const EXECUTE_HOST_CALL_TIMEOUT_MS = 15_000;
+/** Above every program in the recorded evals, below the QuickJS IPC ceiling. */
+const EXECUTE_MAX_CODE_BYTES = 64 * 1024;
 /**
  * The outer ceiling on one execution. It sits above both executors' own
  * deadlines (QuickJS 30s, the Dynamic Worker 60s), so a healthy executor
@@ -272,6 +278,129 @@ function guestErrorPrelude(failureSecret) {
   });
 })(${JSON.stringify(`${GUEST_FAILURE_FRAME}${failureSecret}:`)});`;
 }
+/** A clock read now and a seed drawn from the host's CSPRNG. */
+function freshEnvironment() {
+    const words = new Uint32Array(4);
+    crypto.getRandomValues(words);
+    return {
+        clockMs: Date.now(),
+        seed: [words[0] ?? 0, words[1] ?? 0, words[2] ?? 0, words[3] ?? 0],
+    };
+}
+/**
+ * Trusted guest code installing the pinned clock and stream, evaluated after
+ * the error prelude and before the program. Every replacement is locked the
+ * way `Error` is — non-writable and non-configurable — so a program can read
+ * the pinned values and nothing else.
+ *
+ * `Date` becomes a wrapper whose argument-free forms (`new Date()`, `Date()`,
+ * `Date.now()`) read the pinned instant; with arguments it is the native
+ * constructor, and instances are ordinary dates. The native constructor's own
+ * `now` and the prototype's `constructor` are pinned too, so the usual ways
+ * back to it read the same instant. `Math.random` is sfc32 over the seed:
+ * small, fast, and specified in a few lines anyone can check. Where the
+ * runtime has them (a Dynamic Worker; QuickJS has neither), `crypto`'s
+ * `getRandomValues` and `randomUUID` draw from the same stream and
+ * `performance.now()` stays at 0, the run's start. None of that makes
+ * `crypto` contract (`P2`): it only keeps a Workers-only program from being
+ * the one that cannot replay.
+ */
+function pinnedEnvironmentPrelude(environment) {
+    return `((clock, seed) => {
+  const NativeDate = globalThis.Date;
+  const construct = Reflect.construct;
+  const defineProperty = Object.defineProperty;
+  const lock = (target, key, value) => defineProperty(target, key, {
+    value, writable: false, enumerable: false, configurable: false
+  });
+  let a = seed[0] | 0, b = seed[1] | 0, c = seed[2] | 0, d = seed[3] | 0;
+  const next = () => {
+    const t = (((a + b) | 0) + d) | 0;
+    d = (d + 1) | 0;
+    a = b ^ (b >>> 9);
+    b = (c + (c << 3)) | 0;
+    c = (c << 21) | (c >>> 11);
+    c = (c + t) | 0;
+    return t >>> 0;
+  };
+  const now = function now() { return clock; };
+  function Date(...args) {
+    if (new.target === undefined) return new NativeDate(clock).toString();
+    return construct(NativeDate, args.length === 0 ? [clock] : args, new.target);
+  }
+  Date.prototype = NativeDate.prototype;
+  lock(Date, "now", now);
+  lock(Date, "parse", NativeDate.parse);
+  lock(Date, "UTC", NativeDate.UTC);
+  lock(NativeDate, "now", now);
+  lock(NativeDate.prototype, "constructor", Date);
+  lock(globalThis, "Date", Date);
+  lock(Math, "random", function random() { return next() / 4294967296; });
+  // Lock the replacement on the object and on its prototype, where the
+  // native method lives: \`Object.getPrototypeOf(crypto).getRandomValues\`
+  // would otherwise still reach the real stream. A prototype the runtime
+  // will not let us redefine keeps its native method (\`tryLock\`), and a
+  // program that uses it diverges on replay rather than sending anything.
+  const tryLock = (target, key, value) => {
+    try { lock(target, key, value); } catch {}
+  };
+  if (typeof crypto === "object" && crypto !== null) {
+    const getRandomValues = function getRandomValues(array) {
+      const bytes = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+      for (let i = 0; i < bytes.length; i++) bytes[i] = next() >>> 24;
+      return array;
+    };
+    const randomUUID = function randomUUID() {
+      const bytes = getRandomValues(new Uint8Array(16));
+      bytes[6] = (bytes[6] & 0x0f) | 0x40;
+      bytes[8] = (bytes[8] & 0x3f) | 0x80;
+      let hex = "";
+      for (let i = 0; i < 16; i++) {
+        hex += (bytes[i] + 0x100).toString(16).slice(1);
+        if (i === 3 || i === 5 || i === 7 || i === 9) hex += "-";
+      }
+      return hex;
+    };
+    lock(crypto, "getRandomValues", getRandomValues);
+    lock(crypto, "randomUUID", randomUUID);
+    const cryptoProto = Object.getPrototypeOf(crypto);
+    if (cryptoProto) {
+      tryLock(cryptoProto, "getRandomValues", getRandomValues);
+      tryLock(cryptoProto, "randomUUID", randomUUID);
+    }
+  }
+  if (typeof performance === "object" && performance !== null) {
+    const perfNow = function now() { return 0; };
+    lock(performance, "now", perfNow);
+    const performanceProto = Object.getPrototypeOf(performance);
+    if (performanceProto) tryLock(performanceProto, "now", perfNow);
+  }
+  // An Intl formatter asked for "now" (no date) reads the native clock.
+  if (typeof Intl === "object" && Intl !== null && typeof Intl.DateTimeFormat === "function") {
+    const proto = Intl.DateTimeFormat.prototype;
+    const formatGetter = Object.getOwnPropertyDescriptor(proto, "format");
+    if (formatGetter && typeof formatGetter.get === "function") {
+      const nativeFormat = formatGetter.get;
+      try {
+        defineProperty(proto, "format", {
+          get() {
+            const bound = nativeFormat.call(this);
+            return function format(date) { return bound(date === undefined ? clock : date); };
+          },
+          enumerable: false,
+          configurable: false,
+        });
+      } catch {}
+    }
+    const nativeFormatToParts = proto.formatToParts;
+    if (typeof nativeFormatToParts === "function") {
+      tryLock(proto, "formatToParts", function formatToParts(date) {
+        return nativeFormatToParts.call(this, date === undefined ? clock : date);
+      });
+    }
+  }
+})(${JSON.stringify(environment.clockMs)}, ${JSON.stringify([...environment.seed])});`;
+}
 /**
  * Expose one host provider and typed guest errors. Catalogs load only when
  * the program calls a tool or asks search/describe.
@@ -300,6 +429,7 @@ function sandboxProvider(registry, baseUrl, activity, limits) {
         concurrency: limits.discoveryConcurrency,
         probeTimeoutMs: limits.probeTimeoutMs,
         defer: limits.defer,
+        approval: limits.approval,
     });
     const invocation = new InvocationService(registry, catalog, activity);
     const maxHostCalls = Math.max(1, Math.trunc(limits.maxHostCalls ?? EXECUTE_MAX_HOST_CALLS));
@@ -312,27 +442,135 @@ function sandboxProvider(registry, baseUrl, activity, limits) {
     const spendHostCall = Effect.suspend(() => ++hostCalls > maxHostCalls
         ? Effect.fail(guestFailure("budget_exceeded", `execute_code host-call budget exceeded (${maxHostCalls} calls maximum)`))
         : Effect.void);
-    const invocationContext = () => ({
-        source: "execute_code",
+    const { runState, exemptWrites } = limits;
+    const approval = limits.approval ?? NO_EXEMPTIONS;
+    const maxWrites = resolveBudget(limits.maxWrites, DEFAULT_MAX_WRITES);
+    let exemptWriteCount = 0;
+    /**
+     * Without resumable writes nothing can pause, but a config exemption
+     * (#566) still lets its writes run: the gate covers exactly the exempt
+     * calls, spends the write budget on each, and every other write keeps
+     * E4's refusal, ahead of validation as it always was. A dispatched write
+     * is tracked until it settles (`ExemptWrites`), so the play can wait for
+     * it rather than abort it.
+     */
+    const exemptOnly = (sending) => ({
+        gates: (target) => isApprovalExempt(approval, target.connector, target.toolName, target.definition),
+        writeGate: (target) => Effect.sync(() => {
+            if (exemptWrites?.isClosed) {
+                return {
+                    kind: "refuse",
+                    error: {
+                        code: "cancelled",
+                        message: "The program had already returned, so this write was not sent.",
+                        retryable: false,
+                    },
+                    activity: "none",
+                };
+            }
+            if (exemptWriteCount >= maxWrites) {
+                return {
+                    kind: "refuse",
+                    error: {
+                        code: "budget_exceeded",
+                        message: `execute_code write budget exceeded (${maxWrites} writes maximum, execute.maxWrites); ${target.connector.id}.${target.toolName} was not sent`,
+                        retryable: false,
+                    },
+                };
+            }
+            exemptWriteCount++;
+            if (exemptWrites)
+                sending.settle = exemptWrites.begin();
+            return { kind: "dispatch" };
+        }),
+    });
+    const invocationContext = (seq, key, sending) => ({
+        source: runState?.source ?? "execute_code",
         timeoutMs: hostCallTimeoutMs,
         ...(signal !== undefined ? { requestSignal: signal } : {}),
         unwrapResult: true,
+        // With resumable writes, a consequential call reaches the run's gate
+        // instead of the flat E4 refusal, and a read's decision is marked the
+        // moment it passes the same point.
+        ...(runState && seq !== undefined && key !== undefined
+            ? {
+                beforeDispatch: () => runState.decide(seq),
+                writeGate: (target, args) => runState.gate(seq, key, target, args),
+            }
+            : runState
+                ? {}
+                : exemptOnly(sending)),
+    });
+    /**
+     * The front of every numbered host call once resumable writes are on: a
+     * stopped run makes no call at all (not journaled, no activity), a
+     * recorded one is answered from the journal before the budget-free part
+     * of the path, and one the journal cannot account for is divergence.
+     * Replayed calls spend the host-call budget again, so a play's total is
+     * the run's total and nothing is counted twice.
+     */
+    const fromJournal = (seq, op, address, args) => Effect.gen(function* () {
+        const halted = runState?.halted();
+        if (halted)
+            return yield* Effect.fail(halted);
+        yield* spendHostCall;
+        if (!runState || seq === undefined)
+            return { kind: "live", key: undefined };
+        const key = journalKey(op, address, args);
+        const found = runState.lookup(key);
+        if (found.kind === "diverged") {
+            return yield* Effect.fail(runState.diverge(found.reason));
+        }
+        if (found.kind === "live")
+            return { kind: "live", key };
+        runState.decide(seq);
+        const { outcome } = found.entry;
+        return outcome.ok
+            ? { kind: "replayed", value: outcome.value }
+            : yield* Effect.fail(new InvocationFailure(outcome.error));
     });
     // A call brings its own cancellation: the invocation pipeline reads the
     // run's signal, refuses a call that starts after it, and records the
     // cancelled attempt in activity like any other outcome.
-    const call = (address, args) => spendHostCall.pipe(Effect.andThen(Effect.suspend(() => invocation.pipeline(String(address), args ?? {}, invocationContext()))), Effect.flatMap((outcome) => {
+    const call = (seq, address, args) => Effect.gen(function* () {
+        const addressText = String(address);
+        const callArgs = args ?? {};
+        const front = yield* fromJournal(seq, "call", addressText, callArgs);
+        if (front.kind === "replayed")
+            return front.value;
+        // An exempt write dispatched without a run state settles here —
+        // unknown if the call never returned an outcome.
+        const sending = {};
+        const outcome = yield* invocation.pipeline(addressText, callArgs, invocationContext(seq, front.key, sending)).pipe(Effect.onExit((exit) => Effect.sync(() => sending.settle?.(Exit.isSuccess(exit) ? writeStateOf(exit.value) : "unknown"))));
         diagnostics?.recordCall(outcome);
+        if (runState && seq !== undefined && front.key !== undefined) {
+            if (runState.isLiveWrite(seq)) {
+                const resolved = outcome.resolved;
+                const replaced = yield* runState.settleWrite(seq, front.key, {
+                    address: resolved
+                        ? `${resolved.connector.id}.${resolved.toolName}`
+                        : addressText,
+                    args: callArgs,
+                }, outcome);
+                if (replaced)
+                    return yield* Effect.fail(replaced);
+            }
+            else {
+                runState.record(seq, "call", front.key, outcome.ok
+                    ? { ok: true, value: outcome.value }
+                    : { ok: false, error: outcome.error });
+            }
+        }
         return outcome.ok
-            ? Effect.succeed(outcome.value)
-            : Effect.fail(new InvocationFailure(outcome.error));
-    }));
+            ? outcome.value
+            : yield* Effect.fail(new InvocationFailure(outcome.error));
+    });
     // Discovery gets the same treatment from here (L2): once the run has
     // ended no search or describe starts, and one still in flight fails
     // `cancelled` instead of holding the program until its probe deadline.
     // Policy failures use the same thrown vocabulary as calls and utilities;
     // the transport below reconstructs their code inside the guest.
-    const discovery = (operation, read) => Effect.suspend(() => {
+    const discovery = (operation, seq, raw, read) => Effect.suspend(() => {
         const started = Date.now();
         const cancelled = () => guestFailure("cancelled", `connecta.${operation} was cancelled because the run ended.`);
         const reading = Effect.tryPromise({
@@ -341,22 +579,49 @@ function sandboxProvider(registry, baseUrl, activity, limits) {
                 ? guestFailure(err.code, err.message)
                 : err,
         });
-        return spendHostCall.pipe(Effect.andThen(!signal
-            ? reading
-            : signal.aborted
-                ? Effect.fail(cancelled())
-                : Effect.raceAllFirst([
-                    reading,
-                    fromSignal(signal).pipe(Effect.mapError(cancelled)),
-                ])), Effect.onExit((exit) => Effect.sync(() => diagnostics?.recordCatalog(operation, Date.now() - started, Exit.isSuccess(exit), Exit.isSuccess(exit) ? exit.value : undefined))));
+        return fromJournal(seq, operation, "", raw ?? {}).pipe(Effect.flatMap((front) => {
+            if (front.kind === "replayed")
+                return Effect.succeed(front.value);
+            const live = (!signal
+                ? reading
+                : signal.aborted
+                    ? Effect.fail(cancelled())
+                    : Effect.raceAllFirst([
+                        reading,
+                        fromSignal(signal).pipe(Effect.mapError(cancelled)),
+                    ])).pipe(Effect.onExit((exit) => Effect.sync(() => {
+                if (!runState || seq === undefined || front.key === undefined)
+                    return;
+                // Typed outcomes replay; an untyped throw is a bug, not an
+                // answer, and is not journaled — so a replay that re-issues
+                // the call before repeating the approved write finds no record
+                // and fails `execution_diverged`.
+                if (Exit.isSuccess(exit)) {
+                    runState.record(seq, operation, front.key, {
+                        ok: true,
+                        value: exit.value,
+                    });
+                    return;
+                }
+                const error = Cause.squash(exit.cause);
+                if (error instanceof InvocationFailure) {
+                    runState.record(seq, operation, front.key, {
+                        ok: false,
+                        error: error.details,
+                    });
+                }
+            })));
+            return live;
+        }), Effect.onExit((exit) => Effect.sync(() => diagnostics?.recordCatalog(operation, Date.now() - started, Exit.isSuccess(exit), Exit.isSuccess(exit) ? exit.value : undefined))));
     });
     const operations = {
         call,
         // Emission is a provider function, never an ExecuteResult field —
         // that is what keeps the Executor contract untouched and parity
         // structural (M8). It spends no host-call budget (M7); its own
-        // budgets live in the collector.
-        emit: (block) => Effect.try({
+        // budgets live in the collector. It is never journaled: a replay emits
+        // again, and only the play that completes delivers.
+        emit: (_seq, block) => Effect.try({
             try: () => {
                 if (!limits.emitCollector) {
                     throw guestFailure("unavailable", "connecta.emit is unavailable: no emission collector was configured for this execution", true);
@@ -365,7 +630,7 @@ function sandboxProvider(registry, baseUrl, activity, limits) {
             },
             catch: (err) => err,
         }),
-        search: (raw) => discovery("search", async () => {
+        search: (seq, raw) => discovery("search", seq, raw, async () => {
             const args = (raw ?? {});
             const result = flatSearchResult(await catalog.search({
                 ...args,
@@ -374,7 +639,7 @@ function sandboxProvider(registry, baseUrl, activity, limits) {
             boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
             return result;
         }),
-        describe: (raw) => discovery("describe", async () => {
+        describe: (seq, raw) => discovery("describe", seq, raw, async () => {
             const args = (raw ?? {});
             const result = { tools: await catalog.describe(args) };
             boundedDiscoveryText(result, 'Split the address list or use format: "compact".');
@@ -394,11 +659,22 @@ function sandboxProvider(registry, baseUrl, activity, limits) {
     });
     return {
         name: "connecta",
-        prelude: guestErrorPrelude(failureSecret),
+        // Typed errors first, then the pinned clock and randomness: both are
+        // trusted host code the program runs after and cannot undo.
+        prelude: `${guestErrorPrelude(failureSecret)}\n${pinnedEnvironmentPrelude(runState?.environment ?? limits.environment ?? freshEnvironment())}`,
         fns: Object.fromEntries(Object.entries(operations).map(([name, operation]) => [
             name,
             (...args) => {
-                const settled = runEdge(Effect.suspend(() => operation(...args)).pipe(Effect.catch(framed)));
+                // Numbered here, synchronously, as the program makes the call: the
+                // numbering is the program's own issue order, which is what makes
+                // a pause point and a replay reproducible.
+                const seq = runState && name !== "emit" ? runState.begin() : undefined;
+                const settled = runEdge(Effect.suspend(() => operation(seq, ...args)).pipe(Effect.catch(framed), Effect.ensuring(Effect.sync(() => {
+                    if (seq !== undefined)
+                        runState?.decide(seq);
+                }))));
+                if (seq !== undefined)
+                    runState?.track(seq, settled);
                 // The executor owns this promise, and a program may abandon a call
                 // that the run's end then cancels before anyone has awaited it.
                 // The rejection is still there for whoever does; it is just not an
@@ -494,24 +770,40 @@ function leased(executor, signal) {
         late: (lease) => lease.release(),
     }), (lease) => Effect.sync(() => lease.release()));
 }
-/** The execute_code handler. Exported for direct testing. */
-export function createExecuteTool(registry, baseUrl, executor, logger, activity, config = {}) {
+/**
+ * Room a claim leaves beyond the watchdog and one host-call deadline, for the
+ * executor queue a resumed play waits in first. Only liveness rides on it: a
+ * claim that lapses early lets a takeover start, and the write-ahead mark
+ * still keeps any write from being sent twice.
+ */
+const CLAIM_SLACK_MS = 10_000;
+/** The runner behind both program tools. */
+export function createProgramRunner(registry, baseUrl, executor, logger, activity, config = {}) {
     const watchdog = {
         ms: resolveBudget(config.watchdogMs, EXECUTE_WATCHDOG_MS),
         logger,
     };
-    return ({ code, diagnostics: diagnosticsRequested }, options = {}) => runEdge(Effect.suspend(() => {
+    const hostCallTimeoutMs = resolveBudget(config.hostCallTimeoutMs, EXECUTE_HOST_CALL_TIMEOUT_MS);
+    const storageTimeoutMs = resolveBudget(config.storageTimeoutMs, Math.max(hostCallTimeoutMs, MIN_STORAGE_TIMEOUT_MS));
+    /**
+     * One play of a program. Without a run state it is the execute_code run it
+     * always was. With one, the play also ends when the run stops — a pause or
+     * a typed failure — and then waits for what is still on the wire, persists
+     * what it must, and discards the program's own result.
+     */
+    const play = (program, runState, diagnosticsRequested, callerSignal) => Effect.suspend(() => {
         const diagnostics = diagnosticsRequested
             ? new ExecuteDiagnostics()
             : undefined;
         const emitted = new EmitCollector(resolveBudget(config.maxEmittedBytes, EXECUTE_MAX_EMITTED_BYTES), resolveBudget(config.maxEmittedBlocks, EXECUTE_MAX_EMITTED_BLOCKS), diagnostics);
         const invocationFailures = [];
+        const exemptWrites = runState ? undefined : new ExemptWrites();
         // The run's scope holds its signal and its lease. However the run
         // ends — a result, a thrown executor, the watchdog, cancellation —
         // closing it releases the lease and then aborts the signal, so
         // nothing the run started outlives the request.
         const run = Effect.gen(function* () {
-            const signal = yield* runSignal(options.signal);
+            const signal = yield* runSignal(callerSignal);
             // Admission comes before provider construction: queued calls retain
             // no catalogs, request scopes, or provider closures.
             let lease;
@@ -541,28 +833,103 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 discoveryConcurrency: config.discoveryConcurrency,
                 probeTimeoutMs: config.probeTimeoutMs,
                 maxHostCalls: config.maxHostCalls,
-                hostCallTimeoutMs: config.hostCallTimeoutMs,
+                hostCallTimeoutMs,
                 defer: config.defer,
+                environment: config.environment,
+                runState,
+                approval: config.approval,
+                maxWrites: config.maxWrites,
+                exemptWrites,
             })));
             if (signal.aborted) {
                 return yield* Effect.fail(new ExecutorAdmissionError("executor_cancelled", "Execution was cancelled during sandbox setup."));
             }
             const admitted = lease;
-            // P1: a trailing `;` after the arrow expression breaks both
-            // executors' parenthesized evaluation. Strip it here, above them.
-            const program = withoutProgramTerminator(code);
-            return yield* timed((elapsed) => {
+            const executing = awaitExecutor(() => admitted
+                ? admitted.execute(program, [provider])
+                : executor.execute(program, [provider]), signal, { watchdog }).pipe(Effect.map((settled) => ({ settled })));
+            if (!runState) {
+                // Nothing pauses, but an exempt write may be on the wire: close,
+                // then let it finish before the scope aborts it.
+                return yield* timed((elapsed) => {
+                    if (diagnostics)
+                        diagnostics.executorWallMs = elapsed;
+                }, executing.pipe(Effect.ensuring(Effect.suspend(() => {
+                    exemptWrites?.close();
+                    return exemptWrites?.drain() ?? Effect.void;
+                }))));
+            }
+            // The run stopping wins the race as soon as its gate decides, before
+            // the program even sees the rejection. Either way the play closes —
+            // a write gated after this is not sent — and what is still on the
+            // wire finishes before the scope aborts it: every call after a stop,
+            // since each is journaled, and every write otherwise, since an
+            // abandoned write would be an unknown one.
+            const ended = yield* timed((elapsed) => {
                 if (diagnostics)
                     diagnostics.executorWallMs = elapsed;
-            }, awaitExecutor(() => admitted
-                ? admitted.execute(program, [provider])
-                : executor.execute(program, [provider]), signal, { watchdog }));
+            }, Effect.raceFirst(executing, Deferred.await(runState.stopped).pipe(Effect.map((stop) => ({ stop })))).pipe(Effect.ensuring(Effect.suspend(() => {
+                runState.close();
+                return runState.drain("writes");
+            }))));
+            if ("stop" in ended)
+                yield* runState.drain("all");
+            return ended;
         });
         const reported = { emitted, diagnostics, invocationFailures };
-        return Effect.map(Effect.exit(Effect.scoped(run)), (exit) => Exit.isSuccess(exit)
-            ? finishedRun(exit.value, reported)
-            : failedRun(Cause.squash(exit.cause), logger, reported));
-    }));
+        return Effect.flatMap(Effect.exit(Effect.scoped(run)), (exit) => {
+            if (Exit.isFailure(exit)) {
+                const failed = failedRun(Cause.squash(exit.cause), logger, reported);
+                return runState
+                    ? runState.finishExecutorFailure(failed)
+                    : Effect.succeed(exemptWrites?.finish(failed) ?? failed);
+            }
+            const ended = exit.value;
+            if ("stop" in ended) {
+                return runState
+                    ? runState.finishStopped()
+                    : Effect.die(new Error("a run without state cannot stop"));
+            }
+            const finished = finishedRun(ended.settled, reported);
+            if (config.failOnInvocationFailure && invocationFailures.length > 0) {
+                const refusal = invocationFailures[0];
+                return Effect.succeed(failureResponse(refusal.details.message, {
+                    code: refusal.details,
+                }));
+            }
+            return runState
+                ? runState.finishSettled(finished)
+                : Effect.succeed(exemptWrites?.finish(finished) ?? finished);
+        });
+    });
+    return {
+        claimMs: watchdog.ms + hostCallTimeoutMs + CLAIM_SLACK_MS,
+        storageTimeoutMs,
+        execute: ({ code, diagnostics }, options = {}) => {
+            // A code-unit count above the cap is already too large in UTF-8. Check
+            // that first so a huge direct-call string is never encoded in full.
+            if (code.length > EXECUTE_MAX_CODE_BYTES ||
+                new TextEncoder().encode(code).byteLength > EXECUTE_MAX_CODE_BYTES) {
+                const message = `execute_code code exceeds the ${EXECUTE_MAX_CODE_BYTES}-byte UTF-8 limit.`;
+                return Promise.resolve(failureResponse(message, {
+                    code: { code: "invalid_args", message, retryable: false },
+                }));
+            }
+            return runEdge(Effect.suspend(() => {
+                const program = normalizeProgramSource(code);
+                const storage = config.resumable ? registry.resultsStorage() : undefined;
+                const runState = config.resumable && storage?.compareAndSet
+                    ? RunState.fresh(storage, program, config.environment ?? freshEnvironment(), config.resumable, storageTimeoutMs)
+                    : undefined;
+                return play(program, runState, diagnostics, options.signal);
+            }));
+        },
+        replay: (runState, signal) => play(runState.program, runState, false, signal),
+    };
+}
+/** The execute_code handler. Exported for direct testing. */
+export function createExecuteTool(registry, baseUrl, executor, logger, activity, config = {}) {
+    return createProgramRunner(registry, baseUrl, executor, logger, activity, config).execute;
 }
 /** An execution that never produced an ExecuteResult, as the model sees it. */
 function failedRun(err, logger, { emitted, diagnostics }) {
@@ -750,26 +1117,27 @@ function connectorInventory(connectors) {
         return `${prefix}${shown.join(", ")}.`;
     return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
 }
-const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors) => `Use the configured services below to answer the task. A known address uses call_tool. Unknown-address and wider read-only work uses one execute_code program for discovery, calls, and reduction. Do not return catalog matches alone. Only readOnlyHint: true tools are available. Limits: ${hostLimits.maxHostCalls} host calls, ${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
+const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, resumable) => `Use the configured services below to answer the task. A known address uses call_tool. Unknown-address and wider ${resumable ? "work, writes included," : "read-only work"} uses one execute_code program for discovery, calls, and reduction. Do not return catalog matches alone. ${resumable
+    ? `Writes pause for resume_execution. Keep an authorized batch in one program; approval "tool" covers later same-address calls, other approval-required writes pause separately. Limits: ${hostLimits.maxHostCalls} host calls, ${resumable.maxWrites} writes`
+    : `Only readOnlyHint: true tools are available. Limits: ${hostLimits.maxHostCalls} host calls`}, ${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
 
 ${connectorInventory(connectors)}
 
-Read relevant guides using top-level skills, not sandbox code. Write a plain-JavaScript async arrow:
-- connecta.search({ connector, query, safety: "readOnly", includeSchemas: "json" }) returns { tools }. Search each operation separately; choose by connectorTitle and schemas. Use schema.required and .properties to build args, never guessed fields. Compact schemas are text.
-- connecta.describe({ address }) returns { tools } for unclear schemas.
+Read guides with top-level skills. Write async () => { ... } using the global connecta:
+- connecta.search({ connector, query, ${resumable ? "" : 'safety: "readOnly", '}includeSchemas: "json" }) returns { tools }. Search operations separately; choose by connectorTitle and schema.required/.properties, never guessed fields. Compact schemas are text.
+- connecta.describe({ address }) clarifies schemas.
 - connecta.call(address, args) returns the provider value directly.
-- Use Promise.all for independent calls, or Promise.allSettled to retain failures. Check status before reading value; rejected calls and missing fields are unknown, never false or zero.
-- connecta.emit(block): { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }; success-only, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes.
-- console.log(...) is captured. Return data for the client to render.
+- Use Promise.all for independent calls, or Promise.allSettled to retain failures. Check status; missing values are unknown, never false or zero.
+- connecta.emit(block): { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }; success-only, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes. console.log(...) is captured.
 
-No portable ambient capabilities. Return reduced JSON. If a provider result has an unfamiliar shape, return a small sample and continue in another call; never guess fields or use the whole text as an id. Top-level skills({ name: "usage" }): repair${connectorGuides ? ", guide handling" : ""}; skills({ name: "investigate" }): task planning.`;
+No portable ambient capabilities. Return reduced JSON. Sample unfamiliar reads. Reduce a one-time write's full result here, or use a direct call and get_result paging; never repeat it to recover output. Never guess fields or use the whole text as an id. Top-level skills({ name: "usage" }): repair${connectorGuides ? ", guide handling" : ""}; skills({ name: "investigate" }): task planning.`;
 // Module scope, like the other six meta-tool inputs: its JSON Schema is
 // derived once per process. Budgets and connectors vary by deployment and
 // view, so they live in the description, never here.
 const EXECUTE_INPUT = advertisedSchema(z.object({
     code: z
         .string()
-        .describe("One complete JavaScript async arrow function that discovers, calls, and returns the reduced answer."),
+        .describe("One complete zero-argument JavaScript async arrow: async () => { ... }. Use the provided connecta global to discover, call, and return the reduced answer. At most 65,536 UTF-8 bytes."),
     diagnostics: z
         .boolean()
         .optional()
@@ -790,7 +1158,7 @@ export function registerExecuteTool(server, registry, ctx) {
         hostCallTimeoutMs: resolveBudget(ctx.hostCallTimeoutMs, EXECUTE_HOST_CALL_TIMEOUT_MS),
     };
     const connectors = registry.listConnectors();
-    const handler = createExecuteTool(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, {
+    const runner = createProgramRunner(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, {
         discoveryConcurrency: ctx.discoveryConcurrency,
         probeTimeoutMs: ctx.probeTimeoutMs,
         maxEmittedBytes: emitBudgets.maxBytes,
@@ -799,38 +1167,26 @@ export function registerExecuteTool(server, registry, ctx) {
         hostCallTimeoutMs: hostLimits.hostCallTimeoutMs,
         watchdogMs: ctx.watchdogMs,
         defer: ctx.defer,
+        resumable: ctx.resumable,
+        approval: ctx.approval,
+        maxWrites: ctx.maxWrites,
     });
     server.registerTool("execute_code", {
-        description: executeDescription(emitBudgets, hostLimits, hasConnectorGuides(connectors), connectors),
+        description: executeDescription(emitBudgets, hostLimits, hasConnectorGuides(connectors), connectors, ctx.resumable),
         inputSchema: EXECUTE_INPUT,
-        // This hint describes connector calls, all explicitly read-only. The
-        // supported executor constructions deny outbound access, filesystem,
-        // and deployment config; X5 documents Dynamic runtime modules separately.
+        // This hint describes connector calls: only explicitly read-only ones
+        // run here, and any other call pauses the run unsent (W1) — the write
+        // itself runs inside resume_execution, which is annotated destructive.
+        // The supported executor constructions deny outbound access,
+        // filesystem, and deployment config; X5 documents Dynamic runtime
+        // modules separately.
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             openWorldHint: true,
         },
-    }, async (args, extra) => {
-        const controller = new AbortController();
-        const signals = [extra.mcpReq.signal, ctx.requestSignal].filter((signal) => signal !== undefined);
-        const forwarders = signals.map((signal) => {
-            const forward = () => controller.abort(signal.reason);
-            if (signal.aborted)
-                forward();
-            else
-                signal.addEventListener("abort", forward, { once: true });
-            return { signal, forward };
-        });
-        try {
-            return await handler(args, {
-                signal: controller.signal,
-            });
-        }
-        finally {
-            for (const { signal, forward } of forwarders) {
-                signal.removeEventListener("abort", forward);
-            }
-        }
-    });
+    }, (args, extra) => underAnySignal([extra.mcpReq.signal, ctx.requestSignal], (signal) => runner.execute(args, {
+        signal,
+    })));
+    return runner;
 }