@zackbart/connecta 0.40.0 → 0.41.0

package/dist/routes/activity-disclosure.js

@@ -1,3 +1,4 @@
+import { checkedActivityOperation } from "../operation-activity.js";
 import { recordedToolName } from "../operator-record.js";
 /** A recorded tool is shown only when its name passes the record grammar and its endpoint granted it. */
 function activityToolVisible(access, event) {
@@ -15,6 +16,31 @@ function activityToolVisible(access, event) {
  * pool that is no longer declared is withheld.
  */
 export function activityEventVisible(context, authz, registry, event) {
+    const pool = event.pool !== undefined ? context.opts.pools.get(event.pool) : undefined;
+    if (event.pool !== undefined && !pool)
+        return false;
+    const access = pool ? pool.access : { connectorIds: "all" };
+    if (event.kind === "operation") {
+        const operation = checkedActivityOperation(event.operation);
+        if (!operation ||
+            event.toolName !== operation.name ||
+            event.connectorId !== (operation.connectors.length === 1 ? operation.connectors[0] : "$operation"))
+            return false;
+        const ownerOnly = operation.personal ||
+            event.actorBasis === "principal" ||
+            operation.connectors.some((id) => registry.getConnector(id)?.authScope === "personal");
+        if (ownerOnly) {
+            const owner = authz.identity.principal;
+            if (!owner ||
+                event.actorBasis !== "principal" ||
+                event.actor.id !== owner.id ||
+                event.actor.namespace !== owner.namespace)
+                return false;
+        }
+        return operation.connectors.every((id) => registry.canReadConnectorSkills(id) &&
+            (access.connectorIds === "all" || access.connectorIds.includes(id)) &&
+            !access.toolAccess?.has(id));
+    }
     const connector = registry.getConnector(event.connectorId);
     if (!connector)
         return false;
@@ -26,10 +52,6 @@ export function activityEventVisible(context, authz, registry, event) {
             event.actor.namespace !== owner.namespace)
             return false;
     }
-    const pool = event.pool !== undefined ? context.opts.pools.get(event.pool) : undefined;
-    if (event.pool !== undefined && !pool)
-        return false;
-    const access = pool ? pool.access : { connectorIds: "all" };
     if (access.connectorIds !== "all" && !access.connectorIds.includes(event.connectorId))
         return false;
     // Connector-wide counts reveal tools outside an address-only grant.

package/dist/routes/activity.js

@@ -27,12 +27,13 @@ function enrichActivityActorLabels(page, auth) {
                 ...(event.actor.namespace ? { namespace: event.actor.namespace } : {}),
             };
             // Re-check stored client facts, including custom readers and old rows.
-            const { packageVersion: suppliedPackageVersion, clientName: suppliedName, clientVersion: suppliedVersion, classification: _classification, resultBytes: _resultBytes, kind: _kind, drift: _drift, pool: _pool, actorBasis: _actorBasis, ...record } = event;
+            const { packageVersion: suppliedPackageVersion, clientName: suppliedName, clientVersion: suppliedVersion, classification: _classification, resultBytes: _resultBytes, kind: _kind, drift: _drift, operation: _operation, friction: suppliedFriction, pool: _pool, actorBasis: _actorBasis, ...record } = event;
             const packageVersion = activityPackageVersion(suppliedPackageVersion);
             const clientName = activityClientFact(suppliedName, "name");
             const clientVersion = activityClientFact(suppliedVersion, "version");
             return {
                 ...record,
+                ...(event.kind !== "operation" && suppliedFriction !== undefined ? { friction: suppliedFriction } : {}),
                 ...activityBehaviorFacts(event),
                 ...(packageVersion !== undefined ? { packageVersion } : {}),
                 ...(clientName !== undefined ? { clientName } : {}),

package/dist/routes/mcp.js

@@ -1,3 +1,4 @@
+import { startTimingTrace } from "../timing-trace.js";
 import { routeNames } from "../agent-routes.js";
 import { upwardStep } from "../upward.js";
 import { bindDiscoveryEndpoint } from "../discovery-health.js";
@@ -128,7 +129,7 @@ function withMcpCors(response, request, allowedOrigin) {
         }
         headers.append("Vary", "Access-Control-Request-Headers");
     }
-    headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, Retry-After, mcp-session-id, mcp-protocol-version, Connecta-Error-Code, Connecta-Recovery");
+    headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, Retry-After, mcp-session-id, mcp-protocol-version, Connecta-Error-Code, Connecta-Recovery, Connecta-Next-Action");
     const wrapped = new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
@@ -359,10 +360,11 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             // A request-local server cannot publish catalog changes. Set this before
             // tool registration, whose SDK default otherwise advertises listChanged.
             capabilities: { tools: { listChanged: false }, extensions: { "io.modelcontextprotocol/skills": {} } },
-            // Instructions differ per endpoint only by the admitted pool's
-            // description. Every cache hint below is private, so a client keeps
+            // Instructions reflect the admitted pool and effective write policy. Every cache hint below is private, so a client keeps
             // what it learned per endpoint URL and never shares it across them.
-            instructions: endpointInstructions(pool !== undefined ? opts.pools.get(pool)?.description : undefined, native),
+            instructions: endpointInstructions(pool !== undefined ? opts.pools.get(pool)?.description : undefined, native, readOnly ||
+                (registry.listConnectors().length > 0 &&
+                    registry.listConnectors().every((connector) => connector.readOnly === true))),
             inputRequired: { legacyShim: false },
             requestState: { verify: (state, context) => authElicitation.verify(state, context) },
             cacheHints: {
@@ -378,6 +380,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             ? {
                 sink: opts.config.activity?.store,
                 recordTool: opts.config.activity?.recordTool,
+                recordOperation: opts.config.activity?.recordOperation,
                 actor,
                 ...(principalActor ? { principalActor } : {}),
                 requestId: crypto.randomUUID(),
@@ -635,16 +638,22 @@ export function createMcpRoute(opts) {
         request.signal.addEventListener("abort", onCallerAbort, { once: true });
         if (request.signal.aborted)
             onCallerAbort();
+        const finishTiming = startTimingTrace(requestScope, opts.config.timingTraceSampleRate, opts.config.logger);
         let deadlineTimer;
         return scopedToBody(Effect.gen(function* () {
             yield* Effect.addFinalizer(() => Effect.sync(() => {
-                requestOwner(requestScope).close();
-                if (!localAbort.signal.aborted) {
-                    localAbort.abort(request.signal.reason ?? new Error("MCP request ended."));
+                try {
+                    requestOwner(requestScope).close();
+                }
+                finally {
+                    finishTiming?.();
+                    if (!localAbort.signal.aborted) {
+                        localAbort.abort(request.signal.reason ?? new Error("MCP request ended."));
+                    }
+                    request.signal.removeEventListener("abort", onCallerAbort);
+                    if (deadlineTimer !== undefined)
+                        clearTimeout(deadlineTimer);
                 }
-                request.signal.removeEventListener("abort", onCallerAbort);
-                if (deadlineTimer !== undefined)
-                    clearTimeout(deadlineTimer);
             }));
             // A request naming `subscriptions/listen` defers its permit: nothing of
             // its body is read until auth and endpoint admission pass, and then at
@@ -652,7 +661,9 @@ export function createMcpRoute(opts) {
             // modern listen goes without a permit; trusting the header alone would
             // let a legacy tools/call bypass the pool, so anything else takes one
             // after classification. Every other request takes its permit here,
-            // before auth, and no body is read before auth on any path.
+            // before auth, and this route reads no body before auth on any path.
+            // The Node adapter has already buffered up to its own pre-auth cap
+            // (`listen`'s `maxBodyBytes`) before a request reaches core.
             const startedAt = Date.now();
             const maxDurationMs = opts.requestAdmission.maxDurationMs;
             const listenHeader = request.method === "POST" && request.headers.get("Mcp-Method") === "subscriptions/listen";
@@ -766,8 +777,12 @@ export function createMcpRoute(opts) {
                     const headers = new Headers(response.headers);
                     headers.set("Connecta-Error-Code", "host_auth_required");
                     headers.set("Connecta-Recovery", "host_connection");
-                    // Custom adapters may own a streaming or non-JSON response. Preserve
-                    // that body and its request lifetime, and carry recovery in headers.
+                    headers.set("Connecta-Next-Action", JSON.stringify({
+                        action: "reconnect_host",
+                        purpose: "Reconnect the host with valid inbound credentials and endpoint grants; downstream OAuth cannot repair this connection.",
+                    }));
+                    // Custom adapters own their response stream and request lifetime.
+                    // Their typed recovery is carried in headers instead of replacing it.
                     if (!response.headers.get("Content-Type")?.includes("application/json")) {
                         return cors(new Response(response.body, { status: response.status, headers }));
                     }
@@ -780,6 +795,10 @@ export function createMcpRoute(opts) {
                             message: "The host is not authorized to connect to this endpoint. Sign in or update the host's connecta access token and endpoint grants.",
                             retryable: false,
                             recovery: "host_connection",
+                            nextAction: {
+                                action: "reconnect_host",
+                                purpose: "Reconnect this host to Connecta with valid inbound credentials and endpoint grants. Downstream connector authorization cannot repair the host connection.",
+                            },
                         },
                     })), { status: response.status, headers }));
                 }

package/dist/routes/ui-config.js

@@ -171,7 +171,7 @@ export function scanOperatorActivity(context, authz, registry, rows, agents) {
                         continue;
                     // A last call is a call; any row recorded for an agent, a catalog
                     // refresh included, is a sign it was seen.
-                    const row = event.kind !== "catalog_drift" && OUTCOMES.has(event.outcome) ? byId.get(event.connectorId) : undefined;
+                    const row = event.kind === undefined && OUTCOMES.has(event.outcome) ? byId.get(event.connectorId) : undefined;
                     const agent = (event.actor.kind === "access_token" || event.actor.kind === "vercel_oidc") &&
                         event.actor.namespace === AGENT_NAMESPACE &&
                         event.actor.id

package/dist/routes/ui-data.js

@@ -249,6 +249,7 @@ export function uiData(registry, baseUrl, options) {
                     toolCount,
                     observedAt: Date.now(),
                 }));
+            const observedAgeMs = observation ? Math.max(0, Date.now() - observation.observedAt) : undefined;
             return {
                 id: c.id,
                 authScope: c.authScope ?? "shared",
@@ -271,9 +272,9 @@ export function uiData(registry, baseUrl, options) {
                     ...(status.registrationPath ? { auth: { registrationPath: status.registrationPath } } : {}),
                     catalogAgeMs: registry.catalogAgeMs(c.id),
                     lastCall: null,
-                    ...(observation ? { observedAgeMs: Math.max(0, Date.now() - observation.observedAt) } : {}),
+                    ...(observedAgeMs !== undefined ? { observedAgeMs } : {}),
                 },
-                ...(observation ? { observedAgeMs: Math.max(0, Date.now() - observation.observedAt) } : {}),
+                ...(observedAgeMs !== undefined ? { observedAgeMs } : {}),
                 // Counts only, and only when a refresh in this runtime produced them.
                 // `Registry.withCatalogObservations` rebuilt the report through
                 ...(status.catalogAccess ? { catalogAccess: status.catalogAccess } : {}),

package/dist/runtime/native-storage.js

@@ -25,6 +25,11 @@ export function registerNativeStorage(edge, native) {
     storageMethods.set(edge, own);
     const getMany = native.getMany;
     storage.set(edge, {
+        catalogSnapshot: native.catalogSnapshot
+            ? (keys, generationKey, prefix, suffixes) => typed(() => getNativeStorage(edge)
+                ? native.catalogSnapshot(keys, generationKey, prefix, suffixes)
+                : Effect.succeed(new Map()))
+            : undefined,
         accessToken: native.accessToken
             ? (hash) => typed(() => (getNativeStorage(edge) ? native.accessToken(hash) : Effect.succeed(undefined)))
             : undefined,
@@ -37,6 +42,13 @@ export function registerNativeStorage(edge, native) {
                     : Effect.forEach(keys, (key) => current(edge, "get", own.get, [key], () => native.get(key)))),
             }
             : {}),
+        ...(native.setMany
+            ? {
+                setMany: (entries, options) => typed(() => getNativeStorage(edge)
+                    ? native.setMany(entries, options)
+                    : Effect.asVoid(Effect.forEach(entries, ([key, value]) => current(edge, "set", own.set, [key, value, options], () => native.set(key, value, options))))),
+            }
+            : {}),
         set: (key, value, options) => current(edge, "set", own.set, [key, value, options], () => native.set(key, value, options)),
         delete: (key) => current(edge, "delete", own.delete, [key], () => native.delete(key)),
         list: (prefix) => current(edge, "list", own.list, [prefix], () => native.list(prefix)),

package/dist/runtime/request-reads.js

@@ -1,3 +1,4 @@
+import { utf8Length } from "../bytes.js";
 // Request-scoped memo of storage reads (INV-7).
 //
 // One request often reads the same key many times: a catalog listing reads its
@@ -36,6 +37,7 @@
 // `FinalizationRegistry` (workerd before compatibility date 2025-05-05 without
 // `enable_weak_ref`) memoizes nothing: every read goes to storage.
 import { Effect } from "effect";
+import { getNativeStorage } from "./native-storage.js";
 const roots = new WeakMap();
 const observed = new WeakMap();
 /**
@@ -88,7 +90,7 @@ export function observeStorageWrites(storage, layer) {
     return storage;
 }
 /** The underlying store and key a read of `key` reaches, when every layer is observed. */
-function physical(storage, key) {
+export function physicalStorageAddress(storage, key) {
     const entry = observed.get(storage);
     if (!entry)
         return undefined;
@@ -99,10 +101,17 @@ function physical(storage, key) {
         own.list !== storage.list ||
         own.compareAndSet !== storage.compareAndSet)
         return undefined;
-    return "root" in layer ? { store: layer.root, key } : physical(layer.storage, layer.prefix + key);
+    return "root" in layer ? { store: layer.root, key } : physicalStorageAddress(layer.storage, layer.prefix + key);
 }
 const weakReferences = () => typeof WeakRef === "function" && typeof FinalizationRegistry === "function";
 export class RequestReads {
+    trace;
+    constructor(trace) {
+        this.trace = trace;
+    }
+    note(fresh, hit, value, started) {
+        this.trace?.record(fresh ? "memo.fresh" : hit ? "memo.hit" : "memo.miss", performance.now() - started, value === null ? 0 : utf8Length(value), 0, value === null ? 1 : 0);
+    }
     closed = false;
     stores = new Map();
     ref = weakReferences() ? new WeakRef(this) : undefined;
@@ -129,7 +138,7 @@ export class RequestReads {
     }
     /** A memoized answer, or how to record the value a storage read returns. */
     lookup(storage, key, fresh) {
-        const address = this.closed || !this.ref ? undefined : physical(storage, key);
+        const address = this.closed || !this.ref ? undefined : physicalStorageAddress(storage, key);
         if (!address)
             return undefined;
         const entries = this.entriesFor(address.store);
@@ -155,31 +164,70 @@ export class RequestReads {
     read(storage, key, load, fresh = false) {
         return Effect.suspend(() => {
             const found = this.lookup(storage, key, fresh);
-            if (!found)
+            if (!found && !this.trace)
                 return load;
-            if (found.hit)
+            const started = this.trace ? performance.now() : 0;
+            if (found?.hit) {
+                if (this.trace)
+                    this.note(fresh, true, found.value, started);
                 return Effect.succeed(found.value);
-            return Effect.tap(load, (value) => Effect.sync(() => found.record(value)));
+            }
+            return Effect.tap(load, (value) => Effect.sync(() => {
+                found?.record(value);
+                if (this.trace)
+                    this.note(fresh, false, value, started);
+            }));
         });
     }
     /** Prefetch only keys whose callers already permit request-local staleness. */
-    prefetch(requests, load) {
+    prefetch(requests, load, linked) {
         return Effect.suspend(() => {
             const pending = requests.map(({ storage, key }) => ({
-                address: physical(storage, key),
+                address: physicalStorageAddress(storage, key),
                 found: this.lookup(storage, key, false),
             }));
+            if (this.trace)
+                for (const { found } of pending)
+                    if (found?.hit)
+                        this.note(false, true, found.value, performance.now());
+            const started = this.trace ? performance.now() : 0;
             const root = pending[0]?.address?.store;
             const storage = root && roots.get(root);
             if (!storage || pending.some(({ address, found }) => !found || address?.store !== root))
                 return Effect.void;
+            if (pending.every(({ found }) => found?.hit))
+                return Effect.void;
+            const generation = linked && physicalStorageAddress(linked.storage, linked.generationKey);
+            const prefix = linked && physicalStorageAddress(linked.storage, linked.prefix);
+            const snapshot = getNativeStorage(storage)?.catalogSnapshot;
+            if (linked && snapshot && generation?.store === root && prefix?.store === root) {
+                // Candidates only locate entries. An intervening external write can make
+                // these stale, so consumers retain the separate post-chunk primary fence.
+                return Effect.map(snapshot(pending.map(({ address }) => address.key), generation.key, prefix.key, linked.suffixes), (values) => {
+                    pending.forEach(({ address, found }) => {
+                        if (found && !found.hit)
+                            found.record(values.get(address.key) ?? null);
+                    });
+                    for (const [key, value] of values) {
+                        if (pending.some(({ address }) => address.key === key))
+                            continue;
+                        const found = this.lookup(storage, key, false);
+                        if (found && !found.hit)
+                            found.record(value);
+                    }
+                });
+            }
             const misses = pending.filter(({ found }) => found && !found.hit);
             if (!misses.length)
                 return Effect.void;
             return Effect.map(load(storage, misses.map(({ address }) => address.key)), (values) => {
                 misses.forEach(({ found }, i) => {
-                    if (found && !found.hit)
-                        found.record(values[i] ?? null);
+                    if (found && !found.hit) {
+                        const value = values[i] ?? null;
+                        found.record(value);
+                        if (this.trace)
+                            this.note(false, false, value, started);
+                    }
                 });
             });
         });
@@ -187,12 +235,16 @@ export class RequestReads {
     /** `read` for a Promise-shaped caller, without another Effect edge. */
     async readPromise(storage, key, load, fresh = false) {
         const found = this.lookup(storage, key, fresh);
-        if (!found)
-            return load();
-        if (found.hit)
+        const started = this.trace ? performance.now() : 0;
+        if (found?.hit) {
+            if (this.trace)
+                this.note(fresh, true, found.value, started);
             return found.value;
+        }
         const value = await load();
-        found.record(value);
+        found?.record(value);
+        if (this.trace)
+            this.note(fresh, false, value, started);
         return value;
     }
     close() {

package/dist/runtime/request-scope.js

@@ -1,3 +1,4 @@
+import { traceFor } from "../timing-trace.js";
 // One owner per existing upstream request identity. Facts survive revocation;
 // retaining them never reconstitutes a call capability or a live operation.
 import { Context, Exit, Scope } from "effect";
@@ -71,7 +72,7 @@ export function requestReads(identity) {
 export function ownerReads(owner) {
     const retained = owner.retained;
     if (!retained.reads) {
-        retained.reads = new RequestReads();
+        retained.reads = new RequestReads(traceFor(owner.identity));
         if (!owner.open)
             retained.reads.close();
     }

package/dist/skill-origin.js

@@ -0,0 +1,16 @@
+/**
+ * The fixed sentence that marks downstream guidance as third-party. A prefix has
+ * no closing delimiter to forge, and connector IDs are deployment-authored.
+ */
+export function downstreamOrigin(connectorId) {
+    return `Third-party guidance from connector ${JSON.stringify(connectorId.slice(0, 128))}.`;
+}
+/** Downstream description text on one line, so it cannot begin a new listing entry. */
+export function labeledDownstreamDescription(connectorId, description) {
+    return `${downstreamOrigin(connectorId)} ${description.replace(/\s+/g, " ").trim()}`;
+}
+const SKILL_RESOURCE = /^skill:\/\/|\/SKILL\.md(?:[?#]|$)/i;
+/** Whether a downstream resource URI addresses skill instructions rather than ordinary data. */
+export function isSkillResource(uri) {
+    return SKILL_RESOURCE.test(uri);
+}