@zackbart/connecta 0.16.1 → 0.18.0

package/dist/skills.js

@@ -1,40 +1,77 @@
-export const CONNECTA_INSTRUCTIONS = 'Connecta exposes seven meta-tools. For one read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than a program. For read-only reduction, multiple or dependent calls, loops, joins, or branches, do not call top-level search_tools: make one execute_code call whose program searches, selects, calls, and reduces; never return discovery for another call. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. Unannotated, write-capable, or destructive tools stay top level: search_tools, then call_destructive_tool; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
+export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use fields or get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: "usage" }) once for program syntax, selection, repair, examples, and runtime details.';
 const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
 Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live in a program, not in top-level tools.
 
-## Choose the smallest execution tool
+The always-loaded MCP instructions are authoritative for choosing the top-level route. Read this skill at most once per task for the program workflow and recovery details below.
 
-Use exact addresses from discovery; never invent one. Search 2–4 distinctive action/object terms, not the whole request.
+## Inside a program
 
-- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once — one cold call is cheaper direct than a program.
-- Anything wider — two or more calls, dependent steps, loops, joins, branching, a whole-catalog browse, or a result to reduce: one \`execute_code\` run.
-- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, one at a time, after reviewing its schema and consequences.
-- Truncated result: retry with \`fields\`, else page it with \`get_result\`.
-- \`auth_required\`: \`authorize_connector\`, hand its recovery text to the operator, retry the call.
+Write one plain-JavaScript async arrow function. TypeScript syntax and portable imports do not work. Return JSON-shaped data and reduce large results before returning.
 
-## Inside a program
+The minimum guest API is:
+
+- \`<connectorId>.<toolName>(args)\` calls a sanitized shortcut. Non-identifier characters become \`_\`; leading digits gain \`_\`; reserved words gain a trailing \`_\`.
+- \`connecta.call("connector.tool", args)\` uses the canonical address and returns the unwrapped value.
+- \`connecta.search(args)\` returns \`{ tools, total, offset, limit, hasMore }\`; \`connecta.describe(args)\` returns \`{ tools }\`.
+- \`connecta.batch(calls)\` runs 2–10 independent calls. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails }\`.
+- \`console.log(...)\` is captured. \`connecta.emit(block)\` and \`connecta.ui(html, options?)\` produce rich output.
+
+## Discover and select
+
+Search inside the run and finish the task there. A discovery-only program wastes a round trip. Use 2–4 distinctive action/object terms, not the full request. Use separate short searches for distinct operations.
+
+For top-level \`search_tools\`, omit \`limit\` initially (the default is 10), 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 declared output shapes. 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.
+- Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and declared 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 declared output keys. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
+
+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.
+
+## Errors and repair
+
+Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`details\`. Batch failures expose the same classification in \`errorDetails\`. Branch on fields, never prose. 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\`.
+- \`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: retry \`call_tool\` with \`fields\`, or 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, \`fields\` selects JSON dot-paths and \`[]\` traverses arrays, for example \`results[].id\`. Projection misses return \`data\` plus \`$connecta\` feedback. \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. \`maxRetries\` is honored only for safely annotated tools. \`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.
+
+Limits: 20 host calls per run, 10 calls per batch, and a 15-second deadline per host call.
+
+## Runtime portability
+
+Portable code uses only connector globals, \`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.
+
+## Examples
+
+One read-only call at a known address:
+
+\`async () => await connecta.call("crm.get_account", { id: "acct_42" })\`
 
-One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the \`connecta\` functions, and \`console.log\`.
+Dependent calls, only when the second needs a value from the first:
 
-- \`connecta.search({})\` loads all catalogs; pass \`connector: "<id>"\` when obvious to load one. \`safety: "readOnly"\` keeps executable calls. Neither grants authority. Matches carry \`address\` and annotations.
-- Exact schemas: \`connecta.describe({ address: "connector.tool" })\` for one, \`{ addresses: [...] }\` for many; \`format: "json"\` only for exact constraints.
-- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\` — how a program tells a policy refusal from a transient failure.
-- Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.
-- Only tools annotated \`readOnlyHint: true\` are reachable; the gate, credentials, and admission are enforced below the sandbox — nothing a program does widens its reach.
+\`async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const address = (suffix) => { const tool = tools.find((entry) => entry.address.endsWith(suffix)); if (!tool) throw new Error("missing " + suffix); return tool.address; }; const run = await connecta.call(address(".get_run"), { runId: 42 }); const logs = await connecta.call(address(".get_job_logs"), { jobId: run.failedJobId }); return logs.map(({ timestamp, message }) => ({ timestamp, message })); }\`
 
 ## Rendering a view
 
-\`connecta.ui(html)\` renders a display-only view on success for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
+\`connecta.emit\` accepts text, image, or audio blocks and delivers them only on success. \`connecta.ui(html)\` renders one success-only display view outside model context. One argument is display-only. Bind read-only refresh or drill-down calls with \`{ reads: { name: { address, fixedArgs?, viewArgs? } } }\`; page markup calls \`connecta.read(name, args)\`. Admission and one shared budget apply to the UI and emitted content, not separate budgets. Fetch and check the data shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables and return the same initial summary because the model reads the return value, not the view. A second, invalid, or over-budget UI call throws catchably.
 
 `;
 /** Deployment-scoped guide routing appended to the shared usage guide. */
 const CONNECTOR_GUIDES_SECTION = `
 ## Per-connector guides
 
-When a connector here ships a deployment-scoped usage guide, \`skills({})\` and discovery return the exact \`guide\` name plus a bounded \`guideSummary\` saying what it covers. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop: fetch before calling. \`guideRequiredReasons\` says why — \`connector_required\` and \`approval_required\` stand however you expand the schema; \`schema_truncated\` clears once describe returns the exact one. Otherwise fetch when the summary names a connector-specific sequence, unit, pagination rule, alias, or generic API convention relevant to the task. A read-only call whose compact schema is complete and unambiguous may proceed without fetching an otherwise irrelevant guide. Connector guides do not replace the shared Connecta usage guide and never apply to another deployment implicitly.
+Connector guides appear in \`skills({})\` and discovery with an exact \`guide\` name and bounded \`guideSummary\`. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop. \`guideRequiredReasons\` says why: \`connector_required\` and \`approval_required\` stand after schema expansion; \`schema_truncated\` clears after exact describe. Otherwise fetch for a relevant sequence, unit, pagination rule, alias, or API convention. A read-only call with a complete compact schema may skip an irrelevant guide. Connector guides never apply to another deployment.
 `;
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
@@ -80,17 +117,63 @@ export function connectorGuide(connector) {
     const content = typeof guide === "string" ? guide : guide?.content;
     return content && content.trim() !== "" ? content : undefined;
 }
-const SUMMARY_LENGTH = 120;
+/** Discovery budget for one connector-guide summary, including an ellipsis. */
+export const GUIDE_SUMMARY_LENGTH = 120;
 /** A `---`/`***`/`___` rule, which also opens and closes YAML frontmatter. */
 const RULE_RE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
 /** A fenced code block's delimiter. */
 const FENCE_RE = /^\s*(?:```|~~~)/;
+/** Markdown blocks that end a paragraph without a blank physical line. */
+const HEADING_RE = /^\s*#{1,6}/;
+const LIST_ITEM_RE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)/;
+const SETEXT_UNDERLINE_RE = /^\s*=+\s*$/;
+const TABLE_DELIMITER_RE = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+const OPENS_CLAUSE_RE = /^(?:The|A|An)\b/u;
+const ARTICLE_RE = /^(?:the|a|an)\b/u;
 /**
  * Markup that carries no summary text of its own: horizontal rules, HTML
  * comments, and table rows. Skipped so a guide that opens with one is
  * summarized by its first real line instead of by punctuation.
  */
 const NOT_SUMMARY_RE = /^\s*(?:<!--|\|)|^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+/** A standard Markdown table starts with a pipe-bearing row and delimiter. */
+function startsTable(lines, index) {
+    const header = lines[index] ?? "";
+    const delimiter = lines[index + 1] ?? "";
+    return header.includes("|") && TABLE_DELIMITER_RE.test(delimiter);
+}
+/** True when a sentence-looking period belongs to an abbreviation. */
+function isAbbreviation(text, end) {
+    const token = text.slice(0, end).match(/\S+$/u)?.[0] ?? "";
+    // These introduce an example or restatement even before a capitalized word.
+    if (/^(?:e\.g|i\.e)\.$/iu.test(token))
+        return true;
+    // An initial or title belongs to the proper name that follows it.
+    if (/^[A-Z]\.$/u.test(token))
+        return true;
+    if (/^(?:Mr|Mrs|Ms|Dr|Prof|Sr|Jr|St)\.$/iu.test(token))
+        return true;
+    if (!/^(?:[A-Za-z]\.){2,}$/u.test(token) &&
+        !/^(?:vs|etc|approx|dept|fig|no)\.$/iu.test(token)) {
+        return false;
+    }
+    // Initialisms can end a sentence or extend a name ("U.S. East region").
+    // The mistakes are asymmetric: a false ending presents a fragment as a
+    // complete thought, while a missed ending gets an honest ellipsis. Count
+    // the period only with narrow evidence of a new clause: an article in one
+    // of its first two words. This is grammar evidence, not a starter-word list.
+    const following = text
+        .slice(end)
+        .match(/^[)\]}'"”’]*\s+(\S+)(?:\s+(\S+))?/u);
+    if (!following)
+        return false;
+    const [, nextWord, afterNext] = following;
+    const startsClause = nextWord !== undefined &&
+        /^\p{Lu}/u.test(nextWord) &&
+        (OPENS_CLAUSE_RE.test(nextWord) ||
+            (afterNext !== undefined && ARTICLE_RE.test(afterNext)));
+    return !startsClause;
+}
 /** Drop a leading YAML frontmatter block — metadata, not summary text. */
 function withoutFrontmatter(lines) {
     let start = 0;
@@ -102,33 +185,107 @@ function withoutFrontmatter(lines) {
     const close = lines.findIndex((line, i) => i > start && RULE_RE.test(line));
     return close === -1 ? lines : lines.slice(close + 1);
 }
+/** Normalize authored and derived summaries under one construction contract. */
+export function normalizeGuideSummary(summary) {
+    const normalized = summary.replace(/\s+/g, " ").trim();
+    return normalized === "" ? undefined : normalized;
+}
 /**
- * One line describing a guide, for the cheap list view: the guide's first
- * meaningful line (heading marks and list bullets stripped), falling back to
- * the connector's own description when the guide opens with nothing but
- * markup.
+ * Shorten a normalized summary at the strongest readable boundary available.
+ * A complete sentence needs no ellipsis; clause and word cuts do, so discovery
+ * never presents an unfinished fragment as the guide's complete thought.
  */
 function boundedSummary(summary) {
-    const line = summary.replace(/\s+/g, " ").trim();
-    if (line === "")
+    const normalized = normalizeGuideSummary(summary);
+    if (!normalized)
         return undefined;
-    return line.length <= SUMMARY_LENGTH
-        ? line
-        : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+    if (normalized.length <= GUIDE_SUMMARY_LENGTH)
+        return normalized;
+    const contentBudget = GUIDE_SUMMARY_LENGTH - 1;
+    let sentenceEnd = 0;
+    const sentenceBoundary = /[.!?…。！？](?:[)\]}'"”’]+)?(?=\s|$)/gu;
+    for (const match of normalized.matchAll(sentenceBoundary)) {
+        const end = (match.index ?? 0) + match[0].length;
+        if (end > GUIDE_SUMMARY_LENGTH)
+            break;
+        const punctuationEnd = (match.index ?? 0) + 1;
+        if (match[0].startsWith(".") &&
+            isAbbreviation(normalized, punctuationEnd)) {
+            continue;
+        }
+        // Do not mistake another short fragment for a useful complete thought.
+        if (end >= 24)
+            sentenceEnd = end;
+    }
+    if (sentenceEnd > 0)
+        return normalized.slice(0, sentenceEnd);
+    const available = normalized.slice(0, contentBudget);
+    let clauseEnd = 0;
+    const clauseBoundary = /[,;:](?=\s)|\s[—–-](?=\s)/g;
+    for (const match of available.matchAll(clauseBoundary)) {
+        const end = match.index ?? 0;
+        // Prefer a clause only when it retains most of the discovery budget.
+        if (end >= 80)
+            clauseEnd = end;
+    }
+    if (clauseEnd > 0) {
+        return `${available.slice(0, clauseEnd).trimEnd()}…`;
+    }
+    const wordEnd = available.search(/\s+\S*$/);
+    if (wordEnd > 0) {
+        const prefix = available
+            .slice(0, wordEnd)
+            .trimEnd()
+            .replace(/[,;:([{—–-]+$/u, "")
+            .trimEnd();
+        if (prefix !== "")
+            return `${prefix}…`;
+    }
+    let hardEnd = contentBudget;
+    const code = normalized.charCodeAt(hardEnd - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        hardEnd--;
+    return `${normalized.slice(0, hardEnd)}…`;
 }
+/**
+ * One thought describing a guide for the cheap list view: the first meaningful
+ * paragraph, joined across physical lines, with headings and the connector
+ * description as fallbacks when the guide opens with markup alone.
+ */
 function summarizeGuide(connector, guide) {
+    const lines = withoutFrontmatter(guide.split("\n"));
     let inFence = false;
+    let inComment = false;
     let headingFallback;
-    for (const raw of withoutFrontmatter(guide.split("\n"))) {
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index] ?? "";
+        if (inComment) {
+            if (raw.includes("-->"))
+                inComment = false;
+            continue;
+        }
         if (FENCE_RE.test(raw)) {
             inFence = !inFence;
             continue;
         }
         if (inFence)
             continue;
+        if (raw.trimStart().startsWith("<!--")) {
+            if (!raw.includes("-->"))
+                inComment = true;
+            continue;
+        }
+        if (startsTable(lines, index)) {
+            index++;
+            while (index + 1 < lines.length &&
+                (lines[index + 1] ?? "").includes("|")) {
+                index++;
+            }
+            continue;
+        }
         if (raw.trim() === "" || NOT_SUMMARY_RE.test(raw))
             continue;
-        const heading = /^\s*#{1,6}/.test(raw);
+        const heading = HEADING_RE.test(raw);
         const line = raw
             // `\s*` (not `\s+`) so a bare `#` strips to nothing and is skipped, and
             // an unspaced `#Heading` is still read as a heading.
@@ -142,7 +299,24 @@ function summarizeGuide(connector, guide) {
             headingFallback ??= boundedSummary(line);
             continue;
         }
-        return boundedSummary(line) ?? line;
+        const paragraph = [line];
+        while (index + 1 < lines.length) {
+            const next = lines[index + 1] ?? "";
+            if (next.trim() === "" ||
+                startsTable(lines, index + 1) ||
+                FENCE_RE.test(next) ||
+                HEADING_RE.test(next) ||
+                LIST_ITEM_RE.test(next) ||
+                SETEXT_UNDERLINE_RE.test(next) ||
+                NOT_SUMMARY_RE.test(next)) {
+                break;
+            }
+            paragraph.push(next.trim());
+            index++;
+            if (paragraph.join(" ").length > GUIDE_SUMMARY_LENGTH)
+                break;
+        }
+        return boundedSummary(paragraph.join(" ")) ?? line;
     }
     if (headingFallback)
         return headingFallback;
@@ -155,6 +329,8 @@ export function connectorGuideSummary(connector) {
     if (!guide)
         return undefined;
     const configured = typeof connector.usageGuide === "object"
+        // Registry construction rejects over-budget configured summaries. Keep
+        // normalization here so direct Connector callers see the same text.
         ? boundedSummary(connector.usageGuide.summary ?? "")
         : undefined;
     return configured ?? summarizeGuide(connector, guide);

package/dist/types.d.ts

@@ -180,6 +180,12 @@ export interface CatalogDriftReport extends CatalogDriftCounts {
     /** When the observation was taken; never when a probe was scheduled. */
     observedAt: string;
 }
+/** The last agent-facing catalog read this runtime served for one connector. */
+export interface CatalogAccessObservation {
+    /** Fresh means the read used a live or unexpired catalog; stale means SWR. */
+    state: "fresh" | "stale";
+    observedAt: string;
+}
 export interface ConnectorStatus {
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
@@ -193,6 +199,11 @@ export interface ConnectorStatus {
      * isolate or process has seen nothing, not that nothing drifted.
      */
     catalogDrift?: CatalogDriftReport;
+    /**
+     * The last agent-facing catalog read in this runtime. This payload-free
+     * observation is not persisted and operator reads do not replace it.
+     */
+    catalogAccess?: CatalogAccessObservation;
 }
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
@@ -313,8 +324,9 @@ export interface ConnectorUsageGuide {
     /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
     content: string;
     /**
-     * Bounded discovery hint describing the conventions the guide covers. When
-     * omitted, Connecta derives a summary from the guide's first meaningful line.
+     * Discovery hint describing the conventions the guide covers. Whitespace is
+     * normalized, and a value over 120 characters throws at construction. When
+     * omitted, Connecta derives a bounded summary from the first body paragraph.
      */
     summary?: string;
     /**

package/dist/ui.js

@@ -374,6 +374,9 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
             // `boundedCatalogDrift`, so what lands here cannot carry a name or a
             // schema even if the plugin seam returned one.
             ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
+            ...(status.catalogAccess
+                ? { catalogAccess: status.catalogAccess }
+                : {}),
             ...(c.disconnectAuth && c.startAuth ? { oauth: true } : {}),
             ...(credential ? { credential } : {}),
         };
@@ -461,7 +464,7 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
             : `<span class="product">${escapeHtmlAttr(brand.productName)}</span>`
         : "";
     const clerkScript = clerk && clerkScriptOrigin
-        ? `<script${nonceAttr} defer crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
     return `<!doctype html>
 <html lang="en">

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.16.1";
+export declare const CONNECTA_VERSION = "0.18.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.16.1";
+export const CONNECTA_VERSION = "0.18.0";

package/documentation/architecture.md

@@ -26,7 +26,10 @@ ethos invariant, not a style preference: a client retained across requests on
 Workers is a cross-request capability leak, and a promise awaited after the
 response is work the runtime may have already torn down. Deferred work has one
 sanctioned channel — `ctx.waitUntil`, threaded through `fetch(request, env,
-ctx)` and used for best-effort activity writes.
+ctx)`. Best-effort activity writes use it. An agent read that already demanded
+an expired catalog refresh may also use it while serving a complete catalog
+inside its stale window. That refresh owns a new scope and deadline; it never
+carries the inbound scope or signal past the request.
 
 The registry is deliberately on the long side of that line and the MCP server
 deliberately on the short side. A fresh `McpServer` per request is what makes
@@ -87,8 +90,8 @@ owns or hands out, and a change usually belongs in exactly one of them:
 
 | Module | Owns |
 | --- | --- |
-| `src/registry.ts` | The connector set, id validation, address resolution, connector health, per-connector call limiters, and the drift snapshot. Construction-time refusal of structural mistakes lives here. |
-| `src/catalog-service.ts` | Tool listing: cold-load coalescing, TTL, persistence as manifest plus revision-addressed chunks, stale fallback, and the completeness rule — a partial catalog is a failure, never a cache write. |
+| `src/registry.ts` | The connector set, address resolution, catalog TTL/persistence/completeness, shared refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
+| `src/catalog-service.ts` | Request-local tool listing, search, and describe. It coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
 | `src/invocation.ts` | One tool call: argument validation, call admission, per-attempt timeout, retry with the connector's own `Retry-After` honoured exactly or declined, result unwrapping, size capping, and the activity record. |
 | `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
 
@@ -137,7 +140,7 @@ src/
   apps-shell.ts       the one build-time MCP Apps template
   skills.ts           MCP instructions, the usage skill, connector guides
   registry.ts         connector set, addresses, health, call limiters
-  catalog-service.ts  catalog loading, caching, persistence, stale fallback
+  catalog-service.ts  request-local catalog access, search, and describe
   catalog.ts          ranking, summaries, compact schema rendering
   invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces
@@ -182,7 +185,7 @@ src/
 | The core imports no `node:` builtin and reaches no Node-only module | `test/purity.test.ts` |
 | The published surface matches the same boundary | `test/package-surface.test.ts`, `scripts/check-package.mjs` |
 | Route order, per-route auth, and byte-exact refusals | `test/server-route-contracts.test.ts` |
-| `/mcp` end to end, the open routes, exactly seven tools | `test/server.test.ts`, `test/code-first-surface.test.ts` |
+| `/mcp` end to end, the open routes, exactly seven tools, bounded connector orientation | `test/server.test.ts`, `test/code-first-surface.test.ts` |
 | Construction-time refusals and the grouped config boundary | `test/config.test.ts`, `test/registry.test.ts` |
 | Program and top-level calls take the same enforced path | `test/execute.test.ts` |
 | Both deployment shapes still compile and configure the real thing | `test/deployment-shapes.test.ts`, `npm run check:examples` |