@zackbart/connecta 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -2,6 +2,97 @@
 
 All notable changes to this package are documented here.
 
+## 0.40.0 — 2026-11-02
+
+This release makes warm Connecta calls on Workers cheaper in storage and closes a credential gap on OAuth remote MCP connectors. Deployments need no configuration change or migration, unless they use the Eve helper.
+
+**Eve helper:** `@zackbart/connecta-eve` now requires exactly Eve 1.0.0-rc.1. Eve 0.90 apps must upgrade Eve together with the helper and, when installed, upgrade `@vercel/connect` to `^2.7.0`. The core package and non-Eve deployments are not affected by this change.
+
+**Security:** an OAuth remote MCP connector no longer sends a passive handshake, catalog request or tool call without a credential if its tokens are removed mid-request. It returns OAuth recovery before sending instead. Before this, a server accepting anonymous requests could receive that request without the connector's credential.
+
+**Native pools:** native pools now always list `authorize_connector`, so an agent on a pool without `execute_code` can get the operator a handoff for a connector that needs authorization. On those pools the repaired connector's tools appear only after the host refreshes its tool list, usually by reconnecting; pools with `execute_code` can reach them from a program straight away. Anything that compares a native pool's tool list exactly will see one more tool. Meta endpoints keep the same six tools.
+
+**Storage work per call:** warm remote MCP catalog resolution now takes four D1 round trips instead of six on modern servers and five on legacy ones. Warm agent admission takes two reads instead of four. Warm OAuth calls read the grant 9 times instead of 11 on modern servers and 12 instead of 13 on legacy ones. A warm isolate reuses a stored catalog it has already validated, after the same freshness and partition checks. The catalog and admission round trips were measured with injected latency on local workerd, and the OAuth counts come from request-budget tests. None of this has been measured in production.
+
+### Changed
+
+- Read agent token admission state in one fresh D1 or SQLite statement, reducing warm admission and last-seen observation from four reads to two while preserving next-request rotation and revocation enforcement.
+- **Breaking:** `@zackbart/connecta-eve` now requires exactly Eve 1.0.0-rc.1; Eve 0.90 apps must upgrade Eve together with the helper and, when installed, upgrade `@vercel/connect` to `^2.7.0`. Align installed-consumer probes and upgrade guidance with the tested release candidate. Later candidates and stable 1.0 require a compatibility check.
+- Reduce grant reads on warm OAuth remote MCP calls while retaining fresh catalog acceptance, disconnect, token rotation and dispatch checks. Keep the separate invocation token read so same-epoch invalidation refuses writes with OAuth recovery before dispatch, and expiry changes are observed before early renewal.
+- Reuse validated stored catalogs within a warm isolate after checking stored chunks, partition identity, expiry and the fresh generation fence. Retained facts are immutable and bounded; credential redaction still runs per request.
+
+### Fixed
+
+- Reduce warm remote MCP catalog storage round trips by batching locating reads and private/public manifest probes while preserving fresh generation and OAuth credential acceptance checks.
+- Keep authorization recovery available on native pools without code by listing authorize_connector with the granted connector ids, even when a connector's catalog cannot load.
+
+### Security
+
+- Require a credential on passive OAuth remote MCP sends, including handshakes, catalog requests and tool dispatches, regardless of provider replacement. Return OAuth recovery before sending when the SDK cannot obtain one, and count a verified unsent write as failed without reconciliation. Explicit authorization flows retain their challenges; writes that may already have left remain unknown.
+
+## 0.39.0 — 2026-10-30
+
+This release makes Connecta faster and leaner for agents and operators on Cloudflare Workers. A warm search over remote MCP connectors with cached catalogs no longer reconnects to them: an all-legacy warm search makes no downstream requests. Repeated storage reads are memoized per request, and catalog chunks are read in batches. OAuth tokens refresh before they expire instead of failing the first write after expiry. Legacy negotiation verdicts last six hours, with bounded recovery when a server changes protocol era. A connector that recently hung or failed slowly is reported in `catalogErrors` and skipped by unscoped search for about a minute, and unscoped discovery has a total budget. With one hung connector, three consecutive searches went from 30 s each to 5 s, 11 ms and 8 ms.
+
+The operator UI shows stored connector status at once, then refreshes it with a live read from the browser. Detail reads have an 8 s deadline, load eight at a time, and park a connector that doesn't respond instead of retrying it repeatedly. A credential can be tested before it is saved, and failures are reported as rejected, scope, unreachable, timeout or failed. A credential connector's status shows when it was last verified.
+
+Agents get smaller, clearer responses. The `execute_code` description declares the guest API's shapes. `invalid_args` returns bounded validation findings and a schema-generated example when available; API hatches point to operation details instead. Errors never echo submitted strings or object keys; non-sensitive numeric bounds may include the submitted number. Each `fields` description says where its paths start. `*_api_details` returns the operation's response fields, and catalog search can return a fully determined API read as a ready call. Search rows are smaller, program searches default to TypeScript signatures, and tests cap the size of the always-loaded surface. Meta-tool names in agent text follow the serving surface, so native pools read correctly. Remote cache partitions use a deployment key derived by `encryptedCredentialVault()`, or supplied by a custom vault's `storageDigestKey()`. Without that method, partitions remain exact but cached entries are reused only within one process or isolate.
+
+Breaking changes:
+- Pools must list only people or only agents. Split mixed pools before upgrading ([Split mixed pools](./documentation/pool-membership-upgrade.md)).
+- Search rows move `connectorTitle`, `guide` and `guideSummary` into a page-level `connectors` map.
+- Programs that read JSON schemas from a default `connecta.search` must pass `includeSchemas: "json"`.
+- `invalid_args` drops `repair` and `issues[].code` in favour of `validation`.
+- The published `GuestApi.emit` type no longer accepts a paged handle.
+- `@zackbart/connecta-eve` requires Eve `>=0.90.0 <0.91.0`; Eve apps upgrade together and remove their undici override.
+
+Plain `/mcp` now routes a person to their single pool. Each remote connector refills its catalog cache once after upgrade. Before upgrading, split mixed pools, update clients that consume the changed response shapes or guest types, and upgrade Eve apps as described above. Other deployments need no configuration changes.
+
+### Added
+
+- Credentials can be tested before they are saved. `PUT /ui/credentials/<id>` with `verify: "test"` tests the candidate in memory under `discovery.probeTimeoutMs` and stores it only if the test passes; `verify: "skip"` (the default) stores it unverified, so an outage never blocks a replacement. Tests answer a typed failure class (`rejected`, `scope`, `unreachable`, `timeout`, `failed`) instead of a bare `ok`, `CredentialTestResult` gains an optional `failure`, and the operator page shows a stored last-verified record for credential connectors, bound to the revision each vault save now seals, so a concurrent replacement is never shown as verified. Vaults gain an optional `snapshot()` and per-save `revision` metadata. `remoteMcp()` credential tests now test the value they are given rather than refusing an unsaved one.
+- `eval:agent --target worker` runs the agent tasks and graders against the production Worker shape (local D1, the Dynamic Worker executor and Access) under `wrangler dev`, refuses the tasks it cannot serve, records the target in every result, and pairs node with worker results only through `eval:compare --cross-target`.
+- The agent eval harness reports efficiency medians, response bytes per tool, guide fetches and pass@k/pass^k reliability in `eval:compare`, the `eval:agent` end-of-batch summary and the HTML report.
+- `eval:agent` and `eval:smoke` take opt-in `--latency-ms`, `--hung-connector`, `--unauthorized-connector` and, on workerd, `--d1-latency-ms`. The settings are recorded in every result, and `eval:compare` refuses to pair runs whose injection differs.
+- Standard `*_api_details` answers now carry a capped `response` section: the operation's declared success-response paths, listed in the coordinates the read and write tools' `fields` argument takes, with the anchor stated, so programs can write `fields` filters without a sampling read. It lists at most 100 paths and 4,096 characters of path JSON, with an explicit `omitted` count. It promises no readability: value safety may still withhold or redact any value at read time. A best-effort `withheld` hint names the listed paths its rules always withhold.
+- Search returns fully determined API reads as `readyCalls` on the first page: `{ address: "<id>.<x>_api_read", args: { path }, classification: "read", summary }`, ready to pass unchanged to `connecta.call` or `call_tool`. Only a reviewed GET served by the hatch's read tool with no path template, required parameter or required body qualifies, and every object word of the query must belong to a whole resource name, a path segment or the operationId, stated in order (summaries and parts of compound segments never count); an exact name, or a complete authored tool whose name adds nothing to the query, suppresses ready calls; anything needing an id, method choice or argument still routes through `_api_search` and `_api_details`. Ready calls pass the same endpoint, connector, safety, hidden-tool and grant checks as other discovery, are computed offline, and offer only the top-ranked operation per connector, at most three per page. Listing Granola notes, Vercel deployments or Stripe customers now takes two host calls instead of four.
+
+### Changed
+
+- The `execute_code` connector inventory names every configured connector instead of truncating with `+N more` at 256 bytes. Its cap is now 1,024 bytes; titles appear only where they say more than the id, and past the cap titles, then optional guide pointers, give way before whole entries do. Guide pointers read as the call to make: `read first: skills({name:"connector:<id>"})` for a required guide, `guide: skills({name:"connector:<id>"})` otherwise. `skills({ name })` and `connecta.skill(name)` serve a connector's guide by its bare id; `usage` and `investigate` stay reserved for the built-in skills. Program errors name the engine error once (`Program TypeError: …`, not `Program TypeError: TypeError: …`), and a failed program that read a result field such as `data` or `tools` off an unawaited `connecta.*` call, detected at runtime, gets the hint `connecta.* returns a Promise; await it`.
+- The always-loaded agent surface is smaller and capped in CI. `search_tools`'s output schema defines its typed failure and authorization handoff once under `$defs` instead of once per field (4,642 to 3,622 characters), with every handoff field still typed. The full routing rule is stated once, in the server instructions; `call_tool` and `search_tools` describe only their own scope, and the `usage` skill points to the instructions instead of repeating a routing table. The built-in `investigate` skill is now domain-neutral guidance for investigations spanning several services, and the `execute_code` description no longer advertises it; `skills` still lists it.
+- Search and catalog reads serve a remote MCP connector's complete, unexpired cached catalog without connecting. A warm search over cached legacy (2025, stateful-session) connectors no longer pays an `initialize`, `notifications/initialized`, standalone SSE `GET` and session `DELETE` per connector. A miss, expiry, explicit `ttlMs: 0`, invalidation, or credential, token or OAuth epoch change still connects. The read never seals, binds or refreshes an OAuth grant and never claims a cache generation. A cached catalog does not validate the downstream credential: an expired or revoked credential surfaces on the next call, resource read or credential test, not in search.
+- Repeated storage reads within one request are shared where staleness inside that request is safe, and catalog chunks are read together. The shared reads are the protocol-version verdict, catalog generation reads that only locate an entry, and the credential reads behind status, drift and the operator UI card. OAuth tokens and epochs, refresh and compare-and-set reads, disconnect checks, the catalog generation fence and the credential a call sends still read storage every time; any write in the same isolate clears the shared value at once, and runtimes without weak references share nothing. On D1, a warm OAuth remote MCP call drops from 21 to 18 queries, an expired-token refresh from 51 to 48 statements, a cold-isolate catalog load from 8 to 5, and an operator UI connector detail from 12 to 8.
+- Unscoped search now remembers a connector whose discovery timed out or failed slowly and skips it for up to 60 seconds, reporting it in `catalogErrors` with `retryAfterMs`. Each connector gets at most 5 seconds and the whole fan-out ends within a 9-second budget. Records are typed facts partitioned by owner and configuration, lapse on a credential change, and clear on recovery. Scoped search, describe and calls still reach the connector. Records are kept per owner, admitted endpoint and value-free described configuration, and health storage starts only within the discovery budget and is always awaited. A healthy connector whose catalog always takes more than 5 seconds can stay out of unscoped search until a scoped search or another longer-deadline operation warms its complete catalog.
+- **Breaking:** `@zackbart/connecta-eve` now requires Eve 0.90 (`>=0.90.0 <0.91.0`) and is tested against Eve 0.90.0; Eve 0.86 apps must upgrade Eve to 0.90.0 together with the helper, including Eve's own 0.87–0.90 breaking changes to app code. Eve 0.90.0 pins undici 8.12.3, so remove the app's `eve` undici override (npm `"eve": { "undici": "8.12.3" }`, pnpm `"eve@0.86.0>undici": "8.12.3"`) after upgrading.
+- Every `fields` argument now states where its paths start, with one valid example, in its schema description: `the result` for named reads, `each item in items` for named lists and searches, and `the response body in data` for `*_api_read` and `*_api_write`. Anchors are unchanged. Below the first segment, named tools refuse an undeclared property only inside an object their schema closes with `additionalProperties: false`, with `invalid_args` naming the entry position, the segment and the declared properties; first-segment checks are unchanged. A declared path the response lacks is never refused. Hatch reads and writes still check only the first segment before dispatch, and now return `warnings` naming each `fields` entry that matched nothing in a nonempty response, with the properties the operation declares where matching stopped and never the response's own keys. Warnings are bounded to 10 of at most 512 characters and 4,096 characters together, reviewed vendor warnings included, followed by an omitted count.
+- **Breaking:** The `execute_code` description now declares compact shapes for the guest API's arguments and results instead of naming undeclared types, including the exact authored block variants `emit` accepts and the native blocks it forwards from `result.content`. It explains in plain sentences that search and describe return objects, that a call result over 1 MiB returns a paged handle, and that every guest function except `emit` spends a host call. The published `GuestApi` types `describe`'s `address` as `string` and `addresses` as `string[]`, and its `emit` no longer accepts a paged handle, which the host always refused.
+  
+  Migration: TypeScript programs that pass a `connecta.call` result straight to `connecta.emit` must first narrow it, because a call result may be a paged handle: check `result.format !== "paged"` before emitting, and page and reduce a paged result with `connecta.result` instead. Runtime behaviour is unchanged.
+- Guest functions are listed once in an internal registry. It now generates the guest runtime's `connecta` namespace, the execute_code budget admission for each function, and the compact guest declaration in the execute_code description. The guest runtime source, the execute_code description, the usage skill and `tools/list` are unchanged byte for byte, and so is `GuestApi`.
+- Remote MCP catalog-cache and negotiation-verdict partitions, and connector-health records, are now deployment-keyed. Their inputs enter stored keys through HMAC-SHA-256 under a key that is never stored. Those inputs are each connector's cache configuration, including every configured URL in full and its header values, plus operator-managed and request-resolved credentials, custom connector credential values, OAuth token responses and the described configuration. `encryptedCredentialVault()` derives that key from its credential key and exposes it through a new optional host-only vault method, `storageDigestKey()`. Without a vault, or with a custom vault that lacks the method, each process or isolate uses its own random key, so cached remote catalogs, verdicts and health records are reused within that process or isolate only. Partitioning by owner, configuration, credential, token and epoch is unchanged. After the upgrade, each remote connector refills its cache once with one handshake and catalog listing. Earlier entries are not read and expire on their own TTLs.
+- A remote MCP connector keeps a legacy negotiation verdict for six hours instead of five minutes. A legacy server therefore no longer pays a `server/discover` probe and a verdict write every five minutes; that was 11 probes in an hour of once-a-minute calls. Era changes are still noticed. A server that stops answering the legacy handshake is renegotiated in the same connect. A server that adds the modern era but still answers the legacy handshake is adopted when the verdict expires. A modern verdict still lasts five minutes. A downgraded server's first refusal now deletes it, so the next call renegotiates instead of failing until the verdict expires. A refusal here means an HTTP 400 whose body is empty or is not a recognized modern error; a modern server's `HeaderMismatch`, `MissingRequiredClientCapability` or `UnsupportedProtocolVersion` keeps the verdict. A remote MCP write answered with a 4xx that carries no JSON-RPC error is now reported as an unknown outcome rather than a known refusal.
+- **Breaking:** Every `invalid_args` now repairs the call in one turn. `validation` is the single recovery envelope: up to eight `{ path, expected, received? }` findings that state the actual bound, allowed values, accepted keys or selector shape (`/limit: expected at least 5, received 4`), plus one valid `example` synthesized from the published schema. A refusal never contains a submitted string or object key: paths name only declared properties and indices (`<key>` otherwise), and schema literals at `writeOnly` positions are never rendered. API hatches withhold examples and point to `*_api_details`; `conditionalRequirements` no longer renders `if`/`then`/`else` conditions. Maintained providers' own checks report every problem at once, starting with GitHub `search_scoped` and `list_scopes` and every `fields` path. Responses no longer carry `repair` or `validation.issues[].code`; custom connectors may still pass both to `ConnectorCallError`, which folds `repair` into `validation`.
+- Contributors: a maintained provider keeps its eval fake, tasks and deployment wiring in its own unshipped `src/providers/<name>/eval/` folder, and `providers:generate` registers it with the eval harness and appends a `documentation/providers.md` setup skeleton for a provider without one. Granola moved to this layout; adding a provider now needs no shared eval, Vitest or task-list edit. No published API or package content changes.
+- Contributor tests now hold downstream-request, D1 round-trip and SQL-statement ceilings for the common request shapes (warm and cold-isolate remote MCP calls with header auth and OAuth, refresh after a 401 and before expiry, an `api()` credential call, an unscoped warm search, a five-call program and operator UI connector detail reads) on a production-shaped fixture with a sealed vault, Cloudflare Access and a D1 activity sink. Runtime behavior is unchanged.
+- Plain `/mcp` now admits a non-maintainer person listed in exactly one pool and serves them that pool exactly as `/mcp/<pool>` does: its tools, `readOnly`, `surface`, `executeCode` and `description`. Maintainers keep the whole catalog; zero or several memberships keep the same 404, logged as `not_maintainer` or the new `ambiguous_pool`, and construction warns about people in several pools, also listed in `describeConfig().peopleInSeveralPools`. Result handles and auth or downstream-input continuations are bound to both the requested path and the admitted pool, so handles minted before this release no longer page. The member page shows `/mcp` as a single-pool member's address.
+- Connecta-authored agent text and maintained providers name routes with the names of the surface serving them, resolved when the text is built, instead of spelling meta-tool names. The six-tool surface is byte-identical. Native pools no longer rewrite a caller's unknown tool name, programs on native pools see native recovery wording in failures they catch, and native pools serve provider notes, schema descriptions and authorization errors in complete native phrases with that pool's paging. Custom connectors can build such text from the new optional `ConnectorContext.routes` (`AgentRouteNames`).
+- **Breaking:** Search pages state connector facts once: `connectorTitle`, `guide` and `guideSummary` moved off every tool row into a page-level `connectors` map keyed by connector id (`connectors[id].title`, `.guide`, `.guideSummary`); rows keep `guideRequired` and `guideRequiredReasons`. In-program `connecta.search` now defaults to `includeSchemas: "typescript"` (one `signature` per row, about half the bytes of JSON); pass `includeSchemas: "json"` for JSON Schema. Top-level `search_tools` still omits schemas by default. A query led by `list`, `get`, `find`, `search`, `show`, `read`, `fetch` or `count` ranks read rows above write rows within each relevance tier without hiding writes. Maintained providers may declare `searchSynonyms`, groups of interchangeable lowercase words search matches lexically for that provider only; Church Community Builder declares `person`/`individual` and `household`/`family`, and Granola `meeting`/`note`.
+- **Breaking:** Require every pool to list only people or only agents. Mixed membership now throws ConfigError at construction, including personal pools with or without an owner. Split shared team pools into people-only and agent-only pools sharing a tool list; personal agent pools list only the agent. See documentation/pool-membership-upgrade.md.
+- An unchanged remote catalog refresh no longer rewrites its drift baseline. Zero-TTL listings, the SDK server default, previously rewrote the hash-only baseline (one chunk and one compare-and-set manifest) on every call. A refresh now reads the baseline first and skips the write when the digest matches a baseline written within the last hour. Changed catalogs still write their baseline and report drift. A zero TTL is still never reused, and its listing still deletes any previously cached entry.
+- Split `remoteMcp()` and the downstream OAuth provider into per-seam internal modules, defining each native OAuth method once. Behavior and published declarations are unchanged.
+- The operator page shows each connector's last observed status at once, labelled with its age, then checks it live in a separate request. A live detail read records one status observation per connector and viewer (state, problem code, tool count, time; 120-second TTL) beside discovery health. `GET /ui/connectors/:id?observation=stored` answers from it without probing, with permissions, credential cards and auth links still computed fresh. A stored timeout stays parked until Refresh.
+- The operator page now reads up to eight connector details at once instead of four, so a page of up to eight connectors loads in one round. With 500 ms of downstream latency, a 10-connector page settles in about 2.4 s warm and 3.6 s cold instead of 3.0 s and 5.0 s. Each tab still reads every connector once per load, and detail reads do not count against `admission.requests`.
+- Operator-page connector details stop waiting on a downstream after 8 seconds, or after `discovery.probeTimeoutMs` when that is shorter, instead of the full 30-second probe deadline. A connector that does not answer in time now reports the typed problem `connector_timeout` and renders as **Not responding** with a fix prompt and Refresh, still showing its credential card. The page no longer retries a timed-out connector on its own or on focus; Refresh reads it again, and a consent return from OAuth keeps polling through a timeout. Agent discovery keeps the full `discovery.probeTimeoutMs`.
+
+### Fixed
+
+- A remote MCP connector's credential test always sends a live `tools/list` to the downstream. Against a modern server whose catalog was cached, it previously could report success from the cache without any request.
+- Eval fake vendors share one refcounted, credential-routed transport that fails closed, so `eval:agent --concurrency` trials of different provider families no longer drop each other's routing and reach real vendor hosts.
+- The eval graders now accept two equivalent correct answers they used to reject. Drive revision timestamps (`google-drive-4`) may be keyed by revision id instead of listed in revision order. The Stripe rejected-parameter task accepts any customer page that reaches the five newest matches, as long as the answer reduces it to exactly those ids. `google-drive-4` is no longer treated as an expected capability gap.
+- Hatch details tests expect the position-only `fields` refusal wording that never echoes the submitted path.
+- Downstream OAuth tokens are refreshed before they expire, not only after a 401. Grants now store `expiresAt` with their tokens, counted from when the token request was sent (an `expires_in` of `0` expires at issuance), and a call whose token is within 60 seconds of it renews first through the existing refresh coordinator, so a `remoteMcp()` or `api()` write no longer meets an avoidable 401 and an unknown outcome. The renewal runs in the invocation's authorization check, so a failed one is a plain `downstream_oauth_required` with nothing sent. Two isolates that find the same token due spend one refresh token. Grants stored without `expiresAt` keep refreshing after a 401 until their next refresh stores one; reading a grant never adds it, and status, listing and discovery never refresh. Waiting on another isolate's refresh now polls with a 50 ms to 2 s backoff and reads its lease, grant and spent record in one batched read.
+
 ## 0.38.0 — 2026-10-28
 
 0.38.0 is a minor release that retires the old storage and OAuth layout migrations, adds a configurable program return cap, makes in-program skill calls more forgiving, and moves the Eve helper to Eve 0.86.

package/README.md

@@ -38,7 +38,7 @@ should call.
 
 | Boundary         | What Connecta does                                                                                                        |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Access           | A pool limits the tools its members can reach.                                                                            |
+| Access           | A pool limits the tools its members can reach; it lists only people or only agents.                                       |
 | Writes           | For tools marked as writes, once a change is sent, Connecta won't automatically send it again.                            |
 | Secrets          | Known secrets are redacted from agent output. Enable the credential vault to encrypt stored credentials and OAuth tokens. |
 | Read-only access | Read-only endpoints hide writes and refuse attempts to call them.                                                         |
@@ -69,7 +69,8 @@ connections and access rules still need configuring.
    the server with the access rules you choose.
 3. **Connect your AI app.** This app is the MCP client: it uses Connecta's
    tools on your agent's behalf. Give it the pool address and authentication
-   method supplied by your operator. [Connecting agents](./guides/connecting-agents.md)
+   method supplied by your operator. A person in a single pool can use the
+   plain `/mcp` address; their sign-in selects the pool. [Connecting agents](./guides/connecting-agents.md)
    explains what to ask for; the [deployment guide](./documentation/deploying.md)
    has runnable steps.
 

package/bin/connecta.mjs

@@ -258,18 +258,14 @@ async function doctor() {
         `Native catalogs unavailable: ${surface.catalogErrors.join(", ")}. Inspect connector status and authentication.`,
       );
     const expected = native
-      ? ["skills", executeCode ? "execute_code" : "read_result"].sort()
+      ? ["authorize_connector", "skills", executeCode ? "execute_code" : "read_result"].sort()
       : [...META_TOOL_NAMES].sort();
     if (
       native
         ? expected.some((name) => !actual.includes(name)) ||
-          [
-            "search_tools",
-            "call_tool",
-            "call_destructive_tool",
-            "authorize_connector",
-            executeCode ? "read_result" : "execute_code",
-          ].some((name) => actual.includes(name))
+          ["search_tools", "call_tool", "call_destructive_tool", executeCode ? "read_result" : "execute_code"].some(
+            (name) => actual.includes(name),
+          )
         : JSON.stringify(actual) !== JSON.stringify(expected)
     ) {
       throw new Error(

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.38.0";
+export const CONNECTA_VERSION = "0.40.0";

package/dist/access-tokens.js

@@ -8,7 +8,7 @@ import { accessTokenKeys } from "./storage/keys.js";
 import { AGENT_NAMESPACE, agentSubjectId, isAgentName, trustAgentProvider } from "./agent-identity.js";
 import { keepErrorName } from "./redaction-identity.js";
 import { agentConfig } from "./agent-config.js";
-import { authCall, authCatch, authFlow, authInvoke, authMethod, authOwnMethod, authStorage, registerAuthMethod, } from "./auth/native.js";
+import { authAccessToken, authCall, authCatch, authFlow, authInvoke, authMethod, authOwnMethod, authStorage, registerAuthMethod, } from "./auth/native.js";
 import { runEdge } from "./runtime/run.js";
 const TOKEN_PREFIX = "cta_";
 const TOKEN_BYTES = 32;
@@ -802,7 +802,9 @@ export class AccessTokenManager {
                             signal.throwIfAborted();
                             const hash = (yield authCall(hashToken, [token]));
                             signal.throwIfAborted();
-                            const lookupRaw = (yield authStorage(this.storage, "get", [lookupKey(hash)]));
+                            const snapshot = (yield authAccessToken(this.storage, hash));
+                            const read = (key) => snapshot ? (snapshot.get(key) ?? null) : authStorage(this.storage, "get", [key]);
+                            const lookupRaw = (yield authCall(read, [lookupKey(hash)]));
                             signal.throwIfAborted();
                             if (!lookupRaw)
                                 return unauthorized();
@@ -810,7 +812,7 @@ export class AccessTokenManager {
                             if (!lookup)
                                 return unauthorized();
                             const recordRaw = ID_RE.test(lookup.id)
-                                ? (yield authStorage(this.storage, "get", [recordKey(lookup.id)]))
+                                ? (yield authCall(read, [recordKey(lookup.id)]))
                                 : null;
                             const record = recordRaw ? parseRecord(recordRaw) : null;
                             if (record && record.id !== lookup.id)
@@ -827,7 +829,7 @@ export class AccessTokenManager {
                             // code, refuse exactly as an unknown token does.
                             if (record.principal || record.agent === undefined || !this.agents.has(record.agent))
                                 return unauthorized();
-                            const slotRaw = (yield authStorage(this.storage, "get", [slotKey(record.agent)]));
+                            const slotRaw = (yield authCall(read, [slotKey(record.agent)]));
                             const slot = slotRaw === null ? null : parseSlot(slotRaw, record.agent);
                             signal.throwIfAborted();
                             if (slot?.state !== "issued" || slot.tokenId !== record.id)

package/dist/agent-routes.js

@@ -0,0 +1,231 @@
+/**
+ * Route wording: how Connecta-authored text names a route on the surface that
+ * serves it. Text is built with that surface's wording when Connecta writes
+ * it, never rendered afterwards: nothing scans or rewrites replies, program
+ * values, downstream results, guides or caller data.
+ *
+ * Two tables per surface:
+ * - `AgentRouteNames` (public, `ConnectorContext.routes`) names the tools. Use
+ *   a name only in a sentence written for a surface that lists that tool.
+ * - `RoutePhrases` holds complete phrases for sentences every surface shares,
+ *   such as "for a direct call_tool only" against "when calling this tool
+ *   directly". A message chooses whole phrases; it never splices a name into a
+ *   sentence written for another surface, and it branches when the surface
+ *   runs no programs (`program` is undefined).
+ *
+ * Where the wording comes from:
+ * - Connector and provider code reads `routePhrases(ctx)`, or `Routes` from a
+ *   call's Effect services. The registry stamps every context with the
+ *   deployment's names, and a call carries the names of the request's surface.
+ * - Request handlers (meta-tools, programs, native pools, authorization
+ *   handoffs) receive the request's names from the MCP route.
+ * - Instructions, tool descriptions and built-in guides are built per surface,
+ *   or, when only one surface serves them, with the meta names.
+ * - Static provider schema descriptions declare `routeDescription`. The meta
+ *   text is the declared default; each request's catalog serves `api()`
+ *   catalogs with the description built for its own surface.
+ */
+import { Context } from "effect";
+const NAMES = {
+    meta: Object.freeze({
+        search: "search_tools",
+        read: "call_tool",
+        write: "call_destructive_tool",
+        program: "execute_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    code: Object.freeze({
+        search: "connecta.search inside execute_code",
+        read: "connecta.call inside execute_code",
+        write: "connecta.call inside execute_code",
+        program: "execute_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    native: Object.freeze({
+        search: "your host's tool search",
+        read: "the original native tool",
+        write: "the original native tool",
+        program: "your host's tool search",
+        authorize: "the returned authorization handoff",
+        skills: "skills",
+    }),
+    "native-code": Object.freeze({
+        search: "your host's tool search",
+        read: "the original native tool",
+        write: "the original native tool",
+        program: "execute_code",
+        authorize: "the returned authorization handoff",
+        skills: "skills",
+    }),
+};
+/** The six-tool surface's names: the default wherever no other surface applies. */
+export const META_ROUTES = NAMES.meta;
+export function routeNames(surface) {
+    return NAMES[surface];
+}
+/** The names for the surface a connector operation serves; meta for contexts Connecta did not build. */
+export function routesOf(ctx) {
+    return ctx?.routes ?? META_ROUTES;
+}
+// Meta and code text authorize with authorize_connector, which both list. A
+// native pool lists no authorization tool: its errors carry the handoff in
+// nextAction, so the agent passes that on.
+const metaAuthorize = {
+    authorizeAndOpen: (connector) => `call authorize_connector({ connector: "${connector}" }) and open the returned URL`,
+    authorizeAndFollow: (connector) => `call authorize_connector({ connector: "${connector}" }) and follow the operator handoff it returns`,
+    authorizeFor: (purpose) => `Call authorize_connector for ${purpose}`,
+    authorizeCall: (connector) => connector === undefined ? "Call authorize_connector." : `Call authorize_connector({ connector: "${connector}" }).`,
+    authorizeAgain: "call authorize_connector again",
+};
+const nativeAuthorize = {
+    authorizeAndOpen: () => "give this error's nextAction to the user or operator",
+    authorizeAndFollow: () => "give this error's nextAction to the user or operator",
+    authorizeFor: () => "Give this error's nextAction to the user or operator",
+    authorizeCall: () => "Give this error's nextAction to the user or operator.",
+    authorizeAgain: "retry the original native call",
+};
+const nativeDirect = {
+    directOnly: "when calling this tool directly",
+    forDirect: "when calling this tool directly",
+    onlyDirectRead: "only when calling this tool directly",
+    writeNeedsApproval: "Invoke it through its own native tool so the MCP host can request approval.",
+};
+const PHRASES = {
+    meta: Object.freeze({
+        program: "execute_code",
+        directOnly: "for a direct call_tool only",
+        forDirect: "for a direct call_tool",
+        onlyDirectRead: "only for a direct call_tool read",
+        callDirectlyAndPage: "call directly (call_tool, connecta.result to page)",
+        writeNeedsApproval: "Invoke it through call_destructive_tool so the MCP host can request approval.",
+        ...metaAuthorize,
+    }),
+    // The eval code arm keeps the text its comparator protocol recorded.
+    code: Object.freeze({
+        program: "execute_code",
+        directOnly: "for a direct connecta.call inside execute_code only",
+        forDirect: "for a direct connecta.call inside execute_code",
+        onlyDirectRead: "only for a direct connecta.call inside execute_code read",
+        callDirectlyAndPage: "call directly (connecta.call inside execute_code, connecta.result to page)",
+        writeNeedsApproval: "Invoke it through connecta.call inside execute_code so the MCP host can request approval.",
+        ...metaAuthorize,
+    }),
+    native: Object.freeze({
+        program: undefined,
+        callDirectlyAndPage: "call this tool directly and page with read_result",
+        ...nativeDirect,
+        ...nativeAuthorize,
+    }),
+    "native-code": Object.freeze({
+        program: "execute_code",
+        callDirectlyAndPage: "call this tool directly and page with connecta.result in execute_code",
+        ...nativeDirect,
+        ...nativeAuthorize,
+    }),
+};
+const SURFACES = new Map(Object.keys(NAMES).map((surface) => [NAMES[surface], surface]));
+/** The surface a names table belongs to; meta for a table Connecta did not build. */
+function routeSurface(routes) {
+    return (routes && SURFACES.get(routes)) ?? "meta";
+}
+/** The phrases for the surface an operation serves, from its names or its context. */
+export function routePhrases(source) {
+    const routes = source && "read" in source ? source : routesOf(source);
+    return PHRASES[routeSurface(routes)];
+}
+/**
+ * The same names inside a call's Effect services, for provider code that has
+ * no context in hand (an `authenticate` program, a vendor error table).
+ */
+export const Routes = Context.Reference("connecta/call/Routes", {
+    defaultValue: () => META_ROUTES,
+});
+const descriptions = new Map();
+/**
+ * A static schema description that names a route. Returns the meta text, which
+ * the schema declares; a request on another surface lists the text built from
+ * its own phrases. Declare it once, at module scope.
+ */
+export function routeDescription(build) {
+    const meta = build(PHRASES.meta);
+    descriptions.set(meta, build);
+    return meta;
+}
+const declaringConnectors = new WeakSet();
+/** Mark a connector whose catalog Connecta authors (`api()`), so its declared descriptions follow the surface. */
+export function declaresRouteDescriptions(connector) {
+    declaringConnectors.add(connector);
+}
+// Where an authored tool's declared descriptions sit, per connector and tool
+// name: api() definitions are fixed at construction, while the registry
+// publishes a fresh copy of each tool on every read.
+const descriptionPaths = new WeakMap();
+const rendered = new Map();
+function at(value, path) {
+    let current = value;
+    for (const key of path)
+        current = current?.[key];
+    return current;
+}
+function declaredPaths(tool) {
+    const found = [];
+    const visit = (value, path) => {
+        if (Array.isArray(value))
+            value.forEach((item, index) => visit(item, [...path, index]));
+        else if (value !== null && typeof value === "object")
+            for (const [key, item] of Object.entries(value)) {
+                if (key === "description" && typeof item === "string" && descriptions.has(item))
+                    found.push([...path, key]);
+                else
+                    visit(item, [...path, key]);
+            }
+    };
+    for (const key of ["inputSchema", "outputSchema"])
+        visit(tool[key], [key]);
+    return found;
+}
+/**
+ * Give a request's own copy of one tool the declared descriptions of the
+ * surface it serves, in place, so the copy keeps everything else it carries,
+ * its source classification included. Only tools of connectors Connecta
+ * authors change; downstream catalogs and the meta surface are left as given.
+ */
+export function routeToolInPlace(connector, tool, routes) {
+    const surface = routeSurface(routes);
+    if (surface === "meta" || descriptions.size === 0 || !connector || !declaringConnectors.has(connector))
+        return;
+    let byName = descriptionPaths.get(connector);
+    if (!byName)
+        descriptionPaths.set(connector, (byName = new Map()));
+    let paths = byName.get(tool.name);
+    // Recompute when a path no longer holds declared meta text.
+    if (!paths || !paths.every((path) => descriptions.has(at(tool, path)))) {
+        paths = declaredPaths(tool);
+        byName.set(tool.name, paths);
+    }
+    for (const path of paths) {
+        const meta = at(tool, path);
+        let bySurface = rendered.get(meta);
+        if (!bySurface)
+            rendered.set(meta, (bySurface = new Map()));
+        let text = bySurface.get(surface);
+        if (text === undefined)
+            bySurface.set(surface, (text = descriptions.get(meta)(PHRASES[surface])));
+        at(tool, path.slice(0, -1))["description"] = text;
+    }
+}
+const programRouteConfigs = new WeakMap();
+/**
+ * Eval only: serve this configuration's text with program-form route names.
+ * No package entry exports it and no configuration key selects it; the eval
+ * code arm marks the configuration object it passes to createConnecta.
+ */
+export function renderRoutesAsPrograms(config) {
+    programRouteConfigs.set(config, true);
+}
+/** The names every reply of a deployment built from `config` uses outside native pools. */
+export function deploymentRoutes(config) {
+    return programRouteConfigs.has(config) ? NAMES.code : NAMES.meta;
+}