@zackbart/connecta 0.33.0 → 0.34.0

package/documentation/auth.md

@@ -66,7 +66,8 @@ comma-separated list of these ids; update that environment variable when
 using their roster wiring. Pool membership remains code. To remove a person,
 remove their memberships and maintainer entry, restart/redeploy, and remove
 their sign-in admission as appropriate. Never add another person to an
-agent's `<agent>-<user>` pool; follow [the pool layout](#organizing-an-agents-pools).
+agent's `<agent>-<user>` pool, and add a person to an agent's tier only if
+they are cleared for it; follow [the pool layout](#organizing-an-agents-pools).
 
 ## Connect a shared credential
 
@@ -108,8 +109,8 @@ remoteMcp("crm", {
 
 To rotate a saved token, save its replacement in the same slot; subsequent
 calls use it. Revoke the retired token at the downstream service. For OAuth,
-use Restart to authorize afresh, Continue to resume a pending consent, and
-Disconnect to invalidate the local grant and catalog. To remove a credential,
+use Reconnect (or Connect account) to authorize afresh, Continue requested
+authorization to resume a pending consent link, and Disconnect to invalidate the local grant and catalog. To remove a credential,
 use the connector's credential delete control. Clearing a slot with no saved
 value returns 409 with `problem: "credential_required"`; it does not revoke
 anything downstream. An unreadable stored value can still be cleared for
@@ -132,7 +133,7 @@ pools: { assistant: { tools: ["crm", "tickets"], members: ["agent:assistant"] }
 Typecheck and restart/redeploy, then use either procedure:
 
 - **Signed-in maintainer:** with human auth and `operatorUi()` enabled, open
-  the Access tokens page, select `assistant`, and issue, rotate, or revoke
+  the Tokens page, select `assistant`, and issue, rotate, or revoke
   its token. Save an issued secret privately immediately; it appears once.
   The UI reads the slot revision and sends it with the operation. If the slot
   changed, reload and decide again.
@@ -233,7 +234,7 @@ lists them: each name matches `^[a-z0-9_-]+$`, at most 64 characters, and is
 unique; anything else, or agents without `accessTokens`, throws at
 construction. `describeConfig()` lists the names and never token state.
 `accessTokens` from `@zackbart/connecta/auth/access-tokens` installs the `cta_`
-inbound adapter and, beside `ui`, the Access tokens page and `/ui/access-tokens`
+inbound adapter and, beside `ui`, the Tokens page and `/ui/access-tokens`
 routes. Omitted, none of it loads or is served. It takes no options;
 `accessTokens(storage, { maxActive })` throws, since each declared agent has
 exactly one token slot.
@@ -281,7 +282,8 @@ The token routes require the revision the caller decided from:
 | `POST /ui/access-tokens/<agent>` (issue, rotate) | JSON body `{ "expect": "<revision>" }`, `Content-Type: application/json`                          |
 | `DELETE /ui/access-tokens/<agent>` (revoke)      | the same body, or `?expect=<revision>` for a client that cannot send a body with DELETE; not both |
 
-A missing or malformed `expect` is 400; a body that is not JSON is 415 and one
+A missing or malformed `expect` is 400, as is a JSON body that does not parse
+to an object; a body without `Content-Type: application/json` is 415, and one
 over 1,024 characters is 413. They are checked after authorization and before
 the operation. If the slot's current revision differs, the route answers 409
 `{ "error": "…", "code": "slot_changed" }` before minting a secret or writing
@@ -387,8 +389,9 @@ outcome depends on cleanup or on undoing a write.
   undelivered rotation secret may keep admitting, but it never left the server:
   a liveness problem reported as `outcome_unknown`, never a credential exposure.
 
-The routes pass the request's `AbortSignal` to `rotate`, `revoke`, and `adopt`
-(`{ signal }`); a signal already aborted performs no storage call at all. Authorization caches no token, and D1 and SQLite are strongly
+The routes pass the request's `AbortSignal` to `rotate` and `revoke`
+(`{ signal, expect }`); `adopt` has no route and runs only from trusted
+provisioning, which may pass its own `{ signal }`; a signal already aborted performs no storage call at all. Authorization caches no token, and D1 and SQLite are strongly
 consistent; admitted requests are not recalled. Management writes require an
 exact same-origin Origin; responses are private and non-cacheable.
 
@@ -463,8 +466,11 @@ one fixed address, is applied once per call and only to a request an inbound
 provider authenticated: any `ok`, a subject-less custom credential included, never an open
 deployment's anonymous admission. An agent never reaches the function; it acts
 as its pool's `owner` ([Pool owners](#pool-owners-for-google-workspace)).
-Otherwise, or on `undefined`, the call fails
-`auth_required` before any request leaves. Arguments, headers, and programs
+Without an owner, a mapping-subject connector is absent for agents, and a call
+by address fails `unknown_address`. The provider-level fallback is
+`auth_required` when no inbound provider authenticated the caller or the
+mapping returns `undefined`; it also rejects an ownerless agent context that
+bypasses the scoped registry. These refusals happen before any request leaves. Arguments, headers, and programs
 never reach it; a deployment's own connectors still cannot read the caller.
 
 Access is read from one place, deployment code. Top-level
@@ -496,10 +502,11 @@ provider other than the built-in agent-token adapter), and a non-empty
 can be a maintainer, and plain `/mcp` and every operator API admit nobody; the
 agents reach only `/agent/<pool>` for the pools that list them. With no inbound auth at all, the
 deployment is open (see [pools](#pools)). `describeConfig()` lists
-`maintainers` as `{ namespace, id }` and each pool's resolved `members`.
+`maintainers` as `{ namespace, id }` and each pool's resolved `members` and
+trimmed `description` (`null` when unset).
 
 Pool tools are enforced in the scoped registry view, below the catalog service,
-so `search_tools`, `describe_tools`, both call tools, a program's
+so `search_tools`, both call tools, a program's
 `connecta.search`, `connecta.describe`, and `connecta.call` read one filtered
 list. Connector-level discovery, guides, and `authorize_connector` keep a
 connector when any of its tools is in the pool — `docs.read` permits the
@@ -540,6 +547,10 @@ Marketing's every `campaigns` tool and only `issues.search`. Neither pool
 serves `billing`; only the owner's plain `/mcp` does. A person in both pools
 uses two endpoints, never a union.
 
+A team pool can also be one of an agent's tiers: the same pool lists the
+cleared people and the agent, and each reaches it at their own address
+([people in a tier](#organizing-an-agents-pools)).
+
 | Catalog change          | Exact `connector.tool` in a pool                                        |
 | ----------------------- | ----------------------------------------------------------------------- |
 | New name                | Excluded until reviewed and added                                       |
@@ -572,7 +583,7 @@ secrets. Declare each machine as an agent instead:
 
 1. Configure the existing D1 or SQLite store as `storage`, and install
    `accessTokens(storage)`. Keep its existing keys and namespaces.
-2. Add the machine's name to `agents`. Issue its token from the Access tokens
+2. Add the machine's name to `agents`. Issue its token from the Tokens
    page as a signed-in maintainer, or from trusted
    deployment code with
    `new AccessTokenManager(storage, { agents }).rotate("machine-name", "deployment-provisioning")`.
@@ -609,7 +620,11 @@ createConnecta({
   maintainers: ["user_owner"],
   agents: ["calendar-bot"],
   pools: {
-    support: { tools: ["linear", "notion.search_pages", "notion.fetch_page"], members: supportTeam },
+    support: {
+      tools: ["linear", "notion.search_pages", "notion.fetch_page"],
+      members: supportTeam,
+      description: "Support tools: Linear and three Notion reads. Ask a maintainer for anything else.",
+    },
     calendar_bot: { tools: ["calendar.create_event"], members: ["agent:calendar-bot"] },
     reporting: { tools: ["linear", "notion"], readOnly: true, members: analysts },
   },
@@ -623,14 +638,20 @@ warning says, every pool path answers the 404 because nobody can be a member,
 and every agent endpoint answers the machine-only 401 because no agent can be
 admitted.
 
-| Rule         | Contract                                                                                                                                                                                                                                                                                                                                |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers. Neither intersects with or widens anything.                              |
-| Refusal      | A non-maintainer at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer`, `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                   |
-| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                               |
-| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
-| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                    |
-| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                       |
+| Rule         | Contract                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers. Neither intersects with or widens anything.                                                                                                               |
+| Refusal      | A non-maintainer at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer`, `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                                    |
+| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                |
+| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` append it to the MCP `initialize` instructions after `This endpoint: `; plain `/mcp` and a pool without one serve the shared instructions unchanged. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                                   |
+| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 characters of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
+| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                     |
+| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                                                                                                        |
+
+Pool descriptions are trimmed before validation. The remaining text must be
+1 to 500 characters and contain no C0 or C1 control characters (including tabs,
+newlines, and NEL U+0085), LINE SEPARATOR (U+2028), or PARAGRAPH SEPARATOR
+(U+2029).
 
 ### Agent endpoints
 
@@ -715,7 +736,16 @@ mapping function, the caller decides whose account a call opens:
 | ----------------------------- | ------------------------------------------------------------------------------- |
 | A person, in any pool         | Their own account, through the `subject` mapping. A pool `owner` never applies. |
 | An agent in a pool            | The pool's `owner`, resolved before the mapping, which never sees the agent.    |
-| An agent, pool has no `owner` | Nothing: the call fails `auth_required` before any request leaves.              |
+| An agent, pool has no `owner` | Nothing. The connector is absent for the agent, as a personal connector is.     |
+
+In a pool without an `owner`, a mapping-subject Workspace connector is absent
+for agents, just as an `authScope: "personal"` connector is: `search_tools`,
+`connecta.search`, `connecta.describe`, `skills`, and connector discovery omit
+it, `authorize_connector` answers "Unknown connector", and a call by address
+fails `unknown_address`, the same as for a connector that does not exist.
+People in the same pool still see it and act as themselves. This is what lets
+one pool be a team pool for people, each acting as themselves on Workspace, and
+also list an agent that reaches only the pool's shared connectors.
 
 `owner` is a Workspace email address, checked at construction and listed in
 `describeConfig()` (`null` when unset). Over HTTP, `/ui/api/config` serves it
@@ -728,19 +758,19 @@ change it, and the `auth_required` message never names an address. One
 
 ```ts
 const team = [
-  { id: "alice", email: "alice@example.com" },
-  { id: "bob", email: "bob@example.com" },
+  { handle: "alice", id: "user_alice", email: "alice@example.com" },
+  { handle: "bob", id: "user_bob", email: "bob@example.com" },
 ];
 createConnecta({
   auth: clerkAuth({ publishableKey, secretKey }),
   storage,
   accessTokens: accessTokens(storage),
   readOnly: false,
-  maintainers: ["alice"],
+  maintainers: ["user_alice"],
   agents: ["assistant"],
   pools: Object.fromEntries(
     team.map((person) => [
-      `assistant-${person.id}`,
+      `assistant-${person.handle}`,
       { tools: ["gmail", "drive"], owner: person.email, members: [person.id, "agent:assistant"] },
     ]),
   ),
@@ -767,9 +797,12 @@ members must not share that account.
 
 ### Organizing an agent's pools
 
-Use this layout for every agent's pools. It gives each person's own accounts
-to the agent only when that person is the one talking, without a second
-connection. This section holds the complete rules.
+Use this layout for every agent's pools. It gives a chat no more than
+everyone in it is cleared for, and gives each person's own accounts to the
+agent only when that person is the one talking, all over one connection. This
+section holds the complete rules.
+
+**The pools**
 
 1. **One connection per agent.** Each agent has exactly one Connecta
    connection, and its client (the harness, never the model) chooses the
@@ -777,24 +810,32 @@ connection. This section holds the complete rules.
    it: the model would get two sets of meta-tools, and `execute_code` cannot
    join results across connections. The agent's one `cta_` token works on
    every pool that lists it.
-2. **Base pool `<agent>`.** `/agent/<agent>` serves pool `<agent>`: shared and
-   organization connectors only, with no `owner`. Use it in group chats,
-   scheduled runs, and any turn without exactly one identified person.
+2. **Tiers.** An agent's tiers are named pools ordered from least to most
+   capable. Recommended names are `<agent>` for the lowest tier and
+   `<agent>-<tier>` for higher tiers (`assistant-team`, `assistant-leads`).
+   A tier may be any named pool, including an existing team pool such as
+   `team` or `leadership`, as long as its human members are all cleared for
+   it (rule 10). An agent with one tier uses it as the lowest. Tiers never
+   hold per-user connectors and never set an `owner`.
 3. **Personal pool `<agent>-<user>`.** `/agent/<agent>-<user>` serves pool
-   `<agent>-<user>`: the base plus that user's own connectors. Use it only in
-   a one-on-one with that user. `<user>` is a short, stable handle you choose
-   (`alice`), never a provider id, principal id, or address; pool names match
-   `[a-z0-9_-]+`.
-4. **Define the base once.** Every personal pool spreads one base constant, so
-   a change to the base reaches every pool.
+   `<agent>-<user>`: the highest tier that user is cleared for, plus that
+   user's own connectors. Use it only in a one-on-one with that user.
+   `<user>` is a short, stable handle you choose (`alice`), never a provider
+   id, principal id, or address. When using the recommended `<agent>-<tier>`
+   names, no user handle may equal a tier suffix: their pool names would
+   collide. With any naming scheme, keep personal pool names distinct from
+   tier pool names. Pool names match `[a-z0-9_-]+`.
+4. **Nest by spreading tool lists.** Define each tier's `tools` once, as a
+   constant that spreads the tier below it, and spread a user's highest tier
+   into their personal pool's `tools`. A change to a tier then reaches every
+   pool above it. Spread tool lists, not whole pools: `members`, `readOnly`,
+   and `owner` belong to each pool, and a spread pool would copy them.
 5. **`owner` is the user's Workspace address.** Set `owner` on
    `<agent>-<user>` to that user's Google Workspace email address; it is
    checked as an address at construction, and it makes Workspace connectors
    act as that user for the agent ([pool owners](#pool-owners-for-google-workspace)).
-   The base pool has no owner, so keep Workspace connectors out of it: there
-   they are absent, as in any pool that does not list them. (A Workspace
-   connector listed in a pool without an owner fails `auth_required` for an
-   agent.)
+   Tiers have no owner, so a Workspace connector with a mapping `subject`
+   is absent for the agent there.
 6. **A user's own account is its own connector id.** Agents have no
    principal, so `authScope: "personal"` connectors never appear for them.
    Give each user's account its own connector id with shared auth, which a
@@ -802,20 +843,68 @@ connection. This section holds the complete rules.
    that user's pool. Google Workspace is the exception: one connector whose
    `subject` is a mapping function, with each personal pool's `owner`
    choosing the account.
-7. **Changes stay in config.** Adding an account for a user adds its
-   connector and lists it in that user's pool `tools`; the client does not
-   change. Adding a user adds one `<agent>-<user>` pool.
-8. **No other person in a personal pool.** The only human member an
+7. **Where each connector goes.** A shared connector (the deployment's
+   account, including a fixed-subject Workspace connector) goes in the lowest
+   tier whose entire audience is authorized to use the connector, and so
+   reaches every tier above. For example, billing restricted to leads goes
+   in the leads tier. Per-user connectors (`notes_alice`) go only in personal
+   pools, and so do the Workspace connectors with a mapping `subject` that
+   the agent uses; rule 10 covers listing them in a tier for its people.
+8. **Changes stay in config.** Adding an account for a user adds its
+   connector and lists it in that user's pool `tools`. Adding a user adds one
+   `<agent>-<user>` pool. Adding a tier adds one pool and one constant, and
+   the tier's place in the harness's tier list.
+9. **No other person in a personal pool.** The only human member an
    `<agent>-<user>` pool may have is that same user, and usually it has none.
    Never add another person: its per-user connectors (`notes_alice`) use that
    user's account for everyone the pool admits, so another member would read
    and write the user's account as their own. A person's own use normally
-   goes through their own pools or plain `/mcp`, not the agent's.
+   goes through their own pools or plain `/mcp`.
+10. **People in a tier are cleared for it.** A tier can also be a human team
+    pool: list the people cleared for that tier in its `members` beside the
+    agent. They use it at `/mcp/<pool>`, the agent at `/agent/<pool>`.
+    List no one else: a member reaches
+    every shared connector the tier holds, on the deployment's account. Such a
+    pool may also list Workspace mapping connectors or `authScope: "personal"`
+    connectors for its people, who act as themselves on them; those connectors
+    are absent for the agent, since a tier has no owner and an agent has no
+    principal.
+
+**Choosing the pool each turn**
+
+The harness decides which pool a turn uses, from its own verified view of
+the chat: the platform's sender and participant ids, never names or claims in
+message text, and never the model. Connecta checks only that the agent is a
+member of the pool it opens. The agent's one token opens every pool that
+lists it, so clearance is enforced nowhere but the harness.
+
+- In a one-on-one with a user who has a personal pool, use that pool.
+- Otherwise, use the most capable tier that everyone present is cleared for.
+  Everyone present means every participant who can read the reply, people and
+  other bots, not only the sender.
+- If anyone present is unknown to the harness, or it cannot verify who is
+  present, use the lowest tier.
+- A scheduled run uses the tier of the audience that will read its output, by
+  the same rule; with no audience, the lowest tier.
+- Choose again on every turn. Someone joining a chat lowers its tier from the
+  next turn.
+
+**The lowest tier.** The first pool in the harness's tier list is the
+fallback (recommended name: `<agent>`), so make it safe in front of anyone
+who can reach the agent. Where unknown people can, make it a guest tier:
+`readOnly: true`, with exact `connector.tool` addresses for the reads guests
+may use. A new downstream tool then never appears there, and no write runs.
+The tier above spreads the guest list and adds whole connectors.
 
 ```ts
 import type { GoogleWorkspaceOptions } from "@zackbart/connecta/providers/gmail";
 
-const assistant = { tools: ["crm", "tickets"], members: ["agent:assistant"] };
+const agent = "agent:assistant";
+// Tiers, lowest first. Each tier's tools spread the tier below.
+const guestTools = ["crm.search_contacts", "tickets.list_tickets"];
+const teamTools = [...guestTools, "crm", "tickets"];
+const leadsTools = [...teamTools, "billing"];
+
 const emailOf = (id?: string) => (id === "user_alice" ? "alice@example.com" : undefined);
 const workspace: GoogleWorkspaceOptions = {
   purpose: "Mail and files of the person in a one-on-one",
@@ -831,21 +920,27 @@ createConnecta({
   maintainers: ["user_alice"],
   agents: ["assistant"],
   pools: {
-    assistant,
+    // Lowest tier and fallback: reads guests may use.
+    assistant: { tools: guestTools, readOnly: true, members: [agent] },
+    // Also the team's own pool at /mcp/assistant-team.
+    "assistant-team": { tools: teamTools, members: [agent, "user_alice", "user_bob"] },
+    "assistant-leads": { tools: leadsTools, members: [agent] },
+    // Each personal pool spreads its user's highest tier.
     "assistant-alice": {
-      ...assistant,
-      tools: [...assistant.tools, "notes_alice", "gmail", "drive"],
+      tools: [...leadsTools, "notes_alice", "gmail", "drive"],
       owner: "alice@example.com",
+      members: [agent],
     },
     "assistant-bob": {
-      ...assistant,
-      tools: [...assistant.tools, "notes_bob", "gmail"],
+      tools: [...teamTools, "notes_bob", "gmail"],
       owner: "bob@example.com",
+      members: [agent],
     },
   },
   connectors: [
     crm,
     tickets,
+    billing,
     // Shared auth: a maintainer connects each user's own account once.
     remoteMcp("notes_alice", { url: "https://notes.example.com/mcp", auth: { type: "oauth" } }),
     remoteMcp("notes_bob", { url: "https://notes.example.com/mcp", auth: { type: "oauth" } }),
@@ -856,17 +951,38 @@ createConnecta({
 });
 ```
 
-The agent's client picks the pool from who it is talking to, for example:
+Alice is cleared for leads and Bob for team. The agent's client picks the
+pool from who is present, for example:
 
 ```ts
-const handles: Record<string, string | undefined> = { "<alice's sender id>": "alice", "<bob's sender id>": "bob" };
-const user = turn.isDirect ? handles[turn.verifiedSender] : undefined;
-const url = `https://connecta.example.com/agent/${user ? `assistant-${user}` : "assistant"}`;
+// Lowest first. A person's tier is an index into this list.
+const tiers = ["assistant", "assistant-team", "assistant-leads"];
+const people: Record<string, { tier: number; handle?: string }> = {
+  "<alice's sender id>": { tier: 2, handle: "alice" },
+  "<bob's sender id>": { tier: 1, handle: "bob" },
+};
+
+// `verifiedParticipants`: everyone who can read the reply, other than the
+// agent, from the platform's ids; undefined when the harness cannot verify it.
+function poolFor(turn: { isDirect: boolean; verifiedParticipants?: string[] }) {
+  const present = turn.verifiedParticipants;
+  if (!present?.length) return tiers[0];
+  const known = present.map((id) => people[id]);
+  if (turn.isDirect && present.length === 1 && known[0]?.handle) {
+    return `assistant-${known[0].handle}`;
+  }
+  return tiers[Math.min(...known.map((person) => person?.tier ?? 0))];
+}
+const url = `https://connecta.example.com/agent/${poolFor(turn)}`;
 ```
 
-Rule 8 is why the example lists only the agent in each pool. People act as
-themselves only through a Workspace mapping; a shared-auth connector such as
+A chat with Alice and Bob gets `assistant-team`; add an unknown guest and it
+gets `assistant`, even if the platform marks the chat as direct. Rule 9 is
+why each personal pool lists only the agent: people act as themselves only
+through a Workspace mapping, and a shared-auth connector such as
 `notes_alice` acts as Alice for whoever the pool admits.
+Rule 10 is why `assistant-team` may list Alice and Bob: it holds only
+connectors that every member may use on the deployment's account.
 
 ## Shared and personal auth
 
@@ -941,12 +1057,12 @@ namespace is left to clean up. They then delete each consent whose epoch is no
 longer live; one left behind cannot complete and expires with its link.
 `POST /ui/oauth/<id>` takes a `mode`:
 
-| Request                                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `POST /ui/oauth/<id>` or `?mode=restart` | Issues a signed `/connect/<id>` link requesting a fresh epoch. No downstream authorization starts until the verified browser visits it.                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `?mode=continue`                         | Issues a signed `/connect/<id>` link requesting continuation. At the browser visit, a recent pending consent can be reused; otherwise authorization begins in the current epoch.                                                                                                                                                                                                                                                                                                                                                          |
-| `GET /connect/<id>?h=...`                | Verifies the signed handoff and, when signed in, browser identity, connector visibility and management permission. With the UI mounted, hands off to `/connectors/<id>?h=...#auth` without consuming the link or starting OAuth; Clerk sign-in uses that shell. The Auth tab continues with `start=1`, which repeats verification, consumes the link and calls `startAuth`. Without the UI, the original browser visit starts consent. Explicit `POST /ui/oauth/<id>` actions return a signed link with `start=1` when the UI is mounted. |
-| `DELETE /ui/oauth/<id>`                  | Disconnects and invalidates the cached catalog, even if the browser leaves.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Request                                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `POST /ui/oauth/<id>` or `?mode=restart` | Issues a signed `/connect/<id>` link requesting a fresh epoch. No downstream authorization starts until the verified browser visits it.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `?mode=continue`                         | Issues a signed `/connect/<id>` link requesting continuation. At the browser visit, a recent pending consent can be reused; otherwise authorization begins in the current epoch.                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `GET /connect/<id>?h=...`                | Verifies the signed handoff and, when signed in, browser identity, connector visibility and management permission. With the UI mounted and a maintainer signed in, hands off to `/connectors/<id>?h=...#auth` without consuming the link or starting OAuth; Clerk sign-in uses that shell. The Auth tab continues with `start=1`, which repeats verification, consumes the link and calls `startAuth`. Without the UI, or for a pool member, the original browser visit starts consent. Explicit `POST /ui/oauth/<id>` actions return a signed link with `start=1` when the UI is mounted. |
+| `DELETE /ui/oauth/<id>`                  | Disconnects and invalidates the cached catalog, even if the browser leaves.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 `authorize_connector` issues the same browser link, with `force` carried in the
 signed handoff. On hosts without URL elicitation, direct and program auth
@@ -1827,7 +1943,7 @@ For providers offering both, deployment config chooses; handlers check `ctx.oaut
 
 ## Request-local downstream Bearer tokens
 
-`remoteMcp({ auth: { type: "request", token: async (ctx) => … } })` resolves
+`remoteMcp("<id>", { auth: { type: "request", token: async (ctx) => … } })` resolves
 its token before connecting and before reusing a client. The callback receives
 the operation's cancellation context, never an agent-selected credential owner.
 Only shared ownership is accepted. Tokens remain inside the request's hardened

package/documentation/code-mode.md

@@ -555,6 +555,15 @@ URL-elicitation hosts retain their existing flow.
 **E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program
 may do. A provider maps each downstream failure to the code that tells the
 caller what to do next, and never invents a cause it was not told.
+The table lists the codes a program commonly sees. Codes owned by one
+mechanism are specified with it: `resource_template_ambiguous` and
+`resource_match_budget_exceeded` with resource reads above; the
+`executor_*` admission codes in `E5`; `destructive_tool_requires_approval` with
+direct calls; and `input_required_invalid`, `input_required_limit`,
+`downstream_oauth_required`, `oauth_revocation_failed`,
+`provider_permission_denied`, and `auth_replay_refused` in
+[meta-tools](./meta-tools.md). Each of those is non-retryable except
+`executor_overloaded`.
 
 | Code                         | Raised when                                                                                                                                                                                           | `retryable`   |
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
@@ -577,6 +586,7 @@ caller what to do next, and never invents a cause it was not told.
 | `result_too_large`           | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
 | `budget_exceeded`            | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
 | `write_outcome_unknown`      | a program write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                       | false         |
+| `executor_failed`            | the executor returned a malformed result or failed outside the guest program                                                                                                                          | false         |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -685,6 +695,12 @@ when the metadata describes a write on a read-only endpoint.
 Caught call failures retain that connector visibility when catalog loading or
 tool resolution fails. Recovery messages listing configured connectors or
 local guides retain visibility of those contributors too.
+Search guidance retains its referenced connectors even when no tool matches,
+including connectors named by id or title and identities summarized as an
+additional count. Scoped guides and summaries, absence rosters, and catalog
+errors retain their contributing connectors as well.
+Search counts, ranking, and term analysis retain every searched connector,
+including matches outside the returned page or beyond the requested offset.
 Each page rechecks current auth,
 grants, pool membership, and the endpoint's `readOnly`. Reading a stash inside a program carries
 its dependencies forward to any new return stash. The page cap is the smallest
@@ -711,7 +727,7 @@ has no host log stream and cannot supply logs from its suspended guest (`L4`).
 
 **R6.** Every run returns `hostCalls: { attempted, admitted, succeeded, failed }`,
 including admission failure, cancellation, budget refusal, and code-size refusal.
-Calls include search, describe, call, result, and skill. `emit` has separate budgets.
+Calls include search, describe, call, read, result, and skill. `emit` has separate budgets.
 An abandoned host call counts as failed when the run ends; guest catches do not
 change the counts. These numbers are outside the program's returned `result`.
 `diagnostics: true` adds the existing payload-free timing block. Emitting adds
@@ -770,7 +786,8 @@ a successful result, appended to `content` after the JSON envelope, which gains
 response (`R6`). `structuredContent` stays the envelope alone — emission is
 presentation, not a second data channel.
 
-**M3.** Text emission shares `R2`'s 24,000 serialized-character cap. Its
+**M3.** Text emission shares `R2`'s 24,000 serialized-character cap, less 512
+characters reserved for the envelope (23,488 for emitted text). Its
 serialized block size reduces the return budget, and oversized text fails with
 `result_too_large`. Image/audio blocks use the separate transport budget and
 reach the model as real MCP media content, including when `emit` is not awaited.
@@ -881,7 +898,7 @@ because connecta enforces them above the sandbox:
 
 | Bound                                                                                   | Value                                                                                                        |
 | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Host calls per execution, shared by `search`, `describe`, `call`, and `read`            | 20 by default, `execute.maxHostCalls`                                                                        |
+| 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                                                                  | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
 | Discovery page                                                                          | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
@@ -891,8 +908,9 @@ because connecta enforces them above the sandbox:
 | Result                                                                                  | 24,000 serialized characters                                                                                 |
 | Logs presented to the model                                                             | 4,000 characters                                                                                             |
 
-Every `call`, `read`, `search`, and `describe` spends one host call on entry, before
-resolution, validation, or dispatch. Catching a local refusal refunds nothing.
+Every `call`, `read`, `search`, `describe`, `result`, and `skill` spends one host
+call on entry, before resolution, validation, or dispatch; automatic transfer
+pages of a paged result do not. Catching a local refusal refunds nothing.
 The first call beyond the budget ends the host run with one non-retryable
 `budget_exceeded` (`E2`). Its bridge stays pending until lease disposal so guest
 `try/catch` cannot swallow it. Later host access, including `emit`, stops; pending

package/documentation/deploying.md

@@ -197,7 +197,10 @@ CF_ACCESS_CLIENT_ID='<access-service-id>' CF_ACCESS_CLIENT_SECRET='<access-servi
 
 The service headers admit the health probe at the edge; only the `cta_` token
 authenticates the agent endpoint inside Connecta. If the operator UI is enabled, maintainer-authenticated
-`connecta doctor --config --url <public-url>` prints the caller-scoped
+`connecta doctor --config --url <public-url>` (on Node, `CONNECTA_TOKEN` set to a
+maintainer's current Clerk session token issued for this deployment's origin;
+Clerk OAuth access tokens are refused here, and Access on Workers has no
+non-browser maintainer credential, so otherwise use the UI's Settings page) prints the caller-scoped
 configuration snapshot as JSON. It runs no diagnostic program and prints no
 raw HTTP failure body. [Operator UI](./operator-ui.md) describes the returned
 configuration, live facts, and permission rules. The config route is a human
@@ -227,6 +230,7 @@ Bump the exact package pin, read the [changelog](../CHANGELOG.md) for every
 intervening release, and apply the relevant migration before startup. `init`
 does not merge changes into an existing deployment.
 
+- [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.
 - [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.
 - [Node storage from 0.28](../templates/node/README.md#storage) uses `connecta migrate-state` to copy the JSON state into SQLite. Activity JSONL is not imported.

package/documentation/integrating.md

@@ -19,8 +19,10 @@ To add one:
 3. Add the id (all its tools) or exact `id.tool` addresses to the intended
    pools' `tools`. Maintainers at plain `/mcp` already see the whole catalog.
    Follow [the agent pool layout](./auth.md#organizing-an-agents-pools) for an
-   agent: shared connectors go in its base constant, per-user connectors only
-   in that user's pool.
+   agent: a shared connector goes in the tool list of the lowest tier whose
+   entire audience is authorized to use it (billing restricted to leads goes
+   in the leads tier); per-user connectors and Workspace connectors with a
+   mapping `subject` go only in personal pools.
 4. Run the deployment's `npm run typecheck` (Worker copies: `tsc --noEmit`),
    restart Node or redeploy the Worker, and
    [connect its credential](./auth.md#connect-a-shared-credential) if needed.
@@ -38,14 +40,15 @@ const crm = remoteMcp("crm", {
   authScope: "shared",
   auth: { type: "credential", credential: { label: "CRM API token" } },
 });
-const assistant = { tools: ["crm", "tickets"], members: ["agent:assistant"] };
-// connectors: [crm, tickets], agents: ["assistant"], pools: { assistant }
+const base = ["crm", "tickets"]; // the agent's lowest tier
+// connectors: [crm, tickets], agents: ["assistant"],
+// pools: { assistant: { tools: base, members: ["agent:assistant"] } }
 ```
 
 To remove `crm`, first disconnect its OAuth grant or delete its saved
 credential while the connector still exists, using a signed-in maintainer
 for shared auth. Each person disconnects their own personal account. Remove
-`crm` and all `crm.*` addresses from every pool (including base constants),
+`crm` and all `crm.*` addresses from every pool (including tier tool lists),
 then remove its entry from `connectors`, unused imports, and unused secret
 configuration. Remove any pools left with no tools (empty `tools` fails
 construction), and update or retire clients pointing at those pools. Typecheck, restart/redeploy, run doctor, and confirm discovery
@@ -92,7 +95,7 @@ Linear defaults to OAuth; its read-only endpoint requests only the downstream
 read scope. That is separate from a Connecta `readOnly` endpoint. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
 workspace instructions, and admission choices.
 
-The [human README](../README.md#what-you-can-do-with-it) lists available
+The [human README](../README.md#what-you-can-connect) lists available
 integrations. In the installed package, `dist/providers/<name>/index.d.ts`
 and its imported declarations describe each factory's options. After adding
 a connector, use `search_tools` to discover its current tools and `connecta.skill("connector:<id>")` in `execute_code`