@zackbart/connecta 0.15.1 → 0.16.1

package/documentation/connectors.md

@@ -111,6 +111,11 @@ export const connecta = createConnecta({
 All three are ordinary `Connector` instances by the time the registry sees
 them. Nothing in the list is privileged by how it was authored.
 
+What a maintained connection owes an agent is written down rather than
+inherited from whoever wrote it last:
+[provider conventions](./provider-conventions.md), one set for hand-written
+HTTP surfaces and one for hosted-MCP proxies.
+
 Maintained provider guides:
 
 - [Cloudflare](./cloudflare.md)
@@ -119,6 +124,90 @@ Maintained provider guides:
 - [Notion](./notion.md)
 - [Stripe](./stripe.md)
 
+## The `api()` construction contract
+
+`api()` is the path every custom integration takes, and whatever it accepts is
+what an agent eventually reads. Three things are refused at construction rather
+than discovered in production
+([#340](https://github.com/zackbart/connecta/issues/340)):
+
+- **A tool with no description.** Discovery has nothing else to route on, and a
+  guess costs a call.
+- **A tool with no explicit boolean `annotations.readOnlyHint`.** `true`
+  declares a read and admits the tool to `call_tool` and `execute_code`;
+  `false` declares work that crosses `call_destructive_tool`, where the host
+  can ask a human. Connecta never infers the classification from a tool name,
+  description, schema, HTTP method, or the other annotations — an unclassified
+  tool is a bug in the deployment, not a puzzle to solve.
+- **An `inputSchema` the validator cannot compile.** Declaring one is optional;
+  declaring one that cannot be enforced is not. A schema that only reveals
+  itself on first use — an unresolvable `$ref`, say — fails that call as
+  non-retryable `invalid_args` rather than forwarding raw arguments to the
+  handler. `validateArgs: false` still opts out of enforcement for deployments
+  that want loose coercion; it does not opt out of the schema being real.
+
+None of this reaches a proxied catalog: hosted-MCP tools arrive as their
+downstream wrote them, and an unannotated or contradictory one stays
+fail-closed onto `call_destructive_tool`. The contract binds the surfaces we
+write, not the catalogs we relay.
+
+## The guarded fetch transport
+
+Every hand-written HTTP surface re-derives the same safety machinery, and two
+of them had already derived it slightly differently. `src/connectors/guarded-fetch.ts`
+is that machinery extracted once ([#341](https://github.com/zackbart/connecta/issues/341)):
+one `guardedFetch({ provider, baseUrl, headers, maxResponseBytes, authenticate })`
+factory returning the transport a connector sends every request through.
+
+What it owns is mechanical and provider-independent:
+
+- **Confinement.** A request path is provider-relative, carries no query or
+  fragment, and is re-checked against the base origin and path prefix *after*
+  `new URL` normalization — because normalization is how a path escapes a
+  prefix, not something to trust before it.
+- **Construction.** Query parameters are encoded rather than concatenated, a
+  JSON body is serialized with the `Content-Type` to match, and a pre-framed
+  body gets none, so `fetch` still picks the multipart boundary.
+- **Credential forwarding.** `authenticate` is called once per request and its
+  headers are applied last; a request header wearing one of their names is
+  refused rather than allowed to shadow it. A 3xx is refused outright — a
+  redirect is an instruction to re-send the credential to whatever origin the
+  `Location` names, and a confinement a redirect can undo was never one.
+- **Bounded reads.** `maxResponseBytes` is required, not defaulted: what counts
+  as an absurd response is a fact about the API, not about HTTP. A declared
+  `Content-Length` past the ceiling fails before a byte is read, and a
+  streaming body is abandoned at the ceiling rather than buffered past it.
+- **Normalization.** An unreachable provider becomes a retryable `unavailable`
+  instead of whatever `TypeError` the runtime threw, and `ctx.signal` rides
+  every request.
+
+What it deliberately does not own is meaning. It never reads a status code and
+never invents an authentication scheme: the provider's `authenticate` callback
+supplies the headers, and the provider's mapper turns one `GuardedResponse`
+into a result or a typed failure. That split is not fastidiousness. Notion's
+403 means a capability the integration was never granted — re-authorizing
+cannot fix it — while Cloudflare's means a token scope, and the two want
+opposite next moves. A helper that guessed would be wrong for one of them.
+
+Cloudflare and Notion both run on it. Their existing suites carried over
+unchanged, which proves the migration kept the behavior those suites cover —
+not that nothing changed. Three things did, and the changelog names them: a
+3xx is refused where both providers used to follow it, both now fail past
+their byte ceiling, and `cloudflare()`'s `baseUrl` is validated at
+construction. Each suite gained one test for the ceiling, because the one
+guard the helper was written to add is the one a provider's own mapper can
+most easily disarm: a bare `catch` around `response.json()` swallows the
+transport's refusal along with a parse error, and turns a response nobody was
+allowed to read into an empty success. A mapper re-throws
+`ConnectorCallError` and swallows only what it recognizes.
+
+It is **not exported this release**: the two migrations proved the shape
+preserves behavior for connectors that already had this machinery, not that it
+is the right shape for an author starting from nothing, and an unexported
+symbol costs nothing to reshape while a published one is a promise.
+The provider audit ([#342](https://github.com/zackbart/connecta/issues/342))
+supplies the third caller that would settle it.
+
 ## MCP version skew
 
 Connecta deliberately sits between protocol generations

package/documentation/linear.md

@@ -11,6 +11,7 @@ import { linear } from "@zackbart/connecta/providers/linear";
 const tracker = linear("product_tracker", {
   title: "Product issue tracking",
   purpose: "Issue and project planning for the platform team",
+  access: "read-write",
   instructions: "File bugs into the Platform team unless the request names another.",
 });
 ```
@@ -23,13 +24,21 @@ cannot change the connector's safety classification.
 
 ## Access modes
 
-Linear publishes two hosted endpoints, and `access` selects between them:
+Linear publishes two hosted endpoints, and `access` selects between them. It is
+**required**, with no default:
 
 | `access` | Endpoint | OAuth scopes |
 | --- | --- | --- |
-| `"read-write"` (default) | `https://mcp.linear.app/mcp` | `read`, `write` |
+| `"read-write"` | `https://mcp.linear.app/mcp` | `read`, `write` |
 | `"read-only"` | `https://mcp.linear.app/mcp/readonly` | `read` |
 
+There is no safe default to pick. Defaulting to `"read-write"` hands a
+deployment write access it never asked for; defaulting to `"read-only"` turns a
+deployment that does write into one whose every write fails at Linear — at
+runtime, where no agent can repair it. So the operator declares which one this
+is, and a deployment that forgot fails at construction with a message naming
+both options.
+
 Read-only is not a client-side filter. The endpoint advertises the `read` scope
 alone, so the token minted for it cannot reach Linear's write APIs — a stronger
 guarantee than any annotation Connecta applies. A deployment that only reports
@@ -63,6 +72,7 @@ also accepts a bearer token or a personal API key passed directly in the
 ```ts
 linear("automation_tracker", {
   purpose: "Headless release reporting",
+  access: "read-only",
   auth: {
     type: "headers",
     headers: { Authorization: env.LINEAR_API_KEY },
@@ -130,6 +140,7 @@ one. An operator who knows their workspace can supply one explicitly:
 ```ts
 linear("product_tracker", {
   purpose: "Issue and project planning for the platform team",
+  access: "read-write",
   callAdmission: {
     rules: [
       { budget: { kind: "rolling-window", maxCalls: 1_000, windowMs: 3_600_000 } },
@@ -141,3 +152,10 @@ linear("product_tracker", {
 A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
 for a queue, and the admission controller then requires the rest of the queue
 settings at construction.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention, including every recorded exception, is the Linear section of
+[the provider audit](./provider-audit.md).

package/documentation/mcp-ui-design.md

@@ -375,8 +375,8 @@ buy a guarantee the protocol already gives away.
   source carries the `srcdoc` and sandbox attributes and contains no
   message-forwarding path from the inner frame to the host.
 - `U1`–`U11` fold into `code-mode.md`, the `execute_code` description documents
-  `connecta.ui`, and the test-map row lands in
-  [`operations.md`](./operations.md) with that guide.
+  `connecta.ui`, and the suite takes its row in the
+  [test map](./operations.md#the-test-map).
 - `npm run check` passes.
 
 The implementation issue (#277) carries these as acceptance criteria.

package/documentation/meta-tools.md

@@ -229,7 +229,13 @@ results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
 configured and recommends refining, connector-scoping, or browsing; when a
 connector catalog was unavailable, the response includes
-`unavailableConnectorCount` instead of making that stronger claim. A search
+`unavailableConnectorCount` instead of making that stronger claim. A no-match
+query whose terms name a configured connector's `id` or `title` never makes it
+either: connector identity is not in the lexical index — indexing it would move
+ranking for every query that already matches tools — so instead the guidance on
+an unscoped miss names up to three such connectors by ID and sends the caller
+to a scoped browse. Identity affects that one sentence and nothing else: no
+ranking, no result, and no new field. A search
 explicitly scoped to that unavailable connector also receives `catalogError` —
 the bounded classified failure (`code`, `message`, `retryable`, and any
 `retryAfterMs`) so the caller can tell a transient outage from one a deployment

package/documentation/mixpanel.md

@@ -2,9 +2,9 @@
 
 Import `mixpanel()` independently from
 `@zackbart/connecta/providers/mixpanel`. It wraps Mixpanel's hosted MCP server
-with regional endpoint selection, OAuth by default, a provider-rate admission
-budget, a task-oriented usage guide, and a vetted safety classification. It
-adds no provider dependency and is not reachable from Connecta's root entry.
+with regional endpoint selection, OAuth by default, a task-oriented usage
+guide, and a vetted safety classification. It adds no provider dependency and
+is not reachable from Connecta's root entry.
 
 ```ts
 import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
@@ -25,6 +25,12 @@ connector's safety classification.
 
 `region` accepts `"us"` (the default), `"eu"`, or `"in"` and selects the
 corresponding [official hosted endpoint](https://docs.mixpanel.com/docs/mcp#mcp-server-urls).
+A project lives in exactly one residency, so the region also decides what this
+connection can see at all: a question pointed at the wrong one comes back empty
+rather than wrong, which reads as the project having no data. That makes it a
+routing fact, so it rides the default `title` (`Mixpanel (us)`, `Mixpanel
+(eu)`, `Mixpanel (in)`) and opens the usage guide — `search_tools` renders a
+connector's title and guide summary and never its description.
 OAuth is the recommended default and keeps each connector instance's flow and
 tokens in its connector-scoped storage. Mixpanel service accounts are also
 supported with an explicit header override:
@@ -68,9 +74,36 @@ approval copy the host shows a human.
 Experiments and Feature Flags — 15 of the 63 classified tools — are Mixpanel
 beta surfaces. Expect their names and schemas to move faster than the rest.
 
-The connection also declares a per-runtime call-admission budget matching
-Mixpanel's documented 600 requests per hour — a best-effort approximation of
-the per-user limit, not an enforcement of it. Each runtime keeps its own
-counter, so N Worker isolates or Node processes serving one deployment can each
-admit up to 600. Discovery traffic is outside connector call admission and
-still needs restrained use.
+## Rate limits
+
+Mixpanel meters its MCP server **per user per hour**, shared with everything
+else that credential does. Connecta's counter is per runtime, not per user, and
+the two cannot be reconciled in either direction: one runtime serving several
+users under-counts, and several Worker isolates or Node processes sharing one
+credential each admit a full budget. A hardcoded ceiling would therefore either
+throttle a healthy deployment or fail to protect a busy one, so this connection
+declares **no call-admission budget by default**. An operator who knows the
+account can supply one explicitly:
+
+```ts
+mixpanel("product_analytics", {
+  purpose: "Product and growth decisions for the production app",
+  callAdmission: {
+    rules: [
+      { budget: { kind: "rolling-window", maxCalls: 300, windowMs: 3_600_000 } },
+    ],
+  },
+});
+```
+
+A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
+for a queue, and the admission controller then requires the rest of the queue
+settings at construction. Discovery traffic is outside connector call admission
+either way and still needs restrained use.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention, including every recorded exception, is the Mixpanel section of
+[the provider audit](./provider-audit.md).

package/documentation/notion.md

@@ -166,7 +166,7 @@ should do next, and two of Notion's are easy to mistranslate.
 | 400 (`validation_error`, `invalid_json`, `invalid_request`, `missing_version`, …) | `invalid_args` | every documented 400 is a malformed request |
 | 401 `unauthorized` | `auth_required` | the token is missing or invalid |
 | 403 `restricted_resource` | `connector_call_failed`, non-retryable | **not** `auth_required` |
-| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded; see below |
+| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded — deliberately **not** `not_found`; see below |
 | 409 `conflict_error` | `unavailable`, retryable | Notion says to retry |
 | 429 `rate_limited` | `rate_limited` + `retryAfterMs` | `Retry-After` seconds → ms |
 | 529 `service_overload` | `unavailable` + `retryAfterMs` | back off like a 429 |
@@ -184,7 +184,12 @@ whose message says an operator must change it in Notion.
 object that does not exist and for one that exists but has not been shared with
 the integration, and it will not say which. The message says both, because
 treating it as deletion is exactly how an agent concludes a page is gone when
-it was simply never shared.
+it was simply never shared. This is why the row above does not use `not_found`,
+which exists precisely to say "it is not there": the qualifier on that code
+([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next))
+is that the provider must tell absence apart from a permission gap, and Notion
+does not. A program that skipped this id as missing would be right about half
+the time, which is the half that matters.
 
 ## Rate limiting
 
@@ -231,3 +236,19 @@ block updates or deletes, no page moves. Those are all real Notion endpoints
 and all deliberately absent: this is a deliberate tool surface, not a mirror of
 the API. Anything missing is reachable through a custom `api()` connector
 beside this one, which remains a first-class path.
+
+There is also **no guarded raw-REST escape hatch** — no `notion_api_get`, no
+`notion_api_mutate`. The convention that permits one
+([H14](./provider-conventions.md#h14--a-named-tool-must-beat-the-escape-hatch-and-the-escape-hatch-splits-by-safety))
+also permits a small provider to have none, provided it says so, and Notion's
+public API is finite and slow-moving enough that a named surface can cover it.
+The usage guide says it too, because an agent that assumes a hatch exists
+spends a search proving it does not: absent from the tool list means absent
+from this connection, not hidden behind a generic call.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention, including every recorded exception, is the Notion section of
+[the provider audit](./provider-audit.md).