@zackbart/connecta 0.24.3 → 0.24.4

package/AGENTS.md

@@ -32,8 +32,8 @@ Cloudflare Workers.
 `check:operator-ui` → `check:lint` → `check:unused` → `typecheck` → `test`
 (both vitest projects) → `build` → `check:examples`. It is also the `prepack`
 hook. `npm run release:check` adds `check:security` and `check:package` and is
-what CI runs on publish; use it when touching packaging, dependencies, or
-exports.
+what CI runs on every pull request, on `main`, and again on publish; use it
+when touching packaging, dependencies, or exports.
 
 ## The map
 
@@ -41,13 +41,13 @@ exports.
   decisions table, and the invariants every change must preserve. Check it
   before building something new; "we already decided not to" is a real answer
   there, and its removed/provisional verdicts override anything staler.
-- [`documentation/`](./documentation/) — per-subsystem guides for agents
-  working on the repo. All of them are written now
-  ([#348](https://github.com/zackbart/connecta/issues/348)); the retired manual
-  (`docs/<name>.md`) survives only in git history, which is worth mining for
-  rationale a rewrite dropped and worth nothing where it disagrees with
-  `ethos.md`. Start with `architecture.md`, then the guide for the subsystem
-  you are changing.
+- [`documentation/`](./documentation/) — four guides for agents working on the
+  repo: `architecture.md`, `meta-tools.md`, `code-mode.md`, and `auth.md`.
+  Everything else — connectors, providers, admission, storage, the operator
+  UI, operations — is documented where it lives, in the source and its tests.
+  The guides that once covered those survive only in git history, which is
+  worth mining for rationale and worth nothing where it disagrees with
+  `ethos.md` or the code. Start with `architecture.md`.
 - [`README.md`](./README.md) — the human-facing overview.
 - [`templates/node/`](./templates/node/) — the one standalone Node deployment
   shape copied by `connecta init`, Docker-ready rather than Docker-only. Keep
@@ -56,13 +56,14 @@ exports.
   diff away from one of them is the shape
   [#344](https://github.com/zackbart/connecta/issues/344) deleted.
 
-**Read `ethos.md` and the subsystem's guide before changing a subsystem.**
+**Read `ethos.md` before changing a subsystem, and its guide when it has one.**
 
 ## Deployment setup
 
 `connecta init [directory]` is the golden path. It copies `templates/node/`,
 pins the generated deployment to the CLI package's exact version, restores the
-template `.gitignore`, and refuses to merge into an existing path.
+template `.gitignore` and the `CLAUDE.md` symlink, and refuses to merge into an
+existing path.
 `connecta doctor` verifies a running deployment's health, executor, and exact
 seven-tool surface. The template carries its own `Dockerfile` and
 `docker-compose.yml`, so the generated project is the container: setup changes
@@ -96,8 +97,9 @@ Two boundaries CI enforces that are not obvious from reading a file:
   forbidden is a platform-bound adapter becoming importable from the package,
   not a file appearing in the artifact. `@clerk/backend` and
   `quickjs-emscripten` are optional peers behind the `./auth/clerk` and
-  `./quickjs` subpaths and must never become dependencies or install with
-  core. Enforced by `test/package-surface.test.ts` and
+  `./quickjs` subpaths, and `@cloudflare/codemode` is the third, peered
+  without a subpath because a Worker deployment imports it directly. None may
+  become a dependency or install with core. Enforced by `test/package-surface.test.ts` and
   `scripts/check-package.mjs`. Anything heavyweight or platform-bound gets a
   subpath and an optional peer.
 
@@ -108,10 +110,7 @@ Every `*.test.ts` belongs to exactly one explicit list: runtime-portable suites
 in `WORKERS_SUITES`, Node-bound suites in `NODE_ONLY_SUITES` with a reason. The
 `node` project runs both lists; the `workers` project re-runs the portable list
 inside workerd. `test/suite-partition.test.ts` walks the directory and fails on
-an unclassified, double-classified, stale, or reasonless entry. New behavior
-also gets a row in the test map in `documentation/operations.md`, which
-classifies every suite — one missing from it is either new and undocumented or
-dead, and neither is a state to leave the repository in.
+an unclassified, double-classified, stale, or reasonless entry.
 
 ## Conventions
 
@@ -132,9 +131,8 @@ dead, and neither is a state to leave the repository in.
   documentation and OpenAPI contracts and never reads a provider credential.
   Remote MCP schemas remain owned by the live `tools/list` response rather than
   a vendored copy. Findings are read by a human and become GitHub issues;
-  nothing files itself.
-  See
-  [`documentation/provider-conventions.md`](./documentation/provider-conventions.md#the-maintainer-run-drift-check).
+  nothing files itself. `scripts/drift-check.mjs` is the reference for what
+  each flag covers.
 - **Releases.** `npm run release:check`, tag `v<version>` matching
   `package.json` exactly (the publish workflow verifies this and fails
   otherwise), and publishing fires on GitHub **Release publication**, not on the

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this package are documented here.
 
+## 0.24.4 — 2026-09-17
+
+The operator UI is the release. Its connections page is now a summary line and
+one row per connector instead of a wall of expanded cards, and the stylesheet
+behind it resolves through design tokens a deployment can set with the new
+`branding.theme`. Nothing a deployment configures today changes meaning, no
+storage format moved, and the page shows exactly what it showed before under
+the same gates — an operator who has the page bookmarked will find it reads
+differently, and that is the whole of the upgrade. The documentation cut to
+four guides lands here too, along with one execution-path fix.
+
+### Added
+
+- **`branding.theme`.** Five tokens — `accent`, `radius`, `fontFamily`,
+  `monoFamily`, and `colorScheme` — set on `operatorUi({ branding })`. Every
+  other color on the operator page is mixed from those, so setting one accent
+  themes the page rather than leaving half of it on the defaults. Light and
+  dark are the same tokens and follow the operator's OS setting unless
+  `colorScheme` pins one. Each token is gated the way the branding URLs already
+  were: a hex color, a CSS length, a plain font-family list, one of
+  `system`/`light`/`dark`. A rejected value takes the default and gets named in
+  a startup warning. The gates are narrow because these values land in a
+  `:root` block on the page, where anything unvalidated would be CSS injection.
+
+### Changed
+
+- **The operator UI reads as a dashboard.** The connections page opens with one
+  summary line — connected, anything needing authorization, anything
+  unavailable, tools available — and then one row per connector: status dot,
+  name, auth scope, tool count, state. What used to be stacked in every card at
+  once (the description, the permission line, OAuth actions, the credential
+  panel, diagnostics, drift, and the tool list) is now behind a row an operator
+  expands, so a deployment with twenty connectors is a screen instead of a
+  scroll. Nothing about what the page may show or do changed: same payload,
+  same gates, and the drift panel still refuses to render a tool name or a
+  schema (#554).
+- **The documentation is four guides.** `documentation/` now ships
+  `architecture.md`, `meta-tools.md`, `code-mode.md`, and `auth.md`. The
+  operations, upgrading, connector, provider, admission, storage, and operator
+  UI guides are removed; the rationale source comments used to defer to them
+  for now lives in those comments, and the provider conventions H1–H14 and
+  P1–P13 are defined in `test/provider-conventions.test.ts`. Each release's
+  opening paragraph here is the upgrade guidance. `records/` and `eval/` are
+  removed with the `load:admission` script and the CI job that served them. The
+  template and Worker example keep their `AGENTS.md`, which now points at this
+  changelog for upgrades (#552, #553).
+
+### Fixed
+
+- **`get_result` paging cost.** A stashed result is stored as base64 chunks
+  under one key each — 48 KiB of text per chunk, wider for a result over
+  roughly 1.5 MB so the key and write count stays bounded — and a page reads
+  and decodes only the chunks it covers. Paging a large result no longer reads
+  the whole stash — let alone re-encodes it — once per page, so cost tracks the
+  page rather than the total. Offsets, `nextOffset`, `totalBytes`, and
+  character-boundary alignment are unchanged, and entries stashed in the
+  previous formats stay readable for the rest of their 15-minute TTL (#540).
+
 ## 0.24.3 — 2026-09-16
 
 A bug-fix release from a full audit of the execution path, invocation, catalog
@@ -163,7 +221,7 @@ returns `"all"` or connector ids and declares no pools.
 - **Tool-level grants in `identity.connectorAccess`.** Entries may be a
   connector id (every tool) or an exact `connector.tool` address (that tool
   only); grants are additive. The scoped registry view filters below the
-  catalog service, so `search_tools`, `describe_tools`, `call_tool`,
+  catalog service, so `search_tools`, `call_tool`,
   `call_destructive_tool`, a program's `connecta.search` and `connecta.call`,
   and the connection UI all see the same list, and an ungranted tool fails as
   `unknown_tool` exactly like an absent one. There is no wildcard: a remote
@@ -173,6 +231,11 @@ returns `"all"` or connector ids and declares no pools.
 
 ## 0.24.1 — 2026-09-08
 
+A small additive release for deployments whose providers run long: two
+optional `execute.*` settings and a log line for failed calls. Nothing breaks
+and nothing needs migrating; a deployment that sets neither option behaves as
+it did on 0.24.0.
+
 ### Added
 
 - `execute.maxHostCalls` and `execute.hostCallTimeoutMs` configure the

package/README.md

@@ -95,9 +95,7 @@ Cloudflare Access supplies Worker identity; Node can use Clerk or the optional
 configured bearer adapter. Connecta owns no accounts or groups and issues no
 client access tokens. Shared-credential administration and personal connection
 setup require separate explicit permissions, both denied by default. See
-[inbound auth](./documentation/auth.md#principals-visibility-and-operators),
-[shared and personal auth](./documentation/storage-and-credentials.md#shared-and-personal-auth),
-and the [module migration guide](./documentation/upgrading.md#0240-optional-modules).
+[inbound auth](./documentation/auth.md#principals-visibility-and-operators).
 
 Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
 service. Those are decisions, and the [ethos](./ethos.md) records each one
@@ -107,9 +105,10 @@ and why.
 
 Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
 ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers every subsystem if you want to go
-deeper, and [upgrading](./documentation/upgrading.md) an existing deployment
-is its own runbook.
+[documentation](./documentation/) covers the architecture, the seven tools,
+code mode, and inbound auth if you want to go deeper. When upgrading an
+existing deployment, each [changelog](./CHANGELOG.md) release opens with what
+breaks and what a deployment can ignore.
 
 ## Status
 

package/dist/branding.d.ts

@@ -1,6 +1,13 @@
-import type { ConnectaBranding, UiAuthConfig } from "./types.js";
+import type { ConnectaBranding, ConnectaTheme, UiAuthConfig } from "./types.js";
 /** Connecta's default monochrome "C" mark. */
 export declare const CONNECTA_FAVICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 32 32\">\n  <style>\n    .fg { fill: #000 }\n    @media (prefers-color-scheme: dark) { .fg { fill: #fff } }\n  </style>\n  <path class=\"fg\" d=\"M27 9.4A13 13 0 1 0 27 22.6l-4.4-2.5a8 8 0 1 1 0-8.2z\"/>\n</svg>";
+export interface ResolvedTheme {
+    accent?: string;
+    radius?: string;
+    fontFamily?: string;
+    monoFamily?: string;
+    colorScheme: "system" | "light" | "dark";
+}
 interface ResolvedBranding {
     productName: string;
     productUrl?: string;
@@ -12,8 +19,30 @@ interface ResolvedBranding {
     /** href for the page's icon link. */
     faviconHref: string;
     themeColor: string;
+    /** Only the tokens that survived their gate; the stylesheet owns the rest. */
+    theme: ResolvedTheme;
 }
 export declare function resolveBranding(branding?: ConnectaBranding): ResolvedBranding;
+/**
+ * Read a theme the way branding URLs are read: gate every field, drop what
+ * fails, never throw. This runs during `createConnecta`, so a malformed value
+ * has to fall back to the stylesheet default instead of refusing to serve the
+ * page. `droppedThemeTokens` names the drops for the startup warning.
+ */
+export declare function resolveTheme(theme?: ConnectaTheme): ResolvedTheme;
+/**
+ * Names of the theme tokens the operator set that failed their gate. Same
+ * contract as `droppedBrandingUrls`: rendering falls back silently, so this is
+ * the only place an operator learns their value never reached the page.
+ */
+export declare function droppedThemeTokens(theme?: ConnectaTheme): string[];
+/**
+ * The resolved theme as a `:root` block, or "" when a deployment configured
+ * nothing. It is emitted after the stylesheet so it overrides the defaults.
+ * There is no escaping here: every value has already passed a gate above, and
+ * anything that would need escaping is dropped rather than rewritten.
+ */
+export declare function themeCss(theme: ResolvedTheme): string;
 /**
  * Names of the branding URLs the operator set that failed their gate and were
  * replaced by a default. Lives beside the gates so the startup warning cannot
@@ -55,7 +84,7 @@ export declare function isSafeHttpsUrl(url: unknown): boolean;
  * `frontendApiUrl` is required, so anything that fails its gate is a drop.
  * `signInUrl` and `signUpUrl` are optional, so only a value the operator
  * *supplied* and the gate then rejected is worth a warning — an unset field
- * took no default away from anyone. `isSetUrlValue` decides that, the same way
+ * took no default away from anyone. `isSetValue` decides that, the same way
  * and for the same reasons it decides it for the branding URLs: a warning that
  * fires for one and not the other would be reporting on the field rather than
  * on the operator's intent. Rendering is not consulted for this: it drops on

package/dist/branding.js

@@ -38,17 +38,125 @@ export function resolveBranding(branding) {
             ? faviconHref
             : DEFAULT_FAVICON_HREF,
         themeColor: trimmedString(branding?.themeColor) ?? "#ffffff",
+        theme: resolveTheme(branding?.theme),
     };
 }
+/**
+ * Hex colors only: `#rgb`, `#rrggbb`, `#rrggbbaa`. A hex value cannot carry a
+ * `url()`, a `var()`, or a closing brace into the `:root` block it is written
+ * into, which is the whole reason the gate is this narrow.
+ */
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** A single non-negative CSS length, or a bare number the caller reads as px. */
+const CSS_LENGTH = /^(?:0|[0-9]{1,3}(?:\.[0-9]{1,3})?)(px|rem|em)?$/;
+/**
+ * One family name: bare, or wrapped in matching quotes. The character class
+ * excludes everything CSS needs to end a declaration or open a function (`;`,
+ * `{`, `}`, `(`, `)`, backslash, `<`, `>`, `@`, `*`, `/`, `:`), and matched
+ * quotes mean the value cannot leave an open string that swallows the CSS
+ * after it.
+ */
+const FONT_NAME = /^(?:"[a-z0-9 ._-]+"|'[a-z0-9 ._-]+'|[a-z][a-z0-9 ._-]*)$/i;
+/** A font-family list: comma-separated names and nothing else. */
+function isFontStack(value) {
+    if (value.length > 200)
+        return false;
+    const names = value.split(",");
+    return names.length <= 12 &&
+        names.every((name) => FONT_NAME.test(name.trim()));
+}
+const COLOR_SCHEMES = ["system", "light", "dark"];
+/**
+ * Read a theme the way branding URLs are read: gate every field, drop what
+ * fails, never throw. This runs during `createConnecta`, so a malformed value
+ * has to fall back to the stylesheet default instead of refusing to serve the
+ * page. `droppedThemeTokens` names the drops for the startup warning.
+ */
+export function resolveTheme(theme) {
+    const accent = trimmedString(theme?.accent);
+    const fontFamily = trimmedString(theme?.fontFamily);
+    const monoFamily = trimmedString(theme?.monoFamily);
+    const scheme = trimmedString(theme?.colorScheme);
+    const radius = radiusLength(theme?.radius);
+    return {
+        ...(accent && HEX_COLOR.test(accent) ? { accent } : {}),
+        ...(radius !== undefined ? { radius } : {}),
+        ...(fontFamily && isFontStack(fontFamily) ? { fontFamily } : {}),
+        ...(monoFamily && isFontStack(monoFamily) ? { monoFamily } : {}),
+        colorScheme: COLOR_SCHEMES.includes(scheme)
+            ? scheme
+            : "system",
+    };
+}
+/**
+ * `radius` accepts a number as well as a string, since a config file is more
+ * likely to say `10` than `"10px"`. A bare number means pixels; a string must
+ * carry its own unit or be zero.
+ */
+function radiusLength(radius) {
+    if (typeof radius === "number") {
+        return Number.isFinite(radius) && radius >= 0 && radius <= 999
+            ? `${radius}px`
+            : undefined;
+    }
+    const value = trimmedString(radius);
+    if (!value || !CSS_LENGTH.test(value))
+        return undefined;
+    return /[a-z]$/i.test(value) || value === "0" ? value : `${value}px`;
+}
+/**
+ * Names of the theme tokens the operator set that failed their gate. Same
+ * contract as `droppedBrandingUrls`: rendering falls back silently, so this is
+ * the only place an operator learns their value never reached the page.
+ */
+export function droppedThemeTokens(theme) {
+    if (!theme)
+        return [];
+    const resolved = resolveTheme(theme);
+    const dropped = [];
+    if (isSetValue(theme.accent) && !resolved.accent)
+        dropped.push("accent");
+    if (isSetValue(theme.radius) && resolved.radius === undefined) {
+        dropped.push("radius");
+    }
+    if (isSetValue(theme.fontFamily) && !resolved.fontFamily) {
+        dropped.push("fontFamily");
+    }
+    if (isSetValue(theme.monoFamily) && !resolved.monoFamily) {
+        dropped.push("monoFamily");
+    }
+    // Compared against the trimmed value the resolver reads, so `" dark "` is
+    // not reported as dropped when it was applied.
+    if (isSetValue(theme.colorScheme) &&
+        trimmedString(theme.colorScheme) !== resolved.colorScheme) {
+        dropped.push("colorScheme");
+    }
+    return dropped.map((token) => `theme.${token}`);
+}
+/**
+ * The resolved theme as a `:root` block, or "" when a deployment configured
+ * nothing. It is emitted after the stylesheet so it overrides the defaults.
+ * There is no escaping here: every value has already passed a gate above, and
+ * anything that would need escaping is dropped rather than rewritten.
+ */
+export function themeCss(theme) {
+    const declarations = [
+        theme.accent ? `--accent:${theme.accent}` : "",
+        theme.radius !== undefined ? `--radius:${theme.radius}` : "",
+        theme.fontFamily ? `--sans:${theme.fontFamily}` : "",
+        theme.monoFamily ? `--mono:${theme.monoFamily}` : "",
+    ].filter(Boolean);
+    return declarations.length ? `:root{${declarations.join(";")}}` : "";
+}
 /**
  * Whether the operator meant to supply a value here — the question every
- * dropped-URL warning asks before naming a field, and one definition so the
+ * dropped-value warning asks before naming a field, and one definition so the
  * branding and `uiAuth` warnings cannot answer it differently. A non-string
  * counts as set: the intent was there and is exactly what the warning reports
  * on. A blank or whitespace-only string does not; that is indistinguishable
  * from leaving the field alone, and both take the default silently.
  */
-function isSetUrlValue(value) {
+function isSetValue(value) {
     return typeof value === "string"
         ? trimmedString(value) !== undefined
         : value !== undefined && value !== null;
@@ -65,13 +173,13 @@ export function droppedBrandingUrls(branding) {
     const resolved = resolveBranding(branding);
     const faviconHref = branding.favicon?.href;
     return [
-        ...(isSetUrlValue(branding.productUrl) && !resolved.productUrl
+        ...(isSetValue(branding.productUrl) && !resolved.productUrl
             ? ["productUrl"]
             : []),
-        ...(isSetUrlValue(branding.ownerUrl) && !resolved.ownerUrl
+        ...(isSetValue(branding.ownerUrl) && !resolved.ownerUrl
             ? ["ownerUrl"]
             : []),
-        ...(isSetUrlValue(faviconHref) &&
+        ...(isSetValue(faviconHref) &&
             trimmedString(faviconHref) !== resolved.faviconHref
             ? ["favicon.href"]
             : []),
@@ -153,7 +261,7 @@ export function isSafeHttpsUrl(url) {
  * `frontendApiUrl` is required, so anything that fails its gate is a drop.
  * `signInUrl` and `signUpUrl` are optional, so only a value the operator
  * *supplied* and the gate then rejected is worth a warning — an unset field
- * took no default away from anyone. `isSetUrlValue` decides that, the same way
+ * took no default away from anyone. `isSetValue` decides that, the same way
  * and for the same reasons it decides it for the branding URLs: a warning that
  * fires for one and not the other would be reporting on the field rather than
  * on the operator's intent. Rendering is not consulted for this: it drops on
@@ -166,10 +274,10 @@ export function droppedUiAuthUrls(uiAuth) {
         return [];
     return [
         ...(isSafeHttpsUrl(uiAuth.frontendApiUrl) ? [] : ["uiAuth.frontendApiUrl"]),
-        ...(isSetUrlValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl)
+        ...(isSetValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl)
             ? ["uiAuth.signInUrl"]
             : []),
-        ...(isSetUrlValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl)
+        ...(isSetValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl)
             ? ["uiAuth.signUpUrl"]
             : []),
     ];

package/dist/connectors/api.d.ts

@@ -68,5 +68,5 @@ export interface ApiOptions {
     validateArgs?: boolean;
     tools: ApiTool[];
 }
-/** A static connector; see provider conventions' two construction-time checks. */
+/** A static connector; every tool passes {@link checkToolContract} first. */
 export declare function api(id: string, opts: ApiOptions): Connector;

package/dist/connectors/api.js

@@ -3,7 +3,15 @@ import { compileValidator, validateToolInput } from "../validate.js";
 export function defined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }
-/** Enforce provider conventions' two construction-time checks. */
+/**
+ * Three things a hand-written surface is refused for at construction rather
+ * than in production (#340): no description (discovery has nothing to route on
+ * and a guess costs a call), no explicit `readOnlyHint` (connecta never infers
+ * the safety class, so an unclassified tool is a deployment bug), and an
+ * `inputSchema` the validator cannot compile (declaring one is optional;
+ * declaring an unenforceable one is not). None of this reaches a proxied
+ * catalog — the contract binds the surfaces we write, not the ones we relay.
+ */
 function checkToolContract(id, tool) {
     const address = `${id}.${tool.name}`;
     if (typeof tool.description !== "string" || tool.description.trim() === "") {
@@ -20,7 +28,7 @@ function checkToolContract(id, tool) {
     if (tool.inputSchema)
         compileValidator(tool.inputSchema, { address });
 }
-/** A static connector; see provider conventions' two construction-time checks. */
+/** A static connector; every tool passes {@link checkToolContract} first. */
 export function api(id, opts) {
     for (const t of opts.tools)
         checkToolContract(id, t);

package/dist/connectors/guarded-fetch.d.ts

@@ -87,6 +87,10 @@ export interface GuardedFetchOptions {
 }
 /** Send one guarded request and map its response with provider knowledge. */
 export type GuardedTransport = <T>(request: GuardedRequest, ctx: ConnectorContext, map: GuardedResponseMapper<T>) => Promise<T>;
-/** Build the guarded transport described in documentation/connectors.md. */
+/**
+ * Build the transport a connector sends every request through. `maxResponseBytes`
+ * is required rather than defaulted: what counts as an absurd response is a fact
+ * about the API, not about HTTP.
+ */
 export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
 export {};

package/dist/connectors/guarded-fetch.js

@@ -1,4 +1,17 @@
-/** See documentation/connectors.md#the-guarded-fetch-transport. Web APIs only. */
+/**
+ * The safety machinery every hand-written HTTP surface needs, extracted once
+ * (#341): path confinement, encoded query and framed bodies, per-request
+ * credential headers applied last, a refused redirect, a bounded read, and
+ * network-failure normalization. It owns no *meaning* — it never reads a status
+ * code and never invents an auth scheme, because the same 403 means an ungranted
+ * capability at one provider and a token scope at another, and those want
+ * opposite next moves. The provider's `authenticate` supplies headers and its
+ * mapper turns one `GuardedResponse` into a result or a typed failure.
+ *
+ * Not exported this release: the migrations proved the shape preserves behavior
+ * for connectors that already had this machinery, not that it is the right
+ * public surface. Web APIs only.
+ */
 import { ConnectorCallError, unavailableCallError } from "../errors.js";
 /** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
 export function retryAfterMs(headers) {
@@ -123,7 +136,18 @@ async function drain(provider, stream, limit) {
     }
     return body;
 }
-/** See documentation/connectors.md#the-guarded-fetch-transport. */
+/**
+ * Every read is capped at `maxResponseBytes`: a streaming body is abandoned at
+ * the ceiling rather than buffered past it, and where a runtime gives no body
+ * stream the text is measured in UTF-8 bytes before it is accepted, with JSON
+ * parsed from that same bounded text. Such a runtime still buffers internally,
+ * but cannot return an oversized body as a successful result.
+ *
+ * A mapper must re-throw `ConnectorCallError` and swallow only what it
+ * recognizes: a bare `catch` around `response.json()` eats this refusal along
+ * with a parse error and turns a response nobody was allowed to read into an
+ * empty success.
+ */
 function boundedResponse(provider, response, limit) {
     if (BODILESS_STATUSES.has(response.status)) {
         const emptyJson = async () => undefined;
@@ -186,7 +210,11 @@ async function jsonResult(read) {
         return { parseError: cause };
     }
 }
-/** Build the guarded transport described in documentation/connectors.md. */
+/**
+ * Build the transport a connector sends every request through. `maxResponseBytes`
+ * is required rather than defaulted: what counts as an absurd response is a fact
+ * about the API, not about HTTP.
+ */
 export function guardedFetch(options) {
     const { provider, maxResponseBytes: limit } = options;
     if (!Number.isInteger(limit) || limit < 1) {
@@ -229,7 +257,9 @@ export function guardedFetch(options) {
                     : request.rawBody !== undefined
                         ? { body: request.rawBody }
                         : {}),
-                // Rationale: documentation/connectors.md#the-guarded-fetch-transport.
+                // A redirect is an instruction to re-send the credential to whatever
+                // origin `Location` names, and a confinement a redirect can undo was
+                // never one. Refused below rather than followed.
                 redirect: "manual",
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             });

package/dist/connectors/remote-mcp.js

@@ -105,8 +105,11 @@ function isCursorShapeError(err) {
  * close with the session left to age out as it did before.
  */
 async function terminateSession(transport, logger, connectorId) {
-    // See documentation/connectors.md#mcp-version-skew for the legacy DELETE
-    // that Client.close() does not send.
+    // SDK v2's Client.close() does not send the legacy session DELETE on our
+    // behalf. Connecta's own endpoint creates no protocol session, but a stateful
+    // legacy downstream can still issue `Mcp-Session-Id`, and every path that
+    // abandons one — scope teardown, credential rotation, OAuth retirement, an
+    // abandoned connect — owes it this best-effort, one-second DELETE.
     const terminate = transport.terminateSession;
     if (typeof terminate !== "function")
         return;
@@ -867,8 +870,9 @@ export function remoteMcp(id, opts) {
         // the accumulator is returned rather than stored: a cursor is opaque and
         // session-bound, so nothing here may outlive this call.
         async listTools(ctx) {
-            // The complete-catalog rule is documented at
-            // documentation/connectors.md#catalog-contract.
+            // The catalog contract: a downstream catalog is complete or it is a
+            // failure. Follow every page to the end of the cursor chain, preserve
+            // schemas and annotations, and never cache or serve a partial walk.
             const state = stateFor(ctx);
             await ensureConnected(ctx, state);
             // Bind the client once so the whole walk provably rides one session — a

package/dist/errors.d.ts

@@ -2,11 +2,19 @@
  * Machine-readable classification of a failed connector tool call.
  *
  * A code earns its place by changing what the caller does next, never by
- * naming a cause — the rule provider conventions call H11.
+ * naming a cause — the rule provider conventions call H11, defined in
+ * `test/provider-conventions.test.ts`.
  */
 export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
-/** Provider-owned absence; see provider-conventions.md H11 for the rule and
- * the permission-ambiguity exception. */
+/**
+ * Provider-owned absence: the caller re-addresses rather than waiting,
+ * re-authorizing, or repairing arguments, and a program looping over ids can
+ * continue past it where `connector_call_failed` would abort. Map a status
+ * here only where the provider distinguishes absence from a permission gap —
+ * where it does not (Notion's `object_not_found` covers both), the honest
+ * code stays `connector_call_failed` or `auth_required` with a message that
+ * states the ambiguity (H11).
+ */
  | "not_found" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {

package/dist/errors.js

@@ -20,7 +20,8 @@ function boundedIssueText(value, maxChars) {
  * the payload lands in both the text content and `structuredContent`. The agent
  * already holds what it sent; the echo is a convenience, never the record.
  */
-// Shared by argument and text echoes; see meta-tools.md lines 360-372.
+// One budget shared by the argument and text echoes, so a caller cannot make a
+// refusal larger by splitting what it sent across the two.
 const MAX_ECHOED_BYTES = 512;
 /**
  * The same budget spent on caller-authored *text* — the address it mistyped,

package/dist/index.d.ts

@@ -222,5 +222,5 @@ export { CONNECTA_VERSION } from "./version.js";
 export type { Registry } from "./registry.js";
 export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy, } from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
-export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
+export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
 export type { ActivityActor, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, CatalogDriftActivityEvent, ToolCallActivityEvent, } from "./activity.js";

package/dist/index.js

@@ -2,7 +2,7 @@ import { credentialTestRule, describeCredentialTestMismatch, } from "./credentia
 import { Registry } from "./registry.js";
 import { parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
 import { createFetchHandler } from "./server.js";
-import { droppedBrandingUrls, droppedUiAuthUrls } from "./branding.js";
+import { droppedBrandingUrls, droppedThemeTokens, droppedUiAuthUrls, } from "./branding.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 import { AdmissionController, executorName, isAdmittingExecutor, withExecutorAdmission, } from "./executor-admission.js";
@@ -262,6 +262,17 @@ function warnInsecureConfig(config, inboundAuth, logger) {
             "used as an href, so it must be an absolute http(s) URL (favicon.href " +
             "may also be a root-relative path). The default is rendered instead.");
     }
+    // Theme tokens are written into a `:root` block, so each is gated
+    // syntactically and a rejected value takes the stylesheet's default. Same
+    // reason as the branding URLs above: the page still renders, so without this
+    // line the only evidence is that the operator's color never showed up.
+    const droppedTheme = droppedThemeTokens(config.ui?.branding?.theme);
+    if (droppedTheme.length > 0) {
+        logger.warn(`[connecta] branding ${droppedTheme.join(", ")} dropped: accent must be ` +
+            "a hex color, radius a CSS length, the font families a plain " +
+            "font-family list, and colorScheme one of system/light/dark. The " +
+            "default is rendered instead.");
+    }
     // Operator shells render exactly one provider's browser sign-in config — the
     // first that offers one, matching the server route's `find` — and that
     // provider's URLs reach the browser: frontendApiUrl as the loader's