@zackbart/connecta 0.41.0 → 0.42.0

package/documentation/deploying.md

@@ -270,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
@@ -297,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.

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