@zackbart/connecta 0.38.0 → 0.39.0

package/documentation/pool-membership-upgrade.md

@@ -0,0 +1,44 @@
+# Split mixed pools
+
+Every pool must list only people or only `agent:` references. A mixed pool
+throws `ConfigError` at construction naming the pool, for example
+`ConnectaConfig.pools.team.members mixes people and agents; list only one kind.`
+This also applies to personal pools with or without `owner`. Pool names and
+connector ids do not decide membership type. People-only pools may retain an
+`owner`; it never changes the account a person uses.
+
+Before upgrading, inspect every pool's `members`, including generated lists.
+For each mixed team pool, define its tool list once and create two pools:
+
+```ts
+const teamTools = ["crm", "tickets"];
+const pools = {
+  team: { tools: teamTools, members: ["user_alice", "user_bob"] },
+  "assistant-team": { tools: teamTools, members: ["agent:assistant"] },
+};
+```
+
+Keep the original human pool name when possible so people's existing
+`/mcp/team` address stays valid. Point the agent harness at
+`/agent/assistant-team` and update its tier list to that name. Copy the
+original `readOnly`, `surface`, `executeCode` and `description` settings
+to both new pools as appropriate so each preserves its intended behavior.
+If the mixed pool set `owner`, keep `owner` on the agent pool: it is the
+Workspace address the agent acts as, and without it Workspace connectors with
+a mapping `subject` disappear for the agent. People never use `owner`; they
+always act as themselves, so the people pool does not need it. Agent pools
+never count toward a person's plain `/mcp` routing, so a person who was in
+one mixed pool and no other still reaches the people pool at plain `/mcp`.
+
+For personal `assistant-alice` pools, keep only `"agent:assistant"` in
+`members` and retain the owner's Workspace address and tools. Give people
+their own people-only pools. Workspace mapping connectors act as each person;
+shared-auth connectors act as their saved account for every member, so review
+those grants before copying personal tool lists.
+
+An agent can still belong to many pools with one token. Tokens, credentials,
+`poolFor` tier selection logic and the Eve helper need no changes beyond pool
+names in client configuration. Rebuild and restart the deployment, then verify
+people and agents can each open their intended endpoints. See
+[Organizing an agent's pools](./auth.md#organizing-an-agents-pools) for the
+complete layout.

package/documentation/providers.md

@@ -360,6 +360,67 @@ discovery for your deployment's catalog.
 
 <!-- provider-inventory:end -->
 
+## Field selection with `fields`
+
+Every maintained read that projects a result takes an optional `fields`
+argument: up to 50 dot paths, each 1 to 200 characters, that narrow the
+returned data. Selection runs after value safety and privacy filtering, so it
+can only remove values. `a.b` and `a[].b` are equivalent; a list on the way is
+narrowed item by item.
+
+Where paths start, the anchor, depends on the tool and is stated in each
+`fields` schema description with one valid example:
+
+| Tool                                       | Paths start at                     | Example                                      |
+| ------------------------------------------ | ---------------------------------- | -------------------------------------------- |
+| A named read (`get_*` and similar)         | The result                         | `["id"]`, `["owner.name"]`                   |
+| A named list or search (`{ items, page }`) | Each item in `items`               | `["id"]`, not `["items.id"]`                 |
+| `*_api_read` and `*_api_write`             | The vendor response body in `data` | `["projects.name"]`, not `["data.projects"]` |
+
+A hatch body that is a list is narrowed item by item, so its paths start at
+each item. An enveloping vendor nests records under a root, such as
+`{ "projects": [...] }`; select `projects.name`, not `name`. Copy hatch paths
+from the operation's `*_api_details` `response.fields`, which are already in
+these coordinates. Paging, cut and recovery metadata (`page`, `truncated`)
+remain outside the selection where a tool says so.
+
+**Refused before dispatch.** A path outside the declared contract returns
+`invalid_args` before any request. Each finding names the entry position
+(`/fields/1`), the segment where the path left the contract and the properties
+declared there, never the submitted path:
+
+- Named tools check the first segment against the properties their published
+  output schema declares for the result or item. Deeper segments follow JSON
+  Schema's default: an object is closed only where the schema says
+  `additionalProperties: false`, and only such an object refuses an undeclared
+  property. Paths through other objects, open values such as GitHub
+  `search_scoped` rows' `item`, and paths past a scalar are accepted; a miss
+  there is omitted from the selection.
+- Hatch reads and writes check the first segment against the operation's
+  declared response roots. An operation that declares no response properties
+  refuses `fields`. The pinned index does not establish whether deeper levels
+  are complete, so deeper segments are not refused.
+
+**Declared but absent is not an error.** Optional values, empty lists and
+values that value safety or privacy filtering removed are ordinary. A declared
+path the current response lacks is never refused, and the selection omits it.
+
+**Hatch miss warnings.** A hatch answer adds `warnings: string[]` when a
+`fields` entry matched nothing anywhere in a nonempty response. Each warning
+names the entry position, the segment where matching stopped and the
+properties the operation's contract declares there, for example
+`fields/1 matched nothing in this response after value safety and privacy
+filtering, at segment 2; declared there: id, name.` Where the contract
+declares none, such as inside an open map, it says so. A warning never lists
+the response's own keys, which in an open map such as `metadata` are data, and
+never repeats the submitted path. A path that matched in any listed item, a
+path that runs past a scalar (selection keeps the scalar), and any path of an
+empty body (`null`, `[]` or `{}`) produce no warning. Warnings are bounded: each
+is at most 512 characters, at most 10 are kept within 4,096 characters
+together, reviewed vendor warnings included, and a final entry counts the rest
+(`3 more warnings omitted.`). Treat a warning as a repair hint for the next
+call, not as a failure.
+
 ## API operation discovery and boundaries
 
 Standard API operation search accepts resource nouns, actions and conversational
@@ -418,6 +479,50 @@ then follow `page.nextCursor` to reach operations beyond the leading profile
 results. Responses contain at most eight compact hits within 16 KiB; fetch
 operation details separately and keep the same query when continuing.
 
+Operation details return the request contract and, for an operation that is
+not refused and declares success-response properties, a `response` section.
+Write `fields` filters and reductions from it without a sampling read:
+
+- `anchor` is `data` when paths start at the read result's `data`, or `data[]`
+  when the body is a list and each path applies to every item.
+- `fields` lists the declared paths a read can select, in the read and write
+  tools' `fields` coordinates; pass them unchanged, such as
+  `fields: ["data[].id"]`.
+- `withheld` is a best-effort, incomplete hint: the listed paths whose
+  non-null values value safety always withholds or redacts, by a reviewed
+  redaction path, a credential name, the deployment's sensitive-field choice
+  or a closed projection. A rule that can leave some value unchanged is never
+  a hint. Examples are URL sanitizing, reduction to an origin, which returns a
+  bare origin unchanged, redaction by a key, type or label, and a credential
+  suffix rule that scrubs only strings. A container above a hinted path is
+  not hinted either. Every hinted path also appears in `fields`.
+- `omitted` counts declared paths not listed.
+
+**`response` promises no readability.** Value safety runs on every read. A
+value at any listed path, hinted or not, may still be withheld or redacted at
+read time. An unlisted path may be too, so never treat it as safe. Many rules
+depend on the values a vendor returns, which no index knows in advance:
+
+- An expanded or polymorphic object is redacted by its type: for example, a
+  Stripe event's `data` or a Checkout Session's expanded `payment_intent`
+  loses a payment intent's `client_secret`.
+- An opaque container is redacted by its contents: Google Docs
+  `inlineObjects` loses image `contentUri` capabilities, and Vercel drain
+  `headers`, deployment `env` and `protectionBypass` keys are withheld.
+- A labelled or typed record is redacted by its label or type.
+- URLs carrying credentials are sanitized. QuickBooks replaces every http(s)
+  URL in a returned string, including ordinary text such as a Customer
+  `DisplayName` or `CompanyName`, with `[redacted]`.
+- A value echoing a secret the request sent is redacted.
+
+Paths list shallowest first, in index order, up to 100 paths and 4,096
+characters of path JSON, the hint included; a path over 200 characters is
+never listed. The pinned index carries names only, never response types or
+example values. Only the first page of a whole-operation answer carries
+`response`; `param` answers and continuation pages omit it. An operation
+without declared response properties has no `response`, and its reads refuse
+`fields`.
+
 Maintained REST hatches validate path parameters against their pinned contracts
 before dispatch. Integer ids use canonical ASCII decimal notation within the
 safe-integer range and obey the operation's declared bounds; for example,

package/examples/worker/AGENTS.md

@@ -95,16 +95,16 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   Each agent keeps one Connecta connection whose harness, never the model,
   picks the pool per turn. Tiers are nested pools of shared connectors with
   no `owner`, each spreading the tool list below. Recommended names are
-  `<agent>` for the lowest and `<agent>-<tier>` above it; any named pool,
-  including an existing `team` or `leadership` pool, may be a tier if all its
-  human members are cleared for it. A chat gets the most capable tier everyone
-  present is cleared for, and the lowest when anyone present is unknown.
-  `<agent>-<user>` (that user's highest tier plus their own connector ids,
-  `owner` set to their Workspace address) is used only in a one-on-one with
-  that user. List only cleared people in a tier, and never another person in
-  a `<agent>-<user>` pool: its per-user connectors act as that user for every
-  member. Never add a second Connecta connection or mount downstream tools
-  directly.
+  `<agent>` for the lowest and `<agent>-<tier>` above it. Every pool lists
+  only people or only `agent:` references; mixing them throws at
+  construction. Tiers and `<agent>-<user>` pools list only the agent. People
+  with a tier's reach get their own people-only pool (for example `team`
+  beside `assistant-team`) spreading the same tool-list constant. A chat gets
+  the most capable tier everyone present is cleared for, and the lowest when
+  anyone present is unknown. `<agent>-<user>` (that user's highest tier plus
+  their own connector ids, `owner` set to their Workspace address) is used
+  only in a one-on-one with that user. Never add a second Connecta connection
+  or mount downstream tools directly.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand

package/examples/worker/README.md

@@ -380,9 +380,10 @@ declared agent, is available to signed-in maintainers.
 ## Select optional modules
 
 `cloudflareAccessAuth()` reads trusted identity after Access admits the Worker
-request. Maintainers use plain `/mcp` and the operator pages; people in a pool
-use `/mcp/<pool>`, and agents in it `/agent/<pool>`, which serve exactly that
-pool's tools. Agents authenticate with `accessTokens(storage)` over the same D1
+request. Maintainers use plain `/mcp` and the operator pages; people in a
+people pool use `/mcp/<pool>` (or plain `/mcp` when it is their only pool), and
+agents in an agent pool use `/agent/<pool>`; each serves exactly that pool's
+tools. Agents authenticate with `accessTokens(storage)` over the same D1
 database; human endpoints refuse their tokens, and Access service headers alone
 never grant MCP access or interactive authority.
 Keep users, groups, and admission in Access. Connector visibility and management

package/examples/worker/src/connecta.config.ts

@@ -111,6 +111,7 @@ export default defineConfig((env: Env) => {
     // Access user ids or "agent:<name>". The starter pool is the agent's base
     // pool (shared connectors, no owner), named after the agent as the agent
     // pool layout requires.
+    // Each pool lists only people or only agents; share tool lists across separate pools.
     pools: { ci: { tools: ["echo"], members: ["agent:ci"] } },
     // Connectors that declare a `credential` slot become editable by a
     // maintainer (shared) or by the member it belongs to (personal),

package/guides/connecting-agents.md

@@ -11,7 +11,8 @@ has exact setup and verification steps.
 
 Imagine an agent named `assistant` that helps with CRM records and tickets.
 Its operator creates a pool with the actions needed for that job and adds
-the agent as a member. The pool can be read-only if updates must be impossible.
+the agent as a member. Agent pools contain only agents; people use separate
+pools that can share the same tool list. The pool can be read-only if updates must be impossible.
 
 ```mermaid
 flowchart LR

package/guides/how-it-works.md

@@ -41,7 +41,7 @@ For setup and migrations, see [Integrating services](../documentation/integratin
 
 A **pool** is a named selection of tools and the people or agents allowed
 to use them. The operator creates it and gives it an **endpoint**: a
-connection address for that pool.
+connection address for that pool. Each pool lists only people or only agents.
 
 One pool might let the assistant read CRM records. Another might let a
 person update tickets. Tools and accounts are separate choices: a pool
@@ -65,7 +65,9 @@ choose the right one for the conversation. The model does not choose its
 own access level.
 
 Maintainers run the deployment and can reach its whole tool list through
-the main human endpoint. Other people use their assigned pools.
+the main human endpoint, `/mcp`. Other people use their assigned pools. A
+person in exactly one pool can use that same `/mcp` address: their sign-in
+selects the pool, and they get only its tools.
 Agents use shared accounts selected by the operator. They do not inherit
 the account of the person chatting with them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",

package/templates/node/AGENTS.md

@@ -33,8 +33,9 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   Issue or rotate an agent's token with `npm run --silent rotate-token -- <agent>`
   against the same configuration and database the server uses; bind a token
   from before agents once with `npm run adopt-token -- <token-id> <agent>`.
-  Plain `/mcp` serves `maintainers` only; other people reach `/mcp/<pool>` and
-  agents `/agent/<pool>` for a pool listing them in `members` (`npm run doctor`
+  Plain `/mcp` serves `maintainers` the whole catalog and each other person
+  in exactly one pool that pool; people also reach `/mcp/<pool>` and agents
+  `/agent/<pool>` for a pool listing them in `members` (`npm run doctor`
   checks `/agent/local-machine`). Human endpoints refuse `cta_` tokens. `CONNECTA_TOKEN` is only for clients and doctor; never add a configured
   static bearer or an open startup mode.
   All state, activity included, lives in the one SQLite file `CONNECTA_DATABASE`
@@ -45,16 +46,16 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   Each agent keeps one Connecta connection whose harness, never the model,
   picks the pool per turn. Tiers are nested pools of shared connectors with
   no `owner`, each spreading the tool list below. Recommended names are
-  `<agent>` for the lowest and `<agent>-<tier>` above it; any named pool,
-  including an existing `team` or `leadership` pool, may be a tier if all its
-  human members are cleared for it. A chat gets the most capable tier everyone
-  present is cleared for, and the lowest when anyone present is unknown.
-  `<agent>-<user>` (that user's highest tier plus their own connector ids,
-  `owner` set to their Workspace address) is used only in a one-on-one with
-  that user. List only cleared people in a tier, and never another person in
-  a `<agent>-<user>` pool: its per-user connectors act as that user for every
-  member. Never add a second Connecta connection or mount downstream tools
-  directly.
+  `<agent>` for the lowest and `<agent>-<tier>` above it. Every pool lists
+  only people or only `agent:` references; mixing them throws at
+  construction. Tiers and `<agent>-<user>` pools list only the agent. People
+  with a tier's reach get their own people-only pool (for example `team`
+  beside `assistant-team`) spreading the same tool-list constant. A chat gets
+  the most capable tier everyone present is cleared for, and the lowest when
+  anyone present is unknown. `<agent>-<user>` (that user's highest tier plus
+  their own connector ids, `owner` set to their Workspace address) is used
+  only in a one-on-one with that user. Never add a second Connecta connection
+  or mount downstream tools directly.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand

package/templates/node/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.38.0",
+    "@zackbart/connecta": "0.39.0",
     "quickjs-emscripten": "0.32.0",
     "undici": "6.29.1"
   },

package/templates/node/src/connecta.config.ts

@@ -102,6 +102,7 @@ export default defineConfig((env: Env) => {
     // `npm run doctor` checks /agent/local-machine with its token. The starter
     // pool is the agent's base pool, its lowest tier (shared connectors, no
     // owner), named after the agent as the agent pool layout requires.
+    // Each pool lists only people or only agents; share tool lists across separate pools.
     pools: { "local-machine": { tools: ["time"], members: ["agent:local-machine"] } },
     // Machine clients are agents declared here by name, each with one cta_
     // token. Issue or rotate one locally with