@zackbart/connecta 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -2,6 +2,121 @@
 
 All notable changes to this package are documented here.
 
+## 0.41.0 — 2026-11-03
+
+This release fixes a production outage on Workers, tightens auth and network defaults, and makes warm requests cheaper. Three changes can stop an existing deployment at startup or at validation, so check them before upgrading.
+
+**Upgrade if you run Workers on `@cloudflare/codemode` 0.5.5 or later.** On Connecta 0.40.0, those codemode releases make every `execute_code` host call fail with "The code execution finished before this tool call settled". `workerExecutor()` now works with them. Deployments that pinned codemode to 0.5.4 to avoid this can drop the pin after upgrading; deployments that stay on 0.40.0 must keep it.
+
+**Breaking:** `clerkAuth` now requires a resolved `publicUrl`, set on `clerkAuth({ publicUrl })` or `ConnectaConfig.publicUrl`, and no longer falls back to the request origin. A configured vault must have `seal` and `open` when any connector has `startAuth`; use `encryptedCredentialVault(storage, key)` or add both methods, and existing plaintext grants are sealed on first read. Pool descriptions are limited to 500 UTF-16 code units after trimming. The public activity kind union adds `operation`, which affects exhaustive consumers of activity records.
+
+**Security:** learned OAuth URLs on non-public addresses are refused, including transitional IPv6 forms carrying non-public IPv4 addresses, learned Node URL connections are pinned to validated DNS answers, and the Node adapter answers `400` to a malformed `Host`, `X-Forwarded-Proto` or request target before reading the body. Pending OAuth flow records store less: with a sealing vault the consent URL, binding and PKCE verifier are sealed together, and with no vault the record keeps no consent URL, so a repeated start mints fresh consent. Sealed consents pending from 0.40.0 still complete; a legacy no-vault consent restarts fresh.
+
+**Performance:** warm catalog resolution locates manifests, negotiation and generation in one bounded read. Lexical indexes are reused across requests in an isolate, result-stash writes are batched, and last-seen observation skips redundant reads in its sampling window. Local-only skill catalogs now advertise a five-minute private TTL. Node gains a cap on request body bytes held in flight together, set with `listen(..., { maxInFlightBodyBytes })`. It defaults to the larger of 64 MiB and `maxBodyBytes`, and an explicit value must be at least `maxBodyBytes`; past it, requests get `503` with `Retry-After`.
+
+**Reliability and agent guidance:** a rejected Cloudflare Access identity lookup retries once within its original deadline and records payload-free diagnostics. API OAuth status now comes from typed call outcomes fenced by grant revision. Endpoint instructions lead with pool scope and the guide pointer and state the effective write policy, native tools point at connector guides, skills have readable names with legacy aliases, and downstream skill text is labeled with its third-party origin. Typed failures carry recovery steps across host, availability, utility and result-handle errors.
+
+**Opt-in, ignore unless you want them:** `activityHistory({ operations: true })` for payload-free operation history; `timingTraceSampleRate` for sampled payload-free MCP timing logs; QuickBooks `update_unsent_invoice`, enabled with `readOnly: false`, for sparse `DocNumber` updates on observed unsent US-company USD invoices, an inference from Intuit's documented autosend prerequisites and not a vendor no-email guarantee; and, in `@zackbart/connecta-eve`, a caller or turn `when` predicate on `connectaConnection` and `connectaInstructions`, plus `connectaSkill({ name, description, ... })` for deferred connector instructions as Eve skills.
+
+The downstream Skills extension remains Beta, and unknown Skills revisions are now rejected.
+
+### Added
+
+- Add opt-in sparse DocNumber updates for observed unsent US-company USD QuickBooks invoices, refusing unknown delivery state, enabled payments and stale versions.
+- **Breaking:** Opt in to payload-free operation history with activityHistory({ operations: true }). Search, describe, result, skill and whole-program rows use conservative scope and owner disclosure, remain detached from responses, and do not inflate call or friction counts. The public activity kind union adds operation, which may require updates to exhaustive consumers. Typed operation failures retain their checked codes, and activity reuses existing page byte measurements without serializing operation returns.
+- The Eve helper accepts a caller/turn `when` predicate for instructions and connections. False or a policy failure omits the value before fetching guidance or selecting a pool, including when guidance is cached.
+- `listen(..., { maxInFlightBodyBytes })` bounds the request body bytes all in-flight requests hold together on Node. It defaults to 64 MiB, or `maxBodyBytes` when that is larger. Past it a request is answered `503` with `Retry-After` and `Connection: close`. `maxBodyBytes` and its `413` are unchanged, and Workers are unaffected.
+- Point guided native tool descriptions at the connector guide through the serving skills route.
+- Add eval-only guidance delivery interventions for pointer, summary, inline convention and instruction-led fetch comparisons, with deterministic arm controls and guide-fetch metrics. Inline conventions use the advertised guideSummary field, and wire controls list tools first so the SDK validates every arm's output schema.
+- Offer opt-in deferred connector instructions as Eve skills with caller selection before fetching. Network, timeout and malformed-response failures omit the skill while preserving turn cancellation. Successful content is reused only while Eve retains the endpoint/guide/turn memo; failed later turns serve no stale guide.
+- Opt-in sampled payload-free MCP timing logs with request-read cache outcomes and D1 trip/statement totals. Workers durations are I/O-spanning elapsed observations, not CPU attribution; CPU-only catalog stages report counts and decoded bytes. Trace finalization survives throwing downstream cleanup.
+
+### Changed
+
+- **Breaking:** `createConnecta` throws when `clerkAuth` has no resolved `publicUrl`: neither `clerkAuth({ publicUrl })` nor `ConnectaConfig.publicUrl`. Clerk's token `resource` and session `azp` checks no longer fall back to the request origin. To migrate, set either option to the URL clients reach, or name the loopback origin locally, such as `http://localhost:8787`. A `clerkAuth` `publicUrl` that is not an absolute http(s) URL without credentials also throws. The unset-`publicUrl` startup warning now also fires with inbound auth and describes every URL that follows the request origin.
+- **Breaking:** `createConnecta` throws when a configured vault lacks `seal` or `open` and any connector has `startAuth`, replacing a startup warning that left downstream OAuth tokens, client registrations and PKCE verifiers as plaintext beside encrypted credentials. To migrate, use `encryptedCredentialVault(storage, key)` or add both methods to the custom vault; grants already stored as plaintext are sealed on first read. `encryptedCredentialVault`, deployments with no vault, and non-sealing vaults with no OAuth connector are unaffected.
+- Skip redundant last-seen observation reads during the one-minute sampling window while continuing fresh token admission.
+- Raise the root bundle cap to 422,500 B gzip and `examples/worker` to 806,500 B gzip for this release's measured growth, ending the batch's temporary headroom.
+- Locate catalog manifests alongside negotiation and generation in one bounded SQL read, retaining complete chunk verification and a separate fresh acceptance fence.
+  
+  Keep locator layout metadata and key construction in the shared key builders. Prove expired generation/manifest handling and literal punctuation against both SQL drivers, and pin measured combined warm agent read counts after admission observation sampling.
+- Run CI static/package build phases and two isolated Node test shards in parallel, checking complete shard coverage and every matrix leg's completion at the aggregate gate.
+- Prefix downstream skill text with its third-party connector origin on tool and program surfaces while preserving native manifest bytes.
+- Reuse bounded immutable lexical tokens and postings across complete request catalogs while applying visibility on each request.
+- Advertise a five-minute private TTL for local-only skill catalogs and reads; downstream-enabled caller views retain zero TTL.
+- Use pinned native TypeScript for core and operator UI no-emit feedback, with explicit shared result types accepted by both compilers. Keep TypeScript 6 for AST analysis, emitted builds, declarations and installed consumers.
+- Verify sealed pending OAuth consents from 0.40.0 through callback validation, binding, claim, exchange and token persistence. Cover fresh-start recovery for legacy no-vault consents whose discovery URLs include userinfo, queries or fragments.
+- **Breaking:** Put pool scope and the guide pointer before routing rules in meta and native endpoint instructions, preserving unscoped instructions.
+  
+  Pool descriptions are limited to 500 UTF-16 code units after trimming so accepted text fits the instruction budget and first 512 units in every mode. This tightens validation: previously accepted descriptions with at most 500 Unicode code points but more than 500 UTF-16 units (for example, 500 emoji) now fail construction. Shorten those descriptions before upgrading; required routing rules remain intact.
+- Keep server orchestration and Effect out of the QuickJS child startup graph.
+- Use readable skill slugs with legacy aliases, actionable provider summaries and advisory construction warnings for weak guide summaries.
+  
+  Generated readable names resolve on every skill surface; canonical identities take priority over legacy aliases, ambiguous aliases fail explicitly, and generated names avoid configured connector IDs.
+- Batch SQL result-stash trailing chunks before separate header publication, reducing storage trips while preserving expiry and uncertain-write accounting.
+- Strengthen stash fault probes for delayed SQL batch commits and transactional expiry sweeps.
+
+### Fixed
+
+- Clarify that the redaction guarantee excludes occurrences made entirely of reserved replacement text, including runs across the seam between adjacent markers. Settling behavior is unchanged.
+- QuickBooks write evals now explicitly grade the destination and final answer evidence, completing the selftest check classification without weakening outcome checks.
+- Let `eval:selftest`'s D1 latency control accept a timer that fires just under its delay, so the full selftest no longer fails on a 49.8 ms round trip.
+- QuickBooks eval setup now probes personal credential isolation through a program and checks read-only pools using the tools the selected eval surface serves, so code-only selftests retain their safety checks without calling hidden meta-tools.
+- Attribute eval fake dispatches through a per-server transport marker, retaining unrelated loopback probes separately from vendor ledgers.
+- Probe exact-once eval latency on both deployment targets, disabled fault membership, stopped listening sockets, and each D1 round trip. Count D1 batch waits instead of imposing a load-sensitive upper timing bound.
+- Retry a rejected Cloudflare Access identity lookup once within its original deadline and record checked, payload-free lookup failure diagnostics. Identity failures continue to refuse admission.
+- Restrict native eval workerd TCP connections with fail-closed Linux Landlock port rules and raw-socket controls for disallowed ports and the known allowed-port address limit. Add a model-free check of all eligible Worker references. Document the remaining address and UDP limits.
+- Report API OAuth status from typed real-call outcomes fenced by the token grant's revision. Consent and refresh replace their observation atomically, and passive status reads do not write grant state. Later invocations can recover from transient API refusals; Connect starts fresh consent for a refused grant. Maintained provider middleware records initial and replayed outcomes, and unchanged observations do not rewrite grants. Normal Connect preserves concurrent recovery, and oversized 401 responses record refusal without reading their bodies, including after replay.
+- `workerExecutor()` works with `@cloudflare/codemode` 0.5.5 and later. Those releases close a call gate when the SDK's `execute()` settles, and Connecta's inert loader settled it before the real program ran, so every `execute_code` host call failed with "The code execution finished before this tool call settled". The gate now stays open for the whole native run and closes when it ends or its lease is released. Development and CI use codemode 0.5.6.
+- State effective write policy in endpoint instructions and connector guides, and explain that read-only refusals have no write route.
+- Supply schema recovery for typed argument failures without validation details and explicit safe recovery limits for missing resources, unavailable connectors and uncertain writes.
+- Reuse one observation age for stored connector details and their overlays, keeping both fields consistent across a clock rollover.
+- Corrected the Cloudflare Access `identityLookup.inFlight` documentation: it counts lookup attempts still pending, so a hung lookup counts itself, and a rejected lookup or a deadline during retry backoff does not.
+- Prevent eval startup port reservation races, retry child bind collisions before trials start, and protect a checkout's build with crash-released OS locks while allowing concurrent eval readers. Report failed cross-connector reference reads before attempting the answer post.
+  
+  Restore the fake vendor transport before deployment startup yields, preserving containment and physical-write evidence across interleaved trials.
+  
+  Use descriptor-mode locking on Linux and macOS, retaining the lease when the wrapper dies while its command runs. Keep explicit Wrangler inspector/proxy ports for Landlock and retry native startup collisions with fresh ports. Document the lock's reader/writer fairness limit.
+- Retain remote MCP cleanup settlement across owner and connector close, including abandoned leases, so bounded session termination remains owned by runtime deferred work. Await explicit warmup termination in OAuth rotation tests, including cleanup gated before fetch accounting.
+- `eval:selftest` exits after its last check instead of idling on the egress control's unclosed UDP probe socket.
+- Reject unknown downstream Skills revisions and record the extension’s Beta lifecycle.
+- Complete typed host, availability, utility and result-handle recovery, with continuation actions taking precedence over generic retry advice.
+
+### Security
+
+- Pending downstream OAuth flow records store less. With a sealing vault, the consent URL, server and client binding, and PKCE verifier are sealed together. With no vault, the record stores no consent URL and its binding keeps no URL userinfo, query or fragment, so a repeated non-forced start mints a fresh consent instead of reusing the pending URL. `documentation/auth.md` states the narrower no-vault guarantee. Sealed consents already in flight across the upgrade still complete. A no-vault consent whose discovery URL holds userinfo, a query or a fragment fails cleanly and needs a fresh start.
+- Learned OAuth URLs naming reserved or transitional addresses are refused: IPv4 special-purpose ranges (`192.0.0/24`, `198.18/15`, multicast, reserved and broadcast among them), IPv6 outside global unicast, and IPv4 carried in compatible, translated, NAT64 or 6to4 form, judged by the address it carries. A public address in those forms stays public. A `publicUrl` on such an address no longer offers a self-hosted client metadata document.
+- The Node adapter answers `400` for a `Host` that is not a host with an optional port, an `X-Forwarded-Proto` other than `http` or `https`, or a request target that does not start with `/`, before reading any body. No such value can change the path or host routes see. A malformed value used to fail as a `500` or be parsed into another URL.
+- Pin learned Node URL connections to validated DNS addresses while preserving TLS hostname verification.
+
+## 0.40.0 — 2026-11-02
+
+This release makes warm Connecta calls on Workers cheaper in storage and closes a credential gap on OAuth remote MCP connectors. Deployments need no configuration change or migration, unless they use the Eve helper.
+
+**Eve helper:** `@zackbart/connecta-eve` now requires exactly Eve 1.0.0-rc.1. Eve 0.90 apps must upgrade Eve together with the helper and, when installed, upgrade `@vercel/connect` to `^2.7.0`. The core package and non-Eve deployments are not affected by this change.
+
+**Security:** an OAuth remote MCP connector no longer sends a passive handshake, catalog request or tool call without a credential if its tokens are removed mid-request. It returns OAuth recovery before sending instead. Before this, a server accepting anonymous requests could receive that request without the connector's credential.
+
+**Native pools:** native pools now always list `authorize_connector`, so an agent on a pool without `execute_code` can get the operator a handoff for a connector that needs authorization. On those pools the repaired connector's tools appear only after the host refreshes its tool list, usually by reconnecting; pools with `execute_code` can reach them from a program straight away. Anything that compares a native pool's tool list exactly will see one more tool. Meta endpoints keep the same six tools.
+
+**Storage work per call:** warm remote MCP catalog resolution now takes four D1 round trips instead of six on modern servers and five on legacy ones. Warm agent admission takes two reads instead of four. Warm OAuth calls read the grant 9 times instead of 11 on modern servers and 12 instead of 13 on legacy ones. A warm isolate reuses a stored catalog it has already validated, after the same freshness and partition checks. The catalog and admission round trips were measured with injected latency on local workerd, and the OAuth counts come from request-budget tests. None of this has been measured in production.
+
+### Changed
+
+- Read agent token admission state in one fresh D1 or SQLite statement, reducing warm admission and last-seen observation from four reads to two while preserving next-request rotation and revocation enforcement.
+- **Breaking:** `@zackbart/connecta-eve` now requires exactly Eve 1.0.0-rc.1; Eve 0.90 apps must upgrade Eve together with the helper and, when installed, upgrade `@vercel/connect` to `^2.7.0`. Align installed-consumer probes and upgrade guidance with the tested release candidate. Later candidates and stable 1.0 require a compatibility check.
+- Reduce grant reads on warm OAuth remote MCP calls while retaining fresh catalog acceptance, disconnect, token rotation and dispatch checks. Keep the separate invocation token read so same-epoch invalidation refuses writes with OAuth recovery before dispatch, and expiry changes are observed before early renewal.
+- Reuse validated stored catalogs within a warm isolate after checking stored chunks, partition identity, expiry and the fresh generation fence. Retained facts are immutable and bounded; credential redaction still runs per request.
+
+### Fixed
+
+- Reduce warm remote MCP catalog storage round trips by batching locating reads and private/public manifest probes while preserving fresh generation and OAuth credential acceptance checks.
+- Keep authorization recovery available on native pools without code by listing authorize_connector with the granted connector ids, even when a connector's catalog cannot load.
+
+### Security
+
+- Require a credential on passive OAuth remote MCP sends, including handshakes, catalog requests and tool dispatches, regardless of provider replacement. Return OAuth recovery before sending when the SDK cannot obtain one, and count a verified unsent write as failed without reconciliation. Explicit authorization flows retain their challenges; writes that may already have left remain unknown.
+
 ## 0.39.0 — 2026-10-30
 
 This release makes Connecta faster and leaner for agents and operators on Cloudflare Workers. A warm search over remote MCP connectors with cached catalogs no longer reconnects to them: an all-legacy warm search makes no downstream requests. Repeated storage reads are memoized per request, and catalog chunks are read in batches. OAuth tokens refresh before they expire instead of failing the first write after expiry. Legacy negotiation verdicts last six hours, with bounded recovery when a server changes protocol era. A connector that recently hung or failed slowly is reported in `catalogErrors` and skipped by unscoped search for about a minute, and unscoped discovery has a total budget. With one hung connector, three consecutive searches went from 30 s each to 5 s, 11 ms and 8 ms.

package/bin/connecta.mjs

@@ -258,18 +258,14 @@ async function doctor() {
         `Native catalogs unavailable: ${surface.catalogErrors.join(", ")}. Inspect connector status and authentication.`,
       );
     const expected = native
-      ? ["skills", executeCode ? "execute_code" : "read_result"].sort()
+      ? ["authorize_connector", "skills", executeCode ? "execute_code" : "read_result"].sort()
       : [...META_TOOL_NAMES].sort();
     if (
       native
         ? expected.some((name) => !actual.includes(name)) ||
-          [
-            "search_tools",
-            "call_tool",
-            "call_destructive_tool",
-            "authorize_connector",
-            executeCode ? "read_result" : "execute_code",
-          ].some((name) => actual.includes(name))
+          ["search_tools", "call_tool", "call_destructive_tool", executeCode ? "read_result" : "execute_code"].some(
+            (name) => actual.includes(name),
+          )
         : JSON.stringify(actual) !== JSON.stringify(expected)
     ) {
       throw new Error(

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.39.0";
+export const CONNECTA_VERSION = "0.41.0";

package/dist/access-tokens.js

@@ -8,7 +8,7 @@ import { accessTokenKeys } from "./storage/keys.js";
 import { AGENT_NAMESPACE, agentSubjectId, isAgentName, trustAgentProvider } from "./agent-identity.js";
 import { keepErrorName } from "./redaction-identity.js";
 import { agentConfig } from "./agent-config.js";
-import { authCall, authCatch, authFlow, authInvoke, authMethod, authOwnMethod, authStorage, registerAuthMethod, } from "./auth/native.js";
+import { authAccessToken, authCall, authCatch, authFlow, authInvoke, authMethod, authOwnMethod, authStorage, registerAuthMethod, } from "./auth/native.js";
 import { runEdge } from "./runtime/run.js";
 const TOKEN_PREFIX = "cta_";
 const TOKEN_BYTES = 32;
@@ -802,7 +802,9 @@ export class AccessTokenManager {
                             signal.throwIfAborted();
                             const hash = (yield authCall(hashToken, [token]));
                             signal.throwIfAborted();
-                            const lookupRaw = (yield authStorage(this.storage, "get", [lookupKey(hash)]));
+                            const snapshot = (yield authAccessToken(this.storage, hash));
+                            const read = (key) => snapshot ? (snapshot.get(key) ?? null) : authStorage(this.storage, "get", [key]);
+                            const lookupRaw = (yield authCall(read, [lookupKey(hash)]));
                             signal.throwIfAborted();
                             if (!lookupRaw)
                                 return unauthorized();
@@ -810,7 +812,7 @@ export class AccessTokenManager {
                             if (!lookup)
                                 return unauthorized();
                             const recordRaw = ID_RE.test(lookup.id)
-                                ? (yield authStorage(this.storage, "get", [recordKey(lookup.id)]))
+                                ? (yield authCall(read, [recordKey(lookup.id)]))
                                 : null;
                             const record = recordRaw ? parseRecord(recordRaw) : null;
                             if (record && record.id !== lookup.id)
@@ -827,7 +829,7 @@ export class AccessTokenManager {
                             // code, refuse exactly as an unknown token does.
                             if (record.principal || record.agent === undefined || !this.agents.has(record.agent))
                                 return unauthorized();
-                            const slotRaw = (yield authStorage(this.storage, "get", [slotKey(record.agent)]));
+                            const slotRaw = (yield authCall(read, [slotKey(record.agent)]));
                             const slot = slotRaw === null ? null : parseSlot(slotRaw, record.agent);
                             signal.throwIfAborted();
                             if (slot?.state !== "issued" || slot.tokenId !== record.id)

package/dist/activity.d.ts

@@ -27,7 +27,7 @@ export interface ActivityActor {
     namespace?: string;
 }
 /**
- * Privacy-minimal history of one resolved downstream connector call.
+ * Privacy-minimal history of a resolved call, catalog change or opt-in operation.
  *
  * Arguments, results, generated code, search text, and raw errors are excluded
  * by construction. Deployments that need a safe human summary can add a
@@ -39,6 +39,19 @@ export interface ActivityCatalogChange {
     removedTools: number;
     changedTools: number;
 }
+export type ActivityOperationName = "search" | "describe" | "result" | "skill" | "program";
+export interface ActivityOperation {
+    name: ActivityOperationName;
+    /** Conservative endpoint scope, never caller-supplied addresses. */
+    connectors: string[];
+    personal: boolean;
+    hostCalls?: {
+        attempted: number;
+        admitted: number;
+        succeeded: number;
+        failed: number;
+    };
+}
 /** Integer metadata is checked at every write and read boundary. */
 export declare function activityCount(value: unknown): number | undefined;
 export declare function activityBehaviorFacts(event: {
@@ -46,16 +59,18 @@ export declare function activityBehaviorFacts(event: {
     resultBytes?: unknown;
     kind?: unknown;
     drift?: unknown;
+    operation?: unknown;
     pool?: unknown;
     actorBasis?: unknown;
-}): Pick<ToolCallActivityEvent, "classification" | "resultBytes" | "kind" | "drift" | "pool" | "actorBasis">;
+}): Pick<ToolCallActivityEvent, "classification" | "resultBytes" | "kind" | "drift" | "operation" | "pool" | "actorBasis">;
 export interface ToolCallActivityEvent {
     schemaVersion: 1;
     id: string;
     occurredAt: string;
     requestId: string;
     /** Absent on legacy tool rows. Catalog changes use the same paging envelope. */
-    kind?: "catalog_drift";
+    kind?: "catalog_drift" | "operation";
+    operation?: ActivityOperation | undefined;
     drift?: ActivityCatalogChange;
     /** The final registry verdict captured when resolution succeeded. */
     classification?: "read" | "write";
@@ -162,6 +177,7 @@ export interface CatalogDriftActivityContext {
 }
 /** Request-scoped context shared by direct, batch, and code-mode call paths. */
 export interface ActivityRequestContext {
+    recordOperation?: typeof recordOperationActivity | undefined;
     recordTool?: typeof recordToolActivity | undefined;
     sink: ActivitySink;
     actor: ActivityActor;
@@ -181,7 +197,7 @@ export interface ActivityRequestContext {
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "friction" | "classification" | "resultBytes" | "kind" | "drift"> & {
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "friction" | "classification" | "resultBytes" | "kind" | "drift" | "operation"> & {
     /**
      * A code connecta assigns. Rows written by older deployments may hold
      * others, so the stored event keeps `string`; a new row never does.
@@ -204,8 +220,18 @@ export declare function recordCatalogChangeActivity(context: CatalogDriftActivit
     privateCatalog?: boolean;
 }, request?: ActivityRequestContext): void;
 export interface ActivityHistoryOptions {
+    /** Opt in to one detached storage write per meta operation and program. */
+    operations?: boolean;
     store: ActivityStore;
     deploymentId?: string;
     readGate?: ActivityReadGate;
 }
 export declare function activityHistory(options: ActivityHistoryOptions): ActivityModule;
+/** Operation records reuse the detached sink and accept no payload fields. */
+export declare function recordOperationActivity(context: ActivityRequestContext, input: {
+    operation: ActivityOperation;
+    durationMs: number;
+    resultBytes?: number | undefined;
+    outcome: ActivityOutcome;
+    errorCode?: ClassificationCode | undefined;
+}): void;

package/dist/activity.js

@@ -1,3 +1,4 @@
+import { checkedActivityOperation } from "./operation-activity.js";
 import { CONNECTA_VERSION } from "./version.js";
 import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeActivity } from "./routes/activity.js";
@@ -82,6 +83,7 @@ export function activityBehaviorFacts(event) {
         ...(classification !== undefined ? { classification } : {}),
         ...(resultBytes !== undefined ? { resultBytes } : {}),
         ...(drift ? { kind: "catalog_drift", drift } : {}),
+        ...(event.kind === "operation" ? { kind: "operation", operation: checkedActivityOperation(event.operation) } : {}),
         ...(pool !== undefined ? { pool } : {}),
     };
 }
@@ -106,7 +108,7 @@ export function recordToolActivity(context, input) {
     // Checked here as well as by type: a handler can put any string in a
     // `ConnectorCallError`'s code, and a downstream's own code is not recorded.
     const errorCode = classificationCode(input.errorCode);
-    const friction = input.friction ?? agentFrictionForCode(errorCode);
+    const friction = input.kind === "operation" ? undefined : (input.friction ?? agentFrictionForCode(errorCode));
     // Re-check client grammars at the record boundary; never spread the envelope.
     const clientName = activityClientFact(context.clientInfo?.name, "name");
     const clientVersion = activityClientFact(context.clientInfo?.version, "version");
@@ -176,16 +178,40 @@ export function recordCatalogChangeActivity(context, input, request) {
 }
 /** Attach payload-free history without changing tool results on store failure. */
 /** The closed options activityHistory() accepts; see `assertKnownOptions`. */
-const ACTIVITY_HISTORY_OPTIONS = optionsOf()(keys("store", "deploymentId", "readGate"));
+const ACTIVITY_HISTORY_OPTIONS = optionsOf()(keys("store", "deploymentId", "readGate", "operations"));
 export function activityHistory(options) {
     options = assertKnownOptions(options, "activityHistory()", ACTIVITY_HISTORY_OPTIONS);
     if (!options || typeof options.store?.record !== "function") {
         throw new Error("activityHistory.store must implement record(event)");
     }
+    if (options.operations !== undefined && typeof options.operations !== "boolean")
+        throw new Error("activityHistory.operations must be a boolean");
     return {
         ...options,
+        ...(options.operations ? { recordOperation: recordOperationActivity } : {}),
         handle: routeActivity,
         recordTool: recordToolActivity,
         recordChange: recordCatalogChangeActivity,
     };
 }
+/** Operation records reuse the detached sink and accept no payload fields. */
+export function recordOperationActivity(context, input) {
+    const operation = checkedActivityOperation(input.operation);
+    if (!operation)
+        return;
+    const connectorId = operation.connectors.length === 1 ? operation.connectors[0] : "$operation";
+    recordToolActivity(context, {
+        kind: "operation",
+        operation,
+        connectorId,
+        toolName: operation.name,
+        address: `${connectorId}.${operation.name}`,
+        source: "execute_code",
+        outcome: input.outcome,
+        durationMs: input.durationMs,
+        ...(input.resultBytes !== undefined ? { resultBytes: input.resultBytes } : {}),
+        attempts: 1,
+        ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+        ...(operation.personal ? { privateCatalog: true } : {}),
+    });
+}

package/dist/agent-observation.js

@@ -5,8 +5,13 @@ import { isAgentName } from "./agent-identity.js";
 import { agentObservationKeys } from "./storage/keys.js";
 import { Storage } from "./runtime/services.js";
 import { storageCompareAndSet, storageGet } from "./runtime/storage.js";
+import { physicalStorageAddress } from "./runtime/request-reads.js";
 const OBSERVATION_TIMEOUT_MS = 500;
 const OBSERVATION_FRESHNESS_MS = 60_000;
+// Only scalar telemetry deadlines survive requests. Weak physical-store ownership
+// and a bounded map prevent agent/config churn from retaining unbounded state.
+const observedUntil = new WeakMap();
+const MAX_OBSERVED_AGENTS = 256;
 function timestamp(raw) {
     if (!raw || raw.length !== 24)
         return null;
@@ -26,14 +31,31 @@ export function observeAgentAdmission(storage, name, at, timeoutMs) {
         return Effect.void;
     return Effect.gen(function* () {
         const key = agentObservationKeys.agent(name);
+        const address = physicalStorageAddress(storage, key) ?? { store: storage, key };
+        const now = Date.parse(at);
+        let observations = observedUntil.get(address.store);
+        if (!observations)
+            observedUntil.set(address.store, (observations = new Map()));
+        if ((observations.get(address.key) ?? -Infinity) > now)
+            return;
+        const remember = (seen) => {
+            const until = Math.min(seen + OBSERVATION_FRESHNESS_MS, now + OBSERVATION_FRESHNESS_MS);
+            if (!observations.has(address.key) && observations.size >= MAX_OBSERVED_AGENTS)
+                observations.delete(observations.keys().next().value);
+            observations.set(address.key, Math.max(observations.get(address.key) ?? -Infinity, until));
+        };
         for (let attempt = 0; attempt < 2; attempt++) {
             const previous = yield* storageGet(key);
             const seen = timestamp(previous);
             // Future and recently sampled observations both need no write.
-            if (seen && Date.parse(at) - Date.parse(seen) < OBSERVATION_FRESHNESS_MS)
+            if (seen && now - Date.parse(seen) < OBSERVATION_FRESHNESS_MS) {
+                remember(Date.parse(seen));
                 return;
-            if (yield* storageCompareAndSet(key, previous, at))
+            }
+            if (yield* storageCompareAndSet(key, previous, at)) {
+                remember(now);
                 return;
+            }
         }
     }).pipe(Effect.provideService(Storage, storage), Effect.catchDefect((error) => Effect.fail(error)), Effect.catch(() => Effect.void), Effect.timeoutOption(Duration.millis(Math.min(timeoutMs, OBSERVATION_TIMEOUT_MS))), Effect.asVoid);
 }

package/dist/agent-routes.js

@@ -26,45 +26,8 @@
  *   catalogs with the description built for its own surface.
  */
 import { Context } from "effect";
-const NAMES = {
-    meta: Object.freeze({
-        search: "search_tools",
-        read: "call_tool",
-        write: "call_destructive_tool",
-        program: "execute_code",
-        authorize: "authorize_connector",
-        skills: "skills",
-    }),
-    code: Object.freeze({
-        search: "connecta.search inside execute_code",
-        read: "connecta.call inside execute_code",
-        write: "connecta.call inside execute_code",
-        program: "execute_code",
-        authorize: "authorize_connector",
-        skills: "skills",
-    }),
-    native: Object.freeze({
-        search: "your host's tool search",
-        read: "the original native tool",
-        write: "the original native tool",
-        program: "your host's tool search",
-        authorize: "the returned authorization handoff",
-        skills: "skills",
-    }),
-    "native-code": Object.freeze({
-        search: "your host's tool search",
-        read: "the original native tool",
-        write: "the original native tool",
-        program: "execute_code",
-        authorize: "the returned authorization handoff",
-        skills: "skills",
-    }),
-};
-/** The six-tool surface's names: the default wherever no other surface applies. */
-export const META_ROUTES = NAMES.meta;
-export function routeNames(surface) {
-    return NAMES[surface];
-}
+import { META_ROUTES, routeNames } from "./route-names.js";
+export { META_ROUTES, routeNames } from "./route-names.js";
 /** The names for the surface a connector operation serves; meta for contexts Connecta did not build. */
 export function routesOf(ctx) {
     return ctx?.routes ?? META_ROUTES;
@@ -125,7 +88,7 @@ const PHRASES = {
         ...nativeAuthorize,
     }),
 };
-const SURFACES = new Map(Object.keys(NAMES).map((surface) => [NAMES[surface], surface]));
+const SURFACES = new Map(["meta", "code", "native", "native-code"].map((surface) => [routeNames(surface), surface]));
 /** The surface a names table belongs to; meta for a table Connecta did not build. */
 function routeSurface(routes) {
     return (routes && SURFACES.get(routes)) ?? "meta";
@@ -227,5 +190,5 @@ export function renderRoutesAsPrograms(config) {
 }
 /** The names every reply of a deployment built from `config` uses outside native pools. */
 export function deploymentRoutes(config) {
-    return programRouteConfigs.has(config) ? NAMES.code : NAMES.meta;
+    return programRouteConfigs.has(config) ? routeNames("code") : META_ROUTES;
 }

package/dist/auth/clerk.d.ts

@@ -4,7 +4,12 @@ export type { ClerkGateClient, ClerkUser } from "./clerk-sdk/client.js";
 export interface ClerkAuthOptions {
     publishableKey: string;
     secretKey: string;
-    /** Public base URL of this deployment. Defaults to the request origin. */
+    /**
+     * Public base URL of this deployment: what tokens' resource and sessions'
+     * `azp` are checked against. Defaults to `ConnectaConfig.publicUrl`. One of
+     * the two is required; a request's Host never substitutes for it. A local
+     * deployment names its loopback origin, such as `http://localhost:8787`.
+     */
     publicUrl?: string;
     /**
      * OAuth client IDs dedicated to this deployment, used only when a verified

package/dist/auth/clerk.js

@@ -436,7 +436,22 @@ function mcpPoolSuffix(pathname) {
     const match = /^\/mcp(\/[a-z0-9_-]+)$/.exec(pathname);
     return match ? match[1] : null;
 }
+function assertPublicUrl(value) {
+    if (value === undefined)
+        return;
+    let url;
+    try {
+        url = typeof value === "string" ? new URL(value) : undefined;
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url || (url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
+        throw new Error("clerkAuth: `publicUrl` must be an absolute http(s) URL without credentials.");
+    }
+}
 export function clerkAuth(opts) {
+    assertPublicUrl(opts.publicUrl);
     assertNoRetiredToolkitOptions("clerkAuth", opts);
     // Before the Clerk client, so a malformed key fails as a connecta
     // configuration error rather than however the SDK happens to treat it.
@@ -771,6 +786,7 @@ export function clerkAuth(opts) {
     return {
         kind: "clerk",
         interactiveOperator: true,
+        ...(opts.publicUrl === undefined ? { requiresPublicUrl: true } : {}),
         recognizesCredential: (request) => {
             if (authorizationCredential(request).kind !== "absent")
                 return !isMachineCredential(request);

package/dist/auth/cloudflare-access.js

@@ -1,8 +1,9 @@
+import { Effect } from "effect";
 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";
+import { authCall, authFlow, authMethod } from "./native.js";
 function identityString(identity, field) {
     const value = identity[field];
     return typeof value === "string" && validIdentityReference({ namespace: "cloudflare-access", id: value })
@@ -15,12 +16,30 @@ function unauthorized(reason) {
         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) {
+function unavailable(problem, identityLookup) {
     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 }),
+        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,
+            ...(identityLookup ? { identityLookup } : {}),
+        }),
     };
 }
+let lookups = 0;
+let isolateCold = true;
+const lookupSettled = () => {
+    lookups--;
+};
+function lookupIdentity(access) {
+    lookups++;
+    try {
+        return Promise.resolve(access.getIdentity()).finally(lookupSettled);
+    }
+    catch (error) {
+        lookups--;
+        throw error;
+    }
+}
 /**
  * Trust the identity Cloudflare Access attached to this direct Worker
  * invocation. Access has already validated the browser session, Managed OAuth
@@ -50,16 +69,39 @@ export function cloudflareAccessAuth() {
                 if (typeof access.aud !== "string" || !/^[\x21-\x7e]{1,256}$/.test(access.aud))
                     return unavailable("access_audience_invalid");
                 let identity;
+                const started = performance.now();
+                const cold = isolateCold;
+                isolateCold = false;
+                let rejected = false;
                 try {
                     identity = (yield authCall(withAuthenticationDeadline, [
                         request,
-                        authMethod(() => {
-                            return authInvoke(access, "getIdentity", []);
-                        }),
+                        authMethod((signal) => authFlow(function* () {
+                            for (let attempt = 0;; attempt++) {
+                                signal.throwIfAborted();
+                                try {
+                                    return (yield authCall(lookupIdentity, [access]));
+                                }
+                                catch (error) {
+                                    if (attempt === 1) {
+                                        rejected = true;
+                                        throw error;
+                                    }
+                                }
+                                // Only a rejected identity lookup retries. A hung lookup never
+                                // overlaps a second one; this sleep shares the original deadline.
+                                yield Effect.sleep(100 + Math.floor(Math.random() * 151));
+                            }
+                        })),
                     ]));
                 }
                 catch {
-                    return unavailable("identity_unavailable");
+                    return unavailable("identity_unavailable", {
+                        outcome: rejected ? "rejected" : "timeout",
+                        durationMs: Math.max(0, Math.round(performance.now() - started)),
+                        cold,
+                        inFlight: lookups,
+                    });
                 }
                 // Access binds ctx.access.aud to its Worker application at the edge.
                 // Service credentials can pass that edge, but connecta machines must