@zackbart/connecta 0.17.0 → 0.18.1

package/dist/providers/stripe.js

@@ -1,6 +1,6 @@
 import { remoteMcp, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
-/** Stripe publishes one hosted MCP endpoint; the credential selects the mode. */
+/** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
 /**
  * Stripe documents no MCP-specific rate limit, so this transcribes the account
@@ -89,9 +89,9 @@ const TEST_KEY = /\b(?:sk|rk|pk)_test_/;
  * Refuse a deployment whose declared mode and supplied key disagree.
  *
  * This is the one half of production/sandbox routing connecta can actually
- * enforce. Nothing here reads or reports key material: an unrecognizable
- * credential (OAuth, or a key shape this release does not know) is left alone
- * rather than guessed at, and a mismatch names only the two modes.
+ * enforce. Nothing here reads or reports key material: an unrecognizable key
+ * shape is left alone rather than guessed at, and a mismatch names only the
+ * two modes.
  */
 function assertModeMatchesKey(id, mode, auth) {
     if (auth.type !== "headers")
@@ -125,6 +125,22 @@ function resolveAuth(id, options) {
         headers: { ...auth.headers, "Stripe-Account": connectedAccount },
     };
 }
+const OAUTH_ADMISSION = STRIPE_ADMISSION.sandbox;
+function oauthUsageGuide(purpose, instructions) {
+    const accountInstructions = instructions?.trim();
+    return `# Stripe usage
+
+Scope: live and sandbox accounts. Connector purpose: ${purpose}
+
+This OAuth session may expose both live and sandbox Stripe accounts. Call \`list_available_accounts_or_orgs\`, then carry its exact \`stripe_context\` and \`livemode\` into every account-scoped call. A live-mode write moves real money; a sandbox write changes test data. Never infer the account or mode from connector metadata.
+
+- Call \`list_available_accounts_or_orgs\` before every account-scoped read or write. Select the intended result, then carry its \`stripe_context\` and \`livemode\` unchanged. If the account, mode, or supported selector is ambiguous, stop and ask; never guess.
+- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a separate connector with a deployment-configured restricted key plus Stripe's documented \`Stripe-Account\` header; OAuth does not support that path.
+${sharedUsageGuide("100 requests per second in live mode and 25 in sandbox mode")}
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
 const MODE_COPY = {
     production: {
         title: "Stripe (production)",
@@ -137,34 +153,40 @@ const MODE_COPY = {
         warning: "This is a SANDBOX Stripe connection. Nothing here is real money and none of these objects exist in production, so never answer a question about live revenue, payouts, or a named customer from this connector.",
     },
 };
-function usageGuide(mode, purpose, instructions) {
+function fixedModeUsageGuide(mode, purpose, instructions) {
     const copy = MODE_COPY[mode];
     const accountInstructions = instructions?.trim();
-    const rate = mode === "production" ? "100" : "25";
     return `# Stripe usage
 
 Mode: ${mode}. Connector purpose: ${purpose}
 
 ${copy.warning}
 
-- One OAuth session may cover more than one account in the same Stripe organization. The connector id, title, and purpose state routing intent; they do not prove which account a call will use.
-- Before every account-scoped read or write, resolve the intended organization account. Inspect the chosen tool's live input schema and carry the exact account or context field it exposes. If the account or its supported selection mechanism is ambiguous, stop and ask; never guess from the connector metadata, invent an MCP argument, or add a request header the live contract does not expose.
 - Organization accounts are not Stripe Connect connected accounts. A Connect call requires a deployment-configured restricted key plus Stripe's documented \`Stripe-Account\` header; OAuth does not support that path. Do not try to turn an organization-account call into a Connect call inside tool arguments.
+${sharedUsageGuide(`${mode === "production" ? "100" : "25"} requests per second`)}
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
+function sharedUsageGuide(rate) {
+    return `
 - Four generic tools reach any Stripe API method. Find the method with \`stripe_api_search\`, read its parameters with \`stripe_api_details\`, then call \`stripe_api_read\` (GET) or \`stripe_api_write\` (POST/PATCH/PUT/DELETE). Never guess a path or a parameter name — \`stripe_api_details\` is cheaper than a rejected write.
 - Prefer a dedicated tool when one covers the task: \`get_stripe_account_info\` for account information, \`get_balance_summary\` for balances, \`create_refund\` for refunds, \`stripe_report\` for reports. One call instead of three, and a refund named \`create_refund\` reads far more clearly in the approval a human sees than the same refund buried in \`stripe_api_write\` arguments.
 - \`stripe_api_write\` carries the blast radius of the entire write API — every POST, PATCH, PUT, and DELETE, from a customer edit to a subscription cancellation. State the method and path explicitly; expect approval on every call.
-- Lists are cursor-paginated: \`limit\` defaults to 10 and caps at 100, \`starting_after\` and \`ending_before\` take an object id and are mutually exclusive, and \`has_more\` says whether to continue. Page inside \`execute_code\` and reduce before returning.
+- Lists are cursor-paginated: \`limit\` defaults to 10 and caps at 100, \`starting_after\` and \`ending_before\` take an object id and are mutually exclusive, and \`has_more\` says whether to continue. Page inside \`execute_code\`.
+- Any \`stripe_api_read\` list or \`stripe_api_search\` that returns full objects belongs inside \`execute_code\`, projected to the fields the question needs before \`return\`. Neither \`limit\` nor \`expand\` substitutes for that: an unprojected list of customers or invoices truncates long before it answers, and a projected one keeps the customer's name, email, and address out of the transcript.
+- Search filters on a documented per-resource field set, not on arbitrary attributes. Charges search takes \`amount\`, \`created\`, \`currency\`, \`customer\`, \`status\`, \`refunded\`, \`disputed\`, \`metadata\`, \`billing_details.address.postal_code\`, and \`payment_method_details.<source>.*\` card fields — there is no \`payment_intent\` field. When the field you want is not searchable, retrieve the parent object and follow its reference (the PaymentIntent's \`latest_charge\`) instead of retrying the search with another spelling.
+- The account → \`stripe_api_search\` → \`stripe_api_details\` → \`stripe_api_read\` sequence is one program, not four turns: resolve the method once, then call that method as many times as the investigation needs in the same run.
+- Decline outcomes live on the charge — \`outcome\`, \`failure_code\`, \`failure_message\` — reached from the PaymentIntent's \`latest_charge\`, so "why did this payment fail" is a PaymentIntent read followed by one charge read.
 - Resolve ids before acting; never guess one. Stripe ids are typed prefixes — \`cus_\` customer, \`sub_\` subscription, \`ch_\` charge, \`pi_\` payment intent, \`in_\` invoice, \`acct_\` account — and a plausible-looking id belongs to a different object or to nobody. Find the object with \`stripe_api_search\` (or a list endpoint through \`stripe_api_read\`) and carry the \`id\` it returned into the write.
 - This connection's tool list is not a fixed set. Stripe gates parts of its MCP catalog by account, integration, and beta enrollment, so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - Amounts are integers in the currency's minor unit: \`1099\` is 10.99 USD, and zero-decimal currencies like JPY take \`10\` for 10 JPY. Never send a decimal.
 - Send an \`Idempotency-Key\` on every write you might retry, if the tool accepts it, and reuse the same key for the retry. A retry with a fresh key is a second charge, not a second attempt.
-- Stripe answers a rate limit with \`429\` and a \`Stripe-Rate-Limited-Reason\` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ${rate} requests per second, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.
+- Stripe answers a rate limit with \`429\` and a \`Stripe-Rate-Limited-Reason\` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ${rate}, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.
 - Use \`search_stripe_documentation\` when the shape of an object or a flow is unclear; it is a read and costs nothing but a call.
 - Treat every create, update, delete, refund, and report run as a write. Connecta routes the maintained write catalog through \`call_destructive_tool\`; newly added tools also fail closed until classified.
 - An \`auth_required\` failure means this connector's Stripe authorization is missing or expired: run \`authorize_connector\` for this connector id, then retry the same call unchanged. A rejected argument or a plan restriction comes back in Stripe's own words instead — read it rather than re-authorizing.
-${accountInstructions
-        ? `\n## Account instructions\n\n${accountInstructions}\n`
-        : ""}`;
+`;
 }
 /** A maintained Stripe hosted-MCP connection. */
 export function stripe(id, options) {
@@ -172,31 +194,40 @@ export function stripe(id, options) {
     if (!purpose) {
         throw new Error("stripe() requires a non-empty account purpose.");
     }
-    const mode = options.mode;
-    if (mode !== "production" && mode !== "sandbox") {
-        throw new Error(`stripe("${id}") requires mode "production" or "sandbox".`);
-    }
     const auth = resolveAuth(id, options);
-    assertModeMatchesKey(id, mode, auth);
-    const copy = MODE_COPY[mode];
+    const mode = "mode" in options ? options.mode : undefined;
+    if (auth.type === "oauth" && mode !== undefined) {
+        throw new Error(`stripe("${id}") cannot declare a connector-wide mode for OAuth; Stripe returns mode with each account.`);
+    }
+    if (auth.type === "headers" && mode !== "production" && mode !== "sandbox") {
+        throw new Error(`stripe("${id}") with headers auth requires mode "production" or "sandbox".`);
+    }
+    if (auth.type === "headers") {
+        assertModeMatchesKey(id, mode, auth);
+    }
+    const copy = mode === undefined ? undefined : MODE_COPY[mode];
     const connector = remoteMcp(id, {
         url: STRIPE_MCP_ENDPOINT,
-        title: options.title ?? copy.title,
-        description: `Stripe payments (${copy.blurb}) — ${purpose}`,
+        title: options.title ?? copy?.title ?? "Stripe",
+        description: mode === undefined
+            ? `Stripe payments (live and sandbox accounts) — ${purpose}`
+            : `Stripe payments (${copy?.blurb}) — ${purpose}`,
         auth,
         requireHttps: true,
-        callAdmission: STRIPE_ADMISSION[mode],
+        callAdmission: mode === undefined ? OAUTH_ADMISSION : STRIPE_ADMISSION[mode],
         usageGuide: {
-            content: usageGuide(mode, purpose, options.instructions),
-            // Explicit rather than derived: production versus sandbox is the fact an
-            // agent must not get wrong. Multi-account OAuth also has to reach browse
-            // before connector metadata can be mistaken for authenticated identity.
-            summary: mode === "production"
-                ? "PRODUCTION: real money. OAuth may span organization accounts; resolve the account from live schemas before acting."
-                : "Sandbox: test data only. OAuth may span organization accounts; resolve the account from live schemas before acting.",
-            // Not `required`. The four generic tools are the routing decision, and
-            // the mode warning already rides the title and description; a guide
-            // forced into every call would pay for the same paragraph repeatedly.
+            content: mode === undefined
+                ? oauthUsageGuide(purpose, options.instructions)
+                : fixedModeUsageGuide(mode, purpose, options.instructions),
+            // Explicit rather than derived: fixed credentials must lead with mode,
+            // while OAuth must lead with its account-scoped selector pair.
+            summary: mode === undefined
+                ? "Live and sandbox Stripe accounts. List accounts; carry the returned stripe_context and livemode before acting."
+                : mode === "production"
+                    ? "PRODUCTION: real money. This static credential has one fixed live-mode scope."
+                    : "Sandbox: test data only. This static credential has one fixed sandbox scope.",
+            // Not `required`. The four generic tools are the routing decision; a
+            // guide forced into every call would pay for the same prose repeatedly.
         },
         ...(options.maxResultBytes !== undefined
             ? { maxResultBytes: options.maxResultBytes }

package/dist/routes/ui.js

@@ -28,7 +28,7 @@ const INERT_ICON_HEADERS = {
     "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
     "X-Content-Type-Options": "nosniff",
 };
-/** Per-request base64 nonce for an operator shell's scripts (Node 20+ and Workers). */
+/** Per-request base64 nonce for an operator shell's scripts (Node 22+ and Workers). */
 function uiScriptNonce() {
     const bytes = crypto.getRandomValues(new Uint8Array(16));
     let binary = "";

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Connecta exposes seven meta-tools. For one read at an unknown address, search_tools with 2\u20134 distinctive action/object terms and includeSchemas=\"compact\", then one call_tool \u2014 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 declare 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.";
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export declare const USAGE_SKILL: string;
 /** The always-loaded MCP `instructions` string. */

package/dist/skills.js

@@ -1,33 +1,70 @@
-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" })\`
 
-Portable code uses only connector globals (\`<connectorId>.<toolName>(args)\`), \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch/process/timers/crypto/WebSocket. Dynamic Workers require only \`{ loader }\`; bindings/modules/globalOutbound violate it. Then env maps are empty; node:fs/http/https absent; outbound fetch/WebSocket/node:net/tls denied; DNS unresolved. Runtime builtins remain through import() and process.getBuiltinModule(), including node:path and cloudflare:workers; the set can drift. Timers/process/crypto/WebSocket and data: fetch remain. Avoid them; QuickJS fails.
+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.
-- Caught Connecta errors have \`message\`, \`code\`, \`retryable\`, and \`details\`; branch on fields. For 2–10 independent calls, \`connecta.batch([...])\` returns success data or an \`errorDetails\` whose code and retryable flag match the throw.
-- Search inside the run; 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 one success-only display view, never for the model. Fetch and check the shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables; 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. */

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.17.0";
+export declare const CONNECTA_VERSION = "0.18.1";

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.17.0";
+export const CONNECTA_VERSION = "0.18.1";

package/documentation/architecture.md

@@ -185,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` |

package/documentation/code-mode.md

@@ -173,7 +173,10 @@ global whose properties are its tools, so `<connectorId>.<toolName>(args)` works
 with both parts sanitized into JavaScript identifiers — characters outside
 `[A-Za-z0-9_$]` become `_`, a leading digit gets `_` prefixed, and a reserved
 word gets `_` appended (`my-service.get.thing` → `my_service.get_thing`). The
-globals are lazy: no catalog is fetched until a program touches one.
+globals are lazy: no catalog is fetched until a program touches one. The
+bounded deployment inventory in the `execute_code` description shows each
+canonical connector id and labels the shortcut only when it differs; the
+[discovery guide](./meta-tools.md#discovery-context) defines that bound.
 
 **A3.** A shortcut that resolves to more than one tool fails closed with
 `ambiguous_tool_alias`, naming the colliding tool names and pointing at
@@ -256,10 +259,13 @@ const { tools } = await connecta.describe({
 });
 ```
 
-**S4.** Returns `{ tools }` in the order asked, one entry per address. An
-address that is unknown, or whose connector's catalog could not be loaded,
-returns an entry carrying `error` — one bad address never fails the whole call.
-More than 100 addresses is `invalid_args`; the same 256,000-byte ceiling applies.
+**S4.** Returns `{ tools }` in order, one entry per address. An unknown address
+or failed catalog returns `error` plus typed `errorDetails`: `code`, `message`, and `retryable`. Misses
+carry a route-aware `nextAction`; a close miss may add three canonical `suggestions`.
+Catalog failures add only `retryAfterMs` when known. One bad address never fails the whole call. Each failed entry clamps its
+caller-authored `address` to 512 UTF-8 bytes with an `…` marker. Entry order
+correlates a clipped address with its request; successes keep canonical addresses. More than 100
+addresses is `invalid_args`; the same 256,000-byte ceiling applies.
 
 ### connecta.call
 
@@ -377,7 +383,7 @@ exactly first, by containment second — so a program that *wraps* a failure's
 message in its own text still reports the underlying typed failure. Keeping the
 type beats keeping the prose.
 
-**E7.** `retryable` for `unknown_address`, `unknown_tool`, `ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. Both the message and the derived `query` clamp the address to 512 UTF-8 bytes with a `…` marker: the address is caller-authored and lands in the message, the query, the text content, and `structuredContent`, so an invented 50 KB one would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake; a short one — the common case — is exact and untagged.
+**E7.** `retryable` for `unknown_address`, `unknown_tool`, `ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. The message, the derived `query`, and a failed describe entry's `address` clamp caller-authored text to 512 UTF-8 bytes with an `…` marker. Those values land in the text content and `structuredContent`, so an invented 50 KB address would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake by its position; a short one — the common case — is exact and untagged.
 
 **E8.** A remote MCP tool whose advertised schema rejects the call fails before provider dispatch with `invalid_args`, carrying bounded, value-free `{ path, code, expected }` findings and scoped search recovery keyed `function: "connecta.search"` like every other in-program miss. A declared property reports the schema keyword that failed, never the validator's duplicate `additionalProperties` branch; a truly undeclared property still reports `additionalProperties`. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
 
@@ -585,14 +591,14 @@ the same mistake as automatic host-side projection, refused in `ethos.md`
 ([#282](https://github.com/zackbart/connecta/issues/282)).
 
 **U13.** The always-loaded MCP instructions locate `connecta.ui(html)` before an
-agent chooses a route: it is a guest function inside `execute_code`, never a
-connector address or catalog result, takes one HTML string, and carries `U12`'s
-mirrored-return duty. The detailed tool description proved too late to stop cold
-agents from searching downstream catalogs for UI; the location distinction
-therefore rides `initialize`, under a 1,000-character ceiling for the complete
+agent chooses a route: it exists only inside `execute_code`, never in connector
+search, and carries `U12`'s mirrored-return duty. The detailed call, binding,
+budget, and repair rules live in the on-demand `usage` skill. The location
+distinction rides `initialize`, under a 1,000-character ceiling for the complete
 instructions string. This promotes existing contract, not capability: the
 seven-tool surface, guest API, catalog, Apps delivery, and runtime do not change
-([#286](https://github.com/zackbart/connecta/issues/286)).
+([#286](https://github.com/zackbart/connecta/issues/286),
+[#418](https://github.com/zackbart/connecta/issues/418)).
 
 Bounded view reads follow normative [`V1`–`V8`](./program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
 
@@ -645,6 +651,8 @@ because connecta enforces them above the sandbox:
 | Deadline per host call | 15 s |
 | Discovery page | ≤ 100 tools, ≤ 256,000 serialized bytes |
 | `describe` addresses | ≤ 100 |
+| `describe` nearby suggestions | ≤ 3 canonical addresses per failed entry |
+| Caller text echoed by `describe` recovery | ≤ 512 UTF-8 bytes per field, plus `…` |
 | Result | 24,000 serialized characters |
 | Logs presented to the model | 4,000 characters |
 
@@ -828,13 +836,13 @@ the upstream `Executor` shape assignable.
 | `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
 | `P3`, `X9` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` |
 | `P4` | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution) |
-| `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (sanitizing) |
+| `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (sanitizing), `test/server.test.ts` (bounded live connector inventory) |
 | `A3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (colliding alias) |
 | `A4` | `test/execute.test.ts` (namespace collisions, reserved namespace) |
 | `A5` | verdict; `A1`–`A3` are its enforcement |
 | `S1`, `S2` | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, and the unfiltered browse that replaces `list_connectors`), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools.test.ts` (mixed complete/partial ranking and stable pagination) |
 | `S3` | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound) |
-| `S4` | `test/guest-api-contract.test.ts` (unknown address in `describe`) |
+| `S4` | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds) |
 | `S5` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`) |
 | `S6` | `test/execute.test.ts` (fail-closed annotations, activity parity) |
 | `S7` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (batch cap) |
@@ -875,7 +883,7 @@ the upstream `Executor` shape assignable.
 | `U7`, `U8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `U9` | `test/execute-ui.test.ts` (a `ui` byte aggregate distinct from `emitted`, absent when nothing was accepted) |
 | `U12` | `test/server.test.ts` (the `connecta.ui` bullet carries the return-value clause); a duty on program authors, so the description is the only place it can be enforced |
-| `U13` | `test/code-first-surface.test.ts`, `test/server.test.ts` (served `initialize.instructions` locate UI inside `execute_code`, exclude it from catalog search, state the one-string call and mirrored return, and stay within the complete 1,000-character budget) |
+| `U13` | `test/code-first-surface.test.ts`, `test/server.test.ts` (served `initialize.instructions` locate UI inside `execute_code`, exclude it from connector search, state the mirrored-return duty, and stay within the complete 1,000-character budget; the usage skill carries detailed call rules) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |

package/documentation/connector-guides.md

@@ -60,15 +60,12 @@ unknown name, unknown connector, connector with no guide — is an explicit
 error. Nothing silently falls back to the generic guide, because a generic
 answer to a specific question is worse than no answer.
 
-Discovery text is conditional on the deployment actually having a guide. The
-guide sentences in the `skills`, `search_tools`, `call_destructive_tool`, and
+Discovery text is conditional on the deployment actually having a guide. Short
+pointers in the `skills`, `search_tools`, `call_destructive_tool`, and
 `execute_code` descriptions appear only when at least one visible connector
-declares one — the connector set is fixed at construction, so this is stable
-per deployment, and a deployment with no guides pays no always-loaded context
-for a feature it does not use. The built-in `usage` skill is the deliberate
-exception: it stays byte-identical across every deployment, including its
-per-connector-guides section, so an agent that has read it once in a task never
-needs a deployment-local copy of it.
+declares one. The detailed selection rules live only in the built-in `usage`
+skill. That skill stays byte-identical across deployments, including its
+per-connector-guides section, so an agent reads it at most once per task.
 
 ## What belongs in a guide
 
@@ -175,5 +172,5 @@ each branch, the `guide` pointer in search output, and `guideRequired`
 appearing for connector-required conventions, approval-bound tools, and
 truncated schemas — and being absent from a search that asked for no schemas.
 `test/server.test.ts` owns the conditional half: it compares a guide-free
-deployment's four tool descriptions against a guided one's, and asserts the
-`usage` skill is byte-identical between them.
+deployment's four short pointers against a guided one's, and asserts the
+complete `usage` skill is byte-identical between them.

package/documentation/connectors.md

@@ -122,6 +122,7 @@ Maintained provider guides:
 - [Linear](./linear.md)
 - [Mixpanel](./mixpanel.md)
 - [Notion](./notion.md)
+- [RevenueCat](./revenuecat.md)
 - [Stripe](./stripe.md)
 
 ## The `api()` construction contract

package/documentation/meta-tools.md

@@ -60,6 +60,14 @@ their smallest successful one-tool shapes:
 
 ## Discovery context
 
+The deployment-derived `execute_code` description includes a live connector
+inventory before any catalog search. It preserves registry order and uses each
+canonical id, adding `shortcut <name>` only when the program namespace differs.
+The complete inventory line is capped at 256 UTF-8 bytes. Entries stay whole,
+and a truncated line ends with the exact `+N more` count. This reads only the
+configured registry: it loads no catalog, probes no credential, grants no
+capability, and does not replace canonical discovery or addressing.
+
 Start an unknown-address lookup with two to four distinctive action/object
 terms, not the full request, and omit `limit` so the default eight-result page
 stays small. When the integration is obvious, set `connector` to its id: a
@@ -146,8 +154,12 @@ the zero-tool page.
 The built-in `usage` skill is byte-identical across deployments and says to
 read it at most once per task. Connector guides remain scoped to the deployment
 that listed them, even when two deployments happen to use identical content.
-Deployments without connector guides receive none of the conditional guide
-sentences in their always-loaded tool descriptions.
+The always-loaded instructions and seven tool definitions own route selection,
+the fail-closed boundary, and the minimum guest syntax. The usage skill owns
+program selection detail, examples, runtime differences, and repair guidance.
+This split avoids two normative copies while preserving a valid first program
+for clients that never fetch the skill. Deployments without connector guides
+receive none of the short conditional guide pointers in their definitions.
 
 ## Result representation
 
@@ -316,6 +328,16 @@ a tool. A read path that reaches an unannotated, write-capable, or destructive
 tool returns `nextAction` for `call_destructive_tool` with the canonical
 address. Nothing is executed by these records.
 
+`connecta.describe` keeps failures inline so one miss cannot discard the other
+schemas. Each failed entry keeps its human `error` and adds `errorDetails` with
+the equivalent invocation `code` and `retryable`. Address and tool misses use
+the same route-aware discovery action above. A close tool-name miss on a known
+connector may also carry `suggestions`: at most three deterministically ranked
+canonical addresses, with no scores or descriptions. An unknown connector
+stays unscoped and has no suggestions. A catalog-load failure carries only
+`code`, bounded `message`, `retryable`, and any `retryAfterMs`; discovery does
+not inherit later additions to the call-failure envelope.
+
 That route echoes the caller's own arguments back only while they fit a
 512-byte budget, and then whole — never clipped. An error envelope is not
 size-guarded the way a result is, so an unbounded echo would let a large
@@ -393,3 +415,6 @@ duplicate `additionalProperties` branches never reach the caller. A schema the l
 validator cannot evaluate passes through to the provider. Provider error prose
 is not parsed or guessed, so an unknown format remains
 `connector_call_failed`.
+
+Describe's nearby-address list uses the same three-item recovery bound. It
+contains addresses only; it never serializes ranking scores or result prose.

package/documentation/notion.md

@@ -237,6 +237,23 @@ and all deliberately absent: this is a deliberate tool surface, not a mirror of
 the API. Anything missing is reachable through a custom `api()` connector
 beside this one, which remains a first-class path.
 
+The 2026-03-11 contract also offers more fields on create and update. They were
+reviewed after the 0.17.0 drift check and remain deliberately absent:
+
+- `create_page` does not create workspace-private pages, apply templates,
+  choose page placement, or accept expanded icon and cover forms. Those change
+  ownership, start asynchronous content work, control ordering, or depend on
+  file surfaces. They are not extensions of the maintained page/row authoring
+  contract (#408).
+- `update_page_properties` does not lock pages, apply templates, or erase page
+  content. Locking is coordination state, templates finish asynchronously, and
+  `erase_content` permanently deletes every child block through the API. None
+  belongs under an approval named for property replacement (#409).
+
+`trash_page` stays separate and reversible. The current `create_page`,
+`update_page_properties`, and `trash_page` request subsets remain valid against
+the expanded published contract.
+
 There is also **no guarded raw-REST escape hatch** — no `notion_api_get`, no
 `notion_api_mutate`. The convention that permits one
 ([H14](./provider-conventions.md#h14--a-named-tool-must-beat-the-escape-hatch-and-the-escape-hatch-splits-by-safety))