@zackbart/connecta 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to this package are documented here.
 
+## 0.38.0 — 2026-10-28
+
+0.38.0 is a minor release that retires the old storage and OAuth layout migrations, adds a configurable program return cap, makes in-program skill calls more forgiving, and moves the Eve helper to Eve 0.86.
+
+Breaking: the pre-layout-3 OAuth grant converter, the Workers KV → D1 copy APIs and script, and the Node JSON-state import API and `connecta migrate-state` command are removed. A deployment still holding old state must first upgrade through 0.37.1, run `copyKvToD1` or `migrate-state` as needed, and open every OAuth grant once on that version before moving to 0.38.0; otherwise old OAuth grants need fresh consent and old KV or JSON state is not imported. Retired pause, identity, grant and trust options still fail construction, now as ordinary unknown options without migration hints. `documentation/migration-retired-layouts.md` covers verification and recovery. Deployments that already run on 0.37.x layouts need no change.
+
+`execute.maxResultChars` sets how many serialized characters an `execute_code` program may return before Connecta pages it. The default stays 24,000, and paging notices now ask for pages sized to the configured cap. Programs can call `connecta.skill({ name })` and `connecta.skills(...)` as well as `connecta.skill(name)`, and the `execute_code` description states each host-call deadline truthfully when call and host-call timeouts differ.
+
+Also breaking: `@zackbart/connecta-eve` now requires Eve `>=0.86.0 <0.87.0`, so Eve 0.84 apps upgrade Eve to 0.86.0 together with the helper. Eve 0.86.0 still pins undici 8.10.2, so pnpm apps rekey their override to `"eve@0.86.0>undici": "8.12.3"`; npm apps keep the same override. The rest of the release is contributor-facing: refreshed development dependencies, a slimmer test suite, consolidated internals and trimmed documentation, with no runtime behavior change.
+
+### Added
+
+- Add `execute.maxResultChars`, the serialized characters an `execute_code` program may return before Connecta stashes the return behind a paging notice. The default stays 24,000; values from 4,000 to 1,000,000 are accepted, and anything else fails at construction. Emitted text shares the configured cap, and the paging notices that `execute_code` and direct calls return ask for pages sized to it instead of a fixed 3,829 bytes, never more than the stashed call's `maxResultBytes` or the 32 KiB bridge ceiling. A connector whose cap is below 3,829 bytes now gets a notice asking for the page size it actually serves. `describeConfig()` and the operator settings report it. Stash pages still obey each call's `maxResultBytes`. Connecta has no response-size limit, so keep the cap below what every client accepts: Claude Code passes at most 50,000 characters of text.
+
+### Changed
+
+- Accept the shapes models copy from the top-level `skills` tool into programs. `connecta.skill({ name })` now works like `connecta.skill(name)`, and `connecta.skills` is an undeclared alias of `connecta.skill` with the same host-call accounting, so neither costs a failed run. Any other argument fails `invalid_args` naming `connecta.skill("usage")`. The `execute_code` description, the server instructions, the usage guide and the program-error hint now show the in-program form `connecta.skill("usage")` and call the top-level one the skills tool, instead of giving `skills({ name: "usage" })` beside the guest API.
+- Consolidate internal helpers and remove unused code without changing runtime behavior.
+- Trim historical narration and duplicate procedures from documentation, correct contributor evidence references, and remove unreferenced eval baselines.
+- Refresh development dependencies: TypeScript 6.0, Vitest 5 with Vite 8.3, `@cloudflare/vitest-plugin` 1.4 (renamed from `@cloudflare/vitest-pool-workers`) with Wrangler 4.151, Playwright 1.64, and current oxlint, oxfmt, knip, esbuild, tsx, React and Radix releases, in core and the Eve helper. Published dependency and peer ranges are unchanged, and deployments need no change.
+- **Breaking:** `@zackbart/connecta-eve` now requires Eve 0.86 (`>=0.86.0 <0.87.0`) and is tested against Eve 0.86.0; Eve 0.84 apps must upgrade Eve to 0.86.0 together with the helper. Eve 0.86.0 still pins undici 8.10.2, so pnpm apps rekey their override to `"eve@0.86.0>undici": "8.12.3"`; npm apps keep the same override.
+- Contributor test suite slimmed: about 100 regression, lifetime, parity and meta-guard suites are removed, and workerd now runs only the suites that need real Workers bindings or isolates. No runtime behavior changes.
+
+### Fixed
+
+- The `execute_code` description no longer overstates the deadline of `connecta.result`, `connecta.skill` and `connecta.read`. When `calls.defaultTimeoutMs` differs from `execute.hostCallTimeoutMs`, it states both, for example `Limits: 20 host calls, 10 writes, 25s/call (15s result/skill/read).`, instead of advertising the call default for every host call. Enforcement is unchanged; deployments without `calls.defaultTimeoutMs` see the same `15s/host call` text as before.
+
+### Removed
+
+- **Breaking:** Remove the pre-layout-3 OAuth grant converter and cleanup, Workers KV → D1 copy APIs/types/script, and Node JSON-state import API and `connecta migrate-state` command. Retired pause, identity, grant, and trust options still fail construction as ordinary unknown options, without migration hints. Before upgrading, deployments with old state must upgrade through 0.37.1, run `copyKvToD1` or `migrate-state` as needed, and open every OAuth grant once on that version. Old OAuth grants otherwise require fresh consent; old KV/JSON state is not imported. Follow `documentation/migration-retired-layouts.md` for verification and recovery.
+
+## 0.37.1 — 2026-10-28
+
+0.37.1 is a patch release of fixes and request-path performance work. It needs no configuration change, and deployments on 0.37.0 can upgrade in place. One type change is additive: connector status gains a `per_caller` state, so code that switches exhaustively over status states must handle it.
+
+The headline fix is #1118: `execute_code` could return `hostCalls.failed` (and other numbers beside a redacted string) as `"[redacted]"`, which broke the tool's own output schema, so MCP clients that validate structured content rejected the whole result. Redaction now keeps a number unless it still holds part of a registered form after the strings around it are replaced, and Connecta's own counters are attached after redaction. Redaction also now rechecks a lane after every placeholder replacement until nothing changes, and typed arrays no longer hide a run split across them and their neighbours, so the documented guarantee holds in those corners too.
+
+If a remote MCP connector forwards the admitted principal (`auth.principal`), its resolver's token is registered as a credential, and every eight-unit run of it is withheld from agent output for that request. Return an opaque reference, such as the principal id or a signed assertion, never an email or anything containing the deployment's own domain or names.
+
+Security: a remote MCP OAuth challenge naming protected-resource metadata on a different origin from the connector URL, whether in the challenge or cached from an earlier grant, is now refused before any fetch.
+
+Reliability: OAuth refresh commits are bounded when storage stalls; a connect that straddles an OAuth Restart can no longer act in the newer epoch; executor permits are released when result stashing stalls; timed-out listen candidates and expired connector waiters no longer hold or receive admission; SQLite and D1 reclaim expired rows written by compare-and-set; request-token resolver failures show as `auth_required` in status; the MCP body bound holds on Node 24 and later; and a search in the same request sees catalog changes Connecta itself made.
+
+Operator pages: a principal-forwarding `remoteMcp` connector no longer shows "Authorization needed" when its calls work. The page checks it as the admitted operator, under the same `accept` policy as a call, and a check with no caller reports the neutral `per_caller` state. Cloudflare Access deployments no longer send an admitted browser a sign-in challenge when Access verification context is missing, as seen on fresh isolates; they answer a retryable 503 and log a classified reason for every operator 401. Startup no longer warns about missing OAuth state checks for connectors that never exchange a code, and operator status and config requests dispose workerd RPC results.
+
+Performance: each `execute_code` response is scanned for secrets once instead of twice, repeated searches in a request reuse one lexical index, and responses with no registered secrets skip JSON re-serialization at the MCP route. The root bundle cap rises to 407,000 B gzip to cover these fixes.
+
+### Changed
+
+- Run one envelope redaction scan per execute_code response at the operation boundary, after write accounting and before attaching Connecta’s host-call counters.
+- Reuse private lexical search snapshots within a request and safety view, cloning only selected definitions before returning discovery results.
+- Return MCP response body text untouched when the request has no registered secrets or unregistered private values after the body is fully read, avoiding unnecessary JSON parsing and serialization.
+- Raise the root bundle gzip cap from 404,500 to 407,000 B for the 0.37.1 fix set.
+
+### Fixed
+
+- Keep numbers when replacing an adjacent string breaks their credential match, while still withholding numeric credential runs. Recheck retained numbers after each whole-number replacement so new marker seams cannot expose credential fragments; an incomplete check withholds every originally touched number. Attach execute_code host-call counters after its final redaction so the counters remain integers. Document opaque principal-forwarding tokens and their request-wide redaction.
+- Bound downstream OAuth refresh commit and cleanup so stalled storage settles the flight, releases the owner partition, and reports an unknown outcome while preserving spent-token fencing.
+- Keep remote MCP authorization starts and status checks bound to the successful connection's OAuth epoch, so a concurrent Restart supersedes the older attempt instead of letting it read the replacement grant or publish consent there.
+  
+  Explicit starts after a passive status check or call in the same request scope can still initiate consent without widening the cached connection's authorization permissions.
+- Reclaim expired SQLite and D1 rows during mutating `compareAndSet()` calls with the same bounded sweep as `set()`, preserving atomic comparisons and their results.
+- Report request-token and principal resolver authentication failures as `auth_required` in remote MCP status without exposing resolver error messages.
+- Keep MCP listen-candidate body reads within their existing bound on Node 24 and later by avoiding an extra buffering pipe when attaching the request-local signal.
+- Release executor permits when result-stash storage stalls. Bound reservation and result processing by their deadlines and request cancellation, including final program-return paging after executor release, while preserving successful write accounting and refusing to replay completed writes.
+- Withdraw fallback admission waiters when a header-named subscriptions/listen candidate reaches its request deadline, preventing ended requests from being admitted later.
+- Refuse expired connector call admission waiters before granting a permit, even when the event loop delays their timeout callback.
+- Revalidate request-retained catalogs using in-process catalog invalidation and credential mutation fences, without storage reads on unchanged repeat searches, replacing derived search indexes when a fence changes.
+- Keep typed-array, DataView, and ArrayBuffer numbers adjacent to neighbouring leaves during redaction, while checking their byte views separately and withholding binary whose bytes or numbers hold a match.
+- Report principal-forwarding remote MCP connectors truthfully on the operator page: check as the admitted operator under the same caller policy as a call, and show actual downstream failures without a deployment-secret diagnosis or fix prompt. Checks without an admitted caller return the non-error `per_caller` state ("Authenticates as each caller; verified on use."). Adding `per_caller` to the public status union is an additive type change; exhaustive status consumers must handle it.
+
+  Operator observations are isolated by an opaque admitted viewer key, including same-role Cloudflare Access identity changes during pending probes.
+- Return retryable 503s when Cloudflare Access verification context is unavailable for an assertion-bearing request or its trusted AUD is unusable, including on a fresh instance. Keep admission closed until Access supplies verified human identity, and log classified, non-secret facts for unavailable verification and every operator 401.
+- Warn about missing OAuth state verification only for connectors that declare code-exchange support. Dispose remote MCP RPC responses at the request boundary, including operator configuration and status probes.
+
+### Security
+
+- Refuse remote MCP OAuth challenges whose protected-resource metadata URL is outside the configured resource origin before fetching metadata. Discard foreign cached resource metadata before SDK discovery, including callbacks and flows without challenges, and keep challenged hosts out of refusal messages. Same-origin paths, including Google's per-tool metadata, remain accepted.
+- Recheck redaction lanes until replacements stop creating credential runs beside placeholders, withholding every unchecked seam participant when the shared work budget cannot finish. Include omitted error numbers, whole error names, whole JSON strings and walk-time scalar placeholders in the returned projection. Check typed arrays' returned byte numbers and original element numbers in separate projections with the same neighbours.
+
 ## 0.37.0 — 2026-10-27
 
 Connecta 0.37.0 lets a `remoteMcp()` connection reach a trusted first-party downstream as the caller Connecta admitted, with no per-person OAuth. Request auth's new `principal` option gives the token resolver that caller's reference: people by default, and declared agents only with `accept: "human-or-agent"`. The new optional `fetch` carries all of the connector's MCP traffic, for example through a Workers service binding to a sibling Worker. The downstream must accept a forwarded identity only on its binding entrypoint or behind a verified signature. Operator status checks carry no caller, so a principal-forwarding connector reports `auth_required` on the operator pages even when calls succeed.

package/README.md

@@ -91,8 +91,8 @@ on Node, in Docker, or on Cloudflare Workers. The
 | [Safety and trust](./guides/safety-and-trust.md)    | Uncertain changes, secrets, read-only access, and your responsibilities. |
 | [Operator documentation](./documentation/README.md) | Setup, feature availability, upgrades, and exact contracts.              |
 
-<a id="existing-client-tokens"></a>
-
 Upgrading? Follow the [upgrade guide](./documentation/deploying.md#upgrade-an-existing-deployment).
+Pre-0.29 storage and OAuth layouts must first migrate on 0.37.1; see the
+[required bridge upgrade](./documentation/migration-retired-layouts.md).
 Breaking changes are expected before 1.0. See the [changelog](./CHANGELOG.md)
 and [security policy](./SECURITY.md).

package/bin/connecta.mjs

@@ -4,7 +4,7 @@ import { copyFile, cp, lstat, mkdtemp, readFile, rename, rm, symlink, writeFile
 import { CONNECTA_VERSION } from "./version.mjs";
 import { META_TOOL_NAMES } from "./meta-tool-names.mjs";
 import { basename, dirname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const [command, ...args] = process.argv.slice(2);
@@ -19,7 +19,6 @@ function shellCd(path) {
 function usage() {
   console.log(`Usage:
   connecta init [directory]
-  connecta migrate-state <state.json> <connecta.sqlite>
   CONNECTA_TOKEN=<bearer> connecta doctor [--config] [--url http://localhost:8787] [--pool <name>]
   CF_ACCESS_CLIENT_ID=<id> CF_ACCESS_CLIENT_SECRET=<secret> connecta doctor --url https://worker.example`);
 }
@@ -307,46 +306,9 @@ async function doctor() {
   );
 }
 
-/**
- * One-shot copy of a 0.28 `fileStorage` JSON state file into the SQLite
- * database 0.29 stores everything in. Stop the old deployment first; the file
- * is read, never changed.
- */
-async function migrateState() {
-  if (args.length !== 2 || args.some((arg) => arg.startsWith("--"))) {
-    usage();
-    process.exitCode = 1;
-    return;
-  }
-  const [statePath, databasePath] = args.map((arg) => resolve(process.cwd(), arg));
-  const { importStateFile, openSqlite } = await import(pathToFileURL(join(packageRoot, "dist", "sqlite.js")).href);
-  let database;
-  try {
-    database = openSqlite(databasePath);
-  } catch {
-    throw new Error("State migration failed: could not open the SQLite database");
-  }
-  let closeFailed = false;
-  try {
-    const result = importStateFile(database, statePath);
-    console.log(
-      `Imported ${result.imported} entries from ${statePath} into ${databasePath}` +
-        ` (${result.kept} already present, ${result.expired} expired).`,
-    );
-  } finally {
-    try {
-      database.close();
-    } catch {
-      closeFailed = true;
-    }
-  }
-  if (closeFailed) throw new Error("State migration failed: could not close the SQLite database");
-}
-
 try {
   if (command === "init") await init();
   else if (command === "doctor") await doctor();
-  else if (command === "migrate-state") await migrateState();
   else {
     usage();
     process.exitCode = command === "--help" || command === "-h" ? 0 : 1;

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.37.0";
+export const CONNECTA_VERSION = "0.38.0";

package/dist/access-tokens.js

@@ -1,3 +1,4 @@
+import { sha256Hex } from "./bytes.js";
 import { withAuthenticationDeadline } from "./auth-admission.js";
 import { authorizationCredential, isMachineCredential } from "./inbound-credential.js";
 import { assertKnownOptions, ConfigError, optionsOf, readPlain } from "./config-schema.js";
@@ -137,11 +138,8 @@ function bytesToBase64Url(bytes) {
         binary += String.fromCharCode(byte);
     return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
 }
-function bytesToHex(bytes) {
-    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
 async function hashToken(token) {
-    return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))));
+    return sha256Hex(token);
 }
 const REVISION_RE = /^[A-Za-z0-9_-]{22}$/u;
 /** Whether `value` has the shape of a slot revision. */

package/dist/agent-identity.js

@@ -1,4 +1,4 @@
-// Code-declared agents (#837): the names deployment code lists in `agents`,
+// Code-declared agents: the names deployment code lists in `agents`,
 // the identity an admitted agent carries, and the built-in providers trusted
 // to assert it. Pure, so core reads it without reaching credential modules.
 import { ConfigError } from "./config-schema.js";

package/dist/auth/clerk-sdk/generated.js

@@ -1833,4 +1833,5 @@ var Bc = new Set(["error", "warn", "info", "debug", "trace"]), Nt = { samplingRa
 };
 var ud = Mn(Z);
 function jc(t) { let e = { ...t }, r = he(e), s = qn({ options: e, apiClient: r }), n = new Jt({ publishableKey: e.publishableKey, secretKey: e.secretKey, samplingRate: .1, ...e.sdkMetadata ? { sdk: e.sdkMetadata.name, sdkVersion: e.sdkMetadata.version } : {}, ...e.telemetry || {} }); return { ...r, ...s, telemetry: n }; }
-export { jc as createClerkClient };
+const createClerkClient = jc;
+export { createClerkClient };

package/dist/auth/cloudflare-access.d.ts

@@ -3,6 +3,8 @@ import type { InboundAuth } from "../types.js";
  * Trust the identity Cloudflare Access attached to this direct Worker
  * invocation. Access has already validated the browser session, Managed OAuth
  * token, or service-token headers before the Worker runs; this adapter does
- * not accept or parse a caller-supplied JWT.
+ * not accept or parse a caller-supplied JWT. An assertion header without
+ * trusted context is only a hint that verification infrastructure is missing,
+ * never evidence of an authenticated caller.
  */
 export declare function cloudflareAccessAuth(): InboundAuth;

package/dist/auth/cloudflare-access.js

@@ -1,6 +1,7 @@
 import { withAuthenticationDeadline } from "../auth-admission.js";
 import { validIdentityReference } from "../identity.js";
 import { authorizationCredential } from "../inbound-credential.js";
+import { attachFailureFacts } from "../operator-record.js";
 import { authCall, authFlow, authInvoke, authMethod } from "./native.js";
 function identityString(identity, field) {
     const value = identity[field];
@@ -8,33 +9,46 @@ function identityString(identity, field) {
         ? value
         : undefined;
 }
-function unauthorized() {
+function unauthorized(reason) {
     return {
         ok: false,
-        response: Response.json({ error: "Cloudflare Access authentication required" }, { status: 401, headers: { "WWW-Authenticate": 'Bearer scope="openid email"', "Cache-Control": "no-store" } }),
+        response: attachFailureFacts(Response.json({ error: "Cloudflare Access authentication required" }, { status: 401, headers: { "WWW-Authenticate": 'Bearer scope="openid email"', "Cache-Control": "no-store" } }), { reason }),
+    };
+}
+function unavailable(problem) {
+    return {
+        ok: false,
+        response: attachFailureFacts(Response.json({ error: "Cloudflare Access identity unavailable", problem }, { status: 503, headers: { "Cache-Control": "no-store", "Retry-After": "1" } }), { reason: problem === "identity_unavailable" ? "access_identity_unavailable" : problem }),
     };
 }
 /**
  * Trust the identity Cloudflare Access attached to this direct Worker
  * invocation. Access has already validated the browser session, Managed OAuth
  * token, or service-token headers before the Worker runs; this adapter does
- * not accept or parse a caller-supplied JWT.
+ * not accept or parse a caller-supplied JWT. An assertion header without
+ * trusted context is only a hint that verification infrastructure is missing,
+ * never evidence of an authenticated caller.
  */
 export function cloudflareAccessAuth() {
     return {
         kind: "cloudflare-access",
         interactiveOperator: true,
-        recognizesCredential: (request, context) => authorizationCredential(request).kind === "absent" && Boolean(context?.access),
+        recognizesCredential: (request, context) => authorizationCredential(request).kind === "absent" &&
+            (Boolean(context?.access) || request.headers.has("Cf-Access-Jwt-Assertion")),
         challenge: () => 'Bearer scope="openid email"',
         activityActorNamespace: "cloudflare-access",
         uiAuth: { kind: "cloudflare-access" },
         authorize: authMethod(function (request, _baseUrl, runtimeContext) {
             return authFlow(function* () {
                 if (authorizationCredential(request).kind !== "absent")
-                    return unauthorized();
+                    return unauthorized("access_authorization_header_rejected");
                 const access = runtimeContext?.access;
-                if (!access || typeof access.aud !== "string" || !/^[\x21-\x7e]{1,256}$/.test(access.aud))
-                    return unauthorized();
+                if (!access)
+                    return request.headers.has("Cf-Access-Jwt-Assertion")
+                        ? unavailable("access_context_unavailable")
+                        : unauthorized("access_context_missing");
+                if (typeof access.aud !== "string" || !/^[\x21-\x7e]{1,256}$/.test(access.aud))
+                    return unavailable("access_audience_invalid");
                 let identity;
                 try {
                     identity = (yield authCall(withAuthenticationDeadline, [
@@ -45,10 +59,7 @@ export function cloudflareAccessAuth() {
                     ]));
                 }
                 catch {
-                    return {
-                        ok: false,
-                        response: Response.json({ error: "Cloudflare Access identity unavailable", problem: "identity_unavailable" }, { status: 503, headers: { "Cache-Control": "no-store", "Retry-After": "1" } }),
-                    };
+                    return unavailable("identity_unavailable");
                 }
                 // Access binds ctx.access.aud to its Worker application at the edge.
                 // Service credentials can pass that edge, but connecta machines must