@zackbart/connecta 0.38.0 → 0.40.0

package/dist/skills.js

@@ -1,3 +1,4 @@
+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";
@@ -9,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? }). Missing guidance/repair only: skills tool "usage" or connecta.skill("usage").';
+// 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
@@ -31,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. 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.`;
 }
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
@@ -46,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,
     },
 ];
@@ -84,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. */
@@ -369,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)
@@ -525,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}.`);
     }
@@ -675,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]);

package/dist/storage/keys.js

@@ -153,7 +153,33 @@ export const catalogKeys = {
     manifest: (connectorId) => validateStorageKey(`catalog:${connectorId}`),
     chunk: (connectorId, revision, index) => validateStorageKey(`catalog:${connectorId}:chunk:${revision}:${index}`),
 };
-/** SDK catalog response cache, complete manifests published after their chunks. */
+/** How long a connector-health record outlives its retry time, fencing the next probe's claim. */
+export const CONNECTOR_HEALTH_LINGER_MS = 60_000;
+/**
+ * Bounded connector health by connector id and a digest of the owner
+ * partition and described configuration. `discovery` holds the latest failed
+ * discovery's typed code, observation time, retry time and the catalog
+ * generation it saw; `status` the operator page's latest status observation
+ * (state, problem code, tool count, observation time, generation). Values
+ * never carry downstream text, tools or credentials.
+ */
+export const connectorHealthKeys = {
+    family: {
+        name: "connector-health",
+        scope: "root",
+        prefixes: ["connector-health:v1:"],
+        version: { number: 1, in: "key" },
+        codec: jsonCodec,
+        ttl: { kind: "configured", by: "discovery: retry time plus 60 seconds; status: 120 seconds" },
+        durable: false,
+    },
+    discovery: (connectorId, partitionDigest) => validateStorageKey(`connector-health:v1:${connectorId}:${partitionDigest}:discovery`),
+    status: (connectorId, partitionDigest) => validateStorageKey(`connector-health:v1:${connectorId}:${partitionDigest}:status`),
+};
+/**
+ * SDK catalog response cache, complete manifests published after their chunks.
+ * Secret-bearing inputs reach these keys only through `secretDigest`.
+ */
 export const responseCacheKeys = {
     family: {
         name: "response-cache",
@@ -339,8 +365,31 @@ export const oauthConnectKeys = {
     used: (nonce) => validateStorageKey(`oauth:connect-used:${nonce}`),
     retry: (nonce) => validateStorageKey(`oauth:request-used:${nonce}`),
 };
-/** A bounded, credential-partitioned downstream protocol verdict. */
+/**
+ * The last verification of a connector's operator-managed credential:
+ * `verification:v1`, holding an outcome class, its time and the vault
+ * revision of the save it observed. Payload-free and long-lived; a lost
+ * record only makes the operator page say "not verified".
+ */
+export const verificationKeys = {
+    family: {
+        name: "verification",
+        scope: "connector",
+        prefixes: ["verification:v1"],
+        version: { number: 1, in: "key" },
+        codec: jsonCodec,
+        ttl: { kind: "durable" },
+        durable: false,
+    },
+    record: "verification:v1",
+};
+/** A bounded, credential-partitioned downstream protocol verdict, keyed through `secretDigest`. */
 export const NEGOTIATION_TTL_SECONDS = 300;
+/**
+ * A legacy verdict lives longer: a server that upgrades still answers the
+ * legacy handshake, and one that stops answering it is renegotiated at once.
+ */
+export const LEGACY_NEGOTIATION_TTL_SECONDS = 6 * 60 * 60;
 export const negotiationKeys = {
     family: {
         name: "negotiation",
@@ -348,7 +397,8 @@ export const negotiationKeys = {
         prefixes: ["negotiation:v1:"],
         version: { number: 1, in: "key" },
         codec: jsonCodec,
-        ttl: { kind: "fixed", seconds: NEGOTIATION_TTL_SECONDS },
+        // The longest verdict lifetime; a modern verdict expires sooner.
+        ttl: { kind: "fixed", seconds: LEGACY_NEGOTIATION_TTL_SECONDS },
         durable: false,
     },
     verdict: (partitionDigest) => validateStorageKey(`negotiation:v1:${partitionDigest}`),

package/dist/storage/memory.js

@@ -1,4 +1,5 @@
 import { validateStorageKey } from "./keys.js";
+import { noteStorageWrite, observeStorageWrites } from "../runtime/request-reads.js";
 /** In-memory KV store with expiry. The default for dev and Node. */
 export function memoryStorage() {
     const map = new Map();
@@ -40,7 +41,9 @@ export function memoryStorage() {
             ...(exp !== undefined ? { exp } : {}),
         });
     };
-    return {
+    // Each write settles synchronously, so one note covers it (request-reads.ts).
+    const root = {};
+    return observeStorageWrites({
         capabilities: { absoluteExpiry: true },
         describe: () => ({ kind: "memory" }),
         async get(key) {
@@ -49,10 +52,12 @@ export function memoryStorage() {
         },
         async set(key, value, opts) {
             validateStorageKey(key);
+            noteStorageWrite(root, key);
             write(key, value, opts);
         },
         async delete(key) {
             validateStorageKey(key);
+            noteStorageWrite(root, key);
             map.delete(key);
         },
         async list(prefix) {
@@ -68,6 +73,7 @@ export function memoryStorage() {
         // runs to completion before any other call on this map can start.
         async compareAndSet(key, expected, next, opts) {
             validateStorageKey(key);
+            noteStorageWrite(root, key);
             if ((fresh(key)?.value ?? null) !== expected)
                 return false;
             if (next === null)
@@ -76,5 +82,5 @@ export function memoryStorage() {
                 write(key, next, opts);
             return true;
         },
-    };
+    }, { root });
 }

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 { validateStorageKey } from "./keys.js";
+import { accessTokenKeys, validateStorageKey } from "./keys.js";
 const sql = (text, ...params) => ({
     sql: text,
     params,
@@ -61,6 +61,8 @@ function schemaOnce(driver, ddl) {
     });
 }
 // --- key-value ----------------------------------------------------------
+/** Keys one `getMany` statement binds. */
+const GET_MANY_KEYS = 64;
 /** Expired rows one write removes on its way. */
 const SWEEP_ROWS = 16;
 function ttlMillis(ttlSeconds) {
@@ -105,6 +107,56 @@ export function nativeSqlStorage(driver) {
                 return yield* current(key);
             });
         },
+        accessToken(hash) {
+            return Effect.gen(function* () {
+                const key = accessTokenKeys.lookup(hash);
+                yield* ensure();
+                // The links select candidate rows only. Admission still parses every
+                // raw value and addresses it by its physical key, so JSON extraction
+                // differences (e.g. duplicate fields) cannot substitute another slot.
+                // json_valid guards malformed stored JSON; expiry uses the DB clock.
+                const rows = yield* driver.all(sql(`WITH lookup AS (
+            SELECT key, value FROM connecta_kv WHERE key = ? AND ${live}
+          ), record AS (
+            SELECT key, value FROM connecta_kv WHERE key = ? ||
+              (SELECT CASE WHEN json_valid(value) THEN json_extract(value, '$.id') END FROM lookup)
+              AND ${live}
+          ), slot AS (
+            SELECT key, value FROM connecta_kv WHERE key = ? ||
+              (SELECT CASE WHEN json_valid(value) THEN json_extract(value, '$.agent') END FROM record)
+              AND ${live}
+          )
+          SELECT key, ${textColumn("value")} FROM lookup
+          UNION ALL SELECT key, ${textColumn("value")} FROM record
+          UNION ALL SELECT key, ${textColumn("value")} FROM slot`, key, accessTokenKeys.recordPrefix, accessTokenKeys.agent("")));
+                return new Map(rows.map((row) => [row.key, textOf(row.value, row.value_bytes, "Stored access token metadata")]));
+            });
+        },
+        getMany(keys) {
+            return Effect.gen(function* () {
+                for (const key of keys)
+                    validateStorageKey(key);
+                if (keys.length === 0)
+                    return [];
+                yield* ensure();
+                // One statement for every key: a chunked value costs one round trip.
+                // Rows answer by position, never by the key text a driver returns.
+                // Bound parameters stay under D1's per-statement limit of 100.
+                const values = keys.map(() => null);
+                for (let offset = 0; offset < keys.length; offset += GET_MANY_KEYS) {
+                    const batch = keys.slice(offset, offset + GET_MANY_KEYS);
+                    const rows = yield* driver.all({
+                        sql: `WITH wanted (position, key) AS (VALUES ${batch.map((_, i) => `(${offset + i}, ?)`).join(", ")})
+             SELECT wanted.position AS position, ${textColumn("value")}
+             FROM wanted JOIN connecta_kv ON connecta_kv.key = wanted.key AND ${live}`,
+                        params: batch,
+                    });
+                    for (const row of rows)
+                        values[row.position] = textOf(row.value, row.value_bytes, `the stored value of ${JSON.stringify(keys[row.position])}`);
+                }
+                return values;
+            });
+        },
         set(key, value, opts) {
             return Effect.gen(function* () {
                 validateStorageKey(key);

package/dist/storage/sql.js

@@ -1,11 +1,20 @@
 import { runEdge } from "../runtime/run.js";
 import { registerNativeStorage, registerNativeActivity } from "../runtime/native-storage.js";
+import { observedWrite, observeStorageWrites } from "../runtime/request-reads.js";
 import { nativeSqlDriver } from "./sql-driver.js";
 import { nativeSqlStorage, nativeSqlActivityStore } from "./sql-native.js";
 /** `KVStorage` over one `connecta_kv` table. */
 export function sqlStorage(driver, kind) {
-    const native = nativeSqlStorage(nativeSqlDriver(driver));
-    return registerNativeStorage({
+    const store = nativeSqlStorage(nativeSqlDriver(driver));
+    // Request read memos see every write begin and settle (request-reads.ts).
+    const root = {};
+    const native = {
+        ...store,
+        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)),
+    };
+    const edge = registerNativeStorage({
         capabilities: { absoluteExpiry: true },
         describe: () => ({ kind }),
         get: (key) => runEdge(native.get(key)),
@@ -14,6 +23,7 @@ export function sqlStorage(driver, kind) {
         list: (prefix) => runEdge(native.list(prefix)),
         compareAndSet: (key, expected, next, options) => runEdge(native.compareAndSet(key, expected, next, options)),
     }, native);
+    return observeStorageWrites(edge, { root });
 }
 /**
  * One append-only row per completed downstream call. Rows carry no arguments,

package/dist/storage-digest.js

@@ -0,0 +1,32 @@
+import { Context } from "effect";
+import { bytesToHex } from "./bytes.js";
+import { serviceFor, setViewService } from "./runtime/call.js";
+class StorageDigestKey extends Context.Service()("connecta/operation/StorageDigestKey") {
+}
+const importHmac = (raw) => crypto.subtle.importKey("raw", new Uint8Array(raw), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+// Drawn synchronously on first use, so concurrent first digests share one key.
+let processBytes;
+let processKey;
+const fallbackKey = () => (processKey ??= importHmac((processBytes ??= crypto.getRandomValues(new Uint8Array(32)))));
+const vaultKeys = new WeakMap();
+/** Bind the vault's storage digest key to a registry-built context, when it has one. */
+export function attachStorageDigestKey(ctx, vault) {
+    const derive = vault?.storageDigestKey;
+    if (typeof derive !== "function")
+        return;
+    let key = vaultKeys.get(vault);
+    if (!key) {
+        let pending;
+        key = () => (pending ??= derive.call(vault));
+        vaultKeys.set(vault, key);
+    }
+    setViewService(ctx, StorageDigestKey, key);
+}
+/**
+ * `hmac:<hex>` of a secret-bearing value, for a stored key only. Stable for one
+ * deployment key, so equal inputs still address the same entry.
+ */
+export async function secretDigest(ctx, value) {
+    const key = await (serviceFor(ctx, StorageDigestKey) ?? fallbackKey)();
+    return `hmac:${bytesToHex(new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value))))}`;
+}

package/dist/timeout.js

@@ -9,6 +9,14 @@ import { runEdge, withDeadlineEffect } from "./runtime/run.js";
  * to trip only on a pathological hang, not a realistically slow probe.
  */
 export const DEFAULT_PROBE_TIMEOUT_MS = CONFIG_DEFAULTS.discovery.probeTimeoutMs;
+/**
+ * Each connector's probe deadline in an unscoped search, or
+ * `discovery.probeTimeoutMs` when that is shorter. Scoped search, describe
+ * and calls keep the full probe deadline.
+ */
+export const UNSCOPED_PROBE_TIMEOUT_MS = 5_000;
+/** One unscoped search's whole discovery fan-out ends within this many ms. */
+export const UNSCOPED_DISCOVERY_BUDGET_MS = 9_000;
 /** A finite, positive integer number of milliseconds, or undefined. */
 export function normalizeTimeoutMs(value) {
     if (value === undefined || !Number.isFinite(value) || !(value > 0)) {

package/dist/types.d.ts

@@ -193,6 +193,14 @@ export interface ConnectorCredentialConfig {
      */
     fields?: ConnectorCredentialFieldConfig[];
 }
+/**
+ * Why a credential test did not pass, as a typed fact with no downstream text.
+ * `rejected`: the service refused the credential. `scope`: it accepted the
+ * credential but refused a permission the connection needs. `unreachable`: the
+ * service could not be reached or was unavailable. `timeout`: it did not
+ * answer within the test's deadline. `failed`: anything else.
+ */
+export type CredentialFailureClass = "rejected" | "scope" | "unreachable" | "timeout" | "failed";
 export interface CredentialTestResult {
     ok: boolean;
     /**
@@ -201,6 +209,25 @@ export interface CredentialTestResult {
      * `ok`, and the log records only that a test failed.
      */
     message?: string;
+    /**
+     * Why a failed test failed. Optional: an unclassified failure is `failed`.
+     * Ignored when `ok` is true.
+     */
+    failure?: CredentialFailureClass;
+}
+/**
+ * How agent-facing text names Connecta's routes on the surface serving an
+ * operation: `call_tool`, `call_destructive_tool`, `search_tools`,
+ * `execute_code`, `authorize_connector` and `skills` on the six-tool surface,
+ * and other wording where those tools are not listed.
+ */
+export interface AgentRouteNames {
+    readonly search: string;
+    readonly read: string;
+    readonly write: string;
+    readonly program: string;
+    readonly authorize: string;
+    readonly skills: string;
 }
 export interface ConnectorContext {
     /** Explicit downstream consent initiation, never set by status/catalog/calls. */
@@ -236,6 +263,12 @@ export interface ConnectorContext {
     defer?: (promise: Promise<unknown>) => void;
     /** Requested connector-operation deadline in milliseconds. */
     timeoutMs?: number;
+    /**
+     * Route names for text this operation writes for the agent, such as "call
+     * authorize_connector" in an auth error. Connecta sets it on every context
+     * it builds; build such text from it rather than spelling a tool name.
+     */
+    routes?: AgentRouteNames;
 }
 type ConnectorStatusState = "ok" | "per_caller" | "auth_required" | "credential_required" | "error";
 /** The last agent-facing catalog read this runtime served for one connector. */

package/dist/usage-guide.js

@@ -1,43 +1,36 @@
+import { META_ROUTES } from "./agent-routes.js";
+import { UNCOUNTED_GUEST_FUNCTIONS } from "./guest-functions.js";
 /** Self-contained content for the usage skill; independent of skill registration. */
 export const USAGE_SKILL = `---
 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.
 ---
 
 # Connecta usage
 
 ## Choose the route
 
-| Work | Tool |
-| --- | --- |
-| One known-address read | call_tool |
-| One known-address write | call_destructive_tool |
-| Discovery, multiple or dependent calls, paging, reduction | execute_code |
-
-Read one account with call_tool: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
-Discover and call together when schemas suffice. search_tools covers catalog
-inspection. On a read-only endpoint, as execute_code's description says, search
-omits writes (guides may name them) and each fails read_only_endpoint; tell the
-user. Unannotated tools fail closed to writes.
-For a requested write, make the call through the write route; the host may ask
-the user to confirm it. Connecta classifies and routes writes; the host owns approval.
+Route as the server instructions and ${META_ROUTES.program}'s first sentence say.
+Read one account with ${META_ROUTES.read}: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
+On a read-only endpoint search omits writes (guides may name them) and each
+fails read_only_endpoint; tell the user. Unannotated tools fail closed to writes.
+Connecta classifies and routes a requested write; the host owns approval.
 
 ## The global and the envelopes
 
 Pass JavaScript \`async () => { ... }\`, no arguments. Do not shadow \`connecta\`.
 No imports, require, filesystem, fetch, or timers.
 
-Use \`connecta.call(address, args, { timeoutMs })\` or
-\`connecta.call({ address, args, timeoutMs })\`; both return \`{ data, format }\`.
-\`format: "json"\` carries JSON; \`format: "text"\` carries text. Parse text only
-when documented as JSON. Verify collection roots.
+\`connecta.call(address, args, { timeoutMs })\` and
+\`connecta.call({ address, args, timeoutMs })\` return \`{ data, format }\`.
+Parse \`format: "text"\` only when documented as JSON. Verify collection roots.
 
 \`connecta.read("resource://id/"+encodeURIComponent(uri))\` returns \`{ contents }\` for advertised URIs.
 
-Search/describe return \`{ tools }\`, never an array. Search also returns
-\`catalogErrors\`, pagination, and possible \`absence\`; check failures before
-selecting a match. JSON schemas are the program default. Compact schemas have
-\`schemaFormat: "text"\`; do not read their .properties. Select the exact tool and
+Search/describe return \`{ tools }\`, never an array. Check search's
+\`catalogErrors\` and \`absence\` before selecting a match. Search defaults to a
+TypeScript \`signature\`; text schemas have \`schemaFormat: "text"\` and no .properties.
+A \`readyCalls\` entry is a complete read: \`connecta.call(entry.address, entry.args)\`. Select the exact tool and
 account/environment, inspect its schema, and supply its required keys and types.
 
 Discover an unfamiliar read and reduce its result:
@@ -79,7 +72,7 @@ async () => {
 
 Host-call budget exhaustion ends the run with budget_exceeded. Catch and
 allSettled cannot recover it or return partial output. Bound batches before
-starting them; every guest call except emit spends host calls.
+starting them; every guest call except ${UNCOUNTED_GUEST_FUNCTIONS} spends host calls.
 Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides
@@ -134,15 +127,3 @@ base64 and PNG/JPEG/GIF/WebP MIME. Emit works without await, delivers on success
 and obeys byte/block budgets; text shares the return cap. Return reduced JSON.
 
 `;
-/** Kept in sync with GuestApi by the declaration test. These are type notation, not runnable JS. */
-export const GUEST_API_DECLARATION = `search(args?: CatalogSearchArgs): Promise<CatalogSearchResult>;
-describe(args?: CatalogDescribeArgs): Promise<{ tools: CatalogDescription[] }>;
-call(address: string, args?: unknown, options?: { timeoutMs?: number }): Promise<GuestResult>;
-call(request: { address: string; args?: unknown; timeoutMs?: number }): Promise<GuestResult>;
-read(uri: string): Promise<GuestResourceResult>;
-result(
-  id: string | GuestResultHandle,
-  options?: { page?: number; offset?: number; maxBytes?: number },
-): Promise<GuestResultPage>;
-skill(name: string): Promise<{ name: string; text: string; format: "text" }>;
-emit(block: GuestNativeBlock | GuestResult): PromiseLike<void>;`;

package/dist/validate.d.ts

@@ -1,4 +1,5 @@
 import { ConnectorCallError } from "./errors.js";
+import type { ArgumentValidationDetails } from "./errors.js";
 import { type FailureSubject } from "./operator-record.js";
 import type { JsonSchema, Logger } from "./types.js";
 export interface ValidateToolInputOptions {
@@ -31,6 +32,8 @@ export interface CompileValidatorOptions {
 }
 /** Optional in-process properties have the same absence semantics as JSON input. Never mutate the caller. */
 export declare function normalizeToolInput<A>(value: A): A;
+/** One example synthesized from the published schema alone, checked by its validator; never caller values. */
+export declare function schemaExample(schema: JsonSchema): Pick<ArgumentValidationDetails, "example" | "exampleUnavailable">;
 /**
  * Validate call arguments against a tool's JSON Schema.
  *