@zackbart/connecta 0.41.0 → 0.42.0

package/documentation/operating.md

@@ -12,7 +12,7 @@ Use your host's tool search, call a known operation directly, and follow its
 repair or authorization handoff. Use `execute_code` for combined work when
 listed; without code, page results through the listed `read_result` tool.
 
-Meta endpoints expose six top-level tools. Read [the tool table](./meta-tools.md#the-six-tools)
+Meta endpoints expose six top-level tools, plus `execute_read_code` on a writable `/mcp` or `/mcp/<pool>`. Read [the tool table](./meta-tools.md#the-meta-tools)
 for exact arguments and result envelopes. Follow the endpoint's supplied
 instructions and `skills` usage guide for deployment-specific context.
 
@@ -22,7 +22,7 @@ instructions and `skills` usage guide for deployment-specific context.
 | Discover a tool, chain calls, combine services, or reduce a result | `execute_code`                                            |
 | 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 |
+| Start an authentication handoff no error has given you             | `authorize_connector`, using the returned recovery action |
 
 Whether the endpoint is read-only or writable is part of its tool
 descriptions. On a writable endpoint, programs and `call_destructive_tool` may
@@ -127,7 +127,9 @@ which URIs may be read. Connector guides and native skills are described in
 
 ## Recover without replaying a write
 
-Read typed failures and their `nextAction`. Authorization recovery can point
+Read typed failures and their `nextAction`. An auth error that carries a link
+says so in `nextAction.url`: give that link to the user unchanged and stop, with
+no further call. Authorization recovery can point
 to consent, operator credential setup, or deployment configuration. Discovery
 and status do not begin consent on their own. Follow
 [authorization recovery](./meta-tools.md#authorization-recovery),

package/documentation/providers.md

@@ -409,9 +409,11 @@ path the current response lacks is never refused, and the selection omits it.
 `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
+`fields/1 matched nothing after filtering, at segment 2; declared there: id,
+name.` Filtering means value safety and privacy filtering. The list stops at
+160 characters with a count of the rest, and a later miss stopping at the same
+place says `same as fields/1`. 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
@@ -941,10 +943,20 @@ Enable only vendor permissions needed by the workflows: Metadata read for
 repository lookup; Issues read for issues/comments/labels; Pull requests read
 for PRs/reviews/review comments/changed files/PR commits; Contents read for
 repository commits/comparisons/contents/releases; Actions read for workflows,
-runs and jobs. Release writes require Contents write. The guarded merge retains
+runs and jobs; Checks read for check runs, suites and annotations; Commit statuses
+read for commit statuses. Release writes require Contents write. The guarded merge retains
 Contents, Pull requests and Workflows write. Code search retains Contents read
 and GitHub's own search restrictions. Each operation token is narrowed to its
 reviewed permission and repository IDs; an org grant does not permit org admin.
+A resource 403 that carries no rate-limit header is `provider_permission_denied`, with
+no credential handoff, naming the repository and the permission the endpoint accepts.
+It establishes the refusal, not its cause: a missing permission is likely, but a policy,
+an unmarked secondary rate limit or a lockout gives the same answer, so its message
+ends with credential checks for when every call is refused. A refused token mint is a
+permission gap only when GitHub's installation record lacks the requested permission;
+otherwise a 422 is a neutral `connector_call_failed` and a 403 stays
+`provider_permission_denied` with its causes open. A 401, an unusable key or a 403 on
+the App's own installation list is `auth_required`.
 
 The four github_api tools cover a pinned operation index with a bounded reviewed
 repository read and release-write allowlist. All other operations are refused.
@@ -963,8 +975,8 @@ File contents retain base64 encoding; the character bound applies after decoding
 Use `/repos/alice/widget/contents/src/index.ts` for a nested file and
 `/repos/alice/widget/contents` for the root directory. Contents paths must be
 canonical relative paths, without dot/empty segments, backslashes or encoded
-traversal. Encode branch-name slashes as `%2F` in `commits/{ref}` and
-`compare/{basehead}`. Owner-prefixed object refs and cross-repository compares are
+traversal. Encode branch-name slashes as `%2F` in `commits/{ref}`, its check and
+status reads, and `compare/{basehead}`. Owner-prefixed object refs and cross-repository compares are
 refused before authentication. PR-list head filters require `login:branch`, for
 example `head:"alice:feature/x"`; they filter the selected repository's PRs.
 Bare head branches are refused because GitHub silently ignores them. The base

package/examples/worker/README.md

@@ -10,7 +10,7 @@ runnable Worker steps.
 A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
 API connector, guarded by Cloudflare Access. It uses three Cloudflare resources
 and nothing else: one D1 database (`CONNECTA_DB`) for every piece of state, the
-Worker Loader binding (`LOADER`) behind the six-tool surface, which requires
+Worker Loader binding (`LOADER`) behind the meta-tool surface, which requires
 the Workers Paid plan, and two secrets: `DOWNSTREAM_TOKEN` (the example remote
 MCP connector's token) and `CREDENTIAL_ENCRYPTION_KEY` (the credential vault).
 
@@ -493,7 +493,7 @@ from `@zackbart/connecta/d1`. See [Activity history](#activity-history-optional)
 Omit the module and store wiring to record no history and show no Activity tab. Diagnostics remain independent; `logger: "silent"` suppresses
 them explicitly.
 
-Verify MCP health and the exact six tools with the following. Doctor reads
+Verify MCP health and the exact tool list with the following. Doctor reads
 `/health` through Access with the service credentials, then checks `/agent/ci`
 with the `cta_` token alone:
 
@@ -526,7 +526,7 @@ LOADER: Cloudflare.WorkerLoader(),
 `@zackbart/connecta/worker`. The adapter constructs the upstream
 `DynamicWorkerExecutor` with only the loader and a deadline, and disposes each
 run's loader and RPC handles when its lease ends, even if the guest has not
-settled. It serves the six-tool surface. Its admission pool is per isolate:
+settled. It serves the meta-tool surface. Its admission pool is per isolate:
 two runs, eight queued for up to 60 seconds, then a retryable
 `executor_overloaded`. Pass `admission` to `workerExecutor()` to change it; see
 [code mode](../../documentation/code-mode.md#deploy-time-capability). Do not

package/guides/how-it-works.md

@@ -77,7 +77,7 @@ account choices, including the Google Workspace exception.
 ## Finding a tool and using it are separate steps
 
 First the agent finds an action and learns what information it needs.
-Then it calls that action. The default connection gives the AI app six small
+Then it calls that action. The default connection gives the AI app a few small
 **meta-tools** to help it do this without loading every service's tools into
 the conversation.
 
@@ -87,6 +87,7 @@ the conversation.
 | `call_tool`             | Call a discovered action that reads data.                                    |
 | `call_destructive_tool` | Call a discovered action that changes data, under the app's approval policy. |
 | `execute_code`          | Combine discovery, actions, and a small answer in a program.                 |
+| `execute_read_code`     | The same for read-only work. It refuses anything that changes data.          |
 | `authorize_connector`   | Request the permitted account-connection handoff.                            |
 | `skills`                | Read guidance for using a connection.                                        |
 

package/guides/safety-and-trust.md

@@ -74,9 +74,7 @@ credentials as another boundary where possible.
 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
+on an earlier tool label. If a native tool becomes a write, its cached read name is refused before dispatch. Refresh `tools/list` and use the write's name; approval follows the host's policy. Read-only pools refuse writes. `execute_read_code` is the exception an app need not ask about: it refuses anything that can change data. It can still read, so a page's text can try to talk an agent into sending data through a read action; see [read programs](../documentation/meta-tools.md#read-programs). Connecta does not pause a program to
 ask a person partway through.
 
 See [read-only setup](../documentation/integrating.md#make-one-connection-read-only)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.41.0",
+  "version": "0.42.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

@@ -10,10 +10,10 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
 
 - 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. Keep the required `readOnly` choice in the config: `false` lets
+- Keep `executor: quickJsExecutor()` for the prescribed code-first
+  meta-tool 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
+  a write, with `execute_read_code` listed for read-only programs at `/mcp`; `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`.

package/templates/node/README.md

@@ -272,7 +272,7 @@ npm run typecheck
 CONNECTA_TOKEN='cta_REPLACE_WITH_RETURNED_SECRET' npm run doctor
 ```
 
-Doctor checks health, the executor, and the exact prescribed six-tool
+Doctor checks health, the executor, and the exact prescribed meta-tool
 model-facing surface by running a harmless sandbox program. It reads the bearer
 from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
 Remote URLs must use HTTPS.

package/templates/node/package.json

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