@zackbart/connecta 0.38.0 → 0.40.0

package/documentation/code-mode.md

@@ -114,7 +114,12 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 1. **Expose each provider as a guest global** whose properties are its `fns`,
    called with the program's arguments and awaited. Connecta supplies `search`,
    `describe`, `call`, `read`, `result`, `skill`, and `emit`; the prelude also
-   binds the guest's `skills` alias to `skill`.
+   binds the guest's `skills` alias to `skill`. Connecta also supplies
+   `unawaited`, which the built-in prelude calls at most once, after a failed
+   program read a result field off an unawaited call. It spends no host call;
+   the host admits one notice per run and ends the run with `budget_exceeded`
+   on any further call, so a bridge that exposes it directly gains no
+   uncounted round trips.
 2. **Evaluate `prelude` after the provider globals exist and before the
    program.** It is trusted host code that installs the immutable namespace
    and waits for emission acknowledgements. Capture runner intrinsics first;
@@ -197,8 +202,10 @@ is preserved; no JavaScript identifier conversion takes place.
 
 **A2.** Connectors create no guest globals, so an id resembling a JavaScript
 builtin, or one that would collide after sanitization, stays usable through its
-canonical address. The bounded connector inventory in the tool description shows
-canonical ids with bounded configured titles when present. Clauses A3–A5
+canonical address. The bounded connector inventory in the tool description names
+every connector by canonical id, adding a bounded configured title only when it
+says more than the id, and each guide's fetch call (see
+[meta-tools](./meta-tools.md#discovery-context)). Clauses A3–A5
 belonged to shortcut dispatch and stay retired; nothing reuses those ids.
 
 ## The surface
@@ -219,7 +226,7 @@ const page = await connecta.search({
   limit: 8,                         // 1–100, default 8
   offset: 0,
   fullDescriptions: false,
-  includeSchemas: "json",           // default; or "compact" / "typescript"
+  includeSchemas: "typescript",     // default; or "json" / "compact"
   includeSchemaKeys: true,          // default true in code mode
 });
 ```
@@ -236,18 +243,26 @@ query browses; non-empty input with no ASCII lexical terms returns no tools plus
 bounded no-match analysis in `queryAnalysis`; mixed input searches with its
 ASCII terms.
 
-Each entry carries `address`, `name`, the configured `connectorTitle` when
-present (normalized whitespace, at most 120 UTF-8 bytes), and — when requested —
-`description`, `inputSchema`, `outputSchema`, and `annotations`. An entry whose
-connector carries a usage guide also carries `guide` (the skill name) and a
-bounded `guideSummary`, requested or not. An output shape learned under `S9`
+The first page may also carry `readyCalls`: complete operation reads to pass
+unchanged as `connecta.call(entry.address, entry.args)`
+([fully determined operations](./meta-tools.md#discovery-context) only).
+
+Each entry carries `address`, `name`, and — when requested — `description`,
+the rendered schemas, and `annotations`. The page's `connectors` map holds each
+row's connector facts once, keyed by the id before the address's first dot: the
+configured `title` when present (normalized whitespace, at most 120 UTF-8
+bytes), and `guide` (the skill name) with a bounded `guideSummary` when the
+connector carries a usage guide, requested or not. An output shape learned under `S9`
 also carries `outputSchemaSource: "observed"`; provider declarations carry no
 source marker.
 
-Programs default to `includeSchemas: "json"`: `inputSchema` and available
-`outputSchema` are JSON Schema values, labeled `schemaFormat: "json"`.
-Explicit `includeSchemas: "compact"` returns strings labeled
-`schemaFormat: "text"`; TypeScript signatures carry the same text label.
+Programs default to `includeSchemas: "typescript"`: each row carries one
+`signature` string for its input and available output, labeled
+`schemaFormat: "text"`, with `inputKeys`, `requiredInputKeys`, and `outputKeys`
+for code to check. A signature is about half the bytes of the JSON rows.
+Explicit `includeSchemas: "json"` returns `inputSchema` and available
+`outputSchema` as JSON Schema values, labeled `schemaFormat: "json"`, and
+`includeSchemas: "compact"` returns compact strings labeled `schemaFormat: "text"`.
 Compact shapes omit property prose and put required fields first, under these
 bounds:
 
@@ -351,8 +366,14 @@ says so inside its `Promise<…>`.
 ### connecta.call
 
 The published `GuestApi` type describes the supplied global for editors.
-The executable usage guide checks its API notation against those declarations;
-programs still use plain JavaScript.
+The `execute_code` description declares a compact subset of it inline: argument
+shapes that match what `GuestApi` accepts, result fields it returns, and no
+others. Authored emit blocks are the exact variants `M1` accepts;
+forwarded blocks are the native variants from `result.content`. It also
+states that search and describe return objects rather than arrays, that a call
+result over 1 MiB returns a paged handle, and that every function except `emit`
+spends a host call (`M7`). `GuestApi`'s `emit` takes no paged handle, which the
+host refuses. Programs still use plain JavaScript.
 
 ```js
 const { data: run, format } = await connecta.call("ci.get_run", { runId: 42 });
@@ -411,10 +432,12 @@ mismatches, revoked access, and old entries without bindings are `not_found`, as
 are unknown or expired ids; a storage failure is `unavailable`. IDs are random UUIDs.
 The `get_result` meta-tool is removed.
 
-`await connecta.skill(name)` resolves the same URI or compatibility name as
-top-level `skills`, within the admitted connector view. It reads the registry
-behind native `skills/get` and `resources/read`, including opted-in downstream
-skills. It returns
+`await connecta.skill(name)` resolves the same URI, compatibility name, or bare
+connector id as top-level `skills`, within the admitted connector view; built-in
+names stay reserved (see
+[meta-tools](./meta-tools.md#connector-guides-and-skills)). It reads the
+registry behind native `skills/get` and `resources/read`, including opted-in
+downstream skills. It returns
 `{ name, format: "text", text }`; an unknown name is `not_found`. It also
 accepts the top-level tool's `{ name }` object, and `connecta.skills` is an
 undeclared alias of `connecta.skill` with the same host-call accounting, because
@@ -628,8 +651,20 @@ when empty. An empty string reports `program_error` with
 **E6.** A guest `TypeError`, `ReferenceError`, syntax error, invented API, or
 program-authored throw is `program_error`. `details.name` is a bounded engine
 error name; `details.line` is the source line when the runtime supplies one,
-otherwise null. Fixed hints repair imports/require/filesystem access, shadowed
-`connecta`, and invented globals such as `callTool`.
+otherwise null. `message` is `Program <name>: <engine message>`, naming the
+error once even when an executor reports a prefixed message. Fixed hints repair
+imports/require/filesystem access, shadowed `connecta`, invented globals such
+as `callTool`, and a missing `await`. Detection is at runtime, never from
+source: the Promise each `connecta.*` call except `emit` returns has
+non-enumerable getters for result fields (`data`, `format`, `content`, `tools`,
+`catalogErrors`, `total`, `text`, `resultId`, `hasMore`, `nextOffset`). Reading
+one before `await`, as in `connecta.call(...).data` or
+`const { tools } = connecta.search(...)`, returns undefined as before and sets
+a per-run flag. When that program then fails, the prelude reports the flag
+through the uncounted `unawaited` host function before the failure crosses,
+and the hint is `connecta.* returns a Promise; await it`. Awaiting, `then`,
+`Promise.all`, and `Promise.allSettled` never read those fields. Hints are
+fixed text; no program source, field name, or value enters them.
 
 An unchanged uncaught host error retains its classification through Error
 identity. A new error containing its message is a new program error. Copied
@@ -663,13 +698,14 @@ past the deployment's result cap. A clipped address still identifies the mistake
 by its position; a short one 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 the same scoped
-`function: "connecta.search"` recovery every other in-program miss gets. 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`.
+provider dispatch with `invalid_args`, carrying every bounded
+`{ path, expected, received? }` finding, one corrected `example` when it can be
+built, and the same scoped `function: "connecta.search"` recovery every other
+in-program miss gets ([argument recovery](./meta-tools.md#argument-recovery)).
+A declared property reports the constraint that failed, never the validator's
+duplicate `additionalProperties` branch; a truly undeclared property reports
+the accepted keys. Unsupported schemas pass through; unrecognized provider
+prose remains `connector_call_failed`.
 
 ## Results and projection
 
@@ -938,17 +974,17 @@ deadline past the ceiling means raising the ceiling too.
 **L4.** Per-execution bounds that are contract, identical in both executors
 because connecta enforces them above the sandbox:
 
-| Bound                                                                                   | Value                                                                                                                                                                                                                                                             |
-| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Host calls per execution, shared by every guest call except `emit`                      | 20 by default, `execute.maxHostCalls`                                                                                                                                                                                                                             |
-| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                                                                                                                                                                                |
-| Deadline per host call                                                                  | `connecta.call`: its `timeoutMs`, else `calls.defaultTimeoutMs`, else `execute.hostCallTimeoutMs` (15 s); `result`, `skill` and `read`: `execute.hostCallTimeoutMs`. One deadline covers catalog resolution, admission, the connector call, and result processing |
-| 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 by default, `execute.maxResultChars` (4,000–1,000,000)                                                                                                                                                                               |
-| Logs presented to the model                                                             | 4,000 characters                                                                                                                                                                                                                                                  |
+| Bound                                                                                                | Value                                                                                                                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Host calls per execution, shared by every guest call except `emit` and the single `unawaited` notice | 20 by default, `execute.maxHostCalls`                                                                                                                                                                                                                             |
+| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`)              | 10 by default, `execute.maxWrites`                                                                                                                                                                                                                                |
+| Deadline per host call                                                                               | `connecta.call`: its `timeoutMs`, else `calls.defaultTimeoutMs`, else `execute.hostCallTimeoutMs` (15 s); `result`, `skill` and `read`: `execute.hostCallTimeoutMs`. One deadline covers catalog resolution, admission, the connector call, and result processing |
+| 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 by default, `execute.maxResultChars` (4,000–1,000,000)                                                                                                                                                                               |
+| Logs presented to the model                                                                          | 4,000 characters                                                                                                                                                                                                                                                  |
 
 For any tool whose output declares `page`, continue while `page.hasMore` is true.
 When approaching the program's host-call limit, return `page.nextCursor` before
@@ -1310,6 +1346,9 @@ and on the Worker adapter with a real Miniflare Loader in `test/guest-api-contra
 Titles name clauses; executor-independent clauses run in both arms.
 `test/codemode-compat.test.ts` pins upstream shape compatibility, minified upstream
 rejection, and branded adapter acceptance across module copies.
+`test/package-surface.node.test.ts` compiles the description's compact guest
+declaration against `GuestApi`, checks arguments in both directions, and rejects
+invented, mistyped, and missing members and authored blocks the host refuses.
 
 | Clauses                | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1357,3 +1396,47 @@ rejection, and branded adapter acceptance across module copies.
 
 The surface itself is checked by `test/server.test.ts` (the exact six-tool list)
 and `test/program-writes.test.ts` (deployment policy and classification construction refusals).
+
+### Adding a guest function
+
+`src/guest-functions.ts` lists every `connecta.<name>` function once, as
+guest-safe data with no host code or imports. The guest runtime builds the
+frozen namespace from it, so the runtime source stays one self-contained string
+that QuickJS and the Worker executor evaluate unchanged. `execute.ts` admits
+each bridge call by the entry's budget class and binds it by name to a host
+implementation, and the `execute_code` description joins each entry's compact
+declaration and names the functions that spend no host call.
+
+| Function    | Budget     | Purpose                                                                    |
+| ----------- | ---------- | -------------------------------------------------------------------------- |
+| `search`    | `hostCall` | Searches the catalog and returns one flat page of `{ tools }`.             |
+| `describe`  | `hostCall` | Describes exact addresses, one entry per address in order.                 |
+| `call`      | `hostCall` | Calls one tool and inlines transfer pages and native content.              |
+| `read`      | `hostCall` | Reads one advertised resource URI.                                         |
+| `result`    | `hostCall` | Pages a retained result by page or UTF-8 byte offset.                      |
+| `skill`     | `hostCall` | Fetches a skill's text by exact name.                                      |
+| `emit`      | `emission` | Forwards a content block to the client; needs no await.                    |
+| `unawaited` | `once`     | Tells the host a failed program read a result field off an unawaited call. |
+
+A `hostCall` function spends one host call on entry (`L4`, `M7`) and returns a
+Promise whose result fields mark an unawaited read. The runtime wraps
+`provider.<name>`, or its own local of that name when the entry is `wrapped`,
+as `call` is. An `emission` function spends none, is bounded by the emission
+collector and an attempt cap, and returns a tracked thenable. A `once`
+function accepts one call per run, ends the run on a second, and is called only
+by the runtime, never from the namespace.
+
+To add a function:
+
+1. Add its entry to `GUEST_FUNCTIONS`: name, budget class, compact
+   declaration and a one-line JSDoc purpose. A `wrapped` function also needs a
+   guest-side local of the same name in `guestInitializer`.
+2. Add the member to `GuestApi` in `src/guest-types.ts`. The package-surface
+   declaration test fails until the compact declaration and `GuestApi` agree.
+3. Bind its host implementation in `sandboxProvider`'s `operations` in
+   `src/execute.ts`. Typecheck fails while a registry entry has no binding.
+4. Add behavior cases to `test/guest-contract-cases.ts`, which run on both
+   executors. The namespace-membership and missing-await cases cover the new
+   entry without edits.
+5. Document its clause in this guide and add its row to the table above; the
+   package-surface test compares the table with the registry.

package/documentation/deploying.md

@@ -207,9 +207,11 @@ existing-record migration.
 
 One deployment serves one tenant and may admit several people. Node uses Clerk
 for human auth; Access is Workers-only. With inbound auth, `maintainers` is
-required: only they reach plain `/mcp` and the operator UI. Everyone else
-reaches a pool that lists them in `members`: people at `/mcp/<pool>`, agents
-at `/agent/<pool>`. Maintainers alone administer shared credentials, manage
+required: they receive the whole catalog at plain `/mcp` and the operator UI.
+Everyone else reaches a pool that lists them in `members`: people at
+`/mcp/<pool>`, agents at `/agent/<pool>`. A person in exactly one pool may also
+use plain `/mcp`, which serves them that pool, so one client URL can be handed
+to every person; a person in several pools must use `/mcp/<pool>`. Maintainers alone administer shared credentials, manage
 agent tokens, and read activity; members connect their own accounts on
 personal connectors in their pools.
 [Auth](./auth.md#principals-visibility-and-operators) owns maintainers and members;
@@ -332,6 +334,7 @@ and [Eve agents](./meta-tools.md#eve-agents).
 
 - [Provider migration for 0.35](./provider-migration-0.35.md) collects provider upgrade actions for 0.35.0, including removal of Infisical, Notion, and Mixpanel factories.
 - [Migration to 0.34](./migration-0.34.md) covers the Overview landing page, Endpoints at `/endpoints`, default browser titles, and Workspace discovery in owner-less agent pools. No storage migration or token rotation is needed from 0.33.
+- [Split mixed pools](./pool-membership-upgrade.md) before starting a deployment that lists people and agents together; mixed membership now throws at construction.
 - [Migration to 0.33](./migration-0.33.md) maps every removed access option to `maintainers`, pool `members`, and `agents`, moves agents to `/agent/<pool>`, and covers pool owners, token revisions, operator contract v2 with its operator route changes, and the pre-auth listen fix.
 - [Tokens issued before agents](./auth.md#agent-tokens-and-upgrading-from-earlier-tokens) stop admitting until each machine's token is bound once to a declared agent with `npm run adopt-token -- <token-id> <agent>` (Node) or `AccessTokenManager.adopt`, which keeps its secret. Human-bound tokens stay refused; issue those agents new tokens. Pool members name `"agent:<name>"` instead of matching token record ids.
 - [Retired layout migrations](./migration-retired-layouts.md) requires completing Node JSON → SQLite, Workers KV → D1, and every OAuth layout-2 grant conversion on 0.37.1 before upgrading. The new package no longer supplies those migrations.

package/documentation/integrating.md

@@ -57,6 +57,7 @@ const crm = remoteMcp("crm", {
 });
 const base = ["crm", "tickets"]; // the agent's lowest tier
 // connectors: [crm, tickets], agents: ["assistant"],
+// Agent tiers list only agents; people use a separate pool sharing base.
 // pools: { assistant: { tools: base, members: ["agent:assistant"] } }
 ```
 
@@ -267,6 +268,14 @@ which binds the grant to configured API origins and manages authentication.
 [Downstream OAuth on api()](./auth.md#downstream-oauth-on-api) owns a concrete
 HTTP example and the client setup contract.
 
+Text a handler writes for the agent that names a Connecta route, such as "call
+authorize_connector" in an auth error, uses `ctx.routes` (`ctx.routes.authorize`,
+`ctx.routes.read`, `ctx.routes.write`, `ctx.routes.search`, `ctx.routes.program`,
+`ctx.routes.skills`). Connecta sets it on every context it builds to the names of
+the surface serving the call: the meta-tool names on the default surface, and
+the native contract's wording on a native pool. It is optional in the type, so
+fall back to the meta names for a context built elsewhere.
+
 Mark every side-effecting tool `readOnlyHint: false`. On a writable endpoint
 writes use `call_destructive_tool` or a program, within the caller's grants; a
 `readOnly` endpoint refuses them and omits them from search. Client approval is independent of
@@ -305,6 +314,11 @@ literal header credentials with personal scope. Review
 [management permissions](./auth.md#management-permissions) before exposing a
 new integration or its authentication controls.
 
+Plain `/mcp` serves maintainers the whole catalog and every other person their
+single pool, so one URL can serve the meta-tools to `alice` and a native pool's
+tools to `bob`. After changing a pool's `tools`, `readOnly`, `surface` or
+`executeCode`, check it as a member at plain `/mcp` as well as at `/mcp/<pool>`.
+
 After editing configuration, run the deployment's typecheck and doctor, then
 perform a bounded read. Add negative checks for target restrictions and writes
 when authoring a handler or provider. Follow repository verification policy
@@ -331,8 +345,8 @@ check shared behavior. Provider-specific tests remain beside each provider.
 
 Use [`@zackbart/connecta-eve`](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 in the Eve app for an app-owned connection and endpoint instructions refreshed
-once per turn. It requires Node 24 and Eve 0.86.x, and installs separately from
-Connecta. Follow its README for the two agent files, token environment variables,
+once per turn. It installs separately from Connecta. Follow its README for the
+supported Node and Eve versions, the two agent files, token environment variables,
 optional write approval and Vercel OIDC token source. Configure the server's
 [agent and pool membership](./auth.md#issue-rotate-or-revoke-an-agent-token)
 before connecting.