@zackbart/connecta 0.40.0 → 0.42.0

package/documentation/deploying.md

@@ -61,6 +61,17 @@ authenticated `admission.requests.maxBodyBytes` default. To accept larger MCP
 bodies, configure both core and `listen(..., { maxBodyBytes })`; a smaller
 platform, proxy or adapter cap still wins. See
 [request body limits](./architecture.md#admission-in-two-places).
+`listen(..., { maxInFlightBodyBytes })` caps the body bytes all in-flight
+requests hold together, counted from the first chunk until the response finishes
+or the client leaves. It defaults to 64 MiB, or `maxBodyBytes` when that is
+larger, and may not be set below `maxBodyBytes`. Past it a request gets `503` with
+`Retry-After: 1` and `Connection: close`. Raise it when legitimate concurrent
+large bodies are refused, keeping it within the process's memory budget.
+`listen()` answers `400` with `Connection: close`, before reading any body, when
+`Host` is anything but a host with an optional port, when `X-Forwarded-Proto` is
+anything but `http` or `https`, or when the request target does not start with
+`/`. A reverse proxy must overwrite `X-Forwarded-Proto` with one value; a
+comma-separated chain such as `https,http` is refused.
 A Node host serving `connecta.fetch` without `listen()` has no owned sender:
 every maintained-provider write, every reviewed POST read and every remote MCP
 write is refused before sending. Downstream OAuth credential POSTs also require
@@ -199,7 +210,9 @@ and `describeConfig()`, and [optional modules](./architecture.md#optional-deploy
 owns their composition contracts.
 
 Enable `encryptedCredentialVault(storage, key)` before persisting downstream
-OAuth credentials. Without a sealing vault, OAuth grants are stored as plaintext.
+OAuth credentials. With no vault, OAuth grants are stored as plaintext. A
+configured vault without `seal` and `open` refuses construction when any connector
+uses OAuth.
 The platform templates describe the base64 32-byte encryption key. Keep it
 outside the database and source control, and preserve it across upgrades.
 [OAuth state at rest](./auth.md#downstream-oauth-state-at-rest) owns sealing and
@@ -257,7 +270,7 @@ token and run doctor against a pool that lists the agent:
 CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787 --pool local-machine
 ```
 
-Doctor checks health, the required executor, and the current six-tool set. A
+Doctor checks health, the required executor, and the current meta-tool set, running a harmless program on each listed program route. A
 `cta_` token is checked at `/agent/<pool>` and needs `--pool`.
 For a Worker protected by Access, `/health` still needs edge admission even
 though `/agent/*` bypasses Access. Use an Access service token admitted by the
@@ -284,14 +297,15 @@ connector; resolve credentials using [authorization recovery](./meta-tools.md#au
 
 Use the failed check to choose the next step:
 
-| Symptom                             | Action                                                                                                                                           |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Connection refused or timeout       | Check the public URL, listening process/port, proxy, and Worker deployment.                                                                      |
-| `/health` fails behind Access       | Check the Worker-level Access policy and the two service headers above. Do not broaden the agent bypass.                                         |
-| Executor check fails                | Retain `quickJsExecutor()` and its peer on Node, or `workerExecutor({ loader })`, the codemode peer, and `LOADER` on Workers.                    |
-| MCP 401                             | Check the saved token, declared agent, and slot state; rotated/revoked tokens refuse. Use `/agent/<pool>` with `--pool`.                         |
-| MCP 404                             | Check the pool name and `members: ["agent:assistant"]`; an existing but inaccessible pool is deliberately indistinguishable from a missing one.  |
-| Doctor passes but a connector fails | Discover its tools in that pool, check credential status/account ownership, and perform a bounded read. Doctor does not prove downstream access. |
+| Symptom                             | Action                                                                                                                                                         |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Connection refused or timeout       | Check the public URL, listening process/port, proxy, and Worker deployment.                                                                                    |
+| `/health` fails behind Access       | Check the Worker-level Access policy and the two service headers above. Do not broaden the agent bypass.                                                       |
+| Executor check fails                | Retain `quickJsExecutor()` and its peer on Node, or `workerExecutor({ loader })`, the codemode peer, and `LOADER` on Workers.                                  |
+| MCP 401                             | Check the saved token, declared agent, and slot state; rotated/revoked tokens refuse. Use `/agent/<pool>` with `--pool`.                                       |
+| MCP 404                             | Check the pool name and `members: ["agent:assistant"]`; an existing but inaccessible pool is deliberately indistinguishable from a missing one.                |
+| Doctor passes but a connector fails | Discover its tools in that pool, check credential status/account ownership, and perform a bounded read. Doctor does not prove downstream access.               |
+| `Native discovery degraded`         | The named connectors did not answer and are listed from an older catalog. Check them with a scoped search; tools stay listed but calls check the live catalog. |
 
 After a fix, repeat doctor with the same client credentials and pool. Never
 paste a token or raw downstream failure body into a committed diagnostic log.
@@ -302,6 +316,17 @@ 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.
 
+A custom vault without `seal` and `open` now refuses construction when any
+connector has OAuth. Before upgrading, add both methods or switch to
+`encryptedCredentialVault(storage, key)`. Existing plaintext grants are sealed on
+first read; see [OAuth state at rest](./auth.md#downstream-oauth-state-at-rest).
+
+A deployment using `clerkAuth` must set a fixed URL before upgrading:
+`ConnectaConfig.publicUrl`, or `clerkAuth({ publicUrl })`. Startup otherwise fails
+with a configuration error. Use the origin clients reach, because tokens' `resource`
+must match it exactly; see
+[Clerk OAuth tokens](./auth.md#clerk-oauth-tokens-and-operator-sessions).
+
 Before upgrading past 0.37.1 with pre-0.29 state, follow
 [Retired layout migrations](./migration-retired-layouts.md). Version 0.37.1 is
 the last bridge for KV → D1, JSON → SQLite, and OAuth layout-2 conversions.

package/documentation/hosted-mcp-migration.md

@@ -401,7 +401,13 @@ classification: {
 },
 ```
 
-`"read"` sets the effective read class for tool routing and read-only exposure.
+`"read"` sets the effective read class for tool routing and read-only exposure
+only when the server is silent about the tool, and asserts that the call is safe
+to repeat. It has no effect on a tool the server explicitly declares a write
+(`readOnlyHint: false`, `destructiveHint: true`, or contradictory hints); that tool
+stays a write and an operator warning names the override.
+`"read-repeatable"` serves such a tool as a read anyway, for a deployment that has
+checked it and accepts that hosts may repeat the call, so the vendor can receive it twice.
 `"write"` selects the host approval path. `"hidden"` omits the tool from search
 and describe and refuses guessed-name calls, including programs. An absent
 runtime tool leaves its override dormant, with one operator warning per catalog
@@ -411,8 +417,8 @@ when live hints would expose them as reads. Never copy a retired review map
 wholesale or use it to broaden access or merely recover an old route.
 
 An override does not change replay safety. A call is write-like when either its
-effective class or its source class is write. The source class uses only the server's annotations: missing hints or
-`destructiveHint: true` count as write even when deployment policy sets read. Write-like
+effective class or its source class is write. The source class uses only the server's annotations: missing hints
+and declared writes count as write even when deployment policy serves them as reads. Write-like
 calls get one attempt across OAuth renewal, reconnect, authorization recovery
 and program re-runs. An ambiguous dispatched failure, including timeout or
 cancellation, reports an unknown outcome with no retry or wait advice. Approval,

package/documentation/integrating.md

@@ -202,7 +202,7 @@ only in deployment code through the existing `classification` map:
 
 ```ts
 classification: {
-  crm: { list_tickets: "read", update_ticket: "write", internal_export: "hidden" },
+  crm: { list_tickets: "read", save_view: "read-repeatable", update_ticket: "write", internal_export: "hidden" },
 },
 ```
 
@@ -210,8 +210,30 @@ classification: {
 and describe and refuses guessed-name calls, including programs. An absent
 runtime tool leaves its override dormant with an operator warning once per catalog change; the override
 applies if that exact name returns. Unknown static tool names fail construction.
-No argument can change these rules. A write-to-read override changes exposure
-and approval. Replay and failure decisions treat a call as a write when either its
+No argument can change these rules. `"read"` depends on what the tool's source
+states:
+
+- **The source explicitly declares a write** (`readOnlyHint: false`,
+  `destructiveHint: true`, or contradictory hints): the tool stays a write and is
+  never served read-annotated, because a host may resend a read-annotated call
+  after a connection failure. `call_tool` refuses it with the next step, naming
+  `call_destructive_tool`. It runs on `call_destructive_tool` and `execute_code`, and
+  read-only endpoints and connectors omit and refuse it. An operator warning names the override once per catalog change.
+- **The source is silent** (no `readOnlyHint` and no `destructiveHint: true`): the
+  override is the only evidence, so the tool serves as a read with read
+  annotations. Setting it asserts that the call is safe to repeat, because the host
+  may resend it and Connecta cannot tell a resend from a new call.
+
+`"read-repeatable"` is the opt-in for a tool whose source declares a write but which
+you have checked: `crm.save_view` above adds one immutable record. It serves as a read
+on every route, with read annotations, on read-only endpoints, through `call_tool`,
+in programs and under its plain native name. You accept that a host may resend it after
+a connection failure, so the vendor can receive the call twice; only use it where a
+repeat is harmless. Connecta itself still sends it at most once, as the next paragraph
+describes. Prefer `"read"`: if a vendor later declares a write, `"read"` fails safe and
+`"read-repeatable"` does not.
+
+Replay and failure decisions treat a call as a write when either its
 effective class or its source class is write. The source class is the verified
 server annotations;
 deployment overrides never change it. A write gets one wire attempt across
@@ -229,8 +251,8 @@ Remote catalogs evolve. Discovery, direct calls, and programs enforce the
 current annotations and `ConnectaConfig.classification` overrides. A leftover
 `classify` option throws at construction and names that map. Provider reviews,
 schema pins, `optional`, and `unlisted: "hide"` are removed. Missing or
-contradictory hints make the source class write, even when an override makes
-the effective class read. Review behavior before setting a read override;
+contradictory hints make the source class write. Under `"read"`, contradictory hints also keep
+the effective class write and missing hints do not. `"read-repeatable"` serves either as a read. Review behavior before setting a read override;
 classification does not replace downstream scopes or caller grants.
 
 ## A hand-written HTTP capability