@zackbart/connecta 0.24.4 → 0.26.0

package/dist/server.js

@@ -1,27 +1,155 @@
+import { Effect } from "effect";
 import { aggregateCallAdmissionSnapshots } from "./call-admission.js";
 import { isAdmittingExecutor } from "./executor-admission.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
 import { routeOAuthCallback, } from "./routes/oauth.js";
+import { runEdge } from "./runtime/run.js";
 import { withSecurityHeaders, } from "./routes/shared.js";
+const isArtifactPath = (path) => path === "/artifacts" || path.startsWith("/artifacts/");
 /**
  * Build the Web-standard fetch handler.
  *
  * Route ordering is the contract: private mutation routes precede wildcard
  * OPTIONS, and the security wrapper is applied to every response, including 404s.
+ *
+ * Each request is one fiber tied to `request.signal`: when its caller leaves,
+ * the request stops waiting on whatever it was waiting on, and what it holds
+ * is released (routes/mcp.ts). It runs on no Connecta runtime, because
+ * `/health` and a closed deployment's 503 must keep answering after
+ * `close()` has disposed that runtime.
  */
 export function createFetchHandler(opts) {
     const { auth, publicUrl, registry } = opts;
     const routeMcp = createMcpRoute(opts);
-    return async function fetch(request, runtimeContext) {
+    // The first provider's metadata answer for this request, if any has one.
+    const metadata = (request, baseUrl) => Effect.gen(function* () {
+        for (const provider of auth) {
+            const handleMetadata = provider.handleMetadata?.bind(provider);
+            if (handleMetadata) {
+                const response = yield* Effect.promise(async () => handleMetadata(request, baseUrl));
+                if (response)
+                    return response;
+            }
+        }
+        return null;
+    });
+    const health = async () => {
+        // The executor is required, so code admission always has a shape to
+        // report: either the executor's own pool or the fallback controller
+        // wrapped around it at construction.
+        const codeAdmission = isAdmittingExecutor(opts.executor)
+            ? opts.executor.admissionSnapshot?.()
+            : undefined;
+        return Response.json({
+            status: "ok",
+            connectors: registry.listConnectors().length,
+            server: opts.serverInfo,
+            // Which sandbox, not how it is tuned: `connecta doctor` reports the
+            // executor it just exercised rather than assuming one, and a
+            // deployment whose executor identifies as nothing omits the key
+            // instead of inviting a guess (#368).
+            ...(opts.executorName !== undefined
+                ? { executor: { name: opts.executorName } }
+                : {}),
+            // Whether a program's write pauses for resume_execution or fails E4.
+            // The tool is listed either way; this is the only place an operator
+            // can see which answer it gives (#565).
+            resumableWrites: opts.resumable !== undefined,
+            // Counts only, from refreshes that already happened — the endpoint
+            // asks no downstream anything, and `connecta doctor` reads it to
+            // report a stale allowlist without a probe of its own (#343).
+            // Stable 64-bit hashes preserve that shape without publishing ids.
+            catalogDrift: Object.fromEntries(await Promise.all(Object.entries(registry.catalogDriftSnapshot()).map(async ([id, report]) => {
+                const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(id)));
+                const key = Array.from(hash.subarray(0, 8), byte => byte.toString(16).padStart(2, "0")).join("");
+                return [key, report];
+            }))),
+            admission: {
+                policy: "global-fifo",
+                requests: opts.requestAdmission.snapshot(),
+                code: codeAdmission ?? { managedByExecutor: true },
+                downstreamCalls: {
+                    policy: "connector-partitioned-per-runtime",
+                    aggregate: aggregateCallAdmissionSnapshots(Object.values(registry.callAdmissionSnapshot())),
+                },
+                reservedRoutes: [
+                    "/health",
+                    ...(opts.ui?.reservedPaths ?? []),
+                    ...(opts.ui && opts.activity?.list ? ["/activity"] : []),
+                    ...(opts.ui && opts.artifactsModule ? ["/artifacts", "/artifacts/*"] : []),
+                ],
+            },
+            ...(opts.deploymentInfo ? { deployment: opts.deploymentInfo } : {}),
+        });
+    };
+    const route = (context) => Effect.gen(function* () {
+        const { request, path, baseUrl } = context;
+        // Private mutations own OPTIONS so they never inherit wildcard CORS.
+        const ui = opts.ui;
+        if (ui) {
+            const uiResponse = yield* Effect.promise(() => ui.handle(context));
+            if (uiResponse)
+                return uiResponse;
+        }
+        if (request.method === "OPTIONS") {
+            const preflight = yield* routeMcp.handle(context);
+            if (preflight)
+                return preflight;
+            const response = yield* metadata(request, baseUrl);
+            if (response)
+                return response;
+            return new Response(null, {
+                status: 204,
+                headers: MCP_CORS_HEADERS,
+            });
+        }
+        if (path.startsWith("/.well-known/")) {
+            const response = yield* metadata(request, baseUrl);
+            if (response)
+                return response;
+            return new Response("Not Found", { status: 404 });
+        }
+        if (path === "/health")
+            return yield* Effect.promise(health);
+        const oauthCallback = yield* routeOAuthCallback(context);
+        if (oauthCallback)
+            return oauthCallback;
+        const mcp = yield* routeMcp.handle(context);
+        if (mcp)
+            return mcp;
+        return new Response("Not Found", { status: 404 });
+    });
+    const serve = (request, runtimeContext) => Effect.suspend(() => {
         const url = new URL(request.url);
         const baseUrl = publicUrl ?? url.origin;
         const path = url.pathname;
         const defer = runtimeContext
             ? runtimeContext.waitUntil.bind(runtimeContext)
             : undefined;
+        // The artifact hostname has no MCP, health, OAuth, or operator routes.
+        // Dispatch before MCP origin checks so even a hostile /mcp is a plain 404.
+        if (opts.artifactOrigin && url.origin === new URL(opts.artifactOrigin).origin) {
+            if (!isArtifactPath(path) || !opts.ui || !opts.artifactsModule) {
+                return Effect.succeed(withSecurityHeaders(new Response("Not Found", { status: 404 }), url, path));
+            }
+            const context = {
+                request, url, path, baseUrl: opts.artifactOrigin, opts, defer, runtimeContext,
+            };
+            return Effect.map(Effect.promise(() => opts.ui.handle(context)), response => withSecurityHeaders(response ?? new Response("Not Found", { status: 404 }), url, path));
+        }
+        if (opts.artifactOrigin && isArtifactPath(path) && opts.ui && opts.artifactsModule) {
+            const target = new URL(opts.artifactOrigin);
+            target.pathname = path;
+            target.search = url.search;
+            return Effect.succeed(withSecurityHeaders(new Response(null, {
+                status: 308,
+                headers: { Location: target.toString() },
+            }), url, path));
+        }
         const originRefusal = routeMcp.rejectOrigin(request);
-        if (originRefusal)
-            return withSecurityHeaders(originRefusal, url, path);
+        if (originRefusal) {
+            return Effect.succeed(withSecurityHeaders(originRefusal, url, path));
+        }
         // Container and orchestrator probes reach /health over plain HTTP on
         // loopback, where no proxy has set X-Forwarded-Proto. Redirecting them to
         // the public origin would make an internal liveness check depend on
@@ -43,10 +171,10 @@ export function createFetchHandler(opts) {
             target.pathname = path === "/ui" ? "/" : url.pathname;
             target.search = url.search;
             target.hash = "";
-            return withSecurityHeaders(new Response(null, {
+            return Effect.succeed(withSecurityHeaders(new Response(null, {
                 status: 308,
                 headers: { Location: target.toString() },
-            }), url, path);
+            }), url, path));
         }
         const context = {
             request,
@@ -57,89 +185,9 @@ export function createFetchHandler(opts) {
             defer,
             runtimeContext,
         };
-        const route = async () => {
-            // Private mutations own OPTIONS so they never inherit wildcard CORS.
-            const uiResponse = await opts.ui?.handle(context);
-            if (uiResponse)
-                return uiResponse;
-            if (request.method === "OPTIONS") {
-                const preflight = await routeMcp.handle(context);
-                if (preflight)
-                    return preflight;
-                for (const provider of auth) {
-                    if (provider.handleMetadata) {
-                        const response = await provider.handleMetadata(request, baseUrl);
-                        if (response)
-                            return response;
-                    }
-                }
-                return new Response(null, {
-                    status: 204,
-                    headers: MCP_CORS_HEADERS,
-                });
-            }
-            if (path.startsWith("/.well-known/")) {
-                for (const provider of auth) {
-                    if (provider.handleMetadata) {
-                        const response = await provider.handleMetadata(request, baseUrl);
-                        if (response)
-                            return response;
-                    }
-                }
-                return new Response("Not Found", { status: 404 });
-            }
-            if (path === "/health") {
-                // The executor is required, so code admission always has a shape to
-                // report: either the executor's own pool or the fallback controller
-                // wrapped around it at construction.
-                const codeAdmission = isAdmittingExecutor(opts.executor)
-                    ? opts.executor.admissionSnapshot?.()
-                    : undefined;
-                return Response.json({
-                    status: "ok",
-                    connectors: registry.listConnectors().length,
-                    server: opts.serverInfo,
-                    // Which sandbox, not how it is tuned: `connecta doctor` reports the
-                    // executor it just exercised rather than assuming one, and a
-                    // deployment whose executor identifies as nothing omits the key
-                    // instead of inviting a guess (#368).
-                    ...(opts.executorName !== undefined
-                        ? { executor: { name: opts.executorName } }
-                        : {}),
-                    // Counts only, from refreshes that already happened — the endpoint
-                    // asks no downstream anything, and `connecta doctor` reads it to
-                    // report a stale allowlist without a probe of its own (#343).
-                    // Stable 64-bit hashes preserve that shape without publishing ids.
-                    catalogDrift: Object.fromEntries(await Promise.all(Object.entries(registry.catalogDriftSnapshot()).map(async ([id, report]) => {
-                        const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(id)));
-                        const key = Array.from(hash.subarray(0, 8), byte => byte.toString(16).padStart(2, "0")).join("");
-                        return [key, report];
-                    }))),
-                    admission: {
-                        policy: "global-fifo",
-                        requests: opts.requestAdmission.snapshot(),
-                        code: codeAdmission ?? { managedByExecutor: true },
-                        downstreamCalls: {
-                            policy: "connector-partitioned-per-runtime",
-                            aggregate: aggregateCallAdmissionSnapshots(Object.values(registry.callAdmissionSnapshot())),
-                        },
-                        reservedRoutes: [
-                            "/health",
-                            ...(opts.ui?.reservedPaths ?? []),
-                            ...(opts.ui && opts.activity?.list ? ["/activity"] : []),
-                        ],
-                    },
-                    ...(opts.deploymentInfo ? { deployment: opts.deploymentInfo } : {}),
-                });
-            }
-            const oauthCallback = await routeOAuthCallback(context);
-            if (oauthCallback)
-                return oauthCallback;
-            const mcp = await routeMcp.handle(context);
-            if (mcp)
-                return mcp;
-            return new Response("Not Found", { status: 404 });
-        };
-        return withSecurityHeaders(await route(), url, path);
+        return Effect.map(route(context), (response) => withSecurityHeaders(response, url, path));
+    });
+    return function fetch(request, runtimeContext) {
+        return runEdge(serve(request, runtimeContext), { signal: request.signal });
     };
 }

package/dist/skills.js

@@ -1,10 +1,24 @@
 import { boundedEchoText } from "./errors.js";
-export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
+const ROUTE = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding.";
+const RECOVERY = 'After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
+/**
+ * The MCP instructions of a deployment whose programs pause at writes. The
+ * route sentence is its own, not ROUTE's: with writes in programs, "one known
+ * write" is the only work left for call_destructive_tool, and an agent told
+ * only that programs *may* write reads each write after a lookup as a known
+ * one and sends them one prompt at a time.
+ */
+export const CONNECTA_INSTRUCTIONS = `Choose a route before discovery. A known-address read needs only call_tool; one known write, call_destructive_tool. Everything else starts with execute_code to discover, call, and return the answer: unknown addresses, reduction, multiple or dependent calls, loops, joins, branches, and writes that follow reads. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. A program's call to a tool not annotated readOnlyHint: true pauses unsent; resume_execution with the returned token, address, and args approves it and continues the program (approval "tool" covers that tool for the run). Keep catalog inspection top level with search_tools. ${RECOVERY}`;
+/**
+ * The instructions of a deployment without resumable writes, whose programs
+ * refuse every write: the routing it always had.
+ */
+export const READ_ONLY_PROGRAM_INSTRUCTIONS = `${ROUTE} Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. ${RECOVERY}`;
 const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
-Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Read-only discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
+Eight tools: \`execute_code\`, \`resume_execution\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
 
 Follow the MCP instructions for routing. Read at most once for syntax or repair.
 
@@ -25,7 +39,7 @@ Search and call in one run when schemas suffice. For unfamiliar result formats,
 
 For top-level catalog inspection or approval-required discovery, omit \`limit\` initially (the default is 8), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An \`outputSchemaSource: "observed"\` shape is a hint, not a contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
 
-- \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for program calls. These inputs filter discovery; they grant no authority.
+- \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for reads. These inputs filter discovery; they grant no authority.
 - Use \`includeSchemas: "json"\` for programmatic schema inspection; compact schemas are text, not objects with \`.properties\`. Check connectorTitle for the account/environment, then address, purpose, annotations, inputs, and outputs. Never select only because a result ranks first or has fewer required inputs.
 - Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
 - Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
@@ -34,27 +48,32 @@ For top-level catalog inspection or approval-required discovery, omit \`limit\`
 - Preserve the schema's JSON types exactly: a numeric id is a number, not a numeric-looking string.
 - Validate tabular headers, row arrays, and row widths before mapping them. Never let a header or partial row become data.
 
-Only tools explicitly annotated \`readOnlyHint: true\` are reachable. The catalog, credential, admission, and read-only gates run below the sandbox; code cannot widen its authority.
+Only tools explicitly annotated \`readOnlyHint: true\` are reachable unasked. Where the MCP instructions say programs pause, any other call pauses unsent and \`execute_code\` returns \`paused\` with the write and a token; repeat all three unchanged in top-level \`resume_execution\` to approve (\`approval: "tool"\` covers that tool for the run). Replay reruns the program against a journal: make the same calls in the same order. The catalog, credential, admission, and approval gates run below the sandbox; code cannot widen its authority.
 
 ## Errors and repair
 
 Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`details\`. Promise rejections retain these fields. Branch on fields, never prose. After a shared argument failure, repair one call before repeating it across other records. Do not retry \`retryable: false\`, and do not retry \`rate_limited\` immediately because portable code has no timer.
 
-- \`destructive_tool_requires_approval\`: stop the program and use the returned canonical address with top-level \`call_destructive_tool\`.
+- \`destructive_tool_requires_approval\`: stop and send the returned address through top-level \`call_destructive_tool\`.
+- \`execution_paused\`: the run already stopped at a write; let it end.
+- \`write_outcome_unknown\`: sent but unanswered, never re-sent; check the target.
+- \`execution_expired\`, \`_diverged\`, \`_interrupted\`: check \`writes\`, then rerun.
 - \`auth_required\`: let the failure reach the model, then use top-level \`authorize_connector\`, give its handoff to the operator, and retry after recovery.
 - A truncated direct-call result: follow its \`get_result\` action. A truncated program result has no page handle; filter, map, or slice inside a new program.
 - Unknown addresses and tools carry scoped search recovery. Use it inside the current run. Do not invent an address.
 
 For a direct call, \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. Every call makes one attempt; use the returned error classification and retry hint to decide whether to reissue. \`diagnostics: true\` adds timing.
 
-\`get_result({ id, offset?, maxBytes? })\` returns \`{ text, offset, nextOffset?, totalBytes }\` for a direct-call result. Both sizes are byte counts: \`maxBytes\` must be a whole number at least 1 and defaults to the deployment cap; \`offset\` must be a whole number at least 0 and defaults to 0. An offset inside a multi-byte character moves back to its first byte, and the response reports the served offset. Follow \`nextOffset\` to reassemble pages. An unknown or expired id is an error.
+\`get_result({ id, offset?, maxBytes? })\` returns a one-line JSON header \`{ resultId, offset, bytes, totalBytes, hasMore, nextAction? }\`, a newline, and then the page as raw text, for a direct-call result. Both sizes are byte counts: \`maxBytes\` must be a whole number at least 1, defaults to the result's cap, and is clamped to it; \`offset\` must be a whole number at least 0 and defaults to 0. An offset inside a multi-byte character moves back to its first byte, and the header reports the served offset. Follow \`nextAction\` until \`hasMore\` is false to reassemble pages. An unknown or expired id is an error.
 
-Limits: 20 host calls per run and a 15-second deadline per host call.
+The \`execute_code\` description states this deployment's host-call and write budgets and per-call deadline.
 
 ## Runtime portability
 
 Portable code uses standard JavaScript builtins, \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch, process, timers, crypto, and WebSocket. Dynamic Workers must use only \`{ loader }\`; bindings, modules, or globalOutbound grant ambient authority. With loader only, environment maps are empty; node:fs/http/https are absent; outbound fetch, WebSocket, node:net, and node:tls are denied; DNS is unresolved. Runtime builtins remain through \`import()\` and \`process.getBuiltinModule()\`, including node:path and cloudflare:workers; this set can drift. Timers, process, crypto, WebSocket, and data: fetch remain. Avoid every runtime-only capability because QuickJS fails.
 
+\`Date.now()\` is the run's start and does not advance; \`Math.random()\` is seeded per run.
+
 ## Examples
 
 One read-only call at a known address:
@@ -95,8 +114,8 @@ Connector guides appear in \`skills({})\` and discovery with an exact \`guide\`
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
 /** The always-loaded MCP `instructions` string. */
-export function instructionsFor() {
-    return CONNECTA_INSTRUCTIONS;
+export function instructionsFor(resumableWrites) {
+    return resumableWrites ? CONNECTA_INSTRUCTIONS : READ_ONLY_PROGRAM_INSTRUCTIONS;
 }
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {

package/dist/storage/file.js

@@ -259,8 +259,9 @@ export function fileStorage(path, opts = {}) {
             throw new Error(`[connecta] state file ${path} is closed.`);
     };
     const logger = opts.logger ?? console;
-    // The state file holds downstream OAuth access/refresh tokens in cleartext,
-    // so keep it owner-only. Repair is best-effort: chmod is a no-op or throws on
+    // With a sealing vault, downstream OAuth tokens here are ciphertext; without
+    // one they are cleartext, and OAuth flow state is plaintext either way. Keep
+    // the file owner-only regardless. Repair is best-effort: chmod is a no-op or throws on
     // non-POSIX filesystems, and a loose mode must never keep the store from
     // starting.
     const tighten = () => {
@@ -377,5 +378,41 @@ export function fileStorage(path, opts = {}) {
                 .filter((key) => Boolean(fresh(key)) && key.startsWith(prefix))
                 .sort();
         },
+        // Atomic twice over: the lock makes this process the only writer of the
+        // file, and nothing between the comparison and the persisted rename
+        // yields, so no other call on this store can interleave. A write that
+        // cannot be persisted is rolled back so memory never claims a value the
+        // file does not hold.
+        async compareAndSet(key, expected, next, opts) {
+            assertOpen();
+            lock.assertHeld();
+            const previous = fresh(key);
+            if ((previous?.value ?? null) !== expected)
+                return false;
+            if (next === null) {
+                if (!previous)
+                    return true;
+                delete data[key];
+            }
+            else {
+                data[key] = {
+                    value: next,
+                    ...(opts?.ttlSeconds
+                        ? { exp: Date.now() + opts.ttlSeconds * 1000 }
+                        : {}),
+                };
+            }
+            try {
+                persist();
+            }
+            catch (error) {
+                if (previous)
+                    data[key] = previous;
+                else
+                    delete data[key];
+                throw error;
+            }
+            return true;
+        },
     };
 }

package/dist/storage/memory.js

@@ -12,27 +12,28 @@ export function memoryStorage() {
         }
         return e;
     };
+    const write = (key, value, ttlSeconds) => {
+        // Rotate through at most 16 existing keys. Live entries cannot keep an
+        // expired tail resident forever, and no request starts a background job.
+        for (let i = 0; i < 16; i++) {
+            const next = sweep.next();
+            if (next.done) {
+                sweep = map.keys();
+                break;
+            }
+            fresh(next.value);
+        }
+        map.set(key, {
+            value,
+            ...(ttlSeconds ? { exp: Date.now() + ttlSeconds * 1000 } : {}),
+        });
+    };
     return {
         async get(key) {
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
-            // Rotate through at most 16 existing keys. Live entries cannot keep an
-            // expired tail resident forever, and no request starts a background job.
-            for (let i = 0; i < 16; i++) {
-                const next = sweep.next();
-                if (next.done) {
-                    sweep = map.keys();
-                    break;
-                }
-                fresh(next.value);
-            }
-            map.set(key, {
-                value,
-                ...(opts?.ttlSeconds
-                    ? { exp: Date.now() + opts.ttlSeconds * 1000 }
-                    : {}),
-            });
+            write(key, value, opts?.ttlSeconds);
         },
         async delete(key) {
             map.delete(key);
@@ -45,5 +46,16 @@ export function memoryStorage() {
             })
                 .sort();
         },
+        // Atomic because nothing between the read and the write yields: the body
+        // runs to completion before any other call on this map can start.
+        async compareAndSet(key, expected, next, opts) {
+            if ((fresh(key)?.value ?? null) !== expected)
+                return false;
+            if (next === null)
+                map.delete(key);
+            else
+                write(key, next, opts?.ttlSeconds);
+            return true;
+        },
     };
 }

package/dist/timeout.js

@@ -1,5 +1,7 @@
 // The deadline vocabulary shared by downstream discovery probes and tool calls.
 // One definition keeps those waits bounded consistently.
+import { Effect } from "effect";
+import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 /**
  * Generous default bound for a single downstream probe/catalog call. High enough
  * to trip only on a pathological hang, not a realistically slow probe.
@@ -12,54 +14,48 @@ export function normalizeTimeoutMs(value) {
     }
     return Math.max(1, Math.trunc(value));
 }
-/** Resolve after `ms`, or false when the caller aborts first. */
-export function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", cancel);
-            resolve(value);
-        };
-        const timer = setTimeout(() => finish(true), ms);
-        const cancel = () => finish(false);
-        signal?.addEventListener("abort", cancel, { once: true });
-        if (signal?.aborted)
-            cancel();
-    });
-}
+/**
+ * Run one operation under a deadline and the caller's signal, whichever ends
+ * it first.
+ *
+ * The operation gets a signal of its own: the caller's abort is forwarded to
+ * it, and the deadline aborts it with `timeoutError`. Either way the promise
+ * rejects with that signal's reason, without waiting for work that ignores
+ * the signal. A synchronous throw rejects like an asynchronous one. This is
+ * the Promise face of `withDeadlineEffect` (src/runtime/run.ts), which owns
+ * the contract; an Effect caller uses that directly.
+ */
 export function withDeadline(operation, options) {
+    return runEdge(withDeadlineEffect((signal) => Effect.tryPromise({
+        try: () => operation(signal),
+        catch: (error) => error,
+    }), options));
+}
+/**
+ * Run `operation` under one signal that aborts when any of `signals` does —
+ * the MCP call's own and the inbound request's, for the program tools — and
+ * detach every listener afterwards, however it ends.
+ */
+export async function underAnySignal(signals, operation) {
     const controller = new AbortController();
-    const forwardAbort = () => controller.abort(options.signal?.reason);
-    options.signal?.addEventListener("abort", forwardAbort, { once: true });
-    if (options.signal?.aborted)
-        forwardAbort();
-    let rejectAbort;
-    const aborted = new Promise((_, reject) => { rejectAbort = reject; });
-    const onAbort = () => rejectAbort(controller.signal.reason ?? options.timeoutError);
-    controller.signal.addEventListener("abort", onAbort, { once: true });
-    if (controller.signal.aborted)
-        onAbort();
-    const timer = options.timeoutMs === undefined
-        ? undefined
-        : setTimeout(() => controller.abort(options.timeoutError), options.timeoutMs);
-    let work;
+    const forwarders = signals
+        .filter((signal) => signal !== undefined)
+        .map((signal) => {
+        const forward = () => controller.abort(signal.reason);
+        if (signal.aborted)
+            forward();
+        else
+            signal.addEventListener("abort", forward, { once: true });
+        return { signal, forward };
+    });
     try {
-        work = operation(controller.signal);
+        return await operation(controller.signal);
     }
-    catch (error) {
-        work = Promise.reject(error);
+    finally {
+        for (const { signal, forward } of forwarders) {
+            signal.removeEventListener("abort", forward);
+        }
     }
-    return Promise.race([work, aborted]).finally(() => {
-        controller.abort();
-        if (timer)
-            clearTimeout(timer);
-        controller.signal.removeEventListener("abort", onAbort);
-        options.signal?.removeEventListener("abort", forwardAbort);
-    });
 }
 /**
  * Give one operation a caller-facing deadline and the matching cancellation

package/dist/tool-safety.d.ts

@@ -1,4 +1,4 @@
-import type { ToolDef } from "./types.js";
+import type { Connector, ToolDef } from "./types.js";
 /**
  * The one fail-closed classification shared by discovery and invocation.
  *
@@ -7,3 +7,29 @@ import type { ToolDef } from "./types.js";
  * approval-visible call path.
  */
 export declare function isExplicitlyReadOnly(definition: ToolDef): boolean;
+/**
+ * A deployment's approval exemptions, resolved once at construction from
+ * `execute.approval` (#566). Config is the only source: nothing an agent, the
+ * operator UI, or a downstream catalog says can add an entry.
+ */
+export interface ApprovalPolicy {
+    /** Connector id → the default for that connector's tools. */
+    readonly connectors: ReadonlyMap<string, "never" | "ask">;
+    /** Canonical `connector.tool` address → that tool's own setting. */
+    readonly tools: ReadonlyMap<string, "never" | "ask">;
+}
+export declare const NO_EXEMPTIONS: ApprovalPolicy;
+/**
+ * Whether a program may call this tool without pausing for approval.
+ *
+ * Only a tool that is *not* explicitly read-only can be exempt — a read-only
+ * tool needs no exemption, and reporting one would blur the two classes an
+ * exemption must never merge. The most specific setting wins: the tool's
+ * address, then its connector's entry, then the connector's own default,
+ * then `"ask"`. Annotations play no part beyond that first test: a downstream
+ * that could annotate its way out of approval would be granting itself the
+ * capability this exists to keep in config. Exempt never means read-only:
+ * discovery keeps it in the approval-required class, and `call_tool` still
+ * refuses it.
+ */
+export declare function isApprovalExempt(policy: ApprovalPolicy, connector: Pick<Connector, "id" | "approval">, toolName: string, definition: ToolDef): boolean;

package/dist/tool-safety.js

@@ -9,3 +9,34 @@ export function isExplicitlyReadOnly(definition) {
     return (definition.annotations?.readOnlyHint === true &&
         definition.annotations?.destructiveHint !== true);
 }
+export const NO_EXEMPTIONS = {
+    connectors: new Map(),
+    tools: new Map(),
+};
+/**
+ * Whether a program may call this tool without pausing for approval.
+ *
+ * Only a tool that is *not* explicitly read-only can be exempt — a read-only
+ * tool needs no exemption, and reporting one would blur the two classes an
+ * exemption must never merge. The most specific setting wins: the tool's
+ * address, then its connector's entry, then the connector's own default,
+ * then `"ask"`. Annotations play no part beyond that first test: a downstream
+ * that could annotate its way out of approval would be granting itself the
+ * capability this exists to keep in config. Exempt never means read-only:
+ * discovery keeps it in the approval-required class, and `call_tool` still
+ * refuses it.
+ */
+export function isApprovalExempt(policy, connector, toolName, definition) {
+    if (isExplicitlyReadOnly(definition))
+        return false;
+    // This tool starts another program. Letting a program call it while holding
+    // the only executor permit would deadlock; manual refresh is a top-level
+    // action, even though other artifact writes are exempt inside programs.
+    if (connector.id === "artifacts" && toolName === "run_refresh")
+        return false;
+    const setting = policy.tools.get(`${connector.id}.${toolName}`) ??
+        policy.connectors.get(connector.id) ??
+        connector.approval ??
+        "ask";
+    return setting === "never";
+}