@zackbart/connecta 0.40.0 → 0.42.0

package/dist/execute.js

@@ -1,4 +1,8 @@
+import { operationActivity } from "./operation-activity.js";
+import { SkillLookupError } from "./skills.js";
+import { skillLookupRecovery, utilityRecovery } from "./utility-recovery.js";
 import { META_ROUTES, routeNames } from "./agent-routes.js";
+import { READ_PROGRAM_SOURCE } from "./tool-safety.js";
 import { authCall, authFlow, authInvoke, authMethod } from "./auth/native.js";
 import { nativeRecovery } from "./native-recovery.js";
 import { GUEST_API_DECLARATION, GUEST_FUNCTIONS, UNCOUNTED_GUEST_FUNCTIONS, } from "./guest-functions.js";
@@ -8,29 +12,38 @@ import { Cause, Deferred, Duration, Effect, Exit } from "effect";
 import * as z from "zod";
 import { advertisedSchema } from "./advertised-schema.js";
 import { boundedDiscoveryText, CatalogService, DiscoveryPolicyError, flatSearchResult, } from "./catalog-service.js";
-import { createMetaTools, guardProgramReturn, jsonResult, pageProgramResult, } from "./meta-tools.js";
-import { PROGRAM_RESULT_INLINE_BYTES, PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_WIRE_BYTES, } from "./program-result.js";
+import { createMetaTools, guardProgramReturn, jsonResult, pageProgramResult, releaseStashedResult, } from "./meta-tools.js";
+import { PROGRAM_RESULT_INLINE_BYTES, PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_READ_BYTES, PROGRAM_RESULT_WIRE_BYTES, } from "./program-result.js";
 import { MAX_EXECUTE_LOG_CHARS, MAX_EXECUTE_RESULT_CHARS, truncateExecuteText } from "./executor-result.js";
 import { ExecutorAdmissionError, ExecutorExecutionError, isAdmittingExecutor } from "./executor-admission.js";
-import { boundedEchoText, ConnectorCallError, msg } from "./errors.js";
+import { boundedEchoText, clipSerialized, ConnectorCallError, msg } from "./errors.js";
 import { DEFAULT_MAX_WRITES, ProgramWrites, writeStateOf } from "./program-writes.js";
 import { InvocationFailure, InvocationService, timed } from "./invocation.js";
 import { guestPrelude, programError, wrapGuestProgram } from "./guest-runtime.js";
 import { EXECUTE_OUTPUT } from "./meta-output.js";
 import { normalizeProgramSource } from "./program-source.js";
 import { readResource } from "./resource-read.js";
+import { failureRecord, logFailure } from "./operator-record.js";
+import { HeldResults, sealHeldResults } from "./result-seal.js";
 import { redactAgentOutput, sentSecretsForRequest } from "./sent-secrets.js";
 import { normalizeTimeoutMs } from "./timeout.js";
 import { fromSignal, runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { closeScope } from "./runtime/connector-scope.js";
 import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { executorProgram } from "./runtime/executor.js";
-import { connectorGuide, connectorGuideRequired, connectorSkillName, hasConnectorGuides, SkillsRegistry, } from "./skills.js";
+import { connectorGuide, connectorGuideRequired, addsInformation, connectorInventoryTitle, inventoryNote, hasConnectorGuides, SkillsRegistry, } from "./skills.js";
 /** Keep one model-written program from amplifying into an unbounded fan-out. */
 const EXECUTE_MAX_HOST_CALLS = CONFIG_DEFAULTS.execute.maxHostCalls;
 const EXECUTE_HOST_CALL_TIMEOUT_MS = CONFIG_DEFAULTS.execute.hostCallTimeoutMs;
 /** Above every program in the recorded evals, below the QuickJS IPC ceiling. */
 const EXECUTE_MAX_CODE_BYTES = 64 * 1024;
+/** All of one run's stash reclaim, in milliseconds of waiting on storage. */
+const RECLAIM_BUDGET_MS = 1_000;
+/**
+ * Reclaims per run. Each freed slot lets another read stash and page again, so unbounded
+ * reclaim keeps a program spending storage queries that a full stash would have ended.
+ */
+const RECLAIM_MAX_PER_RUN = 3;
 /**
  * The outer ceiling on one execution. It sits above both executors' own
  * deadlines (QuickJS 30s, the Dynamic Worker 60s), so a healthy executor
@@ -38,6 +51,41 @@ const EXECUTE_MAX_CODE_BYTES = 64 * 1024;
  * never settles at all.
  */
 const EXECUTE_WATCHDOG_MS = CONFIG_DEFAULTS.execute.watchdogMs;
+/**
+ * How long before a deadline a program's reads stop: the time the guest gets
+ * to receive their `timeout` and return what it has.
+ */
+const READ_DEADLINE_MARGIN_MS = 1_000;
+const readMarginMs = (deadlineMs) => Math.min(READ_DEADLINE_MARGIN_MS, Math.floor(deadlineMs / 10));
+/**
+ * When a run's reads stop: before the executor's deadline, measured from now,
+ * and before the response ceiling, which queueing may already have spent.
+ */
+function readDeadlineAt(executor, ceiling) {
+    const beforeCeiling = ceiling.at - readMarginMs(ceiling.ms);
+    const { deadlineMs } = executor;
+    if (deadlineMs === undefined)
+        return beforeCeiling;
+    return Math.min(beforeCeiling, Date.now() + deadlineMs - readMarginMs(deadlineMs));
+}
+/** Past the ceiling, room to store what a run leaves behind. Default 57 s against a 60 s client. */
+const RESPONSE_STORAGE_MARGIN_MS = 2_000;
+function responseCeiling(startedAt, ms) {
+    const at = startedAt + ms;
+    return { ms, at, startedAt, answerBy: at + Math.min(RESPONSE_STORAGE_MARGIN_MS, Math.floor(ms / 10)) };
+}
+/** Refuse a run with no time left to start. Nothing has run, so running it again is safe. */
+const startable = (ceiling) => Effect.suspend(() => {
+    const elapsedMs = Date.now() - ceiling.startedAt;
+    return elapsedMs < ceiling.ms
+        ? Effect.void
+        : Effect.fail(new InvocationFailure({
+            code: "timeout",
+            message: `Operation "execute_code" used its ${ceiling.ms}ms response ceiling before it started, so it did not run and sent nothing. Run it again.`,
+            retryable: true,
+            details: { operation: "execute_code", stage: "response ceiling", elapsedMs, deadlineMs: ceiling.ms },
+        }));
+});
 /**
  * Room to name every connector of a typical deployment. Past it, complete
  * entries plus an exact omission count stay inside this byte cap.
@@ -342,35 +390,22 @@ function serializedDiagnosticBytes(value) {
     }
 }
 function guestFailure(code, message, retryable = false) {
-    return new InvocationFailure({ code, message, retryable });
+    return new InvocationFailure(["unavailable", "unsupported_capability", "input_required_unsupported"].includes(code)
+        ? utilityRecovery(code, message, retryable)
+        : { code, message, retryable });
 }
 /**
  * E1/X11: bound typed host failure metadata, including JSON escapes, before transport.
+ * The guest keeps this text, and may return it after a later call registers a credential it
+ * holds, so the message is cut between tokens.
  * Keep optional recovery whole: clipping an address or echoed args could turn
  * recovery into a different call. Oversized metadata is omitted instead.
  */
 function boundedGuestFailure(failure) {
-    const boundText = (text, maxChars) => {
-        if (JSON.stringify(text).length <= maxChars)
-            return text;
-        let low = 0;
-        let high = Math.min(text.length, maxChars);
-        while (low < high) {
-            const mid = Math.ceil((low + high) / 2);
-            if (JSON.stringify(`${text.slice(0, mid)}…`).length <= maxChars)
-                low = mid;
-            else
-                high = mid - 1;
-        }
-        // Do not manufacture a lone surrogate when clipping a Unicode message.
-        if (low > 0 && /[\uD800-\uDBFF]/.test(text[low - 1]))
-            low--;
-        return `${text.slice(0, low)}…`;
-    };
     let details = {
         ...failure.details,
-        code: boundText(failure.details.code, 128),
-        message: boundText(failure.details.message, 2_000),
+        code: clipSerialized(failure.details.code, 128),
+        message: clipSerialized(failure.details.message, 2_000),
     };
     // Keep typed metadata below the executor bridge bound.
     if (JSON.stringify(details).length > 3_700) {
@@ -396,7 +431,7 @@ class HostCallBudgetExceeded extends InvocationFailure {
     constructor(hostCalls, maxHostCalls) {
         super({
             code: "budget_exceeded",
-            message: `execute_code host-call budget exceeded (${maxHostCalls} calls maximum)`,
+            message: `execute_code host-call budget exceeded (${maxHostCalls} calls maximum); the run returned nothing. Split the rest across programs of at most ${maxHostCalls} calls each; do not resend any write it sent.`,
             retryable: false,
         });
         this.hostCalls = hostCalls;
@@ -426,6 +461,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         readOnly: limits.readOnly,
         // A program that just missed an address cannot call search_tools.
         searchRoute: "connecta.search",
+        markUncallableWrites: limits.readProgram,
         concurrency: limits.discoveryConcurrency,
         probeTimeoutMs: limits.probeTimeoutMs,
         defer: limits.defer,
@@ -435,6 +471,8 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
     const maxHostCalls = Math.max(1, Math.trunc(limits.maxHostCalls ?? EXECUTE_MAX_HOST_CALLS));
     const hostCallTimeoutMs = Math.max(1, Math.trunc(limits.hostCallTimeoutMs ?? EXECUTE_HOST_CALL_TIMEOUT_MS));
     const { signal, diagnostics, programWrites } = limits;
+    /** The part of `requestedMs` left before reads stop; never below one tick. */
+    const readBudget = (requestedMs) => Math.min(requestedMs, Math.max(1, (limits.readDeadlineAt ?? Infinity) - Date.now()));
     const hostCalls = limits.hostCalls ?? { attempted: 0, admitted: 0, succeeded: 0, failed: 0 };
     let budgetFailure;
     let emitAttempts = 0;
@@ -455,33 +493,70 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
     const maxWrites = resolveBudget(limits.maxWrites, DEFAULT_MAX_WRITES);
     let writes = 0;
     // These are transfer cursors only. All result bytes live in the existing stash.
+    // `reclaim` marks a read's stash only this transfer can name, because the guest never saw
+    // its handle. A guest-supplied id stays readable until it expires; a write's stash expires too.
+    const readBytes = limits.readBytes ?? PROGRAM_RESULT_READ_BYTES;
     const transfers = new Map();
     const nativeResults = new Map();
-    const transportResult = (value) => {
+    const transportResult = (value, write) => {
         if (value.format === "paged") {
             const handle = value;
             if (handle.resultId && handle.totalBytes <= PROGRAM_RESULT_INLINE_BYTES) {
                 const transfer = `transfer:${crypto.randomUUID()}`;
-                transfers.set(transfer, { id: handle.resultId, offset: 0 });
-                return { transfer, handle };
+                transfers.set(transfer, {
+                    id: handle.resultId,
+                    offset: 0,
+                    ...(write ? {} : { reclaim: { totalBytes: handle.totalBytes } }),
+                });
+                return { transfer, handle, ...(write ? {} : { reclaim: true }) };
             }
         }
         return value;
     };
+    // Slow storage may cost a run its reclaim, never its answer: all of a run's reclaim shares
+    // this much time, and once it's spent the rest of the run's entries just wait to expire.
+    let reclaimLeftMs = RECLAIM_BUDGET_MS;
+    let reclaimsLeft = RECLAIM_MAX_PER_RUN;
+    const reclaim = (id, totalBytes) => Effect.suspend(() => {
+        if (reclaimLeftMs <= 0 || reclaimsLeft <= 0)
+            return Effect.void;
+        reclaimsLeft--;
+        const started = Date.now();
+        return releaseStashedResult(registry, limits.heldResults, id, totalBytes).pipe(Effect.timeoutOrElse({ duration: Duration.millis(reclaimLeftMs), orElse: () => Effect.void }), Effect.ignore, Effect.ensuring(Effect.sync(() => {
+            reclaimLeftMs -= Date.now() - started;
+        })));
+    });
+    const dispatchDeadlineAt = limits.readDeadlineAt ?? limits.programDeadlineAt;
     /** Budget and account for writes a writable endpoint admits. */
-    const invocationContext = (sending, timeoutMs) => ({
-        source: "execute_code",
+    const invocationContext = (sending, timeoutMs, writeTimeoutMs) => ({
+        source: limits.readProgram ? READ_PROGRAM_SOURCE : "execute_code",
         sentSecrets,
         timeoutMs,
+        writeTimeoutMs,
         ...(limits.routes ? { routes: limits.routes } : {}),
         ...(signal !== undefined ? { requestSignal: signal } : {}),
         ...(limits.dispatchController ? { dispatchSignal: limits.dispatchController.signal } : {}),
+        ...(dispatchDeadlineAt !== undefined
+            ? {
+                // Past the gate's time, a call's answer could not reach the program either.
+                dispatchDeadline: {
+                    at: dispatchDeadlineAt,
+                    refusal: (address) => ({
+                        code: "timeout",
+                        message: `Too little of this run's deadline remains for ${address}, so it was not sent. Return what you have and send it in a new program.`,
+                        retryable: true,
+                        details: { operation: address, stage: "dispatch gate" },
+                    }),
+                },
+            }
+            : {}),
         unwrapResult: true,
         readOnly: limits.readOnly,
         processResult: authMethod((value, resolved, secrets, format, raw) => Effect.gen(function* () {
             // Dispatch succeeded before presentation began. Cancellation of paging
             // cannot turn this completed write into an unknown or failed write.
             sending.settle?.("ok");
+            const write = resolved.definition.classification !== "read";
             const page = (data, valueFormat, wireBytes) => authCall(pageProgramResult, [
                 registry,
                 baseUrl,
@@ -490,7 +565,11 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 valueFormat,
                 secrets,
                 requestScope,
+                { max: maxHostCalls, left: maxHostCalls - hostCalls.attempted },
                 wireBytes,
+                limits.followUpRoutes,
+                limits.heldResults,
+                readBytes,
             ]);
             const envelope = resolved.connector.kind === "mcp" && raw !== null && typeof raw === "object"
                 ? raw
@@ -511,7 +590,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             const content = envelope?.content;
             if (!Array.isArray(content) ||
                 !content.some((block) => block && ["image", "audio", "resource", "resource_link"].includes(block.type))) {
-                return transportResult(yield* page(value, format));
+                return transportResult(yield* page(value, format), write);
             }
             const unavailablePresentation = () => ({
                 format: "paged",
@@ -537,7 +616,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             catch (error) {
                 if (!(error instanceof NativePresentationLimit))
                     throw error;
-                const result = dataKey === undefined ? undefined : transportResult(yield* page(value, format));
+                const result = dataKey === undefined ? undefined : transportResult(yield* page(value, format), write);
                 const notice = unavailablePresentation();
                 return result ? { value: result, native: { value: notice } } : notice;
             }
@@ -551,7 +630,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             });
             let valueResult;
             if (native.format === "paged") {
-                valueResult = result ? transportResult(result) : undefined;
+                valueResult = result ? transportResult(result, write) : undefined;
                 if (!native.resultId || native.totalBytes > PROGRAM_RESULT_INLINE_BYTES) {
                     return valueResult ? { value: valueResult, native: { value: native } } : native;
                 }
@@ -561,14 +640,14 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             // absent or connector-owned blocks.
             if (!retained) {
                 const notice = native.format === "paged" ? native : unavailablePresentation();
-                const valueResult = result ? transportResult(result) : undefined;
+                const valueResult = result ? transportResult(result, write) : undefined;
                 return valueResult ? { value: valueResult, native: { value: notice } } : notice;
             }
             const ref = crypto.randomUUID();
             nativeResults.set(ref, retained);
             return {
                 ...(valueResult ? { value: valueResult } : {}),
-                native: { ref, value: transportResult(native), dataKey },
+                native: { ref, value: transportResult(native, write), dataKey },
             };
         })),
         beforeWrite: (target) => Effect.sync(() => {
@@ -583,13 +662,38 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                     unrecorded: true,
                 };
             }
+            // A write is exactly what its program asked for, or it stays here. Reads
+            // keep the filtered value: sending one changes nothing it could not repeat.
+            if (sending.rewritten) {
+                return {
+                    kind: "refuse",
+                    error: {
+                        code: "invalid_args",
+                        message: `${target.connector.id}.${target.toolName} was not sent: its arguments hold a credential this request sent, and a write is never sent altered. If the value is genuine, send it as its own direct call.`,
+                        retryable: false,
+                    },
+                };
+            }
+            // Its answer could not reach the program, so refuse now while the outcome
+            // is known. Earlier writes go out and drain past the deadline (W9).
+            if (limits.readDeadlineAt !== undefined && Date.now() >= limits.readDeadlineAt) {
+                return {
+                    kind: "refuse",
+                    error: {
+                        code: "timeout",
+                        message: `Too little of this run's deadline remains for ${target.connector.id}.${target.toolName}, so it was not sent. Return what you have and send it in a new program.`,
+                        retryable: true,
+                        details: { operation: `${target.connector.id}.${target.toolName}`, stage: "write gate" },
+                    },
+                };
+            }
             const budgeted = target.definition.classification !== "read";
             if (budgeted && writes >= 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`,
+                        message: `execute_code write budget exceeded (${maxWrites} writes per run); ${target.connector.id}.${target.toolName} was not sent. Check the run's writes count, then send only the rest in a new program; do not resend those that succeeded.`,
                         retryable: false,
                     },
                 };
@@ -633,12 +737,14 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         const requestedMs = normalizeTimeoutMs(timeout) ??
             normalizeTimeoutMs(limits.defaultToolTimeoutMs) ??
             hostCallTimeoutMs;
-        const timeoutMs = Math.min(requestedMs, Math.max(1, (limits.programDeadlineAt ?? Infinity) - Date.now()));
+        const timeoutMs = readBudget(requestedMs);
+        const writeTimeoutMs = Math.min(requestedMs, Math.max(1, (limits.programDeadlineAt ?? Infinity) - Date.now()));
         // A program write settles here — unknown if the call never returned an
         // outcome. Credentials are filtered from arguments; submitted private values are not.
-        const sending = {};
+        const filtered = sentSecrets.filterCredentials(args ?? {});
+        const sending = { rewritten: filtered.changed };
         const outcome = yield* invocation
-            .pipeline(address, sentSecrets.redactCredentials(args ?? {}), invocationContext(sending, timeoutMs))
+            .pipeline(address, filtered.value, invocationContext(sending, timeoutMs, writeTimeoutMs))
             .pipe(Effect.onExit((exit) => Effect.sync(() => sending.settle?.(Exit.isSuccess(exit) ? writeStateOf(exit.value) : "unknown"))));
         if (outcome.resolved) {
             const resolved = outcome.resolved;
@@ -674,19 +780,38 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
     const discovery = (operation, read) => Effect.suspend(() => {
         const started = Date.now();
         const cancelled = () => guestFailure("cancelled", `connecta.${operation} was cancelled because the run ended.`);
-        const reading = Effect.tryPromise({
-            try: read,
-            catch: (err) => (err instanceof DiscoveryPolicyError ? guestFailure(err.code, err.message) : err),
-        });
-        return (!hostAccessSignal
-            ? reading
-            : hostAccessSignal.aborted
-                ? Effect.fail(cancelled())
-                : Effect.raceAllFirst([reading, fromSignal(hostAccessSignal).pipe(Effect.mapError(cancelled))])).pipe(Effect.onExit((exit) => Effect.sync(() => diagnostics?.recordCatalog(operation, Date.now() - started, Exit.isSuccess(exit), Exit.isSuccess(exit) ? exit.value : undefined))));
+        // In the race itself, not behind a Promise: losing interrupts the catalog
+        // work and aborts its listing before the program hears the outcome (L3).
+        // The catalog hears the run's end as well, so its failure may arrive first.
+        const reading = Effect.suspend(read).pipe(Effect.catchDefect((err) => Effect.fail(err)), Effect.mapError((err) => hostAccessSignal?.aborted
+            ? cancelled()
+            : err instanceof DiscoveryPolicyError
+                ? guestFailure(err.code, err.message)
+                : err));
+        const contenders = [reading];
+        // A catalog probe may outlast the run; end it as a catchable timeout first.
+        if (limits.readDeadlineAt !== undefined)
+            contenders.push(Effect.suspend(() => {
+                const deadlineMs = readBudget(Infinity);
+                return Effect.sleep(Duration.millis(deadlineMs)).pipe(Effect.andThen(Effect.suspend(() => {
+                    const elapsedMs = Date.now() - started;
+                    const name = `connecta.${operation}`;
+                    return Effect.fail(new InvocationFailure({
+                        code: "timeout",
+                        message: `Operation "${name}" timed out during catalog after ${elapsedMs}ms (effective deadline ${deadlineMs}ms).`,
+                        retryable: true,
+                        details: { operation: name, stage: "catalog", elapsedMs, deadlineMs },
+                    }));
+                })));
+            }));
+        if (hostAccessSignal)
+            contenders.push(fromSignal(hostAccessSignal).pipe(Effect.mapError(cancelled)));
+        return (hostAccessSignal?.aborted ? Effect.fail(cancelled()) : Effect.raceAllFirst(contenders)).pipe(Effect.onExit((exit) => Effect.sync(() => diagnostics?.recordCatalog(operation, Date.now() - started, Exit.isSuccess(exit), Exit.isSuccess(exit) ? exit.value : undefined))));
     });
     const meta = createMetaTools(registry, baseUrl, {
         readOnly: limits.readOnly,
         requestScope,
+        heldResults: limits.heldResults,
         onResultRead: (dependencies) => limits.resultDependencies?.push(...dependencies),
     });
     const catalogDependency = (connector, tool) => {
@@ -704,63 +829,93 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             catalogDependency(resolved.connector.id, resolved.toolName);
     };
     const operations = {
-        // Uncounted: a failed program read a result field off an unawaited host call.
+        // Uncounted: a program read a result field off an unawaited host call.
         unawaited: () => {
             if (limits.unawaited)
                 limits.unawaited.read = true;
         },
         call,
-        result: (id, options, signal, onStage) => Effect.tryPromise({
-            try: async () => {
-                const transfer = typeof id === "string" ? transfers.get(id) : undefined;
-                const transferId = id;
-                if (transfer) {
-                    id = transfer.id;
-                    options = { offset: transfer.offset, maxBytes: PROGRAM_RESULT_PAGE_BYTES };
-                }
-                else if (id !== null && typeof id === "object" && !Array.isArray(id)) {
-                    id = id.resultId;
-                }
-                if (typeof id !== "string" ||
-                    (!options && options !== undefined) ||
-                    (options !== undefined && (typeof options !== "object" || Array.isArray(options)))) {
-                    throw guestFailure("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? }).");
-                }
-                const args = { ...(options ?? {}) };
-                if (Object.keys(args).some((key) => !["page", "offset", "maxBytes"].includes(key)) ||
-                    (args.page !== undefined &&
-                        (typeof args.page !== "number" ||
-                            !Number.isSafeInteger(args.page) ||
-                            args.page < 0 ||
-                            args.offset !== undefined)) ||
-                    (args.offset !== undefined &&
-                        (typeof args.offset !== "number" || !Number.isSafeInteger(args.offset) || args.offset < 0)) ||
-                    (args.maxBytes !== undefined &&
-                        (typeof args.maxBytes !== "number" || !Number.isSafeInteger(args.maxBytes) || args.maxBytes < 1))) {
-                    throw guestFailure("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? }) with whole page/offset >= 0 and maxBytes >= 1; page and offset are mutually exclusive.");
-                }
-                // A page must fit every shipped bridge even when the connector cap is raised.
-                args.maxBytes = Math.min(args.maxBytes ?? PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_PAGE_BYTES);
-                const page = await meta.readResult({ id, ...args }, {
-                    signal: signal,
-                    onStage: onStage,
-                });
-                if (page.isError)
-                    throw new InvocationFailure((page.structuredContent?.error ?? {
-                        code: "not_found",
-                        message: page.content[0]?.text ?? "Result unavailable.",
-                        retryable: false,
-                    }));
-                if (transfer) {
-                    if (page.structuredContent?.hasMore)
-                        transfer.offset = page.structuredContent.nextOffset;
-                    else
-                        transfers.delete(transferId);
-                }
-                return page.structuredContent;
-            },
-            catch: (err) => err,
-        }),
+        result: (id, options, signal, onStage) => {
+            const finished = typeof id === "string" ? transfers.get(id) : undefined;
+            if (finished?.finished) {
+                // The prelude has the whole value, so a read gives its bytes back.
+                transfers.delete(id);
+                return finished.reclaim
+                    ? reclaim(finished.id, finished.reclaim.totalBytes).pipe(Effect.as({}))
+                    : Effect.succeed({});
+            }
+            return Effect.tryPromise({
+                try: async () => {
+                    const transfer = typeof id === "string" ? transfers.get(id) : undefined;
+                    const transferId = id;
+                    if (transfer) {
+                        id = transfer.id;
+                        options = { offset: transfer.offset, maxBytes: PROGRAM_RESULT_PAGE_BYTES };
+                    }
+                    else if (id !== null && typeof id === "object" && !Array.isArray(id)) {
+                        id = id.resultId;
+                    }
+                    if (typeof id !== "string" ||
+                        (!options && options !== undefined) ||
+                        (options !== undefined && (typeof options !== "object" || Array.isArray(options)))) {
+                        throw new InvocationFailure(utilityRecovery("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? })."));
+                    }
+                    const args = { ...(options ?? {}) };
+                    const whole = args.all === true;
+                    if (args.all === false)
+                        delete args.all;
+                    if ((whole && Object.keys(args).length > 1) || (args.all !== undefined && !whole)) {
+                        throw new InvocationFailure(utilityRecovery("invalid_args", "Use connecta.result(handleOrId, { all: true }) with no other options."));
+                    }
+                    delete args.all;
+                    if (Object.keys(args).some((key) => !["page", "offset", "maxBytes"].includes(key)) ||
+                        (args.page !== undefined &&
+                            (typeof args.page !== "number" ||
+                                !Number.isSafeInteger(args.page) ||
+                                args.page < 0 ||
+                                args.offset !== undefined)) ||
+                        (args.offset !== undefined &&
+                            (typeof args.offset !== "number" || !Number.isSafeInteger(args.offset) || args.offset < 0)) ||
+                        (args.maxBytes !== undefined &&
+                            (typeof args.maxBytes !== "number" || !Number.isSafeInteger(args.maxBytes) || args.maxBytes < 1))) {
+                        throw new InvocationFailure(utilityRecovery("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? }) with whole page/offset >= 0 and maxBytes >= 1; page and offset are mutually exclusive."));
+                    }
+                    // A page must fit every shipped bridge even when the connector cap is raised.
+                    args.maxBytes = Math.min(args.maxBytes ?? PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_PAGE_BYTES);
+                    const page = await meta.readResult({ id, ...args }, {
+                        signal: signal,
+                        onStage: onStage,
+                    });
+                    if (page.isError)
+                        throw new InvocationFailure((page.structuredContent?.error ?? {
+                            code: "not_found",
+                            message: page.content[0]?.text ?? "Result unavailable.",
+                            retryable: false,
+                        }));
+                    if (transfer) {
+                        if (page.structuredContent?.hasMore)
+                            transfer.offset = page.structuredContent.nextOffset;
+                        else if (transfer.reclaim)
+                            transfer.finished = true;
+                        else
+                            transfers.delete(transferId);
+                    }
+                    if (whole) {
+                        const totalBytes = page.structuredContent?.totalBytes;
+                        if (totalBytes > readBytes) {
+                            throw guestFailure("result_too_large", `This result is ${totalBytes} bytes and connecta.result(id, { all: true }) reads at most ${readBytes}. Page it with { offset } and keep only what you need from each page.`);
+                        }
+                        if (!page.structuredContent?.hasMore)
+                            return page.structuredContent;
+                        const started = `transfer:${crypto.randomUUID()}`;
+                        transfers.set(started, { id, offset: page.structuredContent.nextOffset });
+                        return { ...page.structuredContent, transfer: started };
+                    }
+                    return page.structuredContent;
+                },
+                catch: (err) => err,
+            });
+        },
         skill: (name, _options, utilitySignal) => Effect.tryPromise({
             try: async () => {
                 // Accept the top-level skills tool's { name } shape too: models copy it into programs.
@@ -768,6 +923,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 if (typeof skillName !== "string")
                     throw guestFailure("invalid_args", 'Use connecta.skill("usage") or connecta.skill("connector:<id>") with an exact skill name; the skills tool lists names.');
                 const skills = new SkillsRegistry(registry, baseUrl, {
+                    readOnly: limits.readOnly,
                     requestScope,
                     requestSignal: utilitySignal ?? hostAccessSignal,
                     onRead: (connector, source) => limits.resultDependencies?.push({
@@ -780,7 +936,11 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 });
                 return { name: skillName, format: "text", text: await skills.text(skillName) };
             },
-            catch: (err) => err instanceof ConnectorCallError ? guestFailure(err.code, err.message, err.code === "unavailable") : err,
+            catch: (err) => err instanceof SkillLookupError
+                ? new InvocationFailure(skillLookupRecovery(err.message))
+                : err instanceof ConnectorCallError
+                    ? guestFailure(err.code, "Skills are unavailable.", err.retryable)
+                    : err,
         }),
         read: (uri) => Effect.suspend(() => {
             const started = Date.now();
@@ -789,7 +949,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 baseUrl,
                 requestScope,
                 sentSecrets,
-                timeoutMs: hostCallTimeoutMs,
+                timeoutMs: readBudget(hostCallTimeoutMs),
                 onResolved: (connector) => limits.resultDependencies?.push({ connector: connector.id, classification: "read" }),
                 onConnectorTime: (elapsed) => {
                     connectorMs += elapsed;
@@ -829,34 +989,40 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             },
             catch: (err) => err,
         }),
-        search: (raw) => discovery("search", async () => {
+        search: (raw) => discovery("search", () => {
             const args = (raw ?? {});
-            const result = flatSearchResult(await catalog.search({
+            return catalog
+                .searchEffect({
                 ...args,
                 includeSchemas: args.includeSchemas ?? "typescript",
                 includeSchemaKeys: args.includeSchemaKeys !== false,
-            }, catalogDependency));
-            boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
-            return result;
+            }, catalogDependency)
+                .pipe(Effect.map((page) => {
+                const result = flatSearchResult(page);
+                boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
+                return result;
+            }));
         }),
-        describe: (raw) => discovery("describe", async () => {
+        describe: (raw) => discovery("describe", () => {
             const args = (raw ?? {});
-            const result = { tools: await catalog.describe({ ...args, format: args.format ?? "json" }) };
-            boundedDiscoveryText(result, 'Split the address list or use format: "compact".');
-            for (const tool of result.tools) {
-                if (!tool.error)
-                    catalogAddressDependency(tool.address);
-                else {
-                    const resolved = registry.resolveAddress(tool.address);
-                    if (resolved)
-                        catalogDependency(resolved.connector.id);
-                    for (const connector of tool.errorDetails?.configuredConnectors ?? [])
-                        catalogDependency(connector);
-                    for (const suggestion of tool.errorDetails?.suggestions ?? [])
-                        catalogAddressDependency(suggestion);
+            return catalog.describeEffect({ ...args, format: args.format ?? "json" }).pipe(Effect.map((tools) => {
+                const result = { tools };
+                boundedDiscoveryText(result, 'Split the address list, omit fullDescriptions, or use format: "compact".');
+                for (const tool of result.tools) {
+                    if (!tool.error)
+                        catalogAddressDependency(tool.address);
+                    else {
+                        const resolved = registry.resolveAddress(tool.address);
+                        if (resolved)
+                            catalogDependency(resolved.connector.id);
+                        for (const connector of tool.errorDetails?.configuredConnectors ?? [])
+                            catalogDependency(connector);
+                        for (const suggestion of tool.errorDetails?.suggestions ?? [])
+                            catalogAddressDependency(suggestion);
+                    }
                 }
-            }
-            return result;
+                return result;
+            }));
         }),
     };
     // Recoverable failures remain typed at the host-owned executor bridge. Terminal host-budget exhaustion bypasses it.
@@ -888,7 +1054,8 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             return [
                 name,
                 (...args) => {
-                    if (budgetFailure)
+                    // Once sealing begins the run's secret set is final, so nothing new may start.
+                    if (budgetFailure || limits.heldResults?.accepts() === false)
                         return stopped;
                     // Uncounted: one per run; any further call through the bridge ends the run.
                     if (budget === "once") {
@@ -912,23 +1079,27 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                     if (counted)
                         hostCalls.admitted++;
                     const started = Date.now();
+                    const utilityDeadlineMs = readBudget(hostCallTimeoutMs);
                     let stage = deadline ?? "";
                     const invoke = Effect.suspend(() => operation(...args));
                     const guarded = deadline
                         ? withDeadlineEffect((utilitySignal) => Effect.suspend(() => operation(args[0], args[1], utilitySignal, (current) => {
                             stage = current;
                         })), {
-                            timeoutMs: hostCallTimeoutMs,
+                            timeoutMs: utilityDeadlineMs,
                             ...(hostAccessSignal ? { signal: hostAccessSignal } : {}),
                             timeoutError: guestFailure("timeout", `connecta.${name} timed out.`),
                         })
                         : invoke;
-                    const settled = runEdge(guarded.pipe(Effect.catch((error) => {
+                    const operationEffect = activity?.recordOperation && ["search", "describe", "result", "skill"].includes(name)
+                        ? operationActivity(activity, registry, name, guarded, undefined, limits.readProgram ? READ_PROGRAM_SOURCE : undefined)
+                        : guarded;
+                    const running = runEdge(operationEffect.pipe(Effect.catch((error) => {
                         if (deadline && hostAccessSignal?.aborted)
                             return typedFailure(guestFailure("cancelled", `connecta.${name} was cancelled because the run ended.`));
                         if (deadline && error instanceof InvocationFailure && error.code === "timeout") {
                             const elapsedMs = Date.now() - started;
-                            const message = `Operation "connecta.${name}" timed out during ${stage} after ${elapsedMs}ms (effective deadline ${hostCallTimeoutMs}ms).`;
+                            const message = `Operation "connecta.${name}" timed out during ${stage} after ${elapsedMs}ms (effective deadline ${utilityDeadlineMs}ms).`;
                             return typedFailure(new InvocationFailure({
                                 code: "timeout",
                                 message,
@@ -937,12 +1108,14 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                                     operation: `connecta.${name}`,
                                     stage,
                                     elapsedMs,
-                                    deadlineMs: hostCallTimeoutMs,
+                                    deadlineMs: utilityDeadlineMs,
                                 },
                             }));
                         }
                         return typedFailure(error);
-                    }))).then((value) => {
+                    })));
+                    limits.heldResults?.track(running);
+                    const settled = running.then((value) => {
                         if (counted)
                             hostCalls.succeeded++;
                         return budgetFailure ? stopped : redactAgentOutput(sentSecrets, value);
@@ -989,7 +1162,6 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
  * waiting for one.
  */
 function awaitExecutor(start, signal, options = {}) {
-    const started = Date.now();
     const contenders = [
         typeof start !== "function"
             ? start
@@ -1016,21 +1188,34 @@ function awaitExecutor(start, signal, options = {}) {
         contenders.push(options.terminal);
     const { watchdog } = options;
     if (watchdog) {
-        contenders.push(Effect.sleep(Duration.millis(watchdog.ms)).pipe(Effect.andThen(Effect.suspend(() => {
+        contenders.push(untilCeiling(watchdog.ceiling).pipe(Effect.andThen(Effect.suspend(() => {
+            const { ms: deadlineMs, startedAt } = watchdog.ceiling;
+            const elapsedMs = Date.now() - startedAt;
+            // Time ran out before the executor's own deadline could: queueing
+            // spent it, or that deadline is set past the ceiling. Nothing is wedged.
+            if (watchdog.executorDeadlineAt !== undefined && Date.now() < watchdog.executorDeadlineAt) {
+                return Effect.fail(new InvocationFailure({
+                    code: "timeout",
+                    message: `Operation "execute_code" timed out during response ceiling after ${elapsedMs}ms (effective deadline ${deadlineMs}ms). Return sooner, or do less in one program.`,
+                    retryable: true,
+                    details: { operation: "execute_code", stage: "response ceiling", elapsedMs, deadlineMs },
+                }));
+            }
             watchdog.logger.warn("[connecta] execute_code executor did not settle; run abandoned", {
-                watchdogMs: watchdog.ms,
+                watchdogMs: deadlineMs,
             });
-            const elapsedMs = Date.now() - started;
             return Effect.fail(new InvocationFailure({
                 code: "timeout",
-                message: `Operation "execute_code" timed out during sandbox watchdog after ${elapsedMs}ms (effective deadline ${watchdog.ms}ms); sandbox unresponsive.`,
+                message: `Operation "execute_code" timed out during sandbox watchdog after ${elapsedMs}ms (effective deadline ${deadlineMs}ms); sandbox unresponsive.`,
                 retryable: false,
-                details: { operation: "execute_code", stage: "sandbox watchdog", elapsedMs, deadlineMs: watchdog.ms },
+                details: { operation: "execute_code", stage: "sandbox watchdog", elapsedMs, deadlineMs },
             }));
         }))));
     }
     return Effect.raceAllFirst(contenders);
 }
+/** Waits until the ceiling; already past it, one timer turn. */
+const untilCeiling = (ceiling) => Effect.suspend(() => Effect.sleep(Duration.millis(Math.max(1, ceiling.at - Date.now()))));
 /**
  * The run's own signal, aborted however the run ends. It follows the
  * caller's, and aborting it on the way out is what releases outstanding host
@@ -1059,9 +1244,11 @@ function runSignal(caller) {
  * executor, so this request's providers and program run here, never in the
  * releasing request, which workerd refuses.
  */
-function leased(executor, signal) {
+function leased(executor, signal, ceiling) {
     return Effect.acquireRelease(awaitExecutor(() => executor.acquire({ signal, wait: true }), signal, {
         late: (lease) => lease.release(),
+        // A queue configured to outwait the client still answers it.
+        terminal: untilCeiling(ceiling).pipe(Effect.andThen(Effect.suspend(() => Effect.fail(new ExecutorAdmissionError("executor_overloaded", `Executor admission timed out after ${Date.now() - ceiling.startedAt}ms.`))))),
     }), (lease) => Effect.sync(() => lease.release()));
 }
 /** The execute_code handler. Exported for direct testing. */
@@ -1072,12 +1259,13 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
     };
     const hostCallTimeoutMs = resolveBudget(config.hostCallTimeoutMs, EXECUTE_HOST_CALL_TIMEOUT_MS);
     const maxResultChars = resolveBudget(config.maxResultChars, MAX_EXECUTE_RESULT_CHARS);
-    const play = (program, diagnosticsRequested, callerSignal, requestScope, hostCalls, programWrites) => Effect.suspend(() => {
+    const readBytes = resolveBudget(executor.maxReadBytes, PROGRAM_RESULT_READ_BYTES);
+    const play = (program, diagnosticsRequested, callerSignal, requestScope, hostCalls, programWrites, unawaited, retention, ceiling) => Effect.suspend(() => {
         const sentSecrets = sentSecretsForRequest(requestScope);
+        const heldResults = new HeldResults(sentSecrets, requestOwner(requestScope).credentialReads);
         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, maxResultChars);
         const resultDependencies = [];
-        const unawaited = { read: false };
         const dispatchController = new AbortController();
         const terminal = Deferred.makeUnsafe();
         let budgetFailure;
@@ -1092,6 +1280,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             // every exit, using the existing bounded cleanup and deferred tail.
             yield* Effect.addFinalizer(() => Effect.forEach(registry.listConnectors(), (connector) => closeScope(connector, registry.contextFor(connector.id, baseUrl, requestScope), config.defer), { concurrency: "unbounded", discard: true }));
             const signal = yield* runSignal(callerSignal);
+            yield* startable(ceiling);
             // Admission comes before provider construction: queued calls retain
             // no catalogs or provider closures.
             let lease;
@@ -1099,7 +1288,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 lease = yield* timed((elapsed) => {
                     if (diagnostics)
                         diagnostics.admissionMs = elapsed;
-                }, leased(executor, signal));
+                }, leased(executor, signal, ceiling));
                 if ((lease.waitMs ?? 0) > 0) {
                     logger.debug("[connecta] execute_code admitted after queue wait", {
                         waitMs: lease.waitMs,
@@ -1124,19 +1313,25 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 maxHostCalls: config.maxHostCalls,
                 hostCallTimeoutMs,
                 defaultToolTimeoutMs: config.defaultToolTimeoutMs,
-                programDeadlineAt: Date.now() + watchdog.ms,
+                programDeadlineAt: ceiling.at,
+                readDeadlineAt: readDeadlineAt(executor, ceiling),
                 defer: config.defer,
                 readOnly: config.readOnly,
                 maxWrites: config.maxWrites,
                 routes: config.routes,
+                readProgram: config.readProgram,
+                followUpRoutes: config.followUpRoutes,
                 programWrites,
+                readBytes,
                 resultDependencies,
                 dispatchController,
                 unawaited,
+                heldResults,
             }, requestScope)));
             if (signal.aborted) {
                 return yield* Effect.fail(new ExecutorAdmissionError("executor_cancelled", "Execution was cancelled during sandbox setup."));
             }
+            yield* startable(ceiling);
             const admitted = lease;
             // A program write may still be on the wire when the program settles:
             // close, so a write gated after this is not sent, then let the ones
@@ -1156,7 +1351,19 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 interrupted: (logs) => {
                     executorLogs = sentSecrets.redact(logs);
                 },
-            }).pipe(Effect.map((outcome) => sentSecrets.redact(outcome)), Effect.mapError((error) => sentSecrets.redact(error))), signal, { watchdog, terminal: Deferred.await(terminal) }).pipe(Effect.ensuring(Effect.suspend(() => {
+            }).pipe(Effect.map((outcome) => sentSecrets.redact(outcome)), Effect.mapError((error) => sentSecrets.redact(error))), signal, {
+                watchdog: {
+                    ceiling,
+                    // With no published deadline, a run that queued has not shown it is wedged.
+                    executorDeadlineAt: executor.deadlineMs !== undefined
+                        ? Date.now() + executor.deadlineMs
+                        : (admitted?.waitMs ?? 0) > 0
+                            ? Infinity
+                            : undefined,
+                    logger: watchdog.logger,
+                },
+                terminal: Deferred.await(terminal),
+            }).pipe(Effect.ensuring(Effect.suspend(() => {
                 programWrites.close();
                 dispatchController.abort();
                 // Finalizers are masked by default. The request must be able
@@ -1180,6 +1387,10 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 maxResultChars - emitted.textChars,
                 programWrites.hasSucceeded,
                 maxResultChars,
+                heldResults,
+                ceiling.answerBy,
+                readBytes,
+                config.followUpRoutes,
             ]),
         };
         const exited = Effect.exit(Effect.scoped(run)).pipe(Effect.flatMap((exit) => 
@@ -1187,7 +1398,15 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
         // the retained log prefix. Give that report one timer turn, just as
         // cancellation does in awaitExecutor; never wait on a Worker isolate.
         budgetFailure ? Effect.sleep(Duration.millis(1)).pipe(Effect.as(exit)) : Effect.succeed(exit)));
-        return Effect.flatMap(exited, (exit) => {
+        // Every way a run answers can carry a result id, so every one of them seals, by the
+        // time the response must be on its way. A sealing cut short leaves entries unreadable.
+        const sealRun = Effect.suspend(() => sealHeldResults(heldResults, registry.resultsStorage(), ceiling.answerBy, callerSignal)).pipe(Effect.tap(({ refused, refusedWrite }) => Effect.sync(() => {
+            if (refused === 0)
+                return;
+            retention.note = refusedWrite ? RESULTS_REFUSED_WRITE_NOTE : RESULTS_REFUSED_NOTE;
+            logFailure(logger, "result paging unavailable", failureRecord({}));
+        })));
+        const answered = Effect.flatMap(exited, (exit) => {
             // A synchronous fire-and-forget burst can also settle its executor in
             // this turn. The host's terminal refusal always wins over that value.
             if (budgetFailure instanceof HostCallBudgetExceeded) {
@@ -1211,6 +1430,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 timeoutError: cancelled,
             }).pipe(Effect.catch((error) => Effect.succeed(failedRun(callerSignal?.aborted ? cancelled : error, logger, reported))));
         });
+        return Effect.tap(answered, () => sealRun);
     });
     return authMethod(({ code, diagnostics }, options = {}) => Effect.suspend(() => {
         const requestScope = config.requestScope ?? {};
@@ -1220,6 +1440,9 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             return Effect.fail(owner.controller.signal.reason);
         const hostCalls = { attempted: 0, admitted: 0, succeeded: 0, failed: 0 };
         const programWrites = new ProgramWrites();
+        const unawaited = { read: false };
+        const retention = {};
+        const ceiling = responseCeiling(config.requestStartedAt ?? Date.now(), watchdog.ms);
         const response = Effect.suspend(() => {
             // 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.
@@ -1228,22 +1451,53 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 const message = `execute_code code exceeds the ${EXECUTE_MAX_CODE_BYTES}-byte UTF-8 limit.`;
                 return Effect.succeed(failureResponse(message, { code: { code: "invalid_args", message, retryable: false } }));
             }
-            return play(normalizeProgramSource(code), diagnostics, options.signal, requestScope, hostCalls, programWrites);
+            return play(normalizeProgramSource(code), diagnostics, options.signal, requestScope, hostCalls, programWrites, unawaited, retention, ceiling);
         });
-        return response.pipe(Effect.provideService(RequestScope, owner), Effect.map((unfinished) => {
+        return operationActivity(activity, registry, "program", response.pipe(Effect.provideService(RequestScope, owner), Effect.map((unfinished) => {
             // Every response, including intake refusals, crosses accounting and
             // exactly one envelope check at this operation boundary.
-            const result = redactAgentOutput(sentSecrets, programWrites.finish(unfinished));
+            const result = redactAgentOutput(sentSecrets, programWrites.finish(unfinished, sentSecrets, maxResultChars));
             // Calls abandoned by the guest are failed when the run cancels them.
             // Connecta attaches its own integers after the envelope check.
             const counts = { ...hostCalls, failed: hostCalls.attempted - hostCalls.succeeded };
-            result.structuredContent = { ...result.structuredContent, hostCalls: counts };
+            const note = [
+                finishedRunNote(result, hostCalls.attempted, programWrites.sent, unawaited.read),
+                retention.note,
+            ]
+                .filter(Boolean)
+                .join(" ");
+            result.structuredContent = {
+                ...result.structuredContent,
+                ...(note ? { note } : {}),
+                hostCalls: counts,
+            };
             if (result.content[0]?.type === "text")
                 result.content[0].text = JSON.stringify(result.structuredContent);
             return result;
-        }), Effect.catchDefect(Effect.fail), Effect.mapError((error) => redactAgentOutput(sentSecrets, error)));
+        }), Effect.catchDefect(Effect.fail), Effect.mapError((error) => redactAgentOutput(sentSecrets, error))), () => ({ ...hostCalls, failed: hostCalls.attempted - hostCalls.succeeded }), config.readProgram ? READ_PROGRAM_SOURCE : undefined);
     }));
 }
+const RESULTS_REFUSED_NOTE = "A result this run retained was not kept for later runs, so paging its id from a new program may fail. Rerun the read for a fresh result.";
+const RESULTS_REFUSED_WRITE_NOTE = `${RESULTS_REFUSED_NOTE} A write's output among them may not be retrievable: that write already ran, so do not repeat it.`;
+const UNAWAITED_HINT = "connecta.* returns a Promise; await it: (await connecta.call(address, args)).data.";
+const SENT_NOTE = "Its writes were already sent. Do not rerun it, even with a fix: read their targets in a new program.";
+/**
+ * A completed run that gave the agent nothing to read looks like nothing
+ * happened, and a write inside it is exactly what must not run again (INV-9).
+ * Fixed text only: attached after the envelope check, like the counters.
+ */
+function finishedRunNote(result, attempted, wrote, unawaited) {
+    if (result.isError)
+        return undefined;
+    if (unawaited)
+        return wrote ? `${UNAWAITED_HINT} ${SENT_NOTE}` : UNAWAITED_HINT;
+    const body = result.structuredContent;
+    if (body?.result !== undefined || body?.emitted !== undefined)
+        return undefined;
+    if (wrote)
+        return `Program returned nothing. ${SENT_NOTE}`;
+    return `Program returned nothing${attempted > 0 ? ", though its calls ran" : " and made no host calls"}. Add a return.`;
+}
 /** An execution that never produced an ExecuteResult, as the model sees it. */
 function failedRun(err, logger, { emitted, diagnostics, program }) {
     const logs = err !== null && typeof err === "object" && "logs" in err ? executeLogs(err.logs) : undefined;
@@ -1384,67 +1638,87 @@ function failureResponse(message, options) {
 function discardedEmits(emitted) {
     return emitted.blocks.length > 0 ? { emittedDiscarded: emitted.blocks.length } : {};
 }
-const inventoryWords = (text) => text
-    .toLowerCase()
-    .split(/[^\p{L}\p{N}]+/u)
-    .filter(Boolean);
-/** A title that only respells the id ("Google Calendar" for google_calendar) adds nothing. */
-function titleAddsInformation(id, title) {
-    const words = inventoryWords(title);
-    const idWords = inventoryWords(id);
-    return words.join("") !== idWords.join("") && words.some((word) => !idWords.includes(word));
-}
+/** Follows the inventory only when an entry shown carries the mark; `*` cannot appear in an id. */
+const REQUIRED_GUIDE_LEGEND = ' *Read connecta.skill("connector:<id>") before its first call.';
+/** Deployment configuration, normalized and capped like a title: a one-line purpose, never a paragraph. */
+const CONNECTOR_PURPOSE_MAX_BYTES = 57;
 /**
  * Every configured connector, from configuration alone. Detail degrades before
- * names do: titles go first, then optional guide pointers, and only past the
- * byte cap do whole entries give way to an exact omission count.
+ * names do: purposes go first, from the end of registry order, then titles, and
+ * only past the byte cap do whole entries give way to an exact omission count.
+ * Search and describe name optional guides.
  */
 function connectorInventory(connectors) {
     const prefix = "Connectors: ";
     if (connectors.length === 0)
         return `${prefix}none.`;
     const fits = (line) => boundedEchoText(line, CONNECTOR_INVENTORY_MAX_BYTES) === line;
-    const entry = (connector, detail) => {
-        const notes = [];
-        const title = connector.title?.replace(/\s+/g, " ").trim();
-        if (detail >= 2 && title && titleAddsInformation(connector.id, title))
-            notes.push(boundedEchoText(title, 45));
-        const required = connectorGuideRequired(connector);
-        if (connectorGuide(connector) && (required || detail >= 1)) {
-            const fetch = `skills({name:"${connectorSkillName(connector.id)}"})`;
-            notes.push(required ? `read first: ${fetch}` : `guide: ${fetch}`);
-        }
-        return notes.length > 0 ? `${connector.id} (${notes.join("; ")})` : connector.id;
+    const guideFirst = (connector) => connectorGuide(connector) !== undefined && connectorGuideRequired(connector);
+    const legend = (shown) => (shown.some(guideFirst) ? REQUIRED_GUIDE_LEGEND : "");
+    const entry = (connector, titled, withPurpose = false) => {
+        const name = guideFirst(connector) ? `${connector.id}*` : connector.id;
+        const title = titled ? connectorInventoryTitle(connector) : undefined;
+        const description = connector.description?.replace(/\s+/g, " ").trim().replace(/\.$/, "");
+        const shown = `${connector.id} ${connector.title?.replace(/\s+/g, " ").trim() ?? ""}`;
+        const purpose = withPurpose && description && addsInformation(shown, description)
+            ? inventoryNote(description, CONNECTOR_PURPOSE_MAX_BYTES)
+            : undefined;
+        const notes = [title, purpose].filter((note) => note !== undefined);
+        return notes.length > 0 ? `${name} (${notes.join("; ")})` : name;
     };
-    for (const detail of [2, 1, 0]) {
-        const line = `${prefix}${connectors.map((connector) => entry(connector, detail)).join(", ")}.`;
-        if (fits(line))
-            return line;
+    const described = (purposes) => `${prefix}${connectors.map((connector, index) => entry(connector, true, index < purposes)).join(", ")}.${legend(connectors)}`;
+    if (fits(described(0))) {
+        // The most entries, in registry order, whose purposes still fit.
+        let shown = 0;
+        let over = connectors.length + 1;
+        while (over - shown > 1) {
+            const middle = Math.floor((shown + over) / 2);
+            if (fits(described(middle)))
+                shown = middle;
+            else
+                over = middle;
+        }
+        return described(shown);
     }
-    const entries = connectors.map((connector) => entry(connector, 0));
+    const untitled = `${prefix}${connectors.map((connector) => entry(connector, false)).join(", ")}.${legend(connectors)}`;
+    if (fits(untitled))
+        return untitled;
+    const truncated = (shown) => {
+        const kept = connectors.slice(0, shown);
+        const names = kept.map((connector) => entry(connector, false)).join(", ");
+        return `${prefix}${names}${shown > 0 ? "; " : ""}+${connectors.length - shown} more.${legend(kept)}`;
+    };
     let shown = 0;
-    while (fits(`${prefix}${entries.slice(0, shown + 1).join(", ")}; +${entries.length - shown - 1} more.`))
+    while (fits(truncated(shown + 1)))
         shown++;
-    return `${prefix}${entries.slice(0, shown).join(", ")}${shown > 0 ? "; " : ""}+${entries.length - shown} more.`;
+    return truncated(shown);
 }
-const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, readOnly, native = false, routes = META_ROUTES) => `${native ? `Call tools directly; combine work here using their program addresses. ${readOnly ? "Read-only endpoint: writes are omitted and refused." : "Writable endpoint: programs may read and write; the client approves."}` : `${routes === routeNames("code") ? `Every operation uses ${routes.program}.` : readOnly ? `One known read: ${routes.read}. Everything else: ${routes.program}.` : `One known read: ${routes.read}. One known write: ${routes.write}. Everything else: ${routes.program}.`} ${readOnly ? "Read-only endpoint: search and describe omit write tools, and every write call is refused." : "Writable endpoint: programs may read and write; the client approves."}`} Limits: ${hostLimits.maxHostCalls} host calls, ${readOnly ? "" : `${maxWrites} writes, `}${hostLimits.callTimeoutMs === hostLimits.hostCallTimeoutMs ? `${hostLimits.callTimeoutMs / 1_000}s/host call` : `${hostLimits.callTimeoutMs / 1_000}s/call (${hostLimits.hostCallTimeoutMs / 1_000}s result/skill/read)`}.
+/**
+ * Short by design: Codex carries every description in each turn's tool list and
+ * `execute_code` already holds the full declaration. It still names the guest
+ * calls and the connectors, so a host that loads only this tool can write a
+ * program and tell similar connectors apart.
+ */
+const READ_PROGRAM_DESCRIPTION = (hostLimits, inventory) => `Run a read-only JavaScript program without write approval: same sandbox and connecta API as ${META_ROUTES.program}, ${hostLimits.maxHostCalls} host calls. Use it for read work at an unknown address, joins, loops and reductions. Each call that can write is refused before dispatch with its next step, and catching the refusal sends nothing. search and describe list those tools with callable: false; ${META_ROUTES.write} and ${META_ROUTES.program} run them. Use async () => { ... } with connecta.search({ query }), connecta.describe({ address }), connecta.call(address, args), connecta.result(resultId, { page }), and return the answer.
+${inventory}`;
+const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, readOnly, native = false, routes = META_ROUTES, readRoute = false) => `${native ? `Call tools directly; combine work here using their program addresses. ${readOnly ? "Read-only endpoint: writes are omitted and refused." : "Writable endpoint: programs may write; the host approves."}` : `${routes === routeNames("code") ? `Every operation uses ${routes.program}.` : readOnly ? `One known read: ${routes.read}. Everything else: ${routes.program}.` : readRoute ? `One known read: ${routes.read}. One known write: ${routes.write}. Read programs: ${READ_PROGRAM_SOURCE}. Other: ${routes.program}.` : `One known read: ${routes.read}. One known write: ${routes.write}. Everything else: ${routes.program}.`} ${readOnly ? "Read-only endpoint: search and describe omit write tools, and every write call is refused." : "Writable endpoint: programs may write; the host approves."}`} Limits: ${hostLimits.maxHostCalls} host calls, ${readOnly ? "" : `${maxWrites} writes, `}${hostLimits.callTimeoutMs === hostLimits.hostCallTimeoutMs ? `${hostLimits.callTimeoutMs / 1_000}s/host call` : `${hostLimits.callTimeoutMs / 1_000}s/call (${hostLimits.hostCallTimeoutMs / 1_000}s result/skill/read)`}${hostLimits.runDeadlineMs === undefined ? "" : `, ${hostLimits.runDeadlineMs / 1_000}s/run`}.
 ${connectorInventory(connectors)}
 
-Use async () => { ... }, no arguments. No portable ambient capabilities. API:
+Use async () => { ... }, no arguments. No imports, require, fetch, filesystem or timers. API:
 \`\`\`ts
 ${GUEST_API_DECLARATION}
 \`\`\`
-search and describe return objects, not arrays. Search shows a TypeScript signature by default; describe, JSON Schema. A call result over 1 MiB returns a paged handle; read it with connecta.result(handle, { offset }), which pages by UTF-8 byte offset. Every function except ${UNCOUNTED_GUEST_FUNCTIONS} spends a host call. Promise.allSettled keeps per-call errors, but exceeding the host-call limit ends the program. When paging is available, an oversized program return carries resultId and nextAction.
+search and describe return objects, not arrays.${connectorGuides ? " A row with guideRequired: read its connector guide first." : ""} Search shows a TypeScript signature by default; describe, JSON Schema. A call result over 1 MiB returns a paged handle: follow its hint. Every function except ${UNCOUNTED_GUEST_FUNCTIONS} spends a host call; over the limit the program returns nothing, even under Promise.allSettled. Near the host-call limit, return page.nextCursor to resume next program. An oversized return carries nextAction.
 
-Never repeat writes for output. emit(result) or emit(block) from result.content forwards MCP blocks unchanged; an authored Block's image/audio data is base64. emit needs no await. Caps: ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes. Text shares result cap. connecta.skill("usage"): repair${connectorGuides ? ", guide handling" : ""}.`;
+${readOnly ? "" : "Never repeat writes for output. "}emit(result) or emit(block) forwards MCP blocks; authored image/audio data is base64. Caps: ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; text shares the return cap. connecta.skill("usage"): repair.`;
 // Module scope, like the other five 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 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().describe("Add request-local, payload-free timing and result-size summaries."),
+        .describe("Source text of one zero-argument JavaScript async arrow: async () => { ...; return answer; }. Pass a string, even from a JavaScript host. Use the connecta global. At most 65,536 UTF-8 bytes."),
+    diagnostics: z.boolean().optional().describe("Add timing and result-size summaries."),
 }));
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(server, registry, ctx) {
@@ -1462,7 +1736,7 @@ export function registerExecuteTool(server, registry, ctx) {
     };
     const connectors = registry.listConnectors();
     const maxWrites = resolveBudget(ctx.maxWrites, DEFAULT_MAX_WRITES);
-    const execute = createExecuteTool(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, {
+    const runnerConfig = {
         defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
         discoveryConcurrency: ctx.discoveryConcurrency,
         probeTimeoutMs: ctx.probeTimeoutMs,
@@ -1476,23 +1750,11 @@ export function registerExecuteTool(server, registry, ctx) {
         maxWrites,
         maxResultChars: ctx.maxResultChars,
         requestScope: ctx.requestScope,
+        requestStartedAt: ctx.requestStartedAt,
         routes: ctx.routes,
-    });
-    server.registerTool("execute_code", {
-        description: executeDescription(emitBudgets, {
-            ...hostLimits,
-            // connecta.call falls back to calls.defaultTimeoutMs; result, skill and read always use hostCallTimeoutMs.
-            callTimeoutMs: normalizeTimeoutMs(ctx.defaultToolTimeoutMs) ?? hostLimits.hostCallTimeoutMs,
-        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.readOnly === true, ctx.native === true, ctx.routes),
-        inputSchema: EXECUTE_INPUT,
-        outputSchema: EXECUTE_OUTPUT,
-        // The client sees execute_code as a write exactly when the endpoint writes.
-        annotations: {
-            readOnlyHint: ctx.readOnly === true,
-            destructiveHint: ctx.readOnly !== true,
-            openWorldHint: true,
-        },
-    }, authMethod((args, extra) => Effect.gen(function* () {
+        ...(ctx.readRoute ? { followUpRoutes: routeNames("read-route") } : {}),
+    };
+    const programHandler = (execute, name) => (args, extra) => Effect.gen(function* () {
         if (ctx.client)
             bindMcpClient(extra, ctx.client, ctx.activity);
         const run = authMethod(() => Effect.suspend(() => {
@@ -1516,8 +1778,35 @@ export function registerExecuteTool(server, registry, ctx) {
             })));
         }));
         const result = yield* ctx.authElicitation
-            ? authInvoke(ctx.authElicitation, "run", ["execute_code", args, extra, run])
+            ? authInvoke(ctx.authElicitation, "run", [name, args, extra, run])
             : authCall(run, []);
         return ctx.native ? nativeRecovery(result) : result;
-    })));
+    });
+    const newRunner = (config) => createExecuteTool(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, config);
+    server.registerTool("execute_code", {
+        description: executeDescription(emitBudgets, {
+            ...hostLimits,
+            // connecta.call falls back to calls.defaultTimeoutMs; result, skill and read always use hostCallTimeoutMs.
+            callTimeoutMs: normalizeTimeoutMs(ctx.defaultToolTimeoutMs) ?? hostLimits.hostCallTimeoutMs,
+            ...(ctx.executor.deadlineMs !== undefined
+                ? { runDeadlineMs: Math.min(ctx.executor.deadlineMs, resolveBudget(ctx.watchdogMs, EXECUTE_WATCHDOG_MS)) }
+                : {}),
+        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.readOnly === true, ctx.native === true, ctx.routes, ctx.readRoute === true),
+        inputSchema: EXECUTE_INPUT,
+        outputSchema: EXECUTE_OUTPUT,
+        // The client sees execute_code as a write exactly when the endpoint writes.
+        annotations: {
+            readOnlyHint: ctx.readOnly === true,
+            destructiveHint: ctx.readOnly !== true,
+            openWorldHint: true,
+        },
+    }, authMethod(programHandler(newRunner(runnerConfig), "execute_code")));
+    if (ctx.readRoute) {
+        server.registerTool(READ_PROGRAM_SOURCE, {
+            description: READ_PROGRAM_DESCRIPTION(hostLimits, connectorInventory(connectors)),
+            inputSchema: EXECUTE_INPUT,
+            outputSchema: EXECUTE_OUTPUT,
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+        }, authMethod(programHandler(newRunner({ ...runnerConfig, readProgram: true, routes: routeNames("read-route") }), READ_PROGRAM_SOURCE)));
+    }
 }