@zackbart/connecta 0.25.0 → 0.26.1

package/dist/run-journal.js

@@ -0,0 +1,347 @@
+// The paused-run journal: layout, tokens, and the storage it lives in.
+//
+// A paused `execute_code` run is not a held program. It is data — the
+// program's source, every host call it made and what each returned, and one
+// header that says where the run stands — written to the same subject-
+// partitioned storage the result stash uses, at the same trust level, and
+// expiring on its own. Resuming replays the program from the top against
+// those records. Nothing request-bound is in here: a journal is data, not a
+// request (ethos, "Nothing request-bound survives a request").
+//
+// Web-API only, like everything reachable from the root entry.
+import { withDeadline } from "./timeout.js";
+/** Entry chunks are the result stash's size (`RESULT_CHUNK_BYTES`), in characters. */
+const JOURNAL_CHUNK_CHARS = 49_152;
+/**
+ * The most one run may journal: its source plus every recorded host call.
+ * Internal rather than configurable — it bounds what one caller can park in
+ * shared storage for half an hour, and nothing about a deployment makes a
+ * larger notebook the right answer. L6 bounds each host call's result at 256
+ * KiB on QuickJS, so a run near the host-call budget can reach it.
+ */
+export const MAX_JOURNAL_BYTES = 4 * 1024 * 1024;
+/**
+ * The largest pending write a pause will hold, serialized. The arguments are
+ * echoed whole in the pause result and must be repeated whole to resume, so
+ * this is a bound on what a human is asked to read in a prompt, not a storage
+ * limit. A bigger write goes through `call_destructive_tool`.
+ */
+export const MAX_PENDING_ARGS_BYTES = 16 * 1024;
+/** How long an ended run keeps its answer for a repeated resume, in ms. */
+const FINAL_HOLD_MS = 30 * 60 * 1_000;
+/** A completed run keeps at most this much of its answer for a retried resume. */
+export const MAX_FINAL_CHARS = 24_000;
+const encoder = new TextEncoder();
+export function utf8Bytes(text) {
+    return encoder.encode(text).byteLength;
+}
+/**
+ * JSON with object keys sorted at every depth, so two argument objects that
+ * differ only in key order serialize identically. Arrays keep their order and
+ * a type change is a different string: `1` and `"1"` never match.
+ *
+ * Written out directly rather than by building sorted objects and handing
+ * them to `JSON.stringify`: assigning an own `__proto__` key onto a plain
+ * object sets its prototype instead, so a key that `JSON.parse` kept would
+ * vanish from the canonical form, and two different writes would compare
+ * equal.
+ */
+export function canonicalJson(value) {
+    return canonical(value) ?? "null";
+}
+function canonical(input) {
+    let value = input;
+    if (value !== null &&
+        typeof value === "object" &&
+        typeof value.toJSON === "function") {
+        value = value.toJSON();
+    }
+    // Boxed primitives serialize as their value, as JSON.stringify has them.
+    if (value instanceof Number ||
+        value instanceof String ||
+        value instanceof Boolean) {
+        value = value.valueOf();
+    }
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        // Indexed, not mapped: `map` skips a hole, and JSON has none — a hole is
+        // `null`, as JSON.stringify writes it.
+        const items = [];
+        for (let index = 0; index < value.length; index++) {
+            items.push(canonical(value[index]) ?? "null");
+        }
+        return `[${items.join(",")}]`;
+    }
+    const parts = [];
+    for (const key of Object.keys(value).sort()) {
+        const item = canonical(value[key]);
+        if (item !== undefined)
+            parts.push(`${JSON.stringify(key)}:${item}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+/** Whether a `__proto__` key appears anywhere in a JSON value. */
+export function hasProtoKey(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return value.some(hasProtoKey);
+    return Object.keys(value).some((key) => key === "__proto__" ||
+        hasProtoKey(value[key]));
+}
+/**
+ * How a replayed host call finds its record: the operation, the address as
+ * the program wrote it, and its canonical arguments. Several calls may share a
+ * key; they answer in the order they were first issued.
+ */
+export function journalKey(op, address, args) {
+    return `${op}\n${address}\n${canonicalJson(args ?? {})}`;
+}
+const TOKEN_RE = /^r1\.([0-9a-f]{32})\.([0-9a-f]{32})\.(\d{1,15})$/;
+export function formatToken(token) {
+    return `r1.${token.runId}.${token.nonce}.${token.expiresAt}`;
+}
+export function parseToken(value) {
+    const match = TOKEN_RE.exec(value);
+    if (!match)
+        return undefined;
+    return {
+        runId: match[1] ?? "",
+        nonce: match[2] ?? "",
+        expiresAt: Number(match[3]),
+    };
+}
+/** 128 random bits as hex: a run id, a pause nonce, or a claim id. */
+export function randomId() {
+    const words = new Uint32Array(4);
+    crypto.getRandomValues(words);
+    return Array.from(words, (word) => word.toString(16).padStart(8, "0")).join("");
+}
+export async function sha256Hex(text) {
+    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Whether a consequential call landed, as far as anyone can know.
+ *
+ * `unknown` is the one outcome replay must never paper over: the call left
+ * connecta and no answer came back, so sending it again could do it twice and
+ * not sending it could leave it undone. That is a dispatched call that timed
+ * out, was cancelled, found the service unavailable, or failed any way that
+ * is not a verdict. A refusal code (`REFUSALS`) or a downstream tool's own
+ * `isError` is an answer, so it is `failed`, except that an `isError` whose text
+ * classifies as a timeout is a gateway reporting that it gave up, and stays
+ * unknown. A call that was never dispatched is `failed`: nothing was sent.
+ * `result_processing_failed` means the downstream call completed.
+ */
+export function classifyWriteOutcome(outcome) {
+    if (outcome.ok)
+        return "ok";
+    if (!outcome.dispatched)
+        return "failed";
+    const code = outcome.error?.code;
+    if (code === "result_processing_failed")
+        return "ok";
+    if (code === "timeout" || code === "cancelled" || code === "unavailable") {
+        return "unknown";
+    }
+    if (code !== undefined && REFUSALS.has(code))
+        return "failed";
+    return outcome.answered === true ? "failed" : "unknown";
+}
+/**
+ * Codes that say the other side refused the call rather than acted on it:
+ * the credential, the arguments, the resource, the rate, or a base version
+ * someone else already moved past (`conflict`). Anything else a
+ * connector reports after dispatch — `connector_call_failed` from a response
+ * too large to read, a redirect it would not follow, a body it could not
+ * parse, a 5xx — may come after the write landed, so only a downstream
+ * tool's own `isError` answer makes it a known failure.
+ */
+const REFUSALS = new Set([
+    "auth_required",
+    "invalid_args",
+    "not_found",
+    "rate_limited",
+    "input_required_unsupported",
+    "conflict",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** A header read back from storage, or undefined when it is not one. */
+function parseHeader(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value) ||
+        value.v !== 1 ||
+        !["paused", "running", "completed", "failed"].includes(String(value.state)) ||
+        typeof value.nonce !== "string" ||
+        typeof value.expiresAt !== "number" ||
+        typeof value.clock !== "number" ||
+        !Array.isArray(value.seed) ||
+        value.seed.length !== 4 ||
+        !Array.isArray(value.approvals) ||
+        !Array.isArray(value.writes) ||
+        typeof value.entries !== "number" ||
+        typeof value.bytes !== "number" ||
+        typeof value.playFrom !== "number" ||
+        typeof value.programHash !== "string") {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * One run's keys inside the caller's result storage.
+ *
+ * `run:<id>` is the header and the only key ever compare-and-set.
+ * `run:<id>:src` is the program, written once. `run:<id>:e:<n>` is entry `n`,
+ * split into `#<k>` continuation keys past one chunk, written before the
+ * header that counts it. Every key expires with the run.
+ *
+ * Every storage call here answers within `timeoutMs` or rejects, as a
+ * failing store would: a play reserving or settling a write cannot be
+ * interrupted, and a store that never answers must not hold it — or the
+ * request waiting on it — forever. A write that timed out may still land;
+ * each caller treats the call as failed, and every write here is one that is
+ * safe to find landed later (a compare-and-set that landed after all only
+ * makes the next one lose).
+ */
+export class RunJournal {
+    storage;
+    runId;
+    timeoutMs;
+    constructor(storage, runId, timeoutMs) {
+        this.storage = storage;
+        this.runId = runId;
+        this.timeoutMs = timeoutMs;
+    }
+    bounded(operation) {
+        if (this.timeoutMs === undefined)
+            return operation();
+        return withDeadline(() => operation(), {
+            timeoutMs: this.timeoutMs,
+            timeoutError: new Error(`paused-run storage did not answer within ${this.timeoutMs}ms`),
+        });
+    }
+    get headerKey() {
+        return `run:${this.runId}`;
+    }
+    /** Seconds until `expiresAt`, never less than one. */
+    static ttlSeconds(expiresAt, now = Date.now()) {
+        return Math.max(1, Math.ceil((expiresAt - now) / 1_000));
+    }
+    async readHeader() {
+        const raw = await this.bounded(() => this.storage.get(this.headerKey));
+        if (raw === null)
+            return undefined;
+        const header = parseHeader(raw);
+        return header ? { raw, header } : undefined;
+    }
+    /**
+     * Write `next` only if the header is still exactly `expected` (`null`:
+     * absent). Returns the stored string on success, `undefined` when another
+     * writer got there first.
+     */
+    async casHeader(expected, next) {
+        const cas = this.storage.compareAndSet;
+        if (!cas)
+            throw new Error("resumable writes need KVStorage.compareAndSet");
+        const raw = JSON.stringify(next);
+        // The header outlives `expiresAt` while a claim is live, so a play that
+        // runs past it can still record what it sent, and after the run ends, so
+        // a repeated resume gets the same answer rather than "expired, run it
+        // again" — which would repeat every write the run made. For the same
+        // reason a run that has sent writes keeps its header past its deadline
+        // and past a lapsed claim, as a tombstone with their counts.
+        const sent = next.writes.length > 0;
+        const keepUntil = Math.max(next.expiresAt, next.claim?.until ?? 0, next.final ? Date.now() + FINAL_HOLD_MS : 0, sent ? next.expiresAt + FINAL_HOLD_MS : 0, sent && next.claim ? next.claim.until + FINAL_HOLD_MS : 0);
+        const written = await this.bounded(() => cas.call(this.storage, this.headerKey, expected, raw, {
+            ttlSeconds: RunJournal.ttlSeconds(keepUntil),
+        }));
+        return written ? raw : undefined;
+    }
+    async writeSource(source, expiresAt) {
+        await this.bounded(() => this.storage.set(`${this.headerKey}:src`, source, {
+            ttlSeconds: RunJournal.ttlSeconds(expiresAt),
+        }));
+    }
+    async readSource(programHash) {
+        const source = await this.bounded(() => this.storage.get(`${this.headerKey}:src`));
+        if (source === null)
+            return undefined;
+        return (await sha256Hex(source)) === programHash ? source : undefined;
+    }
+    /** Serialized size of an entry as journaled, for the run's byte bound. */
+    static entryText(entry) {
+        return JSON.stringify(entry);
+    }
+    writeEntry(index, entry, expiresAt) {
+        return this.bounded(() => this.writeEntryUnbounded(index, entry, expiresAt));
+    }
+    async writeEntryUnbounded(index, entry, expiresAt) {
+        const text = RunJournal.entryText(entry);
+        const chunks = [];
+        for (let at = 0; at < text.length; at += JOURNAL_CHUNK_CHARS) {
+            chunks.push(text.slice(at, at + JOURNAL_CHUNK_CHARS));
+        }
+        if (chunks.length === 0)
+            chunks.push("");
+        const ttlSeconds = RunJournal.ttlSeconds(expiresAt);
+        const key = `${this.headerKey}:e:${index}`;
+        // Continuations first, the head last: a head that exists names chunks
+        // that all exist.
+        for (let part = 1; part < chunks.length; part++) {
+            await this.storage.set(`${key}#${part}`, chunks[part] ?? "", { ttlSeconds });
+        }
+        await this.storage.set(key, `${chunks.length}\n${chunks[0] ?? ""}`, {
+            ttlSeconds,
+        });
+    }
+    /**
+     * Entries `0 … count - 1`, or undefined when one is missing or unreadable:
+     * a journal with a hole cannot be replayed. (A slot a `sending` write
+     * reserved and never filled is such a hole, and a run holding one has
+     * failed rather than paused, so it is never read.)
+     */
+    readEntries(count) {
+        return this.bounded(() => this.readEntriesUnbounded(count));
+    }
+    async readEntriesUnbounded(count) {
+        const entries = [];
+        for (let index = 0; index < count; index++) {
+            const key = `${this.headerKey}:e:${index}`;
+            const head = await this.storage.get(key);
+            if (head === null)
+                return undefined;
+            const newline = head.indexOf("\n");
+            const parts = Number(head.slice(0, newline));
+            if (newline < 1 || !Number.isSafeInteger(parts) || parts < 1)
+                return undefined;
+            let text = head.slice(newline + 1);
+            for (let part = 1; part < parts; part++) {
+                const chunk = await this.storage.get(`${key}#${part}`);
+                if (chunk === null)
+                    return undefined;
+                text += chunk;
+            }
+            try {
+                const entry = JSON.parse(text);
+                if (!isRecord(entry) || typeof entry.key !== "string" || !isRecord(entry.outcome)) {
+                    return undefined;
+                }
+                entries.push(entry);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return entries;
+    }
+}

package/dist/runtime/shared-read.js

@@ -0,0 +1,106 @@
+// One read that several readers in one request wait on, each on its own terms.
+//
+// Discovery and the registry both coalesce a connector's catalog read inside
+// one request, so a search, a describe, and the call after them cost one
+// downstream listing. The read used to run under whichever reader asked
+// first: its signal was the read's signal, so a short-deadline call that
+// happened to start the read failed a search that joined it with the call's
+// timeout, and a cancelled search cancelled a read others were still waiting
+// on (#571).
+//
+// So the read owns its signal. Each reader waits under its own cancellation,
+// and the read is cancelled only when no reader is left to want it. Nothing
+// here is shared across requests: a SharedRead lives in one request's map and
+// is waited on only by that request's fibers, which is why a plain count of
+// readers is enough and no edge is needed between them.
+import { Deferred, Effect, Exit } from "effect";
+export class SharedRead {
+    onEnd;
+    controller = new AbortController();
+    outcome = Deferred.makeUnsafe();
+    readers = 0;
+    ended = false;
+    /**
+     * Start `read` at once, under a signal the read owns. `onEnd` runs once:
+     * when the read settles, with whether it succeeded, or when it is cancelled
+     * first, with `false`. It runs before any reader hears the outcome, so an
+     * owner that evicts the read there sends a reader who retries on hearing of
+     * a failure to a fresh read, never back to this one.
+     */
+    constructor(read, onEnd = () => { }) {
+        this.onEnd = onEnd;
+        // The executor turns a synchronous throw from `read` into a rejection.
+        new Promise((resolve) => resolve(read(this.controller.signal))).then((value) => this.settle(Exit.succeed(value)), (cause) => this.settle(Exit.fail(cause)));
+    }
+    settle(exit) {
+        this.end(Exit.isSuccess(exit));
+        Deferred.doneUnsafe(this.outcome, exit);
+    }
+    end(succeeded) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.onEnd(succeeded);
+    }
+    // Cancel the read for good. After this it is no longer joinable: whatever
+    // it eventually settles with still reaches the readers already waiting, but
+    // its owner has evicted it and a newcomer starts afresh.
+    cancel(reason) {
+        if (this.ended)
+            return;
+        this.controller.abort(reason);
+        this.end(false);
+    }
+    /**
+     * Wait for the read under this reader's own cancellation.
+     *
+     * A reader whose signal aborts while others still wait fails at once with
+     * its own reason and leaves the read to them. The last reader's abort is the
+     * read's: it is forwarded to the read's signal and that reader waits for the
+     * read's answer, as a lone reader always has, so a connector that finishes
+     * its listing anyway still hands it over. A reader that is interrupted — its
+     * deadline, as `withDeadlineEffect` ends it — simply leaves, and when it was
+     * the last one the read is cancelled with its reason.
+     */
+    join(signal) {
+        return Effect.suspend(() => {
+            this.readers++;
+            let waiting = true;
+            const leave = Effect.sync(() => {
+                if (!waiting)
+                    return;
+                waiting = false;
+                this.readers--;
+                if (this.readers === 0)
+                    this.cancel(signal?.reason);
+            });
+            const answer = Deferred.await(this.outcome);
+            const own = signal
+                ? Effect.raceFirst(answer, this.leftBy(signal))
+                : answer;
+            return Effect.ensuring(own, leave);
+        });
+    }
+    // Fails with the reader's abort reason when other readers remain; when it is
+    // the last, forwards the abort to the read and never completes, leaving the
+    // read's own answer to win the race.
+    leftBy(signal) {
+        return Effect.callback((resume) => {
+            const onAbort = () => {
+                signal.removeEventListener("abort", onAbort);
+                if (this.readers > 1) {
+                    resume(Effect.fail(signal.reason));
+                }
+                else {
+                    this.cancel(signal.reason);
+                }
+            };
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+            return Effect.sync(() => signal.removeEventListener("abort", onAbort));
+        });
+    }
+}

package/dist/server.js

@@ -1,10 +1,12 @@
 import { Effect } from "effect";
+import { notFoundResponse } from "./branding.js";
 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.
  *
@@ -50,6 +52,10 @@ export function createFetchHandler(opts) {
             ...(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).
@@ -71,6 +77,7 @@ export function createFetchHandler(opts) {
                     "/health",
                     ...(opts.ui?.reservedPaths ?? []),
                     ...(opts.ui && opts.activity?.list ? ["/activity"] : []),
+                    ...(opts.ui && opts.artifactsModule ? ["/artifacts", "/artifacts/*"] : []),
                 ],
             },
             ...(opts.deploymentInfo ? { deployment: opts.deploymentInfo } : {}),
@@ -101,7 +108,7 @@ export function createFetchHandler(opts) {
             const response = yield* metadata(request, baseUrl);
             if (response)
                 return response;
-            return new Response("Not Found", { status: 404 });
+            return notFoundResponse(request, opts);
         }
         if (path === "/health")
             return yield* Effect.promise(health);
@@ -111,7 +118,7 @@ export function createFetchHandler(opts) {
         const mcp = yield* routeMcp.handle(context);
         if (mcp)
             return mcp;
-        return new Response("Not Found", { status: 404 });
+        return notFoundResponse(request, opts);
     });
     const serve = (request, runtimeContext) => Effect.suspend(() => {
         const url = new URL(request.url);
@@ -120,6 +127,27 @@ export function createFetchHandler(opts) {
         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 gets the same
+        // 404 as any other unserved path.
+        if (opts.artifactOrigin && url.origin === new URL(opts.artifactOrigin).origin) {
+            if (!isArtifactPath(path) || !opts.ui || !opts.artifactsModule) {
+                return Effect.succeed(withSecurityHeaders(notFoundResponse(request, opts), 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 ?? notFoundResponse(request, opts), 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 Effect.succeed(withSecurityHeaders(originRefusal, url, path));

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 read results 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. One known read: 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, and writes that follow reads. Keep authorized batches in one program. Sample unfamiliar reads. Reduce a one-time write's full result there or page a direct call with get_result; never repeat it to recover output. Non-exempt program writes pause unsent; resume_execution with the returned token, address, and args approves the call and continues the program. Approval "tool" covers later same-address calls in this run; other approval-required writes need their own approval. ${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.
 
@@ -21,40 +35,45 @@ The minimum guest API is:
 
 ## Discover and select
 
-Search and call in one run when schemas suffice. For unfamiliar result formats, return a small sample and continue; do not guess a parser. Use 2–4 distinctive action/object terms; search distinct operations separately.
+Search and call in one run when schemas suffice. Sample unfamiliar reads. Reduce a one-time write's full result here or page a direct call with get_result; never repeat the write to recover output. Search distinct operations separately with 2–4 distinctive action/object terms.
 
 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.
-- Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match is missing, re-search or describe. If a result shape is unclear, return a small sample for inspection before continuing.
+- Reduce through available output keys. An observed key is a hint; later results may differ. Do not guess collection roots such as \`items\` or \`results\`. If a match is missing, re-search or describe.
 - Match provider identifiers and names exactly after resolving them from source data or a connector guide. A broad regular expression that merely finds a plausible value is not identity resolution.
 - 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 explicitly \`readOnlyHint: true\` or config-exempt calls run unasked. With resumable writes, non-exempt approval-required calls pause unsent; \`resume_execution\` repeats the pending address, args, and token. Without them, use \`call_destructive_tool\` for writes. Keep each authorized batch in one resumable program, final post included. \`approval: "call"\` covers one write; \`approval: "tool"\` covers later same-address calls in this run. Other approval-required writes need approval. Replay requires the same call order. Sandbox code cannot widen host gates.
 
 ## 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.
+- Truncated direct call: page with \`get_result\`, never repeat a write. A program result has no page handle; reduce a read in a new program. After a write, check the target or report the gap.
 - 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 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/timeout.js

@@ -31,6 +31,32 @@ export function withDeadline(operation, options) {
         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 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 {
+        return await operation(controller.signal);
+    }
+    finally {
+        for (const { signal, forward } of forwarders) {
+            signal.removeEventListener("abort", forward);
+        }
+    }
+}
 /**
  * Give one operation a caller-facing deadline and the matching cancellation
  * signal. The timeout rejects with the stable, labelled error while aborting