@zackbart/connecta 0.37.1 → 0.39.0

package/dist/runtime/request-reads.js

@@ -0,0 +1,182 @@
+// Request-scoped memo of storage reads (INV-7).
+//
+// One request often reads the same key many times: a catalog listing reads its
+// generation at each step, and status, drift and detail views each open the
+// same credential. A call site that has argued staleness
+// within one request is safe reads through `RequestReads.read`; every other
+// read stays a plain storage read. The memo belongs to one request owner,
+// holds plain strings only, and is emptied when the request closes. Nothing in
+// it crosses requests: each request owner has its own. Entries are keyed by
+// the physical key in the underlying store, through any namespaced views, so
+// one principal's partition never answers another's and two views of the same
+// partition share one entry.
+//
+// Freshness. Every write through a store connecta can observe — the SQL
+// drivers, `memoryStorage()`, and namespaced views over them — tells each open
+// memo over that store, in this isolate, that its key is changing: before the
+// write is submitted and again when it settles. The memo drops that key, and
+// a read of it already in flight is not recorded, since it may or may not
+// include the write. So a write by this request, or by any other request in
+// this isolate, is never hidden by a memoized value. A store whose writes
+// connecta cannot observe (a custom adapter, or a built-in one whose methods
+// were replaced) is never memoized. Writes in another isolate or process, and
+// expiry within the request, are invisible here: a memoized key can lag them
+// for the rest of the request. So no read that gates authority, sends a
+// credential or decides a write may be memoized; a call site that memoizes
+// must say why that staleness is safe.
+//
+// A `fresh` read bypasses the lookup and records what it saw, so a memoized
+// reader never returns a value older than this request's latest fresh read of
+// the same key. Only the latest read of a key this request started records:
+// an earlier read that settles later, possibly from before another isolate's
+// write, never replaces a newer observation.
+//
+// The registry of open memos holds weak references, so a request owner that is
+// never closed cannot pin its memo. A runtime without `WeakRef` and
+// `FinalizationRegistry` (workerd before compatibility date 2025-05-05 without
+// `enable_weak_ref`) memoizes nothing: every read goes to storage.
+import { Effect } from "effect";
+const observed = new WeakMap();
+/**
+ * Open memos holding or reading entries of each store. Weak, so a request
+ * owner that is never closed still lets its memo be collected with it.
+ */
+const open = new WeakMap();
+function eachOpen(store, visit) {
+    const memos = open.get(store);
+    if (!memos)
+        return;
+    for (const ref of memos) {
+        const memo = ref.deref();
+        if (memo)
+            visit(memo);
+        else
+            memos.delete(ref);
+    }
+}
+/** A write to `key` of `store` is about to be submitted, or has settled. */
+export function noteStorageWrite(store, key) {
+    eachOpen(store, (memo) => memo.changed(store, key));
+}
+/** Wrap one write so open memos see it begin and settle, however it ends. */
+export function observedWrite(store, key, write) {
+    return Effect.suspend(() => {
+        noteStorageWrite(store, key);
+        return write;
+    }).pipe(Effect.ensuring(Effect.sync(() => noteStorageWrite(store, key))));
+}
+/**
+ * Declare that every write through `storage` reaches `noteStorageWrite` for
+ * `root`, as long as its methods stay the ones it has now; or that `storage`
+ * stores `key` at `prefix + key` in another store, observed only while that
+ * one is.
+ */
+export function observeStorageWrites(storage, layer) {
+    observed.set(storage, {
+        own: {
+            get: storage.get,
+            set: storage.set,
+            delete: storage.delete,
+            list: storage.list,
+            compareAndSet: storage.compareAndSet,
+        },
+        layer,
+    });
+    return storage;
+}
+/** The underlying store and key a read of `key` reaches, when every layer is observed. */
+function physical(storage, key) {
+    const entry = observed.get(storage);
+    if (!entry)
+        return undefined;
+    const { own, layer } = entry;
+    if (own.get !== storage.get ||
+        own.set !== storage.set ||
+        own.delete !== storage.delete ||
+        own.list !== storage.list ||
+        own.compareAndSet !== storage.compareAndSet)
+        return undefined;
+    return "root" in layer ? { store: layer.root, key } : physical(layer.storage, layer.prefix + key);
+}
+const weakReferences = () => typeof WeakRef === "function" && typeof FinalizationRegistry === "function";
+export class RequestReads {
+    closed = false;
+    stores = new Map();
+    ref = weakReferences() ? new WeakRef(this) : undefined;
+    entriesFor(store) {
+        let entries = this.stores.get(store);
+        if (!entries) {
+            entries = { values: new Map(), versions: new Map(), started: new Map() };
+            this.stores.set(store, entries);
+            eachOpen(store, () => { }); // prune collected memos
+            let memos = open.get(store);
+            if (!memos)
+                open.set(store, (memos = new Set()));
+            memos.add(this.ref);
+        }
+        return entries;
+    }
+    /** A write notice: forget `key` and refuse any read of it in flight. */
+    changed(store, key) {
+        const entries = this.stores.get(store);
+        if (!entries)
+            return;
+        entries.values.delete(key);
+        entries.versions.set(key, (entries.versions.get(key) ?? 0) + 1);
+    }
+    /** 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);
+        if (!address)
+            return undefined;
+        const entries = this.entriesFor(address.store);
+        if (!fresh && entries.values.has(address.key))
+            return { hit: true, value: entries.values.get(address.key) };
+        const before = entries.versions.get(address.key) ?? 0;
+        const read = (entries.started.get(address.key) ?? 0) + 1;
+        entries.started.set(address.key, read);
+        return {
+            hit: false,
+            record: (value) => {
+                if (!this.closed &&
+                    entries.started.get(address.key) === read &&
+                    (entries.versions.get(address.key) ?? 0) === before)
+                    entries.values.set(address.key, value);
+            },
+        };
+    }
+    /**
+     * `load` reads `key` from `storage`. Without `fresh`, a value this request
+     * already read, with no observed write to that key since, answers instead.
+     */
+    read(storage, key, load, fresh = false) {
+        return Effect.suspend(() => {
+            const found = this.lookup(storage, key, fresh);
+            if (!found)
+                return load;
+            if (found.hit)
+                return Effect.succeed(found.value);
+            return Effect.tap(load, (value) => Effect.sync(() => found.record(value)));
+        });
+    }
+    /** `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)
+            return found.value;
+        const value = await load();
+        found.record(value);
+        return value;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const store of this.stores.keys())
+            if (this.ref)
+                open.get(store)?.delete(this.ref);
+        this.stores.clear();
+    }
+}

package/dist/runtime/request-scope.js

@@ -1,6 +1,7 @@
 // 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";
+import { RequestReads } from "./request-reads.js";
 import { detach } from "./run.js";
 export class RequestOwner {
     identity;
@@ -18,6 +19,7 @@ export class RequestOwner {
         secrets: undefined,
         invocations: { entered: [], authFailures: new Map(), retryReads: new Map() },
         handoffs: undefined,
+        reads: undefined,
     };
     constructor(identity) {
         this.identity = identity;
@@ -51,6 +53,7 @@ export class RequestOwner {
         }
         this.calls.clear();
         this.entries.clear();
+        this.retained.reads?.close();
         attempt(() => this.controller.abort(new Error("The request ended.")));
         for (const finalizer of this.finalizers.splice(0).reverse())
             attempt(finalizer);
@@ -61,6 +64,19 @@ export class RequestOwner {
             throw new AggregateError(failures, `Closing the request: ${failures.length} cleanup step(s) failed.`);
     }
 }
+/** This request's read memo; a closed request's memo answers nothing. */
+export function requestReads(identity) {
+    return ownerReads(requestOwner(identity));
+}
+export function ownerReads(owner) {
+    const retained = owner.retained;
+    if (!retained.reads) {
+        retained.reads = new RequestReads();
+        if (!owner.open)
+            retained.reads.close();
+    }
+    return retained.reads;
+}
 export class RequestScope extends Context.Service()("connecta/request/Scope") {
 }
 const requests = new WeakMap();

package/dist/runtime/settlement.js

@@ -10,7 +10,7 @@
 // it was created.") when the Worker's compatibility date is 2025-06-16 or
 // later, in releases since September 2026. The refusal throws out of the call
 // that completed the Deferred, failing the request that released a slot, and
-// the waiter never resumes (#1106). Awaiting a Promise around that wait is no
+// the waiter never resumes. Awaiting a Promise around that wait is no
 // help: the fiber waiting on the Deferred inside the Promise is resumed in the
 // completing request just the same.
 //

package/dist/runtime/shared-read.js

@@ -1,18 +1,5 @@
-// One read that several readers in one request wait on, each on its own terms.
-//
-// Discovery and the registry both coalesce a connector's catalog read inside
-// one request, so a search, a describe, and the call after them cost one
-// downstream listing. The read used to run under whichever reader asked
-// first: its signal was the read's signal, so a short-deadline call that
-// happened to start the read failed a search that joined it with the call's
-// timeout, and a cancelled search cancelled a read others were still waiting
-// on (#571).
-//
-// So the read owns its signal. Each reader waits under its own cancellation,
-// and the read is cancelled only when no reader is left to want it. Nothing
-// here is shared across requests: a SharedRead lives in one request's map and
-// is waited on only by that request's fibers, which is why a plain count of
-// readers is enough and no edge is needed between them.
+// Request-local catalog reads own their signal. Each reader waits under its own
+// cancellation; the read is cancelled only when no reader remains (INV-7).
 import { Deferred, Effect, Exit } from "effect";
 import { forkRequest } from "./run.js";
 import { requestOwner } from "./request-scope.js";

package/dist/runtime/storage.js

@@ -32,6 +32,18 @@ export function storageGet(key) {
             catch: (error) => error,
         }));
 }
+/**
+ * Read several keys, in one round trip when the store can; otherwise one
+ * `get` after another. Values come back in `keys` order.
+ */
+export function storageGetMany(keys) {
+    return Storage.use((storage) => {
+        const native = getNativeStorage(storage);
+        if (native?.getMany)
+            return native.getMany(keys);
+        return Effect.forEach(keys, (key) => storageGet(key).pipe(Effect.provideService(Storage, storage)));
+    });
+}
 /** Write one key, with the adapter's optional TTL. */
 export function storageSet(key, value, options) {
     return Storage.use((storage) => getNativeStorage(storage)?.set(key, value, options) ??

package/dist/sent-secrets.d.ts

@@ -224,7 +224,6 @@ export declare function agentOutputOperations<T extends Record<string, (...args:
 /** Slot reads cover custom handlers too, including keys put in query strings. A field named
  * as an identifier (an application or client ID, a username, a public key) is matched whole. */
 export declare function registerCredentialValues(secrets: SentSecrets, values: import("./types.js").ConnectorCredentialValues | null): void;
-export declare function trackCredentialReads(ctx: ConnectorContext): void;
 /** A connector's result or error as it enters: every connector's credentials and the
  * request's private arguments, under payload rules. */
 export declare function redactSentSecrets<T>(ctx: ConnectorContext, value: T): T;
@@ -235,7 +234,7 @@ export declare function requestSentSecrets(ctx: ConnectorContext): SentSecrets;
  * extracted from. Redact it whole first: a cut through an echoed form can leave a remnant
  * shorter than any fragment the output boundary matches, and a normalized number or
  * extracted substring may no longer hold the form at all. */
-export declare function redactBeforeCut<T>(ctx: ConnectorContext, value: T): T;
+export declare const redactBeforeCut: typeof redactSentSecrets;
 /** Base64, or base64url with `url`, of bytes or UTF-8 text Connecta returns to an agent: a
  * download, an attachment, a REST body, a page cursor. Every such encoding goes through here,
  * since no later pass reads through an encoding the output does not declare: the content is

package/dist/sent-secrets.js

@@ -5,7 +5,7 @@ import { Effect } from "effect";
 import { classificationCode, ConnectorCallError } from "./errors.js";
 import { credentialUrlViews } from "./credential-url.js";
 import { RequestScope, requestOwner } from "./runtime/request-scope.js";
-import { viewSecrets, wrapViewCredentials } from "./runtime/call.js";
+import { viewSecrets } from "./runtime/call.js";
 import { visitPrivateCallArguments } from "./argument-redaction.js";
 import { keptErrorName, redactedCopyOf } from "./redaction-identity.js";
 import { REDACTED } from "./redaction-marker.js";
@@ -688,7 +688,7 @@ function headerSpace(text, at) {
 }
 /**
  * The echo's spans with the value of every sensitive header line (`headerLine`'s names) added,
- * read on the text before the echo is replaced (#703). An echoed private value can take part of a
+ * read on the text before the echo is replaced. An echoed private value can take part of a
  * header's name, its `:`, or a credential prefix such as `Bearer `, so the line cannot be read
  * after replacement; read here, the whole value goes, every cookie pair and any short tail with
  * it. A line that is not a sensitive header keeps its text. One forward pass; nothing is kept.
@@ -2512,9 +2512,6 @@ export function registerCredentialValues(secrets, values) {
             secrets.add(value);
     }
 }
-export function trackCredentialReads(ctx) {
-    wrapViewCredentials(ctx);
-}
 /** A connector's result or error as it enters: every connector's credentials and the
  * request's private arguments, under payload rules. */
 export function redactSentSecrets(ctx, value) {
@@ -2530,9 +2527,7 @@ export function requestSentSecrets(ctx) {
  * extracted from. Redact it whole first: a cut through an echoed form can leave a remnant
  * shorter than any fragment the output boundary matches, and a normalized number or
  * extracted substring may no longer hold the form at all. */
-export function redactBeforeCut(ctx, value) {
-    return requestSentSecrets(ctx).redact(value);
-}
+export const redactBeforeCut = redactSentSecrets;
 /** Base64, or base64url with `url`, of bytes or UTF-8 text Connecta returns to an agent: a
  * download, an attachment, a REST body, a page cursor. Every such encoding goes through here,
  * since no later pass reads through an encoding the output does not declare: the content is

package/dist/server.js

@@ -35,7 +35,7 @@ export function createFetchHandler(opts) {
             // Which sandbox, not how it is tuned: `connecta doctor` reports the
             // executor it just exercised rather than assuming one, and a
             // deployment whose executor identifies as nothing omits the key
-            // instead of inviting a guess (#368).
+            // instead of inviting a guess.
             ...(opts.executorName !== undefined ? { executor: { name: opts.executorName } } : {}),
             admission: {
                 policy: "global-fifo",
@@ -64,7 +64,7 @@ export function createFetchHandler(opts) {
         const defer = runtimeContext ? runtimeContext.waitUntil.bind(runtimeContext) : undefined;
         const originRefusal = routeMcp.rejectOrigin(request);
         if (originRefusal) {
-            return Effect.succeed(withSecurityHeaders(originRefusal, url, path));
+            return Effect.succeed(withSecurityHeaders(originRefusal, url));
         }
         // Container and orchestrator probes reach /health over plain HTTP on
         // loopback, where no proxy has set X-Forwarded-Proto. Redirecting them to
@@ -87,7 +87,7 @@ export function createFetchHandler(opts) {
             return Effect.succeed(withSecurityHeaders(new Response(null, {
                 status: 308,
                 headers: { Location: target.toString() },
-            }), url, path));
+            }), url));
         }
         const context = {
             request,
@@ -98,7 +98,7 @@ export function createFetchHandler(opts) {
             defer,
             runtimeContext,
         };
-        return Effect.map(route(context), (response) => withSecurityHeaders(response, url, path));
+        return Effect.map(route(context), (response) => withSecurityHeaders(response, url));
     });
     return function fetch(request, runtimeContext) {
         return runEdge(serve(request, runtimeContext), { signal: request.signal });

package/dist/skills.js

@@ -1,3 +1,5 @@
+import { META_ROUTES, routeNames } from "./agent-routes.js";
+import { bytesToHex, utf8Length } from "./bytes.js";
 import { duringViewEffect } from "./runtime/call.js";
 import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { upwardStep } from "./upward.js";
@@ -8,15 +10,17 @@ import { Effect } from "effect";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { closeScopeOnExit } from "./runtime/connector-scope.js";
 import { sentSecretsForRequest } from "./sent-secrets.js";
-const ROUTE = "Choose a route before discovery. One known-address read uses call_tool; one known-address write uses call_destructive_tool. Unknown-address read-only work starts with execute_code 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.";
-const RECOVERY = 'When an auth error includes a handoff, give it to the user or operator. Use authorize_connector for a fresh link. Page resultId notices and format:"paged" handles with connecta.result(handleOrId, { page? }). Fetch skills({ name: "usage" }) only for missing guidance or program repair.';
+// 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.`;
+const RECOVERY = `When an auth error includes a handoff, give it to the user or operator. Use ${META_ROUTES.authorize} for a fresh link. Page resultId notices and format:"paged" handles with connecta.result(handleOrId, { page? }). Missing guidance/repair only: skills tool "usage" or connecta.skill("usage").`;
 /**
  * The always-loaded MCP `instructions` string. An endpoint is writable or
  * read-only: a writable one lets programs and call_destructive_tool write,
  * 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 call_destructive_tool may write. On a read-only endpoint, search omits write tools and every write call is refused; guides may still name them. The execute_code description says which this endpoint is. Never repeat a write to recover its output. ${RECOVERY}`;
+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}`;
 /**
  * The instructions one endpoint serves: {@link CONNECTA_INSTRUCTIONS}, then
  * the admitted pool's `description` after a fixed lead-in. Plain `/mcp` and a
@@ -30,7 +34,8 @@ export function endpointInstructions(description, native) {
 }
 /** Instructions for pools whose host searches the listed native tools. */
 export function nativeInstructions(executeCode) {
-    return `Each tool here is one operation; annotations classify reads/writes. Call known tools directly; ${executeCode ? "combine work in execute_code 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. Follow nextAction to page with ${executeCode ? "connecta.result in execute_code" : "read_result"}. skills lists guidance.`;
+    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. 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) {
@@ -45,36 +50,37 @@ export function hasConnectorGuides(connectors) {
 function usageSkill() {
     return USAGE_SKILL;
 }
+const INVESTIGATE_DESCRIPTION = "Plan an investigation that spans several services; resolve scope, identities, and capability limits before querying, then return the answer with its evidence.";
 const INVESTIGATE_SKILL = `---
 name: investigate
-description: Plan purchase verification, experiment checks, and customer or deployment investigations across services; resolve scope and capability limits before querying.
+description: ${INVESTIGATE_DESCRIPTION}
 ---
 
 # Investigate across services
 
 ## Plan the investigation
 
-Start from the user's question and the evidence that would answer it. Select the app, account, and environment from connector titles, purposes, and relevant guides before looking up records. Reuse verified ids within the task; never carry an id across connectors just because its name matches.
+Start from the user's question and the evidence that would answer it. Select the account, environment, and time window from connector titles, purposes, and relevant guides before looking up records. Reuse verified ids within the task; never carry an id across connectors just because its name matches.
 
-- Purchase verification: resolve the same customer and environment across payment, subscription access, and analytics. Check each separately; a recorded payment does not prove access, and a missing analytics event does not prove payment failure.
-- Experiment checks: confirm the project, experiment, time window, and exposure population before comparing outcomes. Return the requested comparison and any missing evidence; do not expand into an unrelated analytics audit.
-- Customer or deployment investigations: locate the exact customer or deployment first, then follow only the records needed to explain the reported symptom. Use provider links or ids so the answer can be checked.
+- Resolve the same subject in each service separately. A record in one service does not prove the matching state in another, and a missing record in one does not prove failure elsewhere.
+- Confirm the scope a comparison needs (which records, which window, which population) before comparing. Return the requested comparison and any missing evidence; do not expand into an unrelated audit.
+- Locate the exact record first, then follow only the records needed to explain the reported symptom. Use provider links or ids so the answer can be checked.
 
 Establish capability limits early. A partial search is not proof that a tool is absent, and an unavailable catalog is not an empty dataset. Try a scoped search for the missing operation, inspect its guide when relevant, and distinguish unsupported work from missing data or authorization. If the required evidence is unavailable, return what was verified and the specific gap instead of approximating a different question through repeated calls.
 
-A host transport error that requires reconnecting this MCP server cannot be repaired by a downstream tool. Reconnect in the host; do not repeatedly call \`authorize_connector\` through the failed connection.
+A host transport error that requires reconnecting this MCP server cannot be repaired by a downstream tool. Reconnect in the host; do not repeatedly call \`${META_ROUTES.authorize}\` through the failed connection.
 
-Return the answer first, then the evidence and any unresolved gap. Include the app/environment, time window, and source ids or links needed to check it. Separate observed facts from inferences. Stop when the requested evidence is sufficient.
+Return the answer first, then the evidence and any unresolved gap. Include the account or environment, time window, and source ids or links needed to check it. Separate observed facts from inferences. Stop when the requested evidence is sufficient.
 `;
 const AVAILABLE_SKILLS = [
     {
         name: "usage",
-        description: "How to route work between one execute_code program and Connecta's explicit call, authorization, and result tools.",
+        description: `How to route work between one ${META_ROUTES.program} program and Connecta's explicit call, authorization, and result tools.`,
         content: usageSkill,
     },
     {
         name: "investigate",
-        description: "Plan purchase verification, experiment checks, and customer or deployment investigations across services; resolve scope and capability limits before querying.",
+        description: INVESTIGATE_DESCRIPTION,
         content: () => INVESTIGATE_SKILL,
     },
 ];
@@ -83,7 +89,8 @@ const AVAILABLE_SKILLS = [
  * are bare identifiers and never contain ":", so `connector:<id>` cannot
  * collide with one — not even when a connector's id is literally "usage".
  * Canonical skill URIs and the prefixed compatibility alias reach connector
- * guides. A bare connector id never resolves, so nothing shadows silently.
+ * guides. A bare connector id reaches its guide too, unless it is a built-in
+ * skill name: built-ins always win, so nothing shadows them.
  */
 const CONNECTOR_SKILL_PREFIX = "connector:";
 /** The skill name that fetches `connector`'s guide. */
@@ -328,25 +335,6 @@ const MAX_SKILL_CATALOG_BYTES = 8 * 1024 * 1024;
 const MAX_SKILLS = 1_024;
 const encoder = new TextEncoder();
 const PRIVATE = { resultType: "complete", ttlMs: 0, cacheScope: "private" };
-/** Bound metadata before cloning it, without another payload-sized byte array. */
-function jsonBytes(value) {
-    const json = JSON.stringify(value);
-    let bytes = 0;
-    for (let i = 0; i < json.length; i++) {
-        const code = json.charCodeAt(i);
-        if (code < 0x80)
-            bytes++;
-        else if (code < 0x800)
-            bytes += 2;
-        else if (code >= 0xd800 && code <= 0xdbff && json.charCodeAt(i + 1) >= 0xdc00 && json.charCodeAt(i + 1) <= 0xdfff) {
-            bytes += 4;
-            i++;
-        }
-        else
-            bytes += 3;
-    }
-    return bytes;
-}
 function localRecord(name, uri, description, content, aliases) {
     return { entry: { uri, frontmatter: { name, description }, resources: "dynamic" }, content, aliases };
 }
@@ -369,12 +357,7 @@ const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (
             (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)), (connector) => authFlow(function* () {
             const name = validSkillName(connector.id)
                 ? connector.id
-                : `connector-${[
-                    ...new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", encoder.encode(connector.id)]))),
-                ]
-                    .map((byte) => byte.toString(16).padStart(2, "0"))
-                    .join("")
-                    .slice(0, 48)}`;
+                : `connector-${bytesToHex(new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", encoder.encode(connector.id)])))).slice(0, 48)}`;
             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)}`;
@@ -392,6 +375,13 @@ const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (
         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));
+}
 /** Keep the downstream path tree, so relative supporting-file references still resolve. */
 export function downstreamSkillUri(connectorId, uri) {
     if (uri.length > 32_768)
@@ -474,11 +464,7 @@ const withManifestNative = /* @__PURE__ */ registerAuth(withManifest, function (
         const bytes = encoder.encode(record.content);
         if (bytes.length > MAX_SKILL_BYTES)
             throw new ConnectorCallError("unavailable", "Local skill exceeds the byte bound.");
-        const digest = [
-            ...new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", bytes]))),
-        ]
-            .map((byte) => byte.toString(16).padStart(2, "0"))
-            .join("");
+        const digest = bytesToHex(new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", bytes]))));
         return {
             ...record,
             entry: {
@@ -552,12 +538,14 @@ export class SkillsRegistry {
         const connector = this.registry.getConnector(id);
         if (connector)
             this.options.onRead?.(connector, "local");
-        const message = name.startsWith(CONNECTOR_SKILL_PREFIX)
-            ? connector
+        // Skill names resolve a bare id with a guide before reaching here; a
+        // resource URI read does not.
+        const message = connector
+            ? connectorGuide(connector) === undefined
                 ? `Connector "${boundedEchoText(id)}" has no usage guide.`
-                : `Unknown connector "${boundedEchoText(id)}".`
-            : connector
-                ? `Unknown skill "${boundedEchoText(name)}". Connector guides are fetched as "${boundedEchoText(connectorSkillName(name))}".`
+                : `Connector "${boundedEchoText(id)}" has its guide at "${boundedEchoText(connectorSkillName(id))}".`
+            : name.startsWith(CONNECTOR_SKILL_PREFIX)
+                ? `Unknown connector "${boundedEchoText(id)}".`
                 : `Unknown skill "${boundedEchoText(name)}".`;
         return new ConnectorCallError("not_found", `${message} Available skills: ${available}.`);
     }
@@ -702,7 +690,9 @@ export class SkillsRegistry {
         registerAuthMethod(SkillsRegistry.prototype, "lookup", 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 records = yield* upwardStep(self.local);
+                const local = records.find((record) => record.entry.uri === uri || record.aliases.includes(uri)) ??
+                    bareConnectorGuide(records, uri);
                 if (local) {
                     const record = yield* upwardStep(authCall(withManifest, [local]));
                     self.assertSafe([record]);
@@ -723,7 +713,7 @@ export class SkillsRegistry {
                 const records = yield* upwardStep(Effect.forEach(yield* upwardStep(self.local), (record) => authCall(withManifest, [record]), {
                     concurrency: "unbounded",
                 }));
-                let catalogBytes = jsonBytes(records.map((record) => record.entry));
+                let catalogBytes = utf8Length(JSON.stringify(records.map((record) => record.entry)));
                 // Bounded sequential connector reads avoid unbounded fan-out and finish
                 // cleanup before a later connector's failure can end the whole listing.
                 for (const connector of self.registry.listConnectors()) {
@@ -736,7 +726,7 @@ export class SkillsRegistry {
                     if (!Array.isArray(entries) || records.length + entries.length > MAX_SKILLS)
                         throw new ConnectorCallError("unavailable", "Downstream skills listing exceeds its bound.");
                     for (const original of entries) {
-                        if (catalogBytes + jsonBytes(original) + 1 > MAX_SKILL_CATALOG_BYTES)
+                        if (catalogBytes + utf8Length(JSON.stringify(original)) + 1 > MAX_SKILL_CATALOG_BYTES)
                             throw new ConnectorCallError("unavailable", "Skills listing exceeds its byte bound.");
                         const entry = structuredClone(original);
                         validateEntry(entry);
@@ -758,14 +748,14 @@ export class SkillsRegistry {
                         if (records.some((record) => record.entry.uri === uri))
                             throw new ConnectorCallError("unavailable", "Downstream skills listing contains duplicate entries.");
                         const mapped = { ...entry, uri, resources };
-                        catalogBytes += jsonBytes(mapped) + 1;
+                        catalogBytes += utf8Length(JSON.stringify(mapped)) + 1;
                         if (catalogBytes > MAX_SKILL_CATALOG_BYTES)
                             throw new ConnectorCallError("unavailable", "Skills listing exceeds its byte bound.");
                         records.push({ entry: mapped, aliases: [], connector, files });
                     }
                 }
                 if (records.length > MAX_SKILLS ||
-                    jsonBytes(records.map((record) => record.entry)) > MAX_SKILL_CATALOG_BYTES) {
+                    utf8Length(JSON.stringify(records.map((record) => record.entry))) > MAX_SKILL_CATALOG_BYTES) {
                     throw new ConnectorCallError("unavailable", "Skills listing exceeds its byte or entry bound.");
                 }
                 // Keep the old investigation guide behind every connector and downstream

package/dist/sqlite.d.ts

@@ -27,22 +27,3 @@ export declare function sqliteStorage(database: SqliteDatabase): KVStorage;
  * older than `retentionDays`.
  */
 export declare function sqliteActivityStore(database: SqliteDatabase, options?: SqliteActivityOptions): ActivityStore;
-export interface StateFileImport {
-    /** Entries copied into the database. */
-    imported: number;
-    /** Entries left alone because the database already held their key. */
-    kept: number;
-    /** Entries whose TTL had already passed. */
-    expired: number;
-}
-/**
- * One-shot migration from the 0.28 `fileStorage` JSON state file: copy every
- * live entry, with its expiry, into the database's key-value table. Run it
- * once, with the old deployment stopped, before the first start on SQLite.
- *
- * Keys the database already holds are kept, so a second run copies nothing
- * twice and never overwrites state written since. The file is read, never
- * changed; delete it once the deployment is verified. A file that is not a
- * state file throws before anything is written.
- */
-export declare function importStateFile(database: SqliteDatabase, statePath: string, now?: number): StateFileImport;