@zackbart/connecta 0.31.0 → 0.32.0

package/documentation/operating.md

@@ -15,14 +15,17 @@ instructions and `skills` usage guide for deployment-specific context.
 | ------------------------------------------------------------------ | --------------------------------------------------------- |
 | One known read, with usable arguments and a small result           | `call_tool`                                               |
 | Discover a tool, chain calls, combine services, or reduce a result | `execute_code`                                            |
-| One write on a read-only endpoint                                  | `call_destructive_tool`                                   |
+| One known write on a writable endpoint                             | `call_destructive_tool`                                   |
 | Obtain connector instructions                                      | `skills` with the returned guide name                     |
 | Start a required authentication handoff                            | `authorize_connector`, using the returned recovery action |
 
-The endpoint's trust is part of its tool descriptions. On a `trusted` endpoint,
-programs may write within the caller's grants, and `execute_code` is annotated
-as a write. On `read-only`, every write is a separate top-level call. The host
-controls approval. Never change pool, identity, or trust to work around a refusal.
+Whether the endpoint is read-only or writable is part of its tool
+descriptions. On a writable endpoint, programs and `call_destructive_tool` may
+write within the caller's grants, and `execute_code` is annotated as a write;
+the client controls approval. On a read-only endpoint, search and describe omit
+write tools and every write call is refused with `read_only_endpoint`, even one
+a connector guide names; tell the user rather than looking for another route. Never change pool, identity, or `readOnly` to work
+around a refusal.
 [Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
 owns the full decision rules.
 
@@ -35,9 +38,9 @@ failed catalog or a service outside the caller's grants.
 
 For normal reads, keep discovery, calls, and reduction in one program when the
 schemas suffice; return the answer rather than catalog matches. Use top-level
-`search_tools` for catalog inspection or to discover a write on a read-only
-endpoint, then dispatch each write with `call_destructive_tool`. An unfamiliar
-read result may return a bounded sample for inspection before the next program.
+`search_tools` for catalog inspection or to find one known write on a writable
+endpoint, then dispatch it with `call_destructive_tool`. An unfamiliar read
+result may return a bounded sample for inspection before the next program.
 
 Use the exact returned `address`, including punctuation. A TypeScript signature
 is guidance for writing JavaScript; do not paste types into executable code.

package/documentation/operator-tests.md

@@ -72,9 +72,8 @@ gh run download RUN_ID --name operator-linux-snapshots \
 
 The workflow uploads all generated baselines and never commits them. Review the
 images and changed files, commit the intentional changes, and push again. The
-normal CI browser job must compare and pass against that commit. Opening the
-initial PR also runs the update workflow, so the first baselines can be generated
-before the workflow reaches main. Later updates use `workflow_dispatch`.
+normal CI browser job must compare and pass against that commit. Snapshot
+updates run only through `workflow_dispatch`.
 
 On a matching Linux runner, `npm ci`, install Chromium with the command above,
 then run `npm run test:browser:snapshots`. The normal command is

package/documentation/operator-ui.md

@@ -42,7 +42,9 @@ from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
 source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
 `config` is the construction-time `describeConfig()` snapshot, filtered to
 visible connectors, granted tools, classification overrides, and admitted
-pools. Pool tools are the intersection with the caller's identity grants.
+pools. `config.hasGrant` reports whether deployment code configures a grant for
+plain `/mcp`; Access displays that fact and Config includes its provenance.
+Pool tools are the intersection with the caller's identity grants.
 `configSources` labels each serialized leaf as `default` or `config`, based on
 option presence rather than equality with the default. Factory descriptions carry
 relative `optionSources` paths so resolved module and transport defaults retain
@@ -52,6 +54,10 @@ ids and pool names and are filtered after disclosure; hidden values leave no
 provenance keys. It contains no source code or credential material.
 Every response is private, `no-store` JSON. Only GET is allowed, with the
 same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
+These catalog reads, activity reads, and connector auth routes also require
+admission through the default `/mcp` grant. Refusals return private JSON 404s;
+there is no per-pool UI view. Public HTML shells and static assets carry no
+catalog data. Access-token management retains its interactive permission gate.
 
 `live.connectors` carries status and problem codes, complete registry tools
 with their final read/write classification, catalog age in milliseconds, and
@@ -69,7 +75,7 @@ personal connectors to the caller's activity identity. Each retained fact
 copies a validated timestamp and outcome only. A null call means unknown or
 absent in that window, not proof of no calls. `live.activity` distinguishes
 available, unconfigured, forbidden, and unavailable history. `you` names no
-identity or auth material; it reports grants, root and admitted-pool trust,
+identity or auth material; it reports grants, whether the root and admitted pools are read-only,
 and effective activity, token, and per-connector auth permissions.
 
 `connecta doctor --config` fetches this authenticated contract and prints only
@@ -112,7 +118,7 @@ id and typed actor when available, otherwise a fresh id and system actor. No
 names, descriptions or schemas enter the event. Private catalog changes require
 a matching principal owner even when the connector uses shared auth. Empty credential declarations
 report `credential_required` before running a connector status or catalog probe.
-The Access adapter reports inbound provider kinds, admitted pools, grants, trust
+The Access adapter reports inbound provider kinds, admitted pools, grants, read-only endpoints
 and endpoint setup; token controls retain their existing permission gate.
 Configuration remains in deployment code. The UI mutates only credentials,
 OAuth connections and client tokens through the existing routes.

package/documentation/provider-auth-migration.md

@@ -183,8 +183,8 @@ connector beside the token connector.
 
 The hosted connection now lists `filter_project_envs`, `get_project_env`,
 `create_project_env`, and `edit_project_env`, which 0.29 hid. The two reads can
-return decrypted values, so they are reviewed as writes and the pool trust
-policy gates them. Vercel admits only reviewed and approved MCP clients to its
+return decrypted values, so they are reviewed as writes, and a `readOnly`
+endpoint refuses them. Vercel admits only reviewed and approved MCP clients to its
 hosted server; if authorization is refused for that reason, the deployment
 needs Vercel's approval or a token connector. The
 [Vercel skill](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/SKILL.md)
@@ -245,8 +245,9 @@ hooks) and redacts stored secrets on every result. A pinned connector refuses
 operations that name no account or zone unless they are reviewed safe, such
 as `/certificates` and `/memberships/{id}`.
 
-Read-only pools: hosted `execute` is always a write, even for a program that
-only reads, so a read-only pool on an OAuth connector reaches only `search`.
+Read-only endpoints: hosted `execute` is always a write, even for a program
+that only reads, so a `readOnly` endpoint on an OAuth connector reaches only
+`search`.
 Use an API-token connector for read-only API access.
 
 Lost on each path. OAuth has no index validation, named tools, GraphQL tool,

package/documentation/provider-migration-0.29.md

@@ -58,7 +58,7 @@ complement. Replace `update_r2_bucket` with `cloudflare_api_mutate` using
 `cf-r2-storage-class` set to `Standard` or `InfrequentAccess`. Omit the body;
 include `cf-r2-jurisdiction` only when the bucket needs it. This remains a write.
 `execute` remains a write even when its program only calls GET.
-Trusted pools may execute writes; read-only pools use direct host-approved writes.
+Writable endpoints may run `execute`; `readOnly` endpoints refuse it.
 
 Vercel's `surface` and ownership rules were later replaced: `auth` now selects
 the implementation. See the [provider auth migration](./provider-auth-migration.md#vercel).

package/examples/worker/AGENTS.md

@@ -37,6 +37,11 @@ This repository is deployment configuration, not a copy of Connecta itself.
   Import it from `@zackbart/connecta/worker`; direct upstream
   `new DynamicWorkerExecutor()` construction throws at boot. Keep the
   `@cloudflare/codemode` optional peer installed.
+- Keep the required `readOnly` choice in `src/connecta.config.ts`; startup
+  fails without it. `true` omits write tools from search and describe and
+  refuses every write call; `false` lets them run with MCP host approval. Named
+  pools inherit it unless they set their own `readOnly`. Do not configure the
+  removed `trust`.
 - Keep credentials in Worker secrets. Never commit credential values, Access
   service-token secrets, or `CREDENTIAL_ENCRYPTION_KEY`.
 - All state lives in the one D1 database bound as `CONNECTA_DB`, through

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

@@ -69,6 +69,11 @@ export default defineConfig((env: Env) => {
   return {
     publicUrl: env.PUBLIC_URL,
     storage,
+    // Required: can /mcp write? false lets call_destructive_tool and programs
+    // write, with the MCP client approving; true leaves write tools out of
+    // search and describe and refuses every write call. Pools inherit it
+    // unless they set their own readOnly. Startup fails without it.
+    readOnly: false,
     // Required adapter owns each run's handles; direct upstream construction throws.
     executor: workerExecutor({ loader: env.LOADER }),
     // Access owns edge admission and proves human identity for MCP and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.31.0",
+  "version": "0.32.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.",
@@ -157,6 +157,10 @@
       "types": "./dist/providers/vercel/index.d.ts",
       "import": "./dist/providers/vercel/index.js"
     },
+    "./providers/wispr-flow": {
+      "types": "./dist/providers/wispr-flow/index.d.ts",
+      "import": "./dist/providers/wispr-flow/index.js"
+    },
     "./ui": {
       "types": "./dist/ui.d.ts",
       "import": "./dist/ui.js"

package/templates/node/AGENTS.md

@@ -5,10 +5,12 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Edit `src/connecta.config.ts` for connectors, authentication, storage, public
   URL, and optional modules. `src/index.ts` only starts it.
 - Keep `executor: quickJsExecutor()` for the prescribed six-tool code-first
-  surface. Root and named pools default to `trust: "read-only"`: programs
-  may read, and writes use `call_destructive_tool`. Explicit `trusted` pools
-  also permit program writes and annotate `execute_code` as a write. Approval
-  belongs to the MCP host. Do not configure the removed `execute.approval`.
+  surface. Keep the required `readOnly` choice in the config: `false` lets
+  `call_destructive_tool` and programs write and annotates `execute_code` as
+  a write; `true` omits write tools from search and describe and refuses every
+  write call. Named pools inherit it unless they set their own `readOnly`.
+  Approval belongs to the MCP host. Do not configure the removed `trust` or
+  `execute.approval`.
 - Keep credentials in environment variables or an external secret store.
   Never commit `.env`, `.connecta.sqlite` (and its `-wal`/`-shm` files),
   tokens, or credential values.

package/templates/node/README.md

@@ -125,8 +125,10 @@ stored machine token to inspect Connections. Sign in with Clerk for human
 connection management. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
-The page labels each tool as a read or write. Trusted programs may write;
-read-only pools use `call_destructive_tool`, with approval controlled by the host. For
+The page labels each tool as a read or write and each endpoint as writable or
+read-only. `src/connecta.config.ts` must set `readOnly`: a read-only endpoint
+refuses every write call and leaves write tools out of search, and the host
+controls approval on a writable one. For
 classified connection failures it offers a fixed repair prompt, and its
 endpoint section has client setup commands for `/mcp` and any pool available
 to the signed-in identity. Those commands contain no bearer token.

package/templates/node/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.31.0",
+    "@zackbart/connecta": "0.32.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

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

@@ -68,6 +68,11 @@ export default defineConfig((env: Env) => {
   return {
     storage,
     publicUrl,
+    // Required: can /mcp write? false lets call_destructive_tool and programs
+    // write, with the MCP client approving; true leaves write tools out of
+    // search and describe and refuses every write call. Pools inherit it
+    // unless they set their own readOnly. Startup fails without it.
+    readOnly: false,
     // Required: model-written programs run in a bounded QuickJS child.
     executor: quickJsExecutor(),
     auth: clerk ? [clerk] : [],

package/dist/tool-safety.d.ts

@@ -1,9 +0,0 @@
-import type { ToolDef, ToolVerdict } from "./types.js";
-export type PoolTrust = "trusted" | "read-only";
-/** Deployment override, then verified provider review, then fail-closed hints. */
-export declare function classifyTool(definition: ToolDef, override?: "read" | "write", review?: {
-    verdict: ToolVerdict;
-    stale?: boolean;
-}): "read" | "write";
-/** The only permission decision for a connector call. Approval is host-owned. */
-export declare function surfaceAllowsTool(classification: ToolDef["classification"], surface: string, trust?: PoolTrust): boolean;