@zackbart/connecta 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -2,6 +2,139 @@
 
 All notable changes to this package are documented here.
 
+## 0.18.1 — 2026-08-18
+
+This patch is the response to one long investigation run against a live
+deployment: a Mixpanel-and-Stripe user-journey reconstruction that rated the
+connectors trustworthy and the ceremony too high. Nothing breaks and no
+constructor changes. The two maintained guides now say the things that
+investigation had to discover the hard way — which questions Insights cannot
+answer, when Mixpanel's `false` is an absent property, which Stripe reads must
+be projected inside the sandbox and why that is a privacy boundary as much as
+a size one, and which fields Stripe search will not filter on. Beside them, a
+new maintained RevenueCat connection lands, with the fact that decides its
+deployment shape stated up front: a RevenueCat secret key reaches exactly one
+project, so several projects are several connectors. A deployment that
+constructs none of the three connections can ignore this release entirely.
+
+### Added
+
+- **`revenuecat()` — a maintained RevenueCat hosted-MCP connection** at
+  `@zackbart/connecta/providers/revenuecat`. OAuth by default (account-scoped:
+  the guide requires `list-projects` first and carries `project_id` into every
+  project-scoped call, stopping on ambiguity); an API v2 secret key as the
+  headless alternative, which binds the connector to one project — the guide's
+  first line names it, and a second project is a second connector with its own
+  key. All 95 documented tools are classified from RevenueCat's tools reference
+  (50 read-only, 15 additive, 29 destructive); `render-paywall-screenshot`
+  carries no access column there and fails closed. Borderline verdicts are
+  argued beside the rows they decide: `create-webhook-integration`,
+  `grant-customer-entitlement`, and `assign-customer-offering` are destructive
+  on consequence, not on verb. RevenueCat publishes six per-domain rate limits
+  and one admission rule cannot honestly cover 95 tools, so `callAdmission`
+  stays with the operator and the guide states the numbers. The maintainer-run
+  drift check accepts `revenuecat` behind `CONNECTA_DRIFT_REVENUECAT_KEY`; no
+  schema digests are recorded until a maintainer runs `--record` against a live
+  project (#433).
+
+### Changed
+
+- **The Mixpanel guide says what Insights cannot answer.** One analysis is one
+  `execute_code` program with one `Get-Query-Schema` fetch; per-user event
+  timelines and sequence questions are out of reach through `Run-Query`
+  (`Get-User-Replays-Data` covers one user only where session replay is on);
+  `false` on a boolean property may be an absent one and must be confirmed with
+  `List-Properties` before it becomes a signal; breakdown responses are
+  flattened one row per combination inside the program with `$overall`
+  dropped. Convention P7 gains the rendering-rule clause this rests on (#430).
+
+- **The Stripe guide names the reads that must be projected and the fields
+  search cannot filter.** Any `stripe_api_read` list or `stripe_api_search`
+  that returns full objects belongs inside `execute_code`, projected before
+  `return` — the reduction keeps customer PII out of the transcript, not only
+  bytes. Charges search takes a documented field set with no `payment_intent`;
+  follow the PaymentIntent's `latest_charge` instead. The account → search →
+  details → read sequence is one program, and decline outcomes are `outcome`,
+  `failure_code`, `failure_message` on the charge (#431).
+
+## 0.18.0 — 2026-08-13
+
+This minor release spends fewer tokens before the first call and answers
+better when a call goes wrong. The always-loaded MCP instructions and tool
+definitions are 44.6% lighter, the `execute_code` description now names the
+deployment's configured connector IDs before the first catalog search, and a
+failed `connecta.describe` entry carries the same typed recovery as a failed
+call. The compatibility change is the floor: Node 22 is now the minimum
+supported release, matching the shipped Docker template, and CI runs one job
+per pull request against it; the Cloudflare Worker target is unchanged. Stripe
+OAuth deployments must drop the connector-wide `mode` — each returned account
+now carries its own. An evaluation of erasable TypeScript syntax in
+`execute_code` programs ended in a recorded refusal, so portable programs
+remain plain JavaScript. A deployment already on Node 22 that lets accounts
+carry their Stripe mode needs no configuration change.
+
+### Added
+
+- **`execute_code` now names the deployment's connectors up front.** Its
+  description carries a connector inventory derived only from the configured
+  registry: canonical IDs in registry order, the executable shortcut when
+  sanitization changes the ID, bounded to 256 serialized bytes with an exact
+  omitted count. A cold model can scope its first catalog search without
+  guessing, and rendering the inventory performs no catalog request and no
+  credential access (#416).
+
+- **Failed `connecta.describe` entries are now as repairable as failed calls.**
+  Each failed entry carries `errorDetails` beside the preserved human text: the
+  invocation path's stable `code` and `retryable`, a route-aware `nextAction`,
+  and up to three deterministic nearby canonical addresses when the connector
+  is known. Caller-authored addresses are clamped everywhere they echo, so
+  hostile input can no longer displace partial results (#417).
+
+### Changed
+
+- **The always-loaded surface got 44.6% lighter.** The MCP instructions and the
+  seven tool definitions now carry route selection, the fail-closed read-only
+  boundary, and the minimum guest syntax — 6,850 bytes instead of 12,358.
+  Selection discipline, runtime differences, worked examples, direct-call
+  options, `get_result` rules, the `connecta.ui` reads-binding shape, and
+  repair guidance moved into the on-demand `usage` skill, which grew to a
+  deliberate 9,000-byte cap and stays byte-identical across deployments.
+  Clients that never fetch the skill keep correct routing from the compact
+  definitions alone (#418).
+
+- **Node 22 is now the minimum supported Node release.** CI and the published
+  engine range now match the Node 22 runtime used by the shipped deployment
+  template. The Worker test project continues to cover the other deployment
+  target (#422).
+
+- **Stripe OAuth mode now belongs to each returned account.** OAuth-backed
+  connectors no longer accept a connector-wide `mode`. Their neutral metadata
+  and guide support mixed live and sandbox accounts, require
+  `list_available_accounts_or_orgs`, and carry its exact `stripe_context` and
+  `livemode` into each account-scoped call. They use the stricter sandbox
+  admission ceiling. Header credentials still require one fixed mode, retain
+  key-prefix contradiction checks, and keep Stripe Connect behavior (#414).
+
+- **The reviewed Notion writes stay narrow.** Newly published workspace-private
+  creation, templates, placement, richer media, locking, and irreversible
+  content erasure do not join the maintained surface. They are distinct
+  ownership, asynchronous, ordering, file, coordination, or deletion workflows,
+  not extra fields on `create_page` or `update_page_properties`. The existing
+  request subsets remain valid, and `trash_page` stays isolated and reversible
+  (#408, #409).
+
+### Fixed
+
+- **The Node template now declares its one reviewed install script.** npm 11 no
+  longer warns that esbuild's install is unreviewed, and npm 12 will not block
+  it. The approval is pinned to `esbuild@0.28.2`; the package smoke reads the
+  generated lockfile and fails if any resolved dependency has an unapproved
+  install script, including a future esbuild version. Local and container
+  installs keep the same `tsx` runtime path (#375).
+
+- The documentation gate now ignores `.claude`, whose nested agent worktrees
+  are separate historical checkouts rather than source in the current tree.
+
 ## 0.17.0 — 2026-08-13
 
 This minor release makes catalog discovery faster and its answers more exact.

package/README.md

@@ -2,129 +2,94 @@
 
 ![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
 
-One place for AI agents to connect to the tools you choose.
+One MCP endpoint. The integrations you chose. Your agent reaches them by
+writing code instead of loading a thousand tool definitions.
 
-Connecta gives an agent a single MCP endpoint instead of making it connect to
-every service separately. You decide which integrations are available and
-Connecta holds their credentials, and the agent mostly works by writing
-ordinary JavaScript that Connecta runs in a sandbox next to them — with a few
-explicit tools for the jobs a program is the wrong shape for, destructive calls
-among them.
+## The mental model
 
-```mermaid
-flowchart LR
-    Agent["AI agent"]
-    Integrations["The integrations you chose"]
-
-    subgraph Connecta["Connecta: one MCP endpoint; credentials stay here"]
-        Sandbox["execute_code<br/>server-side sandbox"]
-        Explicit["Explicit tools<br/>destructive calls, search, auth"]
-    end
-
-    Agent -->|"writes a program"| Sandbox
-    Agent -->|"one deliberate call"| Explicit
-    Sandbox --> Integrations
-    Explicit --> Integrations
-```
+You ask your agent a question that touches a service — Linear, Stripe, an
+internal API, anything you have connected. Here is what happens:
 
-## Why Connecta
+1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
+   no matter how many services sit behind it.
+2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
+   your integrations. The program can search for tools, call them, chain the
+   calls, and shape the result.
+3. Only the answer comes back into the agent's context — not raw pages of
+   API output.
+4. If the agent wants to change something — create, update, delete — it
+   cannot do that from a program. It makes one explicit call, and your MCP
+   client can put that call in front of you first.
 
-- **One connection.** Configure clients once, even as integrations change.
-- **Seven tools, not seven hundred.** A program can search the catalog, chain
-  calls, and trim the results before the agent ever sees them — so nothing has
-  to be loaded up front.
-- **Safer access.** Credentials stay server-side — the program never sees them
-  — and consequential actions remain explicit and individual.
-- **Named client access.** A Clerk operator can issue and revoke one-time,
-  hashed Bearer tokens for MCP clients that support header authentication.
-- **Your deployment.** Connecta runs on Node, Docker, or Cloudflare Workers,
-  with configuration you can review and version.
+Credentials never leave the server. The program never sees them, and neither
+does the agent.
 
-## Start here
+```mermaid
+flowchart TB
+    Client["Your MCP client<br/>Claude, Cursor, …"]
 
-Create the prescribed Node deployment:
+    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools only"]
+        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
+    end
 
-```sh
-npx @zackbart/connecta init my-connecta
-cd my-connecta
-npm install
-CONNECTA_TOKEN=dev-token npm start
-```
+    Integrations["The integrations you chose<br/>Linear · Stripe · Notion · your HTTP API · any MCP server"]
 
-Point an MCP client at `http://localhost:8787/mcp` with
-`Authorization: Bearer dev-token`. The generated project is deliberately small:
-
-```text
-my-connecta/
-├── src/index.ts       # connectors, auth, storage, public URL
-├── src/file-activity.ts # deployment-owned activity store, wired on request
-├── package.json       # exact Connecta and QuickJS versions
-├── tsconfig.json
-├── Dockerfile         # the same source, containerized
-├── docker-compose.yml # one service, state on a named volume
-├── .dockerignore
-├── .env.example
-├── .gitignore
-├── AGENTS.md
-├── CLAUDE.md -> AGENTS.md
-└── README.md
+    Client -->|"one connection"| Sandbox
+    Client --> Explicit
+    Sandbox -->|"reads"| Integrations
+    Explicit -->|"writes"| Integrations
 ```
 
-The same project runs as a long-lived container without changing a line of it:
-
-```sh
-cp .env.example .env    # set CONNECTA_TOKEN
-docker compose up -d --build
+This is the kind of thing the agent writes, not you:
+
+```js
+async () => {
+  const { nodes } = await tracker.list_issues({ state: "started" });
+  const byOwner = {};
+  for (const issue of nodes) {
+    (byOwner[issue.assignee?.name ?? "unassigned"] ??= []).push(issue.identifier);
+  }
+  return byOwner;
+}
 ```
 
-For an agent setting this up, the contract is:
-
-1. Edit `src/index.ts`; do not copy Connecta internals into the deployment.
-2. Keep the required `executor: quickJsExecutor()` configuration; without an
-   executor the deployment refuses to boot.
-3. Keep secrets in environment variables or a secret store, never source.
-4. Add connectors explicitly: import a maintained prebuilt provider
-   constructor when one exists, otherwise write a deliberate `remoteMcp()` or
-   `api()` connector. There is no registry to browse and nothing registers
-   itself.
-5. Run `npm run typecheck`, start the server, and run
-   `CONNECTA_TOKEN=... npm run doctor`. Doctor checks health, the executor, and
-   the exact seven-tool model-facing surface, then executes a harmless sandbox
-   program. The bearer stays in the environment rather than command history.
-
-The operator surface is the same in both shapes and off until you say so:
-Clerk sign-in, the credential vault, access-token issuance, and payload-free
-activity ship as commented configuration, each one a variable and an
-uncommented block away. The generated `README.md` walks through all four, and
-the [Worker example](./examples/worker/) does the same for KV and D1.
-
-Already have a deployment on an older version? `init` deliberately refuses to
-merge into it, so bringing one current is its own procedure:
-[Upgrading an existing deployment](./documentation/upgrading.md) is the
-runbook, written for the agent working inside that project.
-
-The template refuses to merge into an existing directory, so initialization
-cannot overwrite another project. Its generated programs have no filesystem,
-environment, arbitrary network, imports, or timers; only explicitly read-only
-connector tools are reachable. Unannotated or write-capable calls stay
-individual and cross `call_destructive_tool`, where the MCP host can ask the
-operator for approval.
-
-There are two deployment shapes and no others:
-
-- [Node, local or Docker](./templates/node/) — what `init` copies
-- [Cloudflare Worker deployment](./examples/worker/)
-- [Subsystem documentation](./documentation/)
-
-Every deployment configures a sandbox: QuickJS on Node or a Dynamic Worker on
-Cloudflare. Construction fails with an actionable error when the executor is
-missing, so the model-facing interface is always the same seven tools.
-
-## Project status
-
-Connecta is built for its author's deployments first and is still evolving.
-Breaking changes are expected before 1.0.
-
-Read the [ethos](./ethos.md) for the product's principles, the
-[changelog](./CHANGELOG.md) for releases, and [security policy](./SECURITY.md)
-for vulnerability reporting.
+Fifty issues in, one small object out. Your context window notices.
+
+## What you can do with it
+
+- **Put every MCP server you use behind one connection.** Add or remove
+  services in a config file; your client never changes.
+- **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
+  generated tool sprawl is the problem, not the fix.
+- **Use maintained connections** for Cloudflare, Linear, Mixpanel, Notion,
+  RevenueCat, and Stripe — known endpoints, auth defaults, and vetted read/write
+  classifications, imported one at a time.
+- **Let the agent work in code.** Search, chain, filter, join, and reduce
+  inside the sandbox instead of round-tripping every call through the model.
+- **Keep writes deliberate.** Only tools marked read-only run in a program.
+  Everything else is a separate, visible call your client can gate.
+- **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,
+  from the same small deployment file.
+
+There is also an operator surface, off until you turn it on: sign-in, an
+encrypted credential vault with rotation, revocable per-client tokens, and a
+payload-free activity log.
+
+Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
+service. Those are decisions, and the [ethos](./ethos.md) records each one
+and why.
+
+## Getting started
+
+Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
+ask it to set up a Connecta deployment; the
+[documentation](./documentation/) covers every subsystem if you want to go
+deeper, and [upgrading](./documentation/upgrading.md) an existing deployment
+is its own runbook.
+
+## Status
+
+Built for its author's deployments first and published openly. Breaking
+changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
+[security policy](./SECURITY.md).

package/dist/catalog-service.d.ts

@@ -72,6 +72,11 @@ interface CatalogFailureDetail {
     retryable: boolean;
     retryAfterMs?: number;
 }
+interface CatalogDescriptionFailureDetail extends CatalogFailureDetail {
+    nextAction?: NonNullable<CallErrorDetails["nextAction"]>;
+    /** Nearby canonical addresses, ranked deterministically by tool name. */
+    suggestions?: string[];
+}
 export interface CatalogSearchPage {
     entries: CatalogSearchEntry[];
     total: number;
@@ -109,6 +114,7 @@ export interface CatalogDescription {
     outputSchema?: unknown;
     annotations?: ToolDef["annotations"];
     error?: string;
+    errorDetails?: CatalogDescriptionFailureDetail;
 }
 export interface ResolvedCatalogTool {
     connector: Connector;

package/dist/catalog-service.js

@@ -16,6 +16,7 @@ const MAX_QUERY_TERM_LENGTH = 64;
  * of the deployment.
  */
 const MAX_IDENTITY_CONNECTORS = 3;
+const MAX_DESCRIBE_SUGGESTIONS = 3;
 const encoder = new TextEncoder();
 /** Clip one echoed query term without splitting a non-BMP code point. */
 function boundedQueryTerm(term) {
@@ -80,6 +81,39 @@ function recoveryQuery(address) {
     const candidate = separator >= 0 ? address.slice(separator + 1) : address;
     return boundedEchoText(candidate.replaceAll(/[._-]+/g, " ").trim() || address);
 }
+function editDistance(left, right) {
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        const current = [leftIndex + 1];
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            current.push(Math.min(previous[rightIndex + 1] + 1, current[rightIndex] + 1, previous[rightIndex] +
+                (left[leftIndex] === right[rightIndex] ? 0 : 1)));
+        }
+        previous = current;
+    }
+    return previous[right.length];
+}
+/** Nearby names only; descriptions never influence describe-miss recovery. */
+function describeSuggestions(connectorId, attemptedName, tools) {
+    const attempted = attemptedName.toLowerCase();
+    return tools
+        .map((tool, order) => {
+        const name = tool.name.toLowerCase();
+        return { tool, order, distance: editDistance(attempted, name) };
+    })
+        .filter(({ tool, distance }) => {
+        const longest = Math.max(attempted.length, tool.name.length);
+        return (attempted.includes(tool.name.toLowerCase()) ||
+            tool.name.toLowerCase().includes(attempted) ||
+            distance <= Math.max(2, Math.floor(longest * 0.4)));
+    })
+        .sort((left, right) => left.distance - right.distance || left.order - right.order)
+        .map(({ tool }) => `${connectorId}.${tool.name}`)
+        // A clipped address would no longer be canonical. Omit an implausibly
+        // large catalog name instead of letting one suggestion erase the page.
+        .filter((address) => boundedEchoText(address) === address)
+        .slice(0, MAX_DESCRIBE_SUGGESTIONS);
+}
 /** Serialize once and count the exact bytes the MCP adapter would emit. */
 export function boundedDiscoveryText(value, hint) {
     const text = JSON.stringify(value);
@@ -734,17 +768,48 @@ export class CatalogService {
         });
         return resolved.map(({ address, resolved: addressResolution }) => {
             if (!addressResolution) {
-                return { address, error: `Unknown address "${address}"` };
+                const message = `Unknown address "${boundedEchoText(address)}"`;
+                return {
+                    address: boundedEchoText(address),
+                    error: message,
+                    errorDetails: {
+                        ...framingError("unknown_address", message),
+                        nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
+                    },
+                };
             }
             const catalog = catalogs.get(addressResolution.connector.id);
             if (catalog instanceof Error) {
-                return { address, error: catalog.message };
+                const classified = classifyCallError(catalog, "catalog_lookup_failed");
+                const message = boundedEchoText(classified.message);
+                return {
+                    address: boundedEchoText(address),
+                    error: message,
+                    errorDetails: {
+                        code: classified.code,
+                        message,
+                        retryable: classified.retryable,
+                        ...(classified.retryAfterMs === undefined
+                            ? {}
+                            : { retryAfterMs: classified.retryAfterMs }),
+                    },
+                };
             }
             const tool = catalog?.find((item) => item.name === addressResolution.toolName);
             if (!tool) {
+                const message = `Unknown tool "${boundedEchoText(addressResolution.toolName)}" on connector "${addressResolution.connector.id}"`;
+                const suggestions = describeSuggestions(addressResolution.connector.id, addressResolution.toolName, catalog ?? []);
                 return {
-                    address,
-                    error: `Unknown tool "${addressResolution.toolName}" on connector "${addressResolution.connector.id}"`,
+                    address: boundedEchoText(address),
+                    error: message,
+                    errorDetails: {
+                        ...framingError("unknown_tool", message),
+                        nextAction: this.searchRecovery({
+                            query: recoveryQuery(addressResolution.toolName),
+                            connector: addressResolution.connector.id,
+                        }, "Find the connector's current canonical tool address."),
+                        ...(suggestions.length > 0 ? { suggestions } : {}),
+                    },
                 };
             }
             const input = tool.inputSchema ?? { type: "object" };

package/dist/execute.d.ts

@@ -6,6 +6,8 @@ import { InvocationFailure } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type { Executor, ExecutorProvider, Logger } from "./types.js";
 export declare const EXECUTE_MAX_BATCH_CALLS = 10;
+/** Complete entries plus an exact omission count, all inside this byte cap. */
+export declare const CONNECTOR_INVENTORY_MAX_BYTES = 256;
 /**
  * Default budgets for `connecta.emit`. The byte budget is a transport bound,
  * not a context bound — emitted image/audio blocks reach the model as media,

package/dist/execute.js

@@ -4,7 +4,7 @@ import { boundedDiscoveryText, CatalogService, DiscoveryPolicyError, flatSearchR
 import { errorResult, jsonResult } from "./meta-tools.js";
 import { guardExecuteResultValue, MAX_EXECUTE_LOG_CHARS, truncateExecuteText, } from "./executor-result.js";
 import { ExecutorAdmissionError, ExecutorExecutionError, isAdmittingExecutor, } from "./executor-admission.js";
-import { classifyCallError } from "./errors.js";
+import { boundedEchoText, classifyCallError } from "./errors.js";
 import { InvocationFailure, InvocationService, } from "./invocation.js";
 import { hasConnectorGuides } from "./skills.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
@@ -12,6 +12,8 @@ import { isExplicitlyReadOnly } from "./tool-safety.js";
 const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
 const EXECUTE_HOST_CALL_TIMEOUT_MS = 15_000;
+/** Complete entries plus an exact omission count, all inside this byte cap. */
+export const CONNECTOR_INVENTORY_MAX_BYTES = 256;
 /**
  * Default budgets for `connecta.emit`. The byte budget is a transport bound,
  * not a context bound — emitted image/audio blocks reach the model as media,
@@ -996,24 +998,47 @@ function discardedEmitsText(emitted) {
     ];
     return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
 }
-const executeDescription = (emitBudgets, connectorGuides) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool. execute_code is the primary surface for everything wider: make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
+function connectorInventory(connectors) {
+    const prefix = "Connectors: ";
+    if (connectors.length === 0)
+        return `${prefix}none.`;
+    const entries = connectors.map((connector) => {
+        const shortcut = sanitizeIdentifier(connector.id);
+        return shortcut === connector.id
+            ? connector.id
+            : `${connector.id} (shortcut ${shortcut})`;
+    });
+    const shown = [];
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (entry === undefined)
+            break;
+        const candidate = [...shown, entry].join(", ");
+        const omitted = entries.length - index - 1;
+        const suffix = omitted > 0 ? `; +${omitted} more.` : ".";
+        const serialized = prefix + candidate + suffix;
+        if (boundedEchoText(serialized, CONNECTOR_INVENTORY_MAX_BYTES) !== serialized) {
+            break;
+        }
+        shown.push(entry);
+    }
+    const omitted = entries.length - shown.length;
+    if (omitted === 0)
+        return `${prefix}${shown.join(", ")}.`;
+    return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
+}
+const executeDescription = (emitBudgets, connectorGuides, connectors) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool. execute_code is the primary surface for everything wider: make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
+
+${connectorInventory(connectors)}
 
-Write an async arrow function. Portable programs use no ambient capabilities. Use only:
-- Connector globals call sanitized <connectorId>.<toolName>(args): non-identifier characters become "_"; prefix a leading digit; suffix a reserved word.
-- connecta.call(address, args) and connecta.batch(calls) use canonical addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure it.
-- top-level search_tools returns { connectors: [{ id, tools }], total, offset, limit, hasMore }; connecta.search returns { tools, total, offset, limit, hasMore }; connecta.describe returns { tools }.
-- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Check address, description, requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Select by fit; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Every required key needs task or prior-result data; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. Describe one address or an addresses array. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute.${connectorGuides ? " guideRequired: true = stop. Describe clears only schema_truncated; otherwise return its exact guide, fetch with top-level skills, then write the informed call." : ""}
+Write one plain-JavaScript async arrow function. Use only:
+- <connectorId>.<toolName>(args) for a sanitized shortcut, or connecta.call(address, args) for a canonical address.
+- connecta.search(args), connecta.describe(args), and connecta.batch(calls) for discovery and independent read-only calls.
 - connecta.emit(block) — { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only; ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid/over-budget throws.
-- connecta.ui(html, options?) — one success-only view. One arg is display-only; reads use { reads: { name: { address, fixedArgs?, viewArgs? } } } and markup calls connecta.read(name, args). Admission and one budget, not two, apply; a second, over-budget, or invalid call throws catchably; the model reads the return value, not the view; return the initial summary from its variables.
+- connecta.ui(html, options?) for one success-only view; return the same initial summary the HTML renders.
 - console.log(...) — captured.
 
-QuickJS blocks imports and has no fetch, process, timers, crypto, or WebSocket. Dynamic Workers require only { loader }; bindings/modules/globalOutbound violate the contract. Then env maps are empty; node:fs/http/https are absent; outbound fetch/WebSocket/node:net/tls are denied; DNS is 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 runtime-only capabilities; QuickJS fails.
-
-Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }
-
-A caught Connecta failure keeps its message and exposes code, retryable, and details; batch uses the same fields. Branch on fields, never prose. Never retry retryable: false, or rate_limited immediately; portable code cannot wait. Return JSON; reduce large results before they truncate.
-
-Plain JS. Compact schemas are TypeScript-like: write the property names they display; never guess positions or aliases.`;
+Programs have no portable ambient capabilities. Return JSON and reduce large results before they truncate. Fetch skills({ name: "usage" }) once for selection rules, exact result shapes, repair, examples, guide handling${connectorGuides ? ", connector-guide rules" : ""}, and runtime differences.`;
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(server, registry, ctx) {
     // Resolved once so the description and the collector cannot disagree about
@@ -1022,6 +1047,7 @@ export function registerExecuteTool(server, registry, ctx) {
         maxBytes: resolveEmitBudget(ctx.maxEmittedBytes, EXECUTE_MAX_EMITTED_BYTES),
         maxBlocks: resolveEmitBudget(ctx.maxEmittedBlocks, EXECUTE_MAX_EMITTED_BLOCKS),
     };
+    const connectors = registry.listConnectors();
     const handler = createExecuteTool(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, {
         ...(ctx.discoveryConcurrency !== undefined
             ? { discoveryConcurrency: ctx.discoveryConcurrency }
@@ -1034,11 +1060,11 @@ export function registerExecuteTool(server, registry, ctx) {
         ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
     });
     server.registerTool("execute_code", {
-        description: executeDescription(emitBudgets, hasConnectorGuides(registry.listConnectors())),
+        description: executeDescription(emitBudgets, hasConnectorGuides(connectors), connectors),
         inputSchema: z.object({
             code: z
                 .string()
-                .describe("One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing. So does aborting on a missing tool match or result key — re-search, describe, or read the result's actual keys here instead."),
+                .describe("One complete JavaScript async arrow function that discovers, calls, and returns the reduced answer."),
             diagnostics: z
                 .boolean()
                 .optional()