@zackbart/connecta 0.25.0 → 0.26.0

package/dist/routes/shared.d.ts

@@ -1,5 +1,5 @@
 import type { Implementation } from "@modelcontextprotocol/server";
-import type { ActivityModule, OperatorSurface } from "../module-contracts.js";
+import type { ActivityModule, ArtifactsModule, OperatorSurface } from "../module-contracts.js";
 import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity.js";
 import type { CredentialVault } from "../credential-contract.js";
 import type { DeferredWork } from "../connector-scope.js";
@@ -7,6 +7,7 @@ import type { AdmissionController } from "../executor-admission.js";
 import type { Registry, ToolAccess } from "../registry.js";
 import type { ResolvedPool } from "../connector-access.js";
 import type { AuthenticatedIdentity, ConnectaBranding, Executor, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
+import type { ApprovalPolicy } from "../tool-safety.js";
 import type { ConnectorPermission, ConnectaIdentityConfig } from "../index.js";
 export { msg } from "../errors.js";
 export interface ServerOptions {
@@ -16,6 +17,7 @@ export interface ServerOptions {
     /** Validated named pools served at `/mcp/<name>`; empty when none declared. */
     pools?: ReadonlyMap<string, ResolvedPool> | undefined;
     publicUrl?: string | undefined;
+    artifactOrigin?: string | undefined;
     allowedOrigins?: readonly string[] | "*" | undefined;
     serverInfo: Implementation;
     logger: Logger;
@@ -39,6 +41,15 @@ export interface ServerOptions {
     hostCallTimeoutMs?: number | undefined;
     /** Hard ceiling on one execute_code run, outside the sandbox. Default 120_000. */
     watchdogMs?: number | undefined;
+    /** Resumable writes' settings; absent when they are off. */
+    resumable?: {
+        maxWrites: number;
+        ttlSeconds: number;
+    } | undefined;
+    /** Config approval exemptions (`execute.approval`), resolved at construction. */
+    approval?: ApprovalPolicy | undefined;
+    /** Writes one program may send (`execute.maxWrites`), exempt ones included. */
+    maxWrites?: number | undefined;
     /** Required sandbox backing the execute_code meta-tool. */
     executor: Executor;
     /** Sanitized identity of the configured sandbox, when it has one. */
@@ -50,6 +61,8 @@ export interface ServerOptions {
     /** Optional browser routes, with no implementation import in core. */
     ui?: OperatorSurface | undefined;
     activityModule?: ActivityModule | undefined;
+    /** Optional team pages; their routes mount only beside `ui`. */
+    artifactsModule?: ArtifactsModule | undefined;
     /** Optional browser UI and OAuth result-page labels. */
     branding?: ConnectaBranding | undefined;
 }
@@ -86,6 +99,8 @@ export declare function authorize(request: Request, baseUrl: string, auth: Inbou
     connectorIds: "all" | readonly string[];
     /** Per-connector tool allowlist for connectors granted by address only. */
     toolAccess?: ToolAccess;
+    /** Granted addresses that still require the catalog's read-only hint. */
+    guardedToolAccess?: ToolAccess;
     operator: boolean;
     credentialAdministration: ConnectorPermission;
     personalConnection: ConnectorPermission;
@@ -108,6 +123,13 @@ type AuthorizedIdentity = Extract<Awaited<ReturnType<typeof authorize>>, {
 }>;
 /** Unknown configured ids refuse the complete view, including management rights. */
 export declare function validateAuthPermissions(authz: AuthorizedIdentity, registry: Registry): void;
+/**
+ * Whether this identity may open artifact pages: exactly whoever may read the
+ * `artifacts` connector — it is visible to them and `get_artifact` is among
+ * its tools they were granted. Viewing grants nothing a program could not
+ * already read (ethos, "Human routes manage auth, never capability").
+ */
+export declare function mayViewArtifacts(authz: AuthorizedIdentity, registry: Registry): boolean;
 export declare function mayManageConnector(authz: AuthorizedIdentity, connector: {
     id: string;
     authScope?: "shared" | "personal";

package/dist/routes/shared.js

@@ -1,5 +1,6 @@
 import { parseConnectorAccess } from "../connector-access.js";
 import { identityStorageKey, validIdentityReference } from "../identity.js";
+import { isExplicitlyReadOnly } from "../tool-safety.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
     const headers = new Headers(init.headers);
@@ -36,7 +37,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
         const identity = { actor, interactive: false };
         let access;
         try {
-            access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all");
+            access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all", { allowReadOnly: true });
         }
         catch {
             return {
@@ -83,7 +84,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                         ? await identityConfig.activityAccess(principal)
                         : false;
                 }
-                access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all");
+                access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all", { allowReadOnly: true });
                 if (interactive) {
                     credentialAdministration = identityConfig?.credentialAdministration ? await identityConfig.credentialAdministration(identity) : "none";
                     personalConnection = principal && identityConfig?.personalConnection ? await identityConfig.personalConnection(identity) : "none";
@@ -194,6 +195,23 @@ export function validateAuthPermissions(authz, registry) {
         }
     }
 }
+/**
+ * Whether this identity may open artifact pages: exactly whoever may read the
+ * `artifacts` connector — it is visible to them and `get_artifact` is among
+ * its tools they were granted. Viewing grants nothing a program could not
+ * already read (ethos, "Human routes manage auth, never capability").
+ */
+export function mayViewArtifacts(authz, registry) {
+    if (authz.connectorIds !== "all" && !authz.connectorIds.includes("artifacts")) {
+        return false;
+    }
+    const tools = authz.toolAccess?.get("artifacts");
+    if (tools && !tools.has("get_artifact"))
+        return false;
+    if (!authz.guardedToolAccess?.get("artifacts")?.has("get_artifact"))
+        return true;
+    return registry.getConnector("artifacts")?.staticTools?.some((tool) => tool.name === "get_artifact" && isExplicitlyReadOnly(tool)) === true;
+}
 export function mayManageConnector(authz, connector) {
     if (!authz.identity.interactive)
         return false;

package/dist/routes/ui-data.js

@@ -10,6 +10,7 @@ import { resolveDiscoveryConcurrency } from "../concurrency.js";
 import { credentialTestRule, describeUndeclaredCredentialFields, storedCredentialShape, } from "../credential-rules.js";
 import { closeScope } from "../runtime/connector-scope.js";
 import { withDeadlineEffect } from "../runtime/run.js";
+import { isApprovalExempt, NO_EXEMPTIONS, } from "../tool-safety.js";
 import { uiProblemFor, uiToolSafety } from "../ui.js";
 import { CONNECTA_VERSION } from "../version.js";
 const DETAIL_TIMEOUT_MS = 30_000;
@@ -59,7 +60,7 @@ export function uiData(registry, baseUrl, options) {
                     name: t.name,
                     address: `${c.id}.${t.name}`,
                     ...(t.description ? { description: t.description } : {}),
-                    safety: uiToolSafety(t),
+                    safety: uiToolSafety(t, isApprovalExempt(options.approval ?? NO_EXEMPTIONS, c, t.name, t)),
                 }))).pipe(Effect.map((tools) => ({ status, tools, catalogFailed: false })), 
                 // The registry owns the failed catalog observation; the page only
                 // needs to know there was one.

package/dist/routes/ui.js

@@ -3,7 +3,7 @@ import { CONNECTA_VERSION } from "../version.js";
 import { CONNECTA_FAVICON_ICO } from "../favicon.js";
 import { CONNECTA_FAVICON_SVG, operatorPageForPath, renderUiHtml, } from "../ui.js";
 import { authorized, refuse, scopeFor, serveOperator, visibleRegistry, } from "./operator.js";
-import { mayManageConnector, privateJson, } from "./shared.js";
+import { mayManageConnector, mayViewArtifacts, privateJson, } from "./shared.js";
 import { uiData } from "./ui-data.js";
 /**
  * Headers that make an operator-supplied favicon body inert on this origin.
@@ -71,7 +71,10 @@ export async function routeUi(context) {
         });
     }
     const operatorPage = operatorPageForPath(path);
-    if (operatorPage && (operatorPage !== "activity" || opts.activity?.list)) {
+    const artifactPage = operatorPage === "artifacts" || operatorPage === "artifact";
+    if (operatorPage &&
+        (operatorPage !== "activity" || opts.activity?.list) &&
+        (!artifactPage || opts.artifactsModule)) {
         if (request.method !== "GET" && request.method !== "HEAD") {
             return privateJson({ error: "method not allowed" }, { status: 405 });
         }
@@ -89,14 +92,18 @@ export async function routeUi(context) {
         // style/font/network needs and the page's inline <style> stay unrestricted
         // — only script execution, the XSS sink, is gated.
         const nonce = uiScriptNonce();
+        // An artifact shell frames the sandboxed page from its own origin and
+        // nothing else; Connections stays on the deployment's public origin.
+        const homeUrl = opts.publicUrl ? new URL("/", opts.publicUrl).toString() : "/";
         return new Response(request.method === "HEAD"
             ? null
-            : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage), {
+            : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage, { homeUrl }), {
             status: 200,
             headers: {
                 "Content-Type": "text/html; charset=utf-8",
                 "Content-Security-Policy": `script-src 'nonce-${nonce}' 'strict-dynamic' https: 'unsafe-inline'; ` +
-                    "object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+                    "object-src 'none'; base-uri 'none'; frame-ancestors 'none'" +
+                    (artifactPage ? "; frame-src 'self'" : ""),
                 "X-Content-Type-Options": "nosniff",
             },
         });
@@ -146,6 +153,7 @@ function connectorDetail(context, id) {
             mayManage,
             timeoutMs: opts.probeTimeoutMs ?? 30_000,
             signal: request.signal,
+            approval: opts.approval,
         });
         return privateJson({ ...data.connectors[0], permissions: permissions(connector) });
     });
@@ -173,6 +181,7 @@ function summary(context) {
             serverInfo: opts.serverInfo,
             connectaVersion: CONNECTA_VERSION,
             activityEnabled,
+            ...(opts.artifactsModule && mayViewArtifacts(authz, opts.registry) ? { artifactsEnabled: true } : {}),
             credentialManagement,
             oauthManagement: visible.some(c => mayManage(c.id)),
             connectors: visible.map(c => ({ id: c.id, ...(c.title ? { title: c.title } : {}), ...(c.description ? { description: c.description } : {}), authScope: c.authScope ?? "shared", status: "loading", toolCount: 0, tools: [], oauth: Boolean(c.startAuth && c.disconnectAuth), permissions: permissions(c) })),

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));
+        });
+    }
+}