@zackbart/connecta 0.37.1 → 0.39.0

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

@@ -67,12 +67,10 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
 - All state lives in the one D1 database bound as `CONNECTA_DB`, through
   `d1Storage` (and `d1ActivityStore`) from `@zackbart/connecta/d1`. Do not add
   a KV namespace, a second database, or a copied storage adapter; connecta
-  creates its own tables. The only KV binding is in `kv-to-d1.wrangler.jsonc`,
-  which is never deployed. It exists for the one-shot copy from a 0.28 Workers
-  KV deployment (README.md § "Upgrading from 0.28"). Back up, block traffic
-  and background writers, drain, wait for stable KV, copy and verify, deploy
-  while maintenance remains, then mark cutover before reopening traffic. Never
-  rerun stale KV after cutover. Retain backups before removing KV.
+  creates its own tables. Pre-0.29 Workers KV state must be copied on
+  Connecta 0.37.1 before upgrading past that bridge release; follow the installed
+  package's `documentation/migration-retired-layouts.md`. The current example
+  includes no KV copy script or binding.
 - Add application logic only inside deliberate `api()` connector handlers.
   Do not copy or modify Connecta package internals here.
 - Prefer `api()` when the agent must see an exact reviewed capability set;
@@ -97,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

@@ -21,14 +21,13 @@ migrations, and secrets.
 
 ## Files
 
-| File                                                   | What it is                                                                                                                                                        |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/index.ts`                                         | the Worker entrypoint — starts the configuration, under 30 lines                                                                                                  |
-| `src/connecta.config.ts`                               | connectors, auth, storage, and optional modules, as `defineConfig((env) => …)`                                                                                    |
-| `alchemy.run.ts`                                       | the deployment: Worker, vars, secrets, D1, Worker Loader, and both Access applications                                                                            |
-| `wrangler.jsonc`                                       | local `wrangler dev` only, with a simulated Access identity; never used to deploy                                                                                 |
-| `gitignore`                                            | the copied deployment's `.gitignore`, shipped under this name because npm strips `.gitignore` ([Copied into its own repository](#copied-into-its-own-repository)) |
-| `scripts/copy-kv-to-d1.mjs`, `kv-to-d1.wrangler.jsonc` | one-shot copy of a 0.28 Workers KV deployment's state into D1, run once and deleted ([Upgrading from 0.28](#upgrading-from-028))                                  |
+| File                     | What it is                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`           | the Worker entrypoint — starts the configuration, under 30 lines                                                                                                  |
+| `src/connecta.config.ts` | connectors, auth, storage, and optional modules, as `defineConfig((env) => …)`                                                                                    |
+| `alchemy.run.ts`         | the deployment: Worker, vars, secrets, D1, Worker Loader, and both Access applications                                                                            |
+| `wrangler.jsonc`         | local `wrangler dev` only, with a simulated Access identity; never used to deploy                                                                                 |
+| `gitignore`              | the copied deployment's `.gitignore`, shipped under this name because npm strips `.gitignore` ([Copied into its own repository](#copied-into-its-own-repository)) |
 
 Construct Connecta once per isolate and pass `ctx` through to `fetch`, as the
 example entrypoint does.
@@ -261,31 +260,10 @@ the Access policy or application.
 
 ### Let agents through Access
 
-`ConnectaAgents` in `alchemy.run.ts` is a second self-hosted Access
-application whose destination is `<PUBLIC_URL host>/agent/*`, with a single
-policy whose action is **Bypass** and whose include rule is **Everyone**. The
-Worker-level application still protects every other path. Never bypass any
-other path. To serve agents on another hostname too, add a destination for it,
-for example `{ type: "public", uri: "agents.example.com/agent/*" }`. Through the
-Access API, the application is:
-
-```json
-{
-  "type": "self_hosted",
-  "name": "connecta agents",
-  "destinations": [{ "type": "public", "uri": "connecta.example.com/agent/*" }],
-  "policies": [{ "name": "agents bypass", "decision": "bypass", "include": [{ "everyone": {} }] }]
-}
-```
-
-It must be a hostname-and-path (`public`) destination: a second Worker
-destination is refused because the Worker-level application owns it. Changes
-took 15–19 seconds to settle when probed, occasionally longer, with transient
-edge errors meanwhile. Do not rely on a fixed wait; repeat
-[Verify after deploying](#verify-after-deploying). Connecta ignores Access
-context on `/agent/*` and refuses every other spelling of that namespace before
-auth. [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#agent-endpoints-behind-cloudflare-access)
-records the untested cases and the propagation details.
+`ConnectaAgents` in `alchemy.run.ts` declares the agent bypass. Follow
+[Agent endpoints behind Cloudflare Access](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#agent-endpoints-behind-cloudflare-access)
+for the hostname-and-path application, API JSON, matching rules and controls.
+Repeat [Verify after deploying](#verify-after-deploying) after Access changes.
 
 ### Moving a Wrangler-deployed Worker to Alchemy
 
@@ -357,7 +335,7 @@ it reports, run Alchemy and Wrangler only on a trusted machine, keep
 `alchemy dev` and `wrangler dev` bound to localhost, and give the API token
 only the four permissions in [Deploy](#deploy) and a short expiry.
 
-`wrangler` serves only `wrangler dev` and `scripts/copy-kv-to-d1.mjs`. A
+`wrangler` serves local `wrangler dev`. A
 `tsconfig.json` like the following lets `tsc --noEmit`
 resolve `D1Database`, `WorkerLoader`, and `ExecutionContext`, and checks the
 stack:
@@ -402,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
@@ -623,87 +602,14 @@ Each shape moves to the one `CONNECTA_DB` binding:
 
 #### Copying Workers KV state into D1
 
-Storage keys did not change in 0.29. `copyKvToD1(kv, db, { source })` from
-`@zackbart/connecta/d1` preserves live keys, exact values including vault
-ciphertext, and absolute expiries. The source is the KV namespace id. Counts
-and failures name only families, never keys or values. Oversized UTF-8 strings
-or rows are skipped and counted as invalid against D1's
-[2,000,000-byte limit](https://developers.cloudflare.com/d1/platform/limits/).
-A different live D1 value or expiry is a conflict, kept by default.
-
-Use a maintenance window. Copying while either deployment serves can restore
-revoked tokens, stale refresh tokens, or disconnected connectors. A rerun is
-safe only while the source remains stable and D1 has no new application writes.
-The script reads the source id from `kv-to-d1.wrangler.jsonc` and checks two
-consecutive listing/hash passes before a copy or verification pass. The config
-uses remote KV and D1 bindings and is never deployed.
-
-Prepare the new configuration without deploying it. Use the existing activity
-D1 database as `CONNECTA_DB`, keeping its name and id; otherwise create one
-with `wrangler d1 create connecta`. Remove `kv_namespaces` and copied adapters.
-Configuration lives in `src/connecta.config.ts` and
-`src/index.ts` is the entry point. Set the plain var `CONNECTA_ACTIVITY = "on"`
-so preserved activity remains visible. Bind only `CONNECTA_DB` and `LOADER` for storage/execution;
-keep existing auth vars and the credential secret.
-Fill in the copy config's namespace id and the same D1 database name/id,
-then `wrangler login` and check the prepared deployment with a dry run.
-
-1. Back up KV with a bulk export including values and expiration metadata.
-   Export D1 with `wrangler d1 export <db> --remote --output before-cutover.sql`.
-   Store backups securely and preserve the exact credential encryption key,
-   whatever secret name the deployment stores it under.
-2. Block traffic using maintenance mode or turn the route off. Stop cron,
-   queue consumers, scheduled jobs, and every other KV/D1 writer. Drain all
-   in-flight requests, including OAuth callbacks and token refreshes.
-3. Wait at least **60 seconds after the last write**, or the longest configured
-   KV `cacheTtl`, whichever is greater. KV propagation can take longer, so this
-   is a minimum, not proof of consistency. See
-   [KV consistency](https://developers.cloudflare.com/kv/concepts/how-kv-works/).
-   Confirm a stable source with two consecutive listing/hash passes that match;
-   the script performs this check. If they differ, stay in maintenance, wait
-   longer, and repeat. Expiring entries may also require another pass.
-4. Copy **before switching traffic** with
-   `node scripts/copy-kv-to-d1.mjs --maintenance`. Resolve all `invalid` and
-   `conflicts` counts under maintenance; either makes the script exit non-zero.
-   An oversized entry requires a deliberate per-family remediation, not a
-   retry of the same value. Overwrite only families explicitly reviewed as
-   stale in D1, for example `--maintenance --overwrite-family catalog`.
-   Token/OAuth/vault families require the operator to confirm D1 rows are stale
-   and also pass `--confirm-stale-d1`; never infer this from a conflict alone.
-   There is no blanket `--overwrite`. Then run
-   `node scripts/copy-kv-to-d1.mjs --maintenance --verify`. It compares SHA-256
-   hashes of exact values and absolute expiries for live source keys, reports
-   `verified` / `mismatches` counts by family only, and exits non-zero on any
-   invalid entry or mismatch. Keep traffic and writers stopped until these
-   counts are resolved. A verification pass does not rewrite copied entries.
-5. Deploy the D1 configuration with the deployment's `wrangler deploy` while maintenance remains.
-   Run `connecta doctor --pool <pool>` using Access service credentials plus a
-   stored `cta_` bearer through `CONNECTA_TOKEN`. Verify an existing
-   OAuth connector without re-consent, an existing `cta_` token, a connector
-   using a vault credential, and prior activity in the Activity view. Run
-   these controlled checks with other traffic and background writers blocked.
-6. Seal the source with
-   `node scripts/copy-kv-to-d1.mjs --maintenance --mark-live`, then reopen
-   traffic and background writers. The permanent D1 marker refuses later
-   copies. Never rerun after traffic resumes. `--i-know-this-is-stale` is only
-   an emergency override after stopping writers again and assessing stale KV;
-   it does not make stale tokens or credentials safe to restore.
-   Retain backups before deleting the KV namespace. After a clean observation
-   period, remove the copy script/config and delete KV with
-   `wrangler kv namespace delete --namespace-id <id>`.
-
-An in-Worker copy can call
-`copyKvToD1(env.CONNECTA_KV, env.CONNECTA_DB, { source: namespaceId, cursor })`
-from a guarded one-off route under the same maintenance procedure. Each call
-reads at most `maxKeys` keys, default 500. For near-limit rows use 200 or fewer
-so additional byte-bounded D1 batches fit the invocation's query budget.
-Loop until `done`, passing each returned cursor. Tokens keep KV's raw cursor
-in D1 for seven days, are bound to the source id, and are atomically consumed.
-Unknown, spent, or foreign-source tokens are refused without echoing them.
-On failure, use the error's replacement token or restart under maintenance.
-Call `markKvToD1Live(db, namespaceId)` before reopening traffic, and remove the
-route and KV binding. The source stability check is the operator's duty when
-using the API directly. Remote bindings remain unverified until deploy day.
+Complete this conversion on Connecta 0.37.1 before installing the release
+that removes migrations. The current `/d1` subpath provides `d1Storage` and
+`d1ActivityStore`; it no longer exports `copyKvToD1`, `markKvToD1Live`, or
+migration types, and this example no longer includes the copy script/config.
+Use the 0.37.1 package's Worker example under maintenance, verify the copy,
+mark cutover, and open every owner's OAuth grant on that bridge release.
+Follow [Retired layout migrations](../../documentation/migration-retired-layouts.md)
+for the required order and recovery. Never copy stale KV into a live database.
 
 ## Activity history (optional)
 

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
@@ -68,14 +69,11 @@ sequenceDiagram
     C-->>H: Serve the pool's permitted tools
 ```
 
-Anyone who obtains either token can act as the agent. Trust the Vercel
-project code and build steps that can obtain its tokens, and enable only
-environments that should have the pool's access.
-
-The [token management guide](../documentation/auth.md#issue-rotate-or-revoke-an-agent-token)
+[Safety and trust](./safety-and-trust.md#a-credential-proves-an-agent-not-a-person)
+explains who can act with these credentials. The
+[token management guide](../documentation/auth.md#issue-rotate-or-revoke-an-agent-token)
 and [Vercel identity guide](../documentation/auth.md#vercel-workload-credentials)
-own availability, setup, rotation, and revocation. If both methods are
-enabled, stopping one does not stop the other.
+own setup, rotation, and revocation.
 
 ## An optional integration for Eve
 
@@ -114,29 +112,9 @@ identity. Instructions help the model use tools; they grant no permissions.
 
 ## Decide whether writes need a person
 
-The helper defaults to unattended execution of authorized writes. Connecting
-an agent does not automatically add an approval step.
-
-```mermaid
-flowchart TB
-    Call["Agent requests a change"] --> Ask{"App asks for approval?"}
-    Ask -->|Yes| Approved{"Person approves?"}
-    Approved -->|No| Stop["Stop"]
-    Approved -->|Yes| Pool{"Connecta allows this write?"}
-    Ask -->|No| Pool
-    Pool -->|No| Refuse["Refuse before sending"]
-    Pool -->|Yes| Send["Send the change"]
-```
-
-For an interactive Eve agent, `gateWrites: true` asks before tools not marked
-read-only. An explicit Eve approval policy takes precedence. If the agent
-must never update data, use a read-only pool.
-
-Approval may rely on an earlier tool label. A writable pool can execute a
-newly classified write without a fresh approval; a read-only pool refuses it.
-[Safety and trust](./safety-and-trust.md) explains the boundary, and the
-[helper guide](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md#approval-and-writes)
-explains the policy mechanics.
+Agree on an approval policy before enabling writes. See
+[approval boundaries](./safety-and-trust.md#read-only-blocks-actions-that-change-data)
+and the [Eve helper's approval setup](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md#approval-and-writes).
 
 ## When accounts or audiences differ
 

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.
 
@@ -115,8 +117,8 @@ unbounded data.
 
 With meta-tools, one discovered read can use a direct call. Finding an unfamiliar
 action, combining several calls, or reducing a large answer belongs in a program.
-On a writable endpoint, a program may also change data. The AI app decides
-whether to ask for approval before running it.
+On a writable endpoint, a program may also change data; see
+[approval boundaries](./safety-and-trust.md#read-only-blocks-actions-that-change-data).
 
 The [endpoint workflow](../documentation/operating.md) and
 [code reference](../documentation/code-mode.md) explain the mechanics.

package/guides/safety-and-trust.md

@@ -71,7 +71,10 @@ or contradictory read hints count as writes, but a service can mislabel an
 action and an operator can override its label. Use restricted service
 credentials as another boundary where possible.
 
-The AI app owns approvals. It may ask based on an earlier tool label. If a
+The Eve helper defaults to unattended authorized writes. For interactive use,
+`gateWrites: true` asks before tools not marked read-only; an explicit Eve
+approval policy takes precedence. The AI app owns approvals. It may ask based
+on an earlier tool label. If a
 read becomes a write, a writable pool can execute it without a fresh
 approval; a read-only pool refuses it. Connecta does not pause a program to
 ask a person partway through.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.37.1",
+  "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.",
@@ -191,7 +191,6 @@
     "check:declarations": "node scripts/check-declarations.mjs --dist .",
     "check:bundle": "node scripts/bundle-size.mjs",
     "providers:check": "tsx scripts/drift-check.mjs --specs --manual",
-    "drift:check": "tsx scripts/drift-check.mjs",
     "eval:selftest": "tsx eval/selftest.ts",
     "eval:agent": "tsx eval/run-agent.ts",
     "eval:smoke": "tsx eval/run-smoke.ts",
@@ -257,31 +256,32 @@
   "devDependencies": {
     "@clerk/backend": "3.12.0",
     "@cloudflare/codemode": "^0.5.0",
-    "@cloudflare/vitest-pool-workers": "^0.18.8",
-    "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
+    "@cloudflare/vitest-plugin": "^1.4.3",
+    "@cloudflare/workers-types": "5.20260804.1",
     "@effect/platform-node": "4.0.5",
     "@fontsource-variable/hanken-grotesk": "^5.3.0",
     "@fontsource-variable/jetbrains-mono": "^5.3.0",
-    "@playwright/test": "^1.62.0",
-    "@radix-ui/react-dialog": "^1.2.0",
-    "@radix-ui/react-tabs": "^1.1.22",
-    "@tanstack/react-router": "^1.170.41",
-    "@types/node": "^22.0.0",
+    "@playwright/test": "^1.64.1",
+    "@radix-ui/react-dialog": "^1.3.1",
+    "@radix-ui/react-tabs": "^1.2.1",
+    "@tanstack/react-router": "^1.170.44",
+    "@types/node": "^22.20.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "alchemy": "2.0.0-beta.83",
     "cmdk": "^1.1.1",
-    "esbuild": "^0.28.0",
-    "knip": "^6.29.0",
-    "oxfmt": "0.72.0",
-    "oxlint": "^1.76.0",
+    "esbuild": "^0.28.2",
+    "knip": "^6.41.0",
+    "oxfmt": "0.73.0",
+    "oxlint": "^1.88.0",
     "quickjs-emscripten": "^0.32.0",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "tsx": "^4.23.1",
-    "typescript": "^5.9.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
     "undici": "6.29.1",
-    "vitest": "^4.1.6",
-    "wrangler": "^4.114.0"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4",
+    "wrangler": "^4.151.0"
   }
 }

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/README.md

@@ -19,19 +19,9 @@ npm start
 ```
 
 Keep the template's pinned `undici` dependency and its `listen` import from
-`@zackbart/connecta/node`. `listen` installs the owned HTTP transport used by
-every maintained-provider request, reads included, remote MCP writes, and
-downstream OAuth token, registration and revocation POSTs.
-Without `listen()`, maintained-provider writes, reviewed POST reads and remote
-MCP writes are refused before sending; downstream OAuth credential POSTs also
-require the owned sender. It connects directly by default. For an HTTP(S) CONNECT
-proxy, configure `listen(connecta, { port, proxy: "http://proxy.example.com:8080" })`
-in `src/index.ts`. Ambient proxy variables and host dispatchers do not configure
-the owned sender. Remote MCP reads and OAuth discovery GETs retain native fetch
-and need their own host proxy policy. An uncertain refresh requires fresh
-authorization rather than replaying the spent token. See
-[Node transport requirements](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#start-on-node)
-for proxy credentials and TLS trust.
+`@zackbart/connecta/node`. Follow the
+[Node transport and proxy requirements](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#start-on-node)
+when changing `src/index.ts` or configuring egress.
 
 The manifest approves only `esbuild@0.28.2` to run its install script. `tsx`
 uses esbuild to run this TypeScript source, so that script is part of the
@@ -128,19 +118,12 @@ first use, and commits one row per write. Back it up as one file, together
 with its `-wal` file while the server runs. Node 22 and 23 print an
 experimental-feature warning for `node:sqlite` once at startup.
 
-Upgrading from 0.28, which kept state in `.connecta-state.json`: stop the
-server, then copy the old file into the database once, before the first start:
-
-```sh
-npx connecta migrate-state .connecta-state.json .connecta.sqlite
-```
-
-In the container, mount the old file and import it into the volume:
-`docker compose run --rm -v "$PWD/.connecta-state.json:/import/state.json:ro"
-connecta npx connecta migrate-state /import/state.json /data/connecta.sqlite`. It copies every live entry with its expiry, keeps any
-key the database already holds, and never changes the old file; delete that
-once the deployment is verified. The 0.28 activity log
-(`.connecta-activity.jsonl`) is not imported; history starts fresh.
+Upgrading from the pre-SQLite JSON state format requires importing it with
+Connecta 0.37.1 before installing the release that removes migrations. The
+current package has no `importStateFile` or `connecta migrate-state`; SQLite
+never reads `.connecta-state.json`. Follow the installed package's
+`documentation/migration-retired-layouts.md`, including opening every OAuth
+grant on 0.37.1, before changing the pin.
 
 A build with no lockfile in the context resolves the pinned Connecta version
 itself, and a lockfile npm writes inside the image never reaches this project.