@zackbart/connecta 0.34.1 → 0.35.0

package/documentation/meta-tools.md

@@ -5,6 +5,9 @@ tools behind it. `search_tools` finds addresses, the call tools enforce the
 stored classification, `execute_code` runs programs on a writable or read-only endpoint, and `connecta.result` inside programs
 pages bounded results.
 
+A pool may instead list each downstream tool directly, for clients that run
+their own tool search; see [native tool surface](#native-tool-surface).
+
 This guide is the contract an MCP client sees. The in-program `connecta.*` API
 those tools imply belongs to [code mode](./code-mode.md); inbound identity and
 credential administration belong to [auth](./auth.md).
@@ -22,15 +25,23 @@ owns the top-level MCP contract; it does not require reading the core internals.
 | Load provider instructions or native skills        | [Connector guides](#connector-guides-and-skills), [native extension](#native-skills-extension)                                              |
 | Interpret a direct response or page a large result | [Representation](#result-representation), [truncation](#truncated-direct-call-results), [paging](#paging-with-connectaresult)               |
 | Recover a refused or invalid call                  | [Authorization](#authorization-recovery), [routing](#routing-recovery), [arguments](#argument-recovery), [echo budgets](#echo-budgets)      |
+| List downstream tools directly, or connect Eve     | [Native tool surface](#native-tool-surface), [Eve agents](#eve-agents)                                                                      |
 | Change the contract                                | [Source and tests](#source-and-tests), [guest API](./code-mode.md#verification)                                                             |
 
+## Tool presentation
+
+The default surface is the six meta-tools below. From 0.35.0, pools can use
+[native tool presentation](#native-tool-surface) for clients with their own
+tool search. Both presentations use the same invocation enforcement; native
+pools keep code available by default.
+
 ## The six tools
 
-Every deployment requires an executor, so `tools/list` is exactly six. No
-configuration adds a seventh or removes one, so a client's cached tool list
-never depends on the storage behind the deployment. There was an eighth,
-`resume_execution`, while programs paused at writes; it left with pausing
-([#672](https://github.com/zackbart/connecta/issues/672)). `execute_code`
+Every deployment requires an executor. A meta endpoint's `tools/list` is
+exactly six. This is the default; a pool may instead use the
+[native tool surface](#native-tool-surface). No other configuration adds a
+seventh or removes one, so a client's cached meta-tool list never depends on
+the storage behind the deployment. `execute_code`
 is annotated `readOnlyHint: true, destructiveHint: false` on a read-only
 endpoint, and `readOnlyHint: false, destructiveHint: true` on a writable one.
 Approval belongs to the client. A read-only endpoint keeps all six tools, omits
@@ -150,6 +161,37 @@ discovery. Both take the same arguments.
 Neither `connector` nor `safety` grants authority or changes invocation
 admission; they select what discovery shows and nothing else.
 
+Main search also consults a standard hatch's construction-authored operation
+vocabulary (path, operation id, vendor summary and tag), without calling a tool
+or reading account data. A match returns the owning `_api_search` tool; call it
+with the original query to retrieve operations. Exact tool/address and complete
+authored-tool matches retain precedence. A vocabulary match requires every term
+in one operation, and the operation's hatch route must be visible and match the
+read/write filter. On `approvalRequired` searches the returned discovery tool
+is still a read. Hidden tools, missing grants and read-only restrictions remain
+in force. Browsing does not consult operation vocabulary.
+
+Vocabulary is bounded: queries at most 200 characters and eight terms; each
+hatch caches at most 8,192 rows and 2,097,152 characters, with at most 1,024
+characters per row and 128 query intersections. Longer queries and vocabulary
+outside these bounds remain available through the hatch's own search. These
+bounds never claim an exhaustive operation search.
+
+When a non-empty query matches no catalog tool or bounded operation vocabulary,
+visible standard API hatches may still cover it. `queryAnalysis.guidance` names up to three qualified API
+search tools in connector order and reports the omitted count; full indexes have
+not been searched. For example, call `crm.crm_api_search` with the original
+query before concluding that the operation is unavailable. Browse with an
+empty query and follow every page, or search for `_api_search`, to list all API
+search tools. If the query names a configured connector, its identity and
+scoped-browse guidance comes first, followed by the API-search pointer.
+The pointer respects endpoint and tool visibility; a read search tool can
+discover indexed writes when the catalog query selected
+`safety: "approvalRequired"`, provided the endpoint and connector allow writes.
+That filter suppresses pointers on read-only endpoints and for read-only
+connectors. Required connector guides and catalog failures still apply.
+Catalog search itself performs no API index lookup.
+
 `includeSchemas: "compact"` adds each match's input and any provider-declared
 output shape, plus `inputKeys`, `requiredInputKeys`, and `outputKeys` for
 bounded plain objects. Where the provider declared no output shape but an
@@ -404,6 +446,15 @@ match those bindings and pass current auth, connector/tool grants, pool membersh
 and read-only checks. Old entries lacking bindings fail closed. A random UUID is a
 handle, never an access grant.
 
+Each page validates access twice: before decoding its payload and again before
+returning it. Each pass authenticates the caller once, checks every dependency
+against that admitted scope, and reuses each connector's catalog within the
+pass. Authentication is never reused across passes or requests, so revocation
+during the page read still refuses the page. For example, a search handle with
+30 tool dependencies requires the same number of authentications as one with
+one dependency. Paging deadlines cover both storage and access validation;
+timeout errors identify the active stage as `result storage` or `access validation`.
+
 New entries store UTF-8 bytes in a base64 envelope split across storage keys,
 48 KiB of result text per chunk — widening past roughly 1.5 MB so no result
 occupies more than 32 keys, because every chunk is also a write. `connecta.result`
@@ -507,7 +558,7 @@ no paging route.
 
 ### Paging with connecta.result
 
-Paging is a guest operation, never another top-level tool. Program calls also
+Meta endpoints page inside a program. Native pools without code list `read_result` for the same bound handles. Program calls also
 return handles for oversized values; see [program result limits](./code-mode.md#cancellation-and-limits).
 `connecta.result(handle, { page: 0 })` accepts those handles alongside direct
 result IDs. Numbered pages are zero-based and mutually exclusive with offset.
@@ -555,9 +606,9 @@ default to JSON schemas and schema-key metadata.
   "catalogErrors": [],
   "tools": [
     {
-      "name": "get_issue",
-      "address": "linear.get_issue",
-      "connectorTitle": "Linear Production",
+      "name": "get_ticket",
+      "address": "tickets.get_ticket",
+      "connectorTitle": "Tickets",
       "classification": "read",
       "schemaFormat": "json",
       "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }
@@ -604,7 +655,7 @@ terms that never occur in its tools need not be repeated in every tool descripti
 An explicit unknown `connector` scope returns no tools and an `absence` record:
 `{ service, message, configuredConnectors }`. The message says
 `No connector for "X" is configured for this endpoint.` Unscoped queries naming
-recognized services such as GitHub, Linear, Mixpanel, Supabase, or PostHog do the
+recognized services such as GitHub, Linear, Supabase, or PostHog do the
 same when no visible connector ID or title names that service. This service-name
 vocabulary is query interpretation, not an inventory of configured providers.
 For other service names, use the explicit `connector` scope. An unavailable
@@ -615,7 +666,7 @@ is indistinguishable from an unconfigured one.
 If no tool covers every search term, wider any-term fallback remains available
 for ordinary action/object searches and the page carries `matchMode: "partial"`.
 A service absence suppresses that fallback, so `GitHub get issue` cannot return
-Linear issues or Mixpanel/Supabase projects. Tool rows expose no scores or
+Linear issues or Supabase projects. Tool rows expose no scores or
 per-result query coverage. `queryAnalysis` partitions at most eight terms of at
 most 64 characters into `representedTerms`, `otherResultTerms`, and
 `unmatchedTerms`, marking longer input `truncated`. Its guidance distinguishes
@@ -682,7 +733,8 @@ opaque state and input responses is a continuation, not an automatic replay.
 The sealed arguments digest prevents using that continuation for fresh write
 arguments. A timeout or other failure during a continuation leaves its nonce
 spent, so it cannot authorize a second attempt. Write continuations stop at an
-HTTP 401 or redirect before the SDK can refresh authorization or resend the call.
+HTTP 401 or redirect before the SDK can refresh authorization or resend the call;
+an ordinary write lets the refresh run and stops only the resend.
 HTTP 403 scope escalation also remains disabled. Read continuations retain normal
 OAuth refresh behavior.
 
@@ -697,8 +749,16 @@ capped at 128 KiB. `input_required_invalid`, `input_required_limit`,
 and `input_required_unsupported` are non-retryable typed failures;
 `input_required_round_limit` is an untyped failure with `retryable: false`.
 
-Programs and in-process meta-tools return `input_required_unsupported`, with a
-`nextAction` naming the equivalent direct call and bounded original arguments.
+For a read, programs and in-process meta-tools return
+`input_required_unsupported`, with a `nextAction` naming the equivalent direct
+call and bounded original arguments. A downstream asks for input from inside
+its handler, so a write that suspends may already have applied. A write's
+`input_required_unsupported` is `retryable: false` with
+`writeOutcome: "unknown"`, carries no `nextAction`, and its `retry` says to
+re-read the target before any fresh call; a program counts it in
+`writes.unknown`. A direct write whose input cannot be relayed (no sealing
+vault, the round limit, or private state over its cap) also carries
+`writeOutcome: "unknown"` and is never told to start a new request.
 Programs never receive downstream state or prompts, and never restart to
 fulfill downstream input.
 
@@ -720,6 +780,18 @@ from configured `publicUrl`. OAuth consent stays in the browser; a credential
 slot uses the authenticated operator UI. `authorize_connector` uses the same
 flow for explicit connect and restart. There is no legacy shim.
 
+For an operator-managed credential, an explicit `authorize_connector` returns
+`recovery: "ready"` when the declared credential fields are configured. This
+reports local presence, without testing the key or remembering earlier requests.
+The message is conditional: if a call just failed with an authentication or
+operator-configuration error, give the retained `operatorUrl`, `credential` and
+`instructions` to the operator; otherwise proceed with the requested call.
+Without the optional UI, the message retains the deployment configuration
+needed for recovery. A missing, unreadable or mismatched slot returns the
+operator handoff or `unavailable`. The explicit authorization result has its own
+type; authentication errors never carry `ready`. OAuth sign-in and restart
+behavior is unchanged.
+
 The host echoes `requestState` and its bare `inputResponses.connecta_auth`
 response on the original `tools/call`. Accept re-runs the original call; it
 does not prove browser consent completed. Decline or cancel ends without
@@ -737,10 +809,12 @@ stale catalog returns `auth_replay_refused` and reconciliation guidance.
 Each round also checks its own invocation facts. Normal stale-fallback calls
 retain their existing behavior.
 An auth failure after a write handler or transport was entered keeps its
-ordinary error code,
-`retryable: false`, `reconciliationRequired: true`, and manual `/connect` guidance
-where available. The write may have partially run; reconcile its target before
-retrying after connection. Handler-authored error fields cannot clear this guard.
+ordinary error code and manual `/connect` guidance where available. Unless a
+maintained provider's complete ledger records an auxiliary resource read and
+proves that only auxiliary resource reads and authentication token mints departed,
+it also carries `retryable: false` and `reconciliationRequired: true`:
+the write may have partially run, so reconcile its target before retrying after
+connection. An explicit `writeOutcome: "unknown"` always keeps this guard.
 
 State integrity, expiry, principal, endpoint, and tool failures produce the
 SDK's JSON-RPC `-32602` with `data.reason: "invalid_request_state"` before the
@@ -886,15 +960,16 @@ exposing backend error text.
 Submitted `writeOnly` values also enter the call's sent-secret output redaction
 set, including property names inside private object subtrees. Downstream
 result and error text quoting them, in raw or credential-supported encoded
-forms, is redacted before direct-call output, program returns, logs, and emits,
-or result stash persistence; paging in a later request reads already-redacted
-bytes. A program's `connecta.read` resources, connector usage guides, and
-downstream `connecta.skill` files take the same rules before the program sees
-them. JSON stays valid: a matching number or boolean becomes `"[redacted]"`.
-Empty private strings are exempt. A private value shorter than eight characters
-redacts only structured fields that equal it, so identifiers and approval state
-remain, and withholds prose that contains it, including error messages, while
-typed classification, retry facts, and write outcome remain.
+forms, or any run of eight consecutive units of one, is redacted before
+direct-call output, program returns, logs, and emits, or result stash
+persistence; paging in a later request reads already-redacted bytes. A
+program's `connecta.read` resources, connector usage guides, and downstream
+`connecta.skill` files take the same rules before the program sees them. JSON
+stays valid: a matching number or boolean becomes `"[redacted]"`. Empty private
+strings are exempt. A private value of one to three characters is withheld only
+where a whole string, property name, number, or boolean equals it; one of four
+to seven characters is also replaced wherever it occurs in result and error
+text. Typed classification, retry facts, and write outcome remain.
 Work limits withhold the affected text without failing the call. See
 [output redaction](./auth.md#what-a-servers-errors-may-say)
 for the shared encoding, budget, and argument-filter contract.
@@ -910,6 +985,25 @@ carries no `errorCode`.
 
 ## Argument recovery
 
+Standard API hatches refuse marker containment in request paths and query
+keys/values. Body fields and named kit writes refuse whole `[redacted]` values
+(including decoded spellings) and withheld links, before sending. Longer prose
+such as `the log says [redacted]` is allowed. Obtain the original value/link or
+omit its field: do not copy `{ "token": "[redacted]" }` from a read into a write.
+These rules check agent arguments; a body composed later from internal reads
+is not rescanned as a whole. Legacy tools and remote MCP keep their own rules.
+
+Pass signed hatch and named-list cursors back unchanged. They authenticate the
+continuation and bind its connection, personal owner and arguments; hatch
+search/details cursors also bind the index content.
+When the connection acts as a different downstream identity per caller, the
+signature also binds the admitted caller and pool owner. These identities are
+not included in the readable cursor. Fixed shared identities keep the shared
+binding. For example, a cursor issued to `alice` on a caller-mapped connection
+is refused when `bob` presents it, before any downstream request. An altered cursor
+or changed scope/index is `invalid_args`. Start discovery again after that
+refusal. Cursors survive restarts with persistent storage. A signing-key load failure is retryable `unavailable`; operators can follow [cursor-key recovery](./deploying.md#recover-a-cursor-signing-key).
+
 A remote MCP tool's advertised `inputSchema` is checked in the shared invocation
 path before admission and provider dispatch, so a mismatch is the non-retryable
 `invalid_args` identically on `call_tool`, `call_destructive_tool`,
@@ -941,34 +1035,314 @@ Unknown-address errors list `configuredConnectors` from the current endpoint's
 scoped registry, including an empty list when none are accessible. They never
 list connectors from another pool or identity's grants.
 
-A write that times out after dispatch returns `write_outcome_unknown` with
+A write that times out after dispatch without complete auxiliary-only proof
+returns `write_outcome_unknown` with
 `retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted?, recovery? }`.
+An auxiliary-only timeout reported by a completed maintained-provider call keeps
+its `timeout` verdict under the rule below.
 No write is automatically replayed. `recovery` carries facts the connector
 recorded before dispatch, such as a REST connector's
-generated or caller-supplied `idempotencyKey`. Recovery accepts keys up to 255
+generated or caller-supplied `idempotencyKey`. A caller-supplied key that is
+empty once leading and trailing whitespace is removed is refused with
+`invalid_args` before dispatch and never recorded: fetch would send it empty,
+which is no key. Recovery accepts keys up to 255
 characters, matching the REST write schema. Other recovery values remain capped
 at 128 characters, with at most four facts per call and camelCase names of at
-most 32 characters. Values outside these bounds are dropped whole. A deliberate
+most 32 characters. Values outside these bounds are dropped whole. A recovery
+key is a diagnostic. Only when the call sent exactly one write, carrying that
+key, through the one connector it entered does `retry` add that a deliberate
 retry that reuses the key with the exact original arguments cannot repeat the
 write while the vendor retains the key
 (Stripe may prune v1 keys after 24 hours). After that, look the object up before
-retrying. When a connector recorded such facts, any other dispatched write whose
+retrying. The advice needs one boundary that owns the call and exactly one
+dispatched write carrying the key; GET and HEAD reads beside it do not count.
+A second write, a write the key did not travel on, or a connector that wraps
+another or enters more than one boundary never gets it, since reusing the key
+would protect that request alone. A key generated but never sent (a write
+refused before dispatch, such as one with no configured credential) stays in
+the message as a diagnostic, with no reuse advice, direct or served. When a connector recorded such facts, any other dispatched write whose
 outcome is unknown (a lost response body, a 5xx) also carries `uncertainCall`
 with them under its own code, and program write accounting keeps it. `args` may be partial reconciliation context
 with `argsRedacted: true`. A withheld echo or arguments over the 512-byte budget
 carry `argsOmitted: true`; sensitive or unresolved schemas also carry
 `argsRedacted: true`. When `args` is absent or redacted, use the original
 arguments if reconciliation requires another call. A timeout before dispatch remains `timeout`.
+A connector's `callTool` called directly from code, outside an invocation, has
+no such boundary: a write that may have been dispatched and then timed out
+(an SDK deadline or HTTP 408 included) keeps its code and timeout
+`details.code`, and is `retryable: false` with `writeOutcome: "unknown"`. A
+write the caller's own signal aborted after it may have been dispatched is
+the same: `timeout` when the reason is one (`AbortSignal.timeout`), else
+`connector_call_failed`, with the caller's reason as its `cause` (a redacted
+copy of the same class where the connector's output redaction applies, as on
+`remoteMcp()`) and the reason's class and code in `details` (`{ name: "TimeoutError", code:
+"timeout" }`). Only an idempotency key the vendor receives keeps such a direct
+write's retry advice: a key that is blank once trimmed, or that holds a
+character fetch cannot send in a header, is refused as `invalid_args`. A
+direct read's timeout stays retryable, and a direct read's own abort reason is
+rethrown unchanged.
 Program write accounting keeps this detail even if the guest catches the
 failure or returns early. Multiple uncertain writes use `uncertainCalls`,
 bounded to ten calls with `uncertainCallsTruncated` when more exist.
 
+A dispatched write is never reported as retryable once the downstream may
+have acted on it (INV-9). A failed maintained-provider write call whose complete
+request ledger records an auxiliary resource read and proves that no call-owned
+request or kit auxiliary falsely declared as a read departed keeps the failure's retry advice and needs no write
+reconciliation. For example, a Gmail connector named `mail` can fail
+`mail.update_draft` during its auxiliary draft lookup before sending the update;
+its authorization handoff then says to retry after recovery. The same rule applies
+to a timeout reported by that completed call. An explicit `writeOutcome: "unknown"`
+always takes precedence. A kit request declared `effect: "read"` that uses POST
+or a method-overridden GET blocks this inference even alongside an auxiliary read,
+while retaining core write reservation and replay rules. Authentication token mints
+supply no resource-read proof but do not invalidate a later auxiliary resource read.
+Empty, absent or incomplete ledgers, invocation deadlines and caller
+cancellation without a complete answer retain conservative write outcomes.
+Custom `api()` and `remoteMcp()` connectors always stay conservative: the internal
+complete-tracking declaration is available only to maintained providers.
+A 5xx (a gateway's 502 to 504 included), any
+network failure of its send (a refused connection included), or a reply that
+broke off is a non-retryable `connector_call_failed` whose outcome is unknown,
+from `remoteMcp()`, `api()` handlers, and the maintained providers alike;
+reads keep their retryable verdict. One send can hide several attempts:
+Node's fetch sends a request again after HTTP 421 and after an HTTP/2
+`REFUSED_STREAM`, both of which servers define as not processed, and an
+operator-installed dispatcher such as undici's `RetryAgent` can retry further,
+so a refusal on the last attempt says nothing about the earlier ones.
+Connecta therefore never reports a transport-failed write as known failed. A
+write stays a known failure, with its own advice, only on refusal provenance
+recorded where the evidence was observed: connecta refused it before it left,
+or the downstream served an HTTP refusal, a 4xx other than 408 that its
+provider reads as a refusal. A 408 is a timeout, and a refusing status the
+provider reads as `unavailable` or a timeout (Stripe's 424) does not prove the
+write unapplied, so a keyless Stripe write answered 424 is unknown. An error
+code is never that evidence by itself. A `rate_limited`,
+`invalid_args`, or any other code thrown after a 2xx (by a response mapper,
+a parser, or an output-schema check) or after a 408, and any JSON-RPC error a
+`remoteMcp()` server returns once the `tools/call` was sent (`-32602`
+included: a server can run the tool and then reject its own result), keeps
+its code and message for diagnostics but is `retryable: false` with
+`writeOutcome: "unknown"`, on a direct and a served call alike, and counts in
+a program's `writes.unknown`. An HTTP refusal of the call's own write stays
+known only under the refusal rules above and a complete ledger proving the
+refusal covers the whole call; its recovery advice and program accounting both
+report failure. Partial or unknown ledgers remain conservative. An auth failure after entering a write with
+no call-owned dispatch reports an unknown outcome and requires reconciliation,
+including credential refusals, static-OAuth refresh failures, and `remoteMcp()`
+connect or initialize 401s before `tools/call`. A non-auth refusal before
+`tools/call` is sent stays known. A custom connector can show no such
+provenance: a served write whose
+`callTool` throws after it was entered is `retryable: false` with
+`writeOutcome: "unknown"` whatever its code, and gets no retry advice
+(neither "grant the permission, then retry" nor "correct the arguments and
+retry"). That includes a refusal it rethrows from a call it made to another
+connector: refusal evidence holds only for the whole call, so a custom
+connector that deletes one Stripe customer and is then refused 429 on a
+second reports the unknown outcome. A served write whose downstream MCP tool
+answers `isError` came back over a 2xx after the tool ran, so it is unknown
+too, with its text kept; a read's `isError` stays a known answer. No text on
+an unknown write says to retry it: a rate limit's or overload's wait-and-retry
+wording is dropped from its message, and an authorization or credential
+handoff (`instructions`) says to re-read the target before any fresh call
+instead of to retry the original call. A read, and a write with a known
+outcome, keep that advice. A failure during a composite
+call's later request leaves earlier requests' outcomes unknown, and once the
+call's outcome is decided, a request that had not left is never sent. A
+write the downstream answered with HTTP 401 has an unknown outcome, since a
+server may act on a request before it rejects the credential, and is never
+resent. It is never retryable and carries no wait. Until the credential is
+renewed, the failure keeps its authorization code (`auth_required`, or
+`downstream_oauth_required` for an OAuth connector) with
+`writeOutcome: "unknown"`, `reconciliationRequired: true`, and the
+`authorize_connector` handoff, whose `instructions` say to authorize and then
+re-read the target before any fresh call. That holds whatever renewal meets: a
+refused or unreachable token endpoint, a disconnect, or the caller leaving. It
+also holds whatever the call met after the 401: a body past the response
+ceiling, a later failure in the same call, a 401 on a later request of a
+composite write, a 401 answered inside another connector the call reached
+(an `api()` or `remoteMcp()` connector, through a custom connector or a
+program), or the call's deadline or the caller's cancellation cutting the
+write off after the 401: the result is that verdict, not
+`write_outcome_unknown`. Nor can such a call succeed: a handler that caught
+the 401 and returned, or a result that could not be processed, still ends
+in that verdict, and a program counts the write in `writes.unknown`. An
+idempotency key never makes such a write repeatable, so it gets no
+key-reuse advice. Once every such 401 is renewed
+the handoff goes, but the call stays unknown, even if its handler caught
+the failure and returned a result: renewal does not prove whether the write
+took effect. A caught read 401, or a declared refusal followed by a successful
+write, does not prevent the call from succeeding. A read needs positive
+operation or tool classification and a recorded GET or HEAD; the method
+alone is insufficient. Breeze GET writes and requests carrying
+`X-HTTP-Method-Override`, `X-HTTP-Method` or `X-Method-Override` remain writes,
+even when a handler catches their 401 and returns.
+Once renewal succeeds (an OAuth refresh), nothing is left
+to authorize: the call reports a non-retryable `connector_call_failed` with
+the unknown outcome, and the renewed credential serves any fresh call after
+the target is reconciled. Renewal succeeds only when it yields a different
+credential than the one the write sent: a refresh or login that hands back
+the rejected token, or an earlier recovery in the same request, renews
+nothing, and the write keeps its handoff. Google Workspace renews on the next call, so its
+write keeps the authorization code and handoff. A write answered 401 is a
+known refusal only where its provider has reviewed vendor documentation that
+the vendor authenticates a request before acting on it. Among the maintained
+providers that is Stripe with an API key, for an API v1 answer that carries
+Stripe's `Request-Id`, since Stripe documents that an invalid API key is an
+error that occurs before execution begins. A read answered 401 keeps its
+refusal, and its handoff says to retry the original call.
+A `remoteMcp()` write answered with a redirect is not sent to the new location,
+whatever the connector's `redirects` setting, and reports the unknown outcome;
+reads follow same-origin redirects as configured. An error whose write outcome
+is unknown carries `writeOutcome: "unknown"` unless its code is already
+`write_outcome_unknown`, and a program that sent the write fails with it counted
+in `writes.unknown` even when the program caught the failure. When that write
+met an authorization verdict, the program's error is that verdict, as a direct
+call reports it: its code, `connector`, `recovery`, and `nextAction`, with
+`writeOutcome: "unknown"` and `reconciliationRequired: true`. Any other unknown
+write makes it `write_outcome_unknown`.
+
+The classification served for the call decides this advice, including deployment
+`classification` overrides. For example, `classification: { crm: { get_person:
+"write" } }` makes a dispatched `crm.get_person` that receives HTTP 503 report
+`retryable: false` and `writeOutcome: "unknown"`, even if its request uses GET.
+A served read keeps the provider's read retry advice even if its request uses
+POST. Tool defaults and HTTP methods supply a fallback only when no served
+classification exists. A vendor idempotency key does not change an uncertain
+served write into retry advice; its recovery facts still help reconcile the
+target before any fresh call. An operation hint (a whole-resource `PUT`,
+fixed spreadsheet cells, a content-addressed upload) grants no retry credit on
+any call, direct or served: only an idempotency key the vendor honors, which is
+Stripe's today, keeps a direct write's retry advice.
+
 Retryability comes from typed errors, HTTP status, registered OAuth error codes,
 SDK timeout classes, and runtime network codes. Untyped prose is non-retryable:
 "timeout", "temporarily unavailable", "rate limit", or "503" in a body, tool
 name, or URL never changes the verdict. JSON-RPC `ProtocolError.data` is dropped
 at the downstream boundary, even when the agent may see the error's message.
 
+## Native tool surface
+
+A pool set to `surface: "native"` lists each downstream tool as its own MCP
+tool instead of the six meta-tools, for clients that already defer tools behind
+their own search (Eve, Claude Code with tool search). The meta surface stays
+the default everywhere, and plain `/mcp` is always meta.
+
+```ts
+pools: {
+  assistant: { tools: ["crm", "tickets"], members: ["agent:assistant"], surface: "native" },
+  assistant_lean: { tools: ["crm"], members: ["agent:assistant"], surface: "native", executeCode: false },
+}
+```
+
+`executeCode: false` is valid only with `surface: "native"`; construction
+refuses it otherwise, and refuses any `surface` other than `"meta"` or
+`"native"`. Both pool endpoints, `/mcp/<pool>` and `/agent/<pool>`, serve the
+pool's surface.
+
+| A native pool lists          | Shape                                                                                                                                                             |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Each visible downstream tool | Named `<connector>__<tool>`; object input constraints and local references preserved; no `outputSchema`; `_meta["dev.connecta/address"]` is its address           |
+| `execute_code`               | Unless `executeCode: false`. Each downstream tool's description then ends with `Program address: <connector>.<tool>`, the address `connecta.call` takes           |
+| `read_result`                | Only with `executeCode: false`: `{ id, offset?, page?, maxBytes? }` pages a stashed result exactly as `connecta.result` does, with the same bindings and rechecks |
+| `skills`                     | Always                                                                                                                                                            |
+
+`search_tools`, `call_tool`, `call_destructive_tool`, and `authorize_connector`
+are not listed. Auth failures still carry their handoff in the error envelope.
+
+**Names.** A name is a pure function of the connector id and downstream tool
+name, so it survives catalog refreshes. It is `<connector>__<tool>` when the
+tool name uses only `[A-Za-z0-9_-]`, contains no `__`, does not start with `_`,
+and the whole name fits 48 characters; otherwise it is that name's head plus
+`_` and the first six hex digits of the SHA-256 of `<connector>.<tool>`. A
+connector id that does not start with a letter is prefixed with `C`. 48
+characters leave room for a client's own prefix under common 64-character
+tool-name limits (Eve's `connecta__`, Claude Code's `mcp__connecta__`). Two
+tools that would share a name are both left out of the list, with an operator
+warning, and a call by that name is refused; both stay callable by address in
+`execute_code`.
+
+**Annotations** come from the served classification only: a read is
+`{ readOnlyHint: true, destructiveHint: false, openWorldHint: true }` and a
+write `{ readOnlyHint: false, destructiveHint: true, openWorldHint: true }`,
+whatever hints the downstream declared. A read-only endpoint or connector
+leaves write tools out of the list, by the same rule search and describe use.
+
+**Calls take the existing paths.** A call to a downstream tool is the
+`call_tool` call for its address when the tool is currently a read, and the
+`call_destructive_tool` call when it is a write, run by the same handler. So
+classification, `read_only_endpoint` refusal, argument validation and repair,
+admission, redaction, single-attempt writes, auth elicitation, downstream input,
+result caps, and activity use the same enforcement. Activity records source
+`native` with the canonical address and served classification. A name must
+exactly match the definition's native name before dispatch. Unknown or ambiguous
+names fail with `unknown_tool`; catalog failures retain their handoff. Success results are
+`call_tool`'s default mode: native `content`, never `structuredContent`, which
+is why no `outputSchema` is advertised. A truncated result's notice pages with
+`connecta.result` inside `execute_code`, or with `read_result` on a pool without
+`execute_code`.
+
+**Approval is the host's, enforcement is Connecta's.** The host approves from
+the annotations of the list it cached. If a tool changes from read to write
+between that list and a call (a downstream changes its hints, or the deployment
+changes its classification), the call runs under Connecta's current verdict:
+on the `call_destructive_tool` route, refused on a read-only endpoint, and never
+resent, although the host approved what it saw as a read. To narrow that
+window, a native `tools/list` carries a 300-second private cache hint, against
+an hour on meta endpoints. This hint does not guarantee that a host refreshes
+its cached annotations; the stale-approval race is accepted on writable pools.
+
+**Listing.** `tools/list` is one page with no cursor (Eve 0.83 reads only the
+first page). A pool listing more than 1,000 tools fails `tools/list` with a
+JSON-RPC error asking the operator to narrow the pool; nothing is silently
+dropped. A connector whose catalog cannot load is left out of that listing
+whole, never partially, with an operator warning; its tools return with the
+next listing that loads it. Listing never starts authorization. The server
+still declares `tools.listChanged: false`.
+
+**Instructions** replace the meta routing text: call one known operation
+directly; with `execute_code`, use one program for several, dependent, or
+reduced calls; write tools are absent and refused on a read-only endpoint;
+never repeat a write; page a truncated result as its notice says. A pool
+`description` is appended as on meta endpoints.
+
+**Recovery.** Repair and validation fields retain the exact constraint details.
+Discovery `nextAction` points to the host's tool search (`host: "search"`), with
+only a `query` argument. Retry actions and retry text name the native tool,
+never a meta wrapper. Auth actions carry `authorizationUrl` or `operatorUrl`;
+give the returned URL and instructions to the user or operator. Capable modern
+clients may resume native auth and downstream form/URL input with the same
+wire name, arguments and returned `requestState`. Changed names, targets or
+arguments, expired state and spent retry nonces are refused. Never resend a
+write to recover output.
+
+**Schemas.** Ordinary `type: "object"` schemas are byte-identical. Object
+constraints without a top-level type, composed object schemas and local
+`$defs`/`$ref` keep their constraints with `type: "object"` at the root. A schema
+that cannot be represented as object arguments omits its connector whole from
+that listing, with an operator warning naming the connector and tool. Other
+connectors remain listed. Correct the schema or use the meta surface.
+
+**Diagnostics.** `connecta doctor --pool assistant` recognizes the configured
+surface and code setting from the local `skills` tool's
+`_meta["dev.connecta/surface"]`. It checks the required local tools, reports
+unavailable connector catalogs and listing-cap errors, and runs only a constant
+program when code is enabled. It never dispatches a downstream tool. The
+metadata's `catalogErrors` exposes this request's failing connector ids,
+including connectors with unrepresentable schemas, to every client of the pool.
+Connector ids already appear in native tool names. The
+operator UI and `describeConfig()` show every pool's effective `surface` and
+`executeCode` as facts from deployment code. Change these settings in code.
+
+Keep native pools bounded. Comparisons so far used 40 synthetic tools;
+large production catalogs near the cap have not been evaluated.
+
+### Eve agents
+
+Starting with 0.35.0, the Eve helper ships separately as `@zackbart/connecta-eve`.
+Connecta core supplies the native pool surface and has no Eve dependency.
+Consult that package's documentation for its compatibility and setup.
+
 ## Contributor reference
 
 ### Source and tests
@@ -978,12 +1352,15 @@ Handlers and schemas live in [meta-tools.ts](https://github.com/zackbart/connect
 and [invocation](https://github.com/zackbart/connecta/blob/main/src/invocation.ts)
 serve both direct tools and programs. [Skills](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
 owns the supplied usage instructions, each endpoint's instructions
-(`endpointInstructions`), and connector guides.
+(`endpointInstructions`), and connector guides. The native surface's names,
+listing, and call translation live in
+[native-tools.ts](https://github.com/zackbart/connecta/blob/main/src/native-tools.ts).
 
 [Schema tests](https://github.com/zackbart/connecta/blob/main/test/meta-tool-schemas.test.ts),
 [search tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-search.test.ts),
 [call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
 [skills tests](https://github.com/zackbart/connecta/blob/main/test/skills-extension.test.ts),
+[native surface tests](https://github.com/zackbart/connecta/blob/main/test/native-tools.test.ts),
 [surface tests](https://github.com/zackbart/connecta/blob/main/test/code-first-surface.test.ts),
 and [pool description tests](https://github.com/zackbart/connecta/blob/main/test/pool-description.test.ts)
 check the published contract. Guest parity and clause evidence are in

package/documentation/operating.md

@@ -7,7 +7,12 @@ and credentials are the deployment operator's responsibility; use
 
 ## Choose the call path
 
-Connecta exposes six top-level tools. Read [the tool table](./meta-tools.md#the-six-tools)
+A [native pool](./meta-tools.md#native-tool-surface) lists individual operations.
+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)
 for exact arguments and result envelopes. Follow the endpoint's supplied
 instructions and `skills` usage guide for deployment-specific context.
 
@@ -100,6 +105,12 @@ values. Treat it as evidence, not a provider contract; handle missing fields.
 
 ## Large results and resources
 
+MCP request bodies default to a 4 MiB limit on every endpoint. Deployment code
+can set `admission.requests.maxBodyBytes`; `describeConfig()` reports its value
+and source. An oversized body returns 413 before tool dispatch. See
+[request admission and body limits](./architecture.md#admission-in-two-places)
+for Node's separate pre-auth buffer and the listen-classification bound.
+
 Direct calls may return a preview and a result handle. Page the handle through
 `connecta.result` in a program using the returned offset and byte limits, or
 reduce the data in the original program. Handles are short-lived and bound to
@@ -122,10 +133,23 @@ and status do not begin consent on their own. Follow
 [argument recovery](./meta-tools.md#argument-recovery) for the specific failure.
 
 A dispatched write is never automatically replayed. An ambiguous timeout may
-mean the provider applied it; inspect state or ask for the missing decision
-before issuing it again. [Retry semantics](./code-mode.md#retry-semantics) and
+mean the provider applied it; inspect state to check whether it took effect, or
+ask for the missing decision, before any fresh call. [Retry semantics](./code-mode.md#retry-semantics) and
 [writes](./code-mode.md#writes) describe program outcomes and write accounting.
 
+## Read failure records
+
+Failure logs and connector status report checked facts without downstream
+error text. A failure record can include `httpStatus`, an integer from 100
+through 599; status messages can include `with HTTP <status>`. Recorded status
+is retained when a write's 401 had no mapped authorization verdict, when a Google write reports
+an unknown outcome, and when a response exceeds the connector's byte ceiling.
+If no answer was recorded, the field is absent. The status alone does not
+prove whether a write took effect or permit replaying it.
+
+For example, a `crm` write answered HTTP 503 can log `httpStatus: 503` while
+its outcome stays unknown. Inspect the target before repeating the call.
+
 ## Contributor reference
 
 ### Implementation and evidence