@zackbart/connecta 0.40.0 → 0.41.0

package/dist/skills.js

@@ -5,11 +5,15 @@ import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authMethod, registerAuth, registerAuthMethod, authOwnMethod, } from "./auth/native.js";
 import { USAGE_SKILL } from "./usage-guide.js";
+import { downstreamOrigin, labeledDownstreamDescription } from "./skill-origin.js";
 import { boundedEchoText, ConnectorCallError } from "./errors.js";
 import { Effect } from "effect";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { closeScopeOnExit } from "./runtime/connector-scope.js";
 import { sentSecretsForRequest } from "./sent-secrets.js";
+/** Trusted diagnostics constructed from the caller-visible local registry. */
+export class SkillLookupError extends ConnectorCallError {
+}
 // The meta instructions and built-in guides use the meta names: built-in guides
 // are byte-identical across deployments, and the eval code arm replaces usage.
 const ROUTE = `Choose a route before discovery. One known-address read uses ${META_ROUTES.read}; one known-address write uses ${META_ROUTES.write}. Unknown-address read-only work starts with ${META_ROUTES.program} to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.`;
@@ -20,22 +24,36 @@ const RECOVERY = `When an auth error includes a handoff, give it to the user or
  * and the client owns approval; a read-only one omits write tools from search
  * and describe and refuses every write call. Guides may still name them.
  */
-export const CONNECTA_INSTRUCTIONS = `${ROUTE} On a writable endpoint, programs and ${META_ROUTES.write} may write. On a read-only endpoint, search omits write tools and every write call is refused; guides may still name them. The ${META_ROUTES.program} description says which this endpoint is. Never repeat a write to recover its output. ${RECOVERY}`;
+function writePolicy(readOnly, routes) {
+    return readOnly
+        ? "This endpoint can't perform writes; guide steps that change data will be refused. No write route exists on this endpoint."
+        : `This endpoint permits writes through ${routes.write}${routes.program === META_ROUTES.program ? ` and ${routes.program}` : ""}, subject to connector restrictions; the host owns approval.`;
+}
+export const CONNECTA_INSTRUCTIONS = `${ROUTE} ${writePolicy(false, META_ROUTES)} Never repeat a write to recover its output. ${RECOVERY}`;
 /**
- * The instructions one endpoint serves: {@link CONNECTA_INSTRUCTIONS}, then
- * the admitted pool's `description` after a fixed lead-in. Plain `/mcp` and a
+ * The instructions one endpoint serves: pool scope and guide pointer first,
+ * then stable routing rules. Plain `/mcp` and a
  * pool without a description serve the constant unchanged. The description
  * comes from deployment config for the pool the request was admitted through;
  * nothing a request sends reaches it.
  */
-export function endpointInstructions(description, native) {
-    const instructions = native ? nativeInstructions(native.executeCode) : CONNECTA_INSTRUCTIONS;
-    return description === undefined ? instructions : `${instructions} This endpoint: ${description}`;
+export function endpointInstructions(description, native, readOnly = false) {
+    const instructions = native
+        ? nativeInstructions(native.executeCode, readOnly)
+        : readOnly
+            ? `Choose a route before discovery. One known read uses ${META_ROUTES.read}; other read work uses ${META_ROUTES.program} to discover, call and return the answer. ${writePolicy(true, META_ROUTES)} Never repeat a write for output. ${RECOVERY}`
+            : CONNECTA_INSTRUCTIONS;
+    if (description === undefined)
+        return instructions;
+    const routing = native
+        ? instructions
+        : `Known read: ${META_ROUTES.read}${readOnly ? "" : `; known write: ${META_ROUTES.write}`}. Other work: ${META_ROUTES.program}; discover and call together, return answers, sample unfamiliar reads. ${writePolicy(readOnly, META_ROUTES)} Never repeat writes for output. Give auth handoffs to user/operator; ${META_ROUTES.authorize} refreshes links. Page resultId/format:"paged" with connecta.result(handleOrId,{page?}).`;
+    return `Use skills. ${description} ${routing}`;
 }
 /** Instructions for pools whose host searches the listed native tools. */
-export function nativeInstructions(executeCode) {
+export function nativeInstructions(executeCode, readOnly = false) {
     const routes = routeNames(executeCode ? "native-code" : "native");
-    return `Each tool here is one operation; annotations classify reads/writes. Call known tools directly; ${executeCode ? `combine work in ${routes.program} using the program addresses in tool descriptions.` : "find tools with your host's search."} Read-only endpoints omit and refuse writes. Never repeat a write for output. Give auth handoffs to the user/operator. Tools missing? Call authorize_connector; after repair, reconnect to refresh your list. Follow nextAction to page with ${executeCode ? `connecta.result in ${routes.program}` : "read_result"}. ${routes.skills} lists guidance.`;
+    return `Annotations classify reads/writes. Call known tools directly; ${executeCode ? `combine work in ${routes.program} using tool descriptions’ program addresses.` : "find tools with your host's search."} ${writePolicy(readOnly, routes)} Never repeat a write for output. Give auth handoffs to the user/operator. Tools missing? Ask the operator to repair, then reconnect. Follow nextAction to page with ${executeCode ? `connecta.result in ${routes.program}` : "read_result"}. ${routes.skills} lists guidance.`;
 }
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
@@ -104,7 +122,7 @@ export function connectorGuide(connector) {
     if (!content || content.trim() === "")
         return undefined;
     return connector.readOnly === true
-        ? `Read-only connection: only read-classified tools are available. Write calls are refused, including tools named in this guide.\n\n${content}`
+        ? `This connection can't perform writes; guide steps that change data will be refused. No write route exists for this connection.\n\n${content}`
         : content;
 }
 /** Discovery budget for one connector-guide summary, including an ellipsis. */
@@ -342,45 +360,103 @@ function localRecord(name, uri, description, content, aliases) {
 function validSkillName(name) {
     return name.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
 }
-function localRecords(connectors) {
-    return runEdge(localRecordsNative(connectors));
+/** Resolve guide names once from the admitted connector roster, including collisions. */
+export function resolvedConnectorGuides(connectors) {
+    return runEdge(resolvedConnectorGuidesNative(connectors));
+}
+const resolvedConnectorGuidesNative = /* @__PURE__ */ registerAuth(resolvedConnectorGuides, function (connectors) {
+    return authFlow(function* () {
+        const allocated = new Set(connectors.map((connector) => connector.id));
+        return yield* upwardStep(Effect.forEach(connectors
+            .filter((connector) => connectorGuide(connector) !== undefined)
+            .sort((a, b) => Number(connectorGuideRequired(b)) - Number(connectorGuideRequired(a)) ||
+            (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)), (connector) => authFlow(function* () {
+            const digest = validSkillName(connector.id)
+                ? ""
+                : bytesToHex(new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", encoder.encode(connector.id)]))));
+            const legacy = `connector-${digest.slice(0, 48)}`;
+            const slug = connector.id
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "")
+                .slice(0, 42)
+                .replace(/-$/g, "") || "connector";
+            let name = connector.id;
+            if (!validSkillName(name)) {
+                const base = `${slug}-${digest.slice(0, 12)}`;
+                name = base;
+                let suffix = 1;
+                while (allocated.has(name))
+                    name = `${base}-${suffix++}`;
+                allocated.add(name);
+            }
+            return {
+                connector,
+                name,
+                legacy,
+                reference: AVAILABLE_SKILLS.some((skill) => skill.name === name)
+                    ? `skill://connecta/connectors/${name}`
+                    : name,
+            };
+        }), { concurrency: 1 }));
+    });
+});
+function localRecords(connectors, readOnly = false) {
+    return runEdge(localRecordsNative(connectors, readOnly));
 }
-const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (connectors) {
+const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (connectors, readOnly = false) {
     return authFlow(function* () {
         const builtIns = AVAILABLE_SKILLS.map((skill) => localRecord(skill.name, `skill://connecta/${skill.name}/SKILL.md`, skill.description, skill.content(), [
             skill.name,
             `skill://connecta/${skill.name}`,
         ]));
-        const guides = yield* upwardStep(Effect.forEach(connectors
-            .filter((connector) => connectorGuide(connector) !== undefined)
-            .sort((a, b) => Number(connectorGuideRequired(b)) - Number(connectorGuideRequired(a)) ||
-            (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)), (connector) => authFlow(function* () {
-            const name = validSkillName(connector.id)
-                ? connector.id
-                : `connector-${bytesToHex(new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", encoder.encode(connector.id)])))).slice(0, 48)}`;
+        const identities = yield* upwardStep(authCall(resolvedConnectorGuides, [
+            connectors,
+        ]));
+        const guides = identities.map(({ connector, name, legacy }) => {
             const description = connectorGuideSummary(connector);
             const root = `skill://connecta/connectors/${encodeURIComponent(name)}`;
-            const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${connectorGuide(connector)}`;
+            const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${readOnly ? `${writePolicy(true, META_ROUTES)}\n\n` : ""}${connectorGuide(connector)}`;
             return {
                 ...localRecord(name, `${root}/SKILL.md`, description, content, [
                     connectorSkillName(connector.id),
+                    ...(connector.id.includes(":") ? [] : [connector.id]),
+                    ...(name !== connector.id
+                        ? [legacy, `skill://connecta/connectors/${legacy}`, `skill://connecta/connectors/${legacy}/SKILL.md`]
+                        : []),
                     `skill://connecta/connectors/${encodeURIComponent(connector.id)}`,
                     root,
                 ]),
                 connector,
             };
-        }), { concurrency: "unbounded" }));
+        });
         if (new Set(guides.map((guide) => guide.entry.uri)).size !== guides.length)
             throw new ConnectorCallError("unavailable", "Connector skill slugs collide.");
         return [builtIns[0], ...guides, ...builtIns.slice(1)];
     });
 });
-/** `granola` names connector granola's guide; built-in names and URIs never do. */
-function bareConnectorGuide(records, name) {
-    if (name.includes(":") || AVAILABLE_SKILLS.some((skill) => skill.name === name))
-        return undefined;
-    const alias = connectorSkillName(name);
-    return records.find((record) => record.connector !== undefined && record.aliases.includes(alias));
+/** Canonical identities win; an alias shared by different guides is ambiguous. */
+function localLookup(records, key) {
+    const canonical = new Map();
+    for (const record of records) {
+        canonical.set(record.entry.uri, record);
+        canonical.set(record.entry.uri.slice(0, -"/SKILL.md".length), record);
+        const name = record.entry.frontmatter.name;
+        if (!record.connector || !AVAILABLE_SKILLS.some((skill) => skill.name === name))
+            canonical.set(name, record);
+    }
+    const aliases = new Map();
+    for (const record of records) {
+        for (const alias of record.aliases) {
+            if (canonical.has(alias))
+                continue;
+            aliases.set(alias, aliases.has(alias) && aliases.get(alias) !== record ? null : record);
+        }
+    }
+    const result = canonical.get(key) ?? aliases.get(key);
+    if (result === null)
+        throw new ConnectorCallError("invalid_args", "Ambiguous skill alias; use its canonical URI.");
+    return result;
 }
 /** Keep the downstream path tree, so relative supporting-file references still resolve. */
 export function downstreamSkillUri(connectorId, uri) {
@@ -485,6 +561,7 @@ export class SkillsRegistry {
     baseUrl;
     options;
     scope;
+    cacheHints;
     local;
     snapshot;
     constructor(registry, baseUrl, options = {}) {
@@ -493,7 +570,11 @@ export class SkillsRegistry {
         this.options = options;
         void SkillsRegistry.nativePrograms;
         this.scope = options.requestScope ?? {};
-        this.local = authCall(localRecords, [registry.listConnectors()]);
+        this.cacheHints = {
+            ...PRIVATE,
+            ttlMs: registry.listConnectors().some((connector) => connector.downstreamSkills !== undefined) ? 0 : 300_000,
+        };
+        this.local = authCall(localRecords, [registry.listConnectors(), options.readOnly === true]);
     }
     operation(connector, read) {
         return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "operation", [connector, read]));
@@ -547,7 +628,7 @@ export class SkillsRegistry {
             : name.startsWith(CONNECTOR_SKILL_PREFIX)
                 ? `Unknown connector "${boundedEchoText(id)}".`
                 : `Unknown skill "${boundedEchoText(name)}".`;
-        return new ConnectorCallError("not_found", `${message} Available skills: ${available}.`);
+        return new SkillLookupError("not_found", `${message} Available skills: ${available}.`);
     }
     list(cursor) {
         return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "list", [cursor]));
@@ -574,7 +655,9 @@ export class SkillsRegistry {
                 return (yield* upwardStep(authInvoke(self, "records", []))).map((record) => ({
                     name: record.aliases[0] ?? record.entry.uri,
                     uri: record.entry.uri,
-                    description: String(record.entry.frontmatter.description),
+                    description: record.files
+                        ? labeledDownstreamDescription(record.connector.id, String(record.entry.frontmatter.description))
+                        : String(record.entry.frontmatter.description),
                 }));
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
         }, SkillsRegistry.prototype.summaries);
@@ -583,10 +666,12 @@ export class SkillsRegistry {
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
                 const record = yield* upwardStep(authInvoke(self, "lookup", [name]));
                 const content = (yield* upwardStep(authInvoke(self, "read", [record.entry.uri]))).contents[0];
+                const origin = record.files ? `${downstreamOrigin(record.connector.id)}\n\n` : "";
                 if (typeof content.text === "string")
-                    return content.text;
+                    return origin + content.text;
                 try {
-                    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(atob(content.blob), (char) => char.charCodeAt(0)));
+                    return (origin +
+                        new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(atob(content.blob), (char) => char.charCodeAt(0))));
                 }
                 catch {
                     throw new ConnectorCallError("unavailable", "Skill instructions are not UTF-8 text.");
@@ -596,7 +681,7 @@ export class SkillsRegistry {
         registerAuthMethod(SkillsRegistry.prototype, "read", function (uri) {
             const self = this;
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
-                const local = (yield* upwardStep(self.local)).find((record) => record.entry.uri === uri || record.aliases.includes(uri));
+                const local = localLookup(yield* upwardStep(self.local), uri);
                 if (local) {
                     const record = yield* upwardStep(authCall(withManifest, [local]));
                     self.assertSafe([record]);
@@ -606,7 +691,7 @@ export class SkillsRegistry {
                     const text = record.connector
                         ? sentSecretsForRequest(self.scope).redact(record.content)
                         : record.content;
-                    return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
+                    return { ...self.cacheHints, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
                 }
                 if (!uri.startsWith("skill://downstream/"))
                     throw self.missing(uri);
@@ -642,7 +727,7 @@ export class SkillsRegistry {
                 self.options.onRead?.(record.connector, "downstream");
                 // Downstream file contents take the request's full payload rules before any reader sees them.
                 const clean = sentSecretsForRequest(self.scope).redact(content);
-                return { ...PRIVATE, contents: [{ ...clean, uri }] };
+                return { ...self.cacheHints, contents: [{ ...clean, uri }] };
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
         }, SkillsRegistry.prototype.read);
         registerAuthMethod(SkillsRegistry.prototype, "resources", function (cursor) {
@@ -650,7 +735,7 @@ export class SkillsRegistry {
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
                 const page = yield* upwardStep(authInvoke(self, "list", [cursor]));
                 return {
-                    ...PRIVATE,
+                    ...self.cacheHints,
                     resources: page.skills.flatMap((skill) => (skill.resources === "dynamic" ? [{ uri: skill.uri }] : skill.resources).map((file) => ({
                         uri: file.uri,
                         name: file.uri === skill.uri
@@ -668,7 +753,10 @@ export class SkillsRegistry {
         registerAuthMethod(SkillsRegistry.prototype, "get", function (uri) {
             const self = this;
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
-                return { ...PRIVATE, skill: (yield* upwardStep(authInvoke(self, "lookup", [uri]))).entry };
+                return {
+                    ...self.cacheHints,
+                    skill: (yield* upwardStep(authInvoke(self, "lookup", [uri]))).entry,
+                };
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
         }, SkillsRegistry.prototype.get);
         registerAuthMethod(SkillsRegistry.prototype, "list", function (cursor) {
@@ -679,7 +767,7 @@ export class SkillsRegistry {
                 if (!Number.isSafeInteger(offset) || offset % SKILL_PAGE_SIZE !== 0 || offset >= records.length)
                     throw new ConnectorCallError("invalid_args", "Invalid skills cursor.");
                 return {
-                    ...PRIVATE,
+                    ...self.cacheHints,
                     skills: records.slice(offset, offset + SKILL_PAGE_SIZE).map((record) => record.entry),
                     ...(offset + SKILL_PAGE_SIZE < records.length
                         ? { nextCursor: `skills:${offset + SKILL_PAGE_SIZE}` }
@@ -691,8 +779,7 @@ export class SkillsRegistry {
             const self = this;
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
                 const records = yield* upwardStep(self.local);
-                const local = records.find((record) => record.entry.uri === uri || record.aliases.includes(uri)) ??
-                    bareConnectorGuide(records, uri);
+                const local = localLookup(records, uri);
                 if (local) {
                     const record = yield* upwardStep(authCall(withManifest, [local]));
                     self.assertSafe([record]);
@@ -791,9 +878,11 @@ export class SkillsRegistry {
                     ...(self.options.defer ? { defer: self.options.defer } : {}),
                 });
                 yield* closeScopeOnExit(connector, ctx, self.options.defer);
-                return yield* authCall(read, [ctx]).pipe(Effect.mapError((error) => error instanceof ConnectorCallError && error.code === "auth_required"
-                    ? new ConnectorCallError("auth_required", "Downstream skills require authorization.")
-                    : new ConnectorCallError("unavailable", "Downstream skills are unavailable.")));
+                return yield* authCall(read, [ctx]).pipe(Effect.mapError((error) => error instanceof ConnectorCallError && error.code === "unsupported_capability"
+                    ? new ConnectorCallError("unsupported_capability", "Downstream Skills capability is not supported.", { retryable: false })
+                    : error instanceof ConnectorCallError && error.code === "auth_required"
+                        ? new ConnectorCallError("auth_required", "Downstream skills require authorization.")
+                        : new ConnectorCallError("unavailable", "Downstream skills are unavailable.")));
             })), {
                 timeoutMs,
                 ...(self.options.requestSignal ? { signal: self.options.requestSignal } : {}),

package/dist/storage/d1-driver.js

@@ -1,15 +1,43 @@
+import { Effect, Option } from "effect";
+import { RequestScope } from "../runtime/request-scope.js";
+import { hasTimingTraces, traceFor } from "../timing-trace.js";
+import { utf8Length } from "../bytes.js";
+// Request-wide totals include admission, credentials and catalog work. These
+// I/O-spanning observations are not pure storage latency or CPU attribution.
+function timedD1(family, statements, operation) {
+    return Effect.suspend(() => {
+        if (!hasTimingTraces())
+            return operation;
+        return Effect.flatMap(Effect.serviceOption(RequestScope), (owner) => {
+            const trace = Option.isSome(owner) ? traceFor(owner.value.identity) : undefined;
+            if (!trace)
+                return operation;
+            const start = performance.now();
+            let bytes = 0;
+            return operation.pipe(Effect.tap((value) => Effect.sync(() => {
+                // Count serialized application result bytes, not D1 wire bytes.
+                try {
+                    bytes = utf8Length(JSON.stringify(value) ?? "");
+                }
+                catch {
+                    /* no payload retained */
+                }
+            })), Effect.ensuring(Effect.sync(() => trace.record(family, performance.now() - start, bytes, statements))));
+        });
+    });
+}
 import { effectSqlDriver, sqlDriverEdge, sqlPromise } from "./sql-driver.js";
 export function d1Driver(db) {
     const prepare = (statement) => statement.params.length > 0 ? db.prepare(statement.sql).bind(...statement.params) : db.prepare(statement.sql);
     return sqlDriverEdge(effectSqlDriver({
-        all: (statement) => sqlPromise(() => prepare(statement)
+        all: (statement) => timedD1("d1.read", 1, sqlPromise(() => prepare(statement)
             .all()
-            .then((result) => result.results)),
-        run: (statement) => sqlPromise(() => prepare(statement)
+            .then((result) => result.results))),
+        run: (statement) => timedD1("d1.write", 1, sqlPromise(() => prepare(statement)
             .run()
-            .then((result) => result.meta.changes ?? 0)),
+            .then((result) => result.meta.changes ?? 0))),
         // D1's public binding API preserves per-statement changes, including zero;
         // execute the whole array once. No withTransaction, RETURNING, or replay.
-        batch: (statements) => sqlPromise(() => db.batch(statements.map(prepare)).then((results) => results.map((result) => result.meta.changes ?? 0))),
+        batch: (statements) => timedD1("d1.batch", statements.length, sqlPromise(() => db.batch(statements.map(prepare)).then((results) => results.map((result) => result.meta.changes ?? 0)))),
     }));
 }

package/dist/storage/keys.js

@@ -176,6 +176,8 @@ export const connectorHealthKeys = {
     discovery: (connectorId, partitionDigest) => validateStorageKey(`connector-health:v1:${connectorId}:${partitionDigest}:discovery`),
     status: (connectorId, partitionDigest) => validateStorageKey(`connector-health:v1:${connectorId}:${partitionDigest}:status`),
 };
+const responseCacheLocatorPrefix = (id, config) => validateStorageKey(`response-cache:v1:${id}:${config}:`);
+const responseCacheLocatorSeparator = ":";
 /**
  * SDK catalog response cache, complete manifests published after their chunks.
  * Secret-bearing inputs reach these keys only through `secretDigest`.
@@ -195,7 +197,11 @@ export const responseCacheKeys = {
     },
     prefix: (id) => validateStorageKey(`response-cache:v1:${id}:`),
     generation: (id) => validateStorageKey(`response-cache:v1:${id}:generation`),
-    namespace: (id, config, generation) => validateStorageKey(`response-cache:v1:${id}:${config}:${generation}:`),
+    namespace: (id, config, generation) => validateStorageKey(`${responseCacheLocatorPrefix(id, config)}${generation}${responseCacheLocatorSeparator}`),
+    /** SQL binds these layout parts around the stored generation; it owns no delimiters. */
+    locatorPrefix: responseCacheLocatorPrefix,
+    locatorSeparator: responseCacheLocatorSeparator,
+    locatedEntry: (prefix, generation, partition) => validateStorageKey(`${prefix}${generation}${responseCacheLocatorSeparator}${partition}`),
     entry: (namespace, partition) => validateStorageKey(`${namespace}${partition}`),
     refreshDigest: (id, config, partition) => validateStorageKey(`response-cache:v1:${id}:refresh-digest:${config}:${partition}`),
     chunk: (entry, revision, index) => validateStorageKey(`${entry}:chunk:${revision}:${index}`),

package/dist/storage/sql-native.js

@@ -27,7 +27,7 @@ import { Effect } from "effect";
 import { activityBehaviorFacts, activityPackageVersion, activityClientFact, InvalidActivityCursorError, } from "../activity.js";
 import { assertKnownOptions, ConfigError, keys, optionsOf } from "../config-schema.js";
 import { agentFrictionForCode } from "../activity-friction.js";
-import { accessTokenKeys, validateStorageKey } from "./keys.js";
+import { accessTokenKeys, responseCacheKeys, validateStorageKey } from "./keys.js";
 const sql = (text, ...params) => ({
     sql: text,
     params,
@@ -132,6 +132,34 @@ export function nativeSqlStorage(driver) {
                 return new Map(rows.map((row) => [row.key, textOf(row.value, row.value_bytes, "Stored access token metadata")]));
             });
         },
+        catalogSnapshot(keys, generationKey, prefix, suffixes) {
+            return Effect.gen(function* () {
+                if (keys.length < 1 || keys.length > 4 || suffixes.length > 2)
+                    throw new RangeError("Catalog locator exceeds bounds");
+                for (const key of [...keys, generationKey, prefix, ...suffixes])
+                    validateStorageKey(key);
+                yield* ensure();
+                const rows = yield* driver.all(sql(`WITH initial AS (
+            SELECT key, value FROM connecta_kv WHERE key IN (${keys.map(() => "?").join(",")}) AND ${live}
+          ), suffixes(suffix) AS (VALUES ${suffixes.map(() => "(?)").join(",") || "(NULL)"}), wanted(key) AS (
+            SELECT key FROM initial UNION ALL
+            SELECT ? || (SELECT value FROM initial WHERE key = ?) || ? || suffix FROM suffixes
+          ) SELECT key, ${textColumn("value")} FROM connecta_kv
+            WHERE key IN (SELECT key FROM wanted) AND ${live}`, ...keys, ...suffixes, prefix, generationKey, responseCacheKeys.locatorSeparator));
+                const values = new Map(rows.map((row) => [row.key, textOf(row.value, row.value_bytes, "Stored catalog locator")]));
+                for (const key of keys)
+                    if (!values.has(key))
+                        values.set(key, null);
+                const generation = values.get(generationKey);
+                if (generation)
+                    for (const suffix of suffixes) {
+                        const key = responseCacheKeys.locatedEntry(prefix, generation, suffix);
+                        if (!values.has(key))
+                            values.set(key, null);
+                    }
+                return values;
+            });
+        },
         getMany(keys) {
             return Effect.gen(function* () {
                 for (const key of keys)
@@ -157,6 +185,25 @@ export function nativeSqlStorage(driver) {
                 return values;
             });
         },
+        setMany(entries, opts) {
+            return Effect.gen(function* () {
+                if (entries.length > 64)
+                    throw new RangeError("setMany accepts at most 64 rows");
+                for (const [key] of entries)
+                    validateStorageKey(key);
+                const expiry = expiryOptions(opts);
+                if (!entries.length)
+                    return;
+                yield* ensure();
+                const changes = yield* driver.batch([
+                    expirySweep(),
+                    ...entries.map(([key, value]) => sql(`INSERT INTO connecta_kv (key, value, expires_at_ms) VALUES (?, ?, ${expiry.expression})
+           ON CONFLICT (key) DO UPDATE SET value = excluded.value, expires_at_ms = excluded.expires_at_ms`, key, value, expiry.value)),
+                ]);
+                if (changes.length !== entries.length + 1 || changes.slice(1).some((changed) => changed !== 1))
+                    throw new Error("SQL multi-set confirmation is incomplete");
+            });
+        },
         set(key, value, opts) {
             return Effect.gen(function* () {
                 validateStorageKey(key);
@@ -334,11 +381,20 @@ function activityRow(read) {
     }
     return row;
 }
+// Operation metadata shares the existing kind-tagged text slot; no new columns.
+function parseOperation(raw) {
+    try {
+        return raw === null ? undefined : JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 function rowToEvent(row) {
     // Rows written before `friction` had a column derive it from the code.
     // Friction without a code — an oversized but successful result — exists
     // only in the column, which is why the column exists.
-    const friction = row.friction ?? agentFrictionForCode(row.error_code ?? undefined);
+    const friction = row.event_kind === "operation" ? undefined : (row.friction ?? agentFrictionForCode(row.error_code ?? undefined));
     const packageVersion = activityPackageVersion(row.package_version);
     const clientName = activityClientFact(row.client_name, "name");
     const clientVersion = activityClientFact(row.client_version, "version");
@@ -351,6 +407,7 @@ function rowToEvent(row) {
             classification: row.classification,
             resultBytes: row.result_bytes,
             kind: row.event_kind,
+            operation: row.event_kind === "operation" ? parseOperation(row.drift_kind) : undefined,
             pool: row.pool_name,
             actorBasis: row.actor_basis,
             drift: {
@@ -461,7 +518,7 @@ export function nativeSqlActivityStore(driver, kind, options = {}) {
                     // Stored beside the code rather than derived from it: a truncated
                     // result is friction on a call that succeeded, and
                     // `error_code IS NOT NULL` stays an honest count of failures.
-                    event.friction ?? null, event.approval ?? null, activityPackageVersion(event.packageVersion) ?? null, event.serverName, event.serverVersion, activityClientFact(event.clientName, "name") ?? null, activityClientFact(event.clientVersion, "version") ?? null, event.deploymentId ?? null, facts.classification ?? null, facts.resultBytes ?? null, facts.kind ?? null, facts.drift?.kind ?? null, facts.drift?.addedTools ?? null, facts.drift?.removedTools ?? null, facts.drift?.changedTools ?? null, facts.pool ?? null, facts.actorBasis ?? null),
+                    event.kind === "operation" ? null : (event.friction ?? null), event.approval ?? null, activityPackageVersion(event.packageVersion) ?? null, event.serverName, event.serverVersion, activityClientFact(event.clientName, "name") ?? null, activityClientFact(event.clientVersion, "version") ?? null, event.deploymentId ?? null, facts.classification ?? null, facts.resultBytes ?? null, facts.kind ?? null, facts.kind === "operation" ? JSON.stringify(facts.operation ?? null) : (facts.drift?.kind ?? null), facts.drift?.addedTools ?? null, facts.drift?.removedTools ?? null, facts.drift?.changedTools ?? null, facts.pool ?? null, facts.actorBasis ?? null),
                     sql(`DELETE FROM tool_call_activity WHERE id IN (
             SELECT id FROM tool_call_activity
             WHERE occurred_at_ms < ?

package/dist/storage/sql.js

@@ -10,6 +10,12 @@ export function sqlStorage(driver, kind) {
     const root = {};
     const native = {
         ...store,
+        setMany: (entries, options) => {
+            let write = store.setMany(entries, options);
+            for (const [key] of entries)
+                write = observedWrite(root, key, write);
+            return write;
+        },
         set: (key, value, options) => observedWrite(root, key, store.set(key, value, options)),
         delete: (key) => observedWrite(root, key, store.delete(key)),
         compareAndSet: (key, expected, next, options) => observedWrite(root, key, store.compareAndSet(key, expected, next, options)),

package/dist/timing-trace.js

@@ -0,0 +1,84 @@
+const families = new Set([
+    "catalog.cache.lookup",
+    "catalog.cache.hit",
+    "catalog.cache.expired",
+    "catalog.chunks",
+    "catalog.validated.hit",
+    "catalog.validated.miss",
+    "catalog.intake",
+    "catalog.decode",
+    "catalog.validate",
+    "catalog.accepted",
+    "catalog",
+    "admission",
+    "connector",
+    "result",
+    "d1.read",
+    "d1.write",
+    "d1.batch",
+    "memo.hit",
+    "memo.miss",
+    "memo.fresh",
+]);
+const traces = new WeakMap();
+let active = 0;
+let firstRequest = true;
+export const hasTimingTraces = () => active > 0;
+export const traceFor = (identity) => identity ? traces.get(identity) : undefined;
+const finite = (value) => (Number.isFinite(value) && value >= 0 ? value : 0);
+export class TimingTrace {
+    first;
+    started = performance.now();
+    totals = new Map();
+    closed = false;
+    constructor(first) {
+        this.first = first;
+    }
+    record(family, durationMs = 0, bytes = 0, statements = 0, absent = 0, items = 0) {
+        if (this.closed || !families.has(family))
+            return;
+        const total = this.totals.get(family) ?? { count: 0, durationMs: 0, bytes: 0, statements: 0, absent: 0, items: 0 };
+        total.count++;
+        total.durationMs += finite(durationMs);
+        total.bytes += finite(bytes);
+        total.statements += finite(statements);
+        total.absent += finite(absent);
+        total.items += finite(items);
+        this.totals.set(family, total);
+    }
+    finish(logger) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            logger.info("connecta.timing", {
+                version: 1,
+                isolateFirstRequest: this.first,
+                durationMs: performance.now() - this.started,
+                weakReferences: typeof WeakRef === "function" && typeof FinalizationRegistry === "function",
+                operations: Object.fromEntries(this.totals),
+            });
+        }
+        catch {
+            /* Observability cannot change a request's outcome. */
+        }
+        this.totals.clear();
+    }
+}
+/** Called for each MCP request, including those not sampled. */
+export function startTimingTrace(identity, sampleRate, logger) {
+    const first = firstRequest;
+    firstRequest = false;
+    if (sampleRate <= 0 || (sampleRate < 1 && Math.random() >= sampleRate))
+        return undefined;
+    const trace = new TimingTrace(first);
+    traces.set(identity, trace);
+    active++;
+    return () => {
+        if (traces.get(identity) !== trace)
+            return;
+        traces.delete(identity);
+        active--;
+        trace.finish(logger);
+    };
+}

package/dist/types.d.ts

@@ -842,6 +842,11 @@ export interface InboundAuth {
     kind: string;
     /** This provider may admit a human identity to operator mutation routes. */
     interactiveOperator?: true;
+    /**
+     * This provider checks credentials against the deployment's own URL and was
+     * given none, so construction refuses a configuration without `publicUrl`.
+     */
+    requiresPublicUrl?: true;
     /**
      * Recognize credential syntax or trusted runtime context, without verifying
      * it or doing I/O. The first recognizing provider owns the verdict, including