@zackbart/connecta 0.18.2 → 0.19.0

package/dist/registry.js

@@ -1,14 +1,15 @@
 import { closeConnectorScope, } from "./connector-scope.js";
 import { recordCatalogDriftActivity, } from "./activity.js";
 import { storedCredentialShape, } from "./credentials.js";
-import { ConnectorCallError } from "./errors.js";
+import { ConnectorCallError, msg } from "./errors.js";
 import { ConnectorCallAdmissionController, } from "./call-admission.js";
 import { boundedCatalogDrift } from "./catalog-drift.js";
 import { fingerprintSerializedCatalog, snapshotCatalog, } from "./catalog-fingerprint.js";
 import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES, } from "./catalog-limits.js";
 import { mapSettledWithConcurrency } from "./concurrency.js";
+import { ObservedOutputSchemas } from "./result-shapes.js";
 import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
-import { withAbortableTimeout } from "./timeout.js";
+import { withDeadline } from "./timeout.js";
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
@@ -67,37 +68,6 @@ export function resolveMaxResultBytes(value, inherited) {
         : inherited;
 }
 const CATALOG_CHUNK_IO_CONCURRENCY = 4;
-/**
- * Recent real-call outcomes per connector.
- */
-class HealthLog {
-    observations = new Map();
-    recordSuccess(id, latencyMs) {
-        const previous = this.observations.get(id);
-        const observation = {
-            ...previous,
-            lastSuccessAt: new Date().toISOString(),
-            lastLatencyMs: latencyMs,
-            consecutiveFailures: 0,
-        };
-        delete observation.lastError;
-        this.observations.set(id, observation);
-    }
-    recordFailure(id, latencyMs, error) {
-        const previous = this.observations.get(id);
-        this.observations.set(id, {
-            ...previous,
-            lastFailureAt: new Date().toISOString(),
-            lastLatencyMs: latencyMs,
-            consecutiveFailures: (previous?.consecutiveFailures ?? 0) + 1,
-            lastError: msg(error),
-        });
-    }
-    get(id) {
-        const observation = this.observations.get(id);
-        return observation ? { ...observation } : undefined;
-    }
-}
 function namespaced(storage, prefix) {
     return {
         get: (k) => storage.get(prefix + k),
@@ -105,9 +75,6 @@ function namespaced(storage, prefix) {
         delete: (k) => storage.delete(prefix + k),
     };
 }
-function msg(err) {
-    return err instanceof Error ? err.message : String(err);
-}
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
  * lists in memory with a TTL. Connector failures are isolated: a broken
@@ -123,16 +90,16 @@ export class Registry {
     catalogGenerations = new Map();
     /** Serialize persisted catalog set/delete operations within this isolate. */
     catalogMutations = new Map();
-    /** Same-request cold loads share one promise without retaining the request. */
+    /** Same-request cold loads share one promise without retaining the request.
+     * See documentation/architecture.md#the-two-lifetimes. */
     requestCatalogLoads = new WeakMap();
     /** One live refresh per connector across agent and operator requests. */
     catalogRefreshes = new Map();
     /** Last payload-free agent catalog access in this runtime. */
     catalogAccess = new Map();
-    /** Deployment-wide observations — every call, whatever view made it. */
-    health = new HealthLog();
     /** Last drift counts reported to activity, per connector, in this runtime. */
     reportedDrift = new Map();
+    observedOutputSchemas;
     ttlMs;
     staleMs;
     persistToolCatalog;
@@ -140,6 +107,7 @@ export class Registry {
     maxResultBytes;
     constructor(connectors, opts) {
         this.opts = opts;
+        this.observedOutputSchemas = new ObservedOutputSchemas();
         this.ttlMs =
             (opts.toolCacheTtlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
         this.staleMs =
@@ -342,6 +310,12 @@ export class Registry {
     resultsStorage() {
         return namespaced(this.opts.storage, "results:");
     }
+    observedOutputSchema(connectorId, definition) {
+        return this.observedOutputSchemas.get(connectorId, definition);
+    }
+    observeOutputShape(connectorId, definition, value) {
+        this.observedOutputSchemas.observe(connectorId, definition, value);
+    }
     /** Resolve "<connectorId>.<toolName>" → connector + tool name. */
     resolveAddress(address) {
         const parts = splitAddress(address);
@@ -358,21 +332,6 @@ export class Registry {
     catalogChunkKey(id, revision, index) {
         return `${this.catalogKey(id)}:chunk:${revision}:${index}`;
     }
-    validLegacyCatalog(value) {
-        if (!value || typeof value !== "object")
-            return null;
-        const catalog = value;
-        if (!Array.isArray(catalog.tools) ||
-            typeof catalog.fetchedAt !== "number" ||
-            typeof catalog.expiresAt !== "number" ||
-            typeof catalog.staleUntil !== "number" ||
-            (catalog.fingerprint !== undefined &&
-                typeof catalog.fingerprint !== "string") ||
-            !this.validCatalogTools(catalog.tools)) {
-            return null;
-        }
-        return catalog;
-    }
     validCatalogTools(value) {
         return value.every((tool) => tool !== null &&
             typeof tool === "object" &&
@@ -443,28 +402,6 @@ export class Registry {
         catch {
             return null;
         }
-        if (!parsed ||
-            typeof parsed !== "object" ||
-            parsed.version !== 2) {
-            const legacy = this.validLegacyCatalog(parsed);
-            if (!legacy || legacy.staleUntil <= now)
-                return null;
-            const snapshot = await snapshotCatalog(legacy.tools);
-            if (legacy.tools.length > MAX_CATALOG_TOOLS ||
-                snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES ||
-                (legacy.fingerprint !== undefined &&
-                    legacy.fingerprint !== snapshot.fingerprint)) {
-                this.opts.logger.warn(`[connecta] connector "${id}" legacy catalog is oversized or has a fingerprint mismatch; ignoring persisted catalog.`);
-                return null;
-            }
-            return {
-                tools: legacy.tools,
-                fingerprint: snapshot.fingerprint,
-                fetchedAt: legacy.fetchedAt,
-                expiresAt: legacy.expiresAt,
-                staleUntil: legacy.staleUntil,
-            };
-        }
         const manifest = this.validCatalogManifest(parsed);
         if (!manifest) {
             this.opts.logger.warn(`[connecta] connector "${id}" catalog manifest is invalid; ignoring persisted catalog.`);
@@ -739,7 +676,7 @@ export class Registry {
         if (!flight) {
             const requestScope = {};
             let ctx;
-            flight = this.startCatalogRefresh(id, expectedGeneration, () => withAbortableTimeout((signal) => {
+            flight = this.startCatalogRefresh(id, expectedGeneration, () => withDeadline((signal) => {
                 const current = this.cache.get(id);
                 if (current && current.exp > Date.now()) {
                     return Promise.resolve(current.tools);
@@ -753,7 +690,10 @@ export class Registry {
                     timeoutMs: options.refreshTimeoutMs,
                 });
                 return this.refreshToolsWithContext(id, connector, ctx, true);
-            }, options.refreshTimeoutMs, `deferred catalog refresh of "${id}"`), async () => {
+            }, {
+                timeoutMs: options.refreshTimeoutMs,
+                timeoutError: new Error(`deferred catalog refresh of "${id}" timed out after ${options.refreshTimeoutMs}ms`),
+            }), async () => {
                 if (ctx)
                     await closeConnectorScope(connector, ctx, options.defer);
             });
@@ -912,31 +852,6 @@ export class Registry {
                 this.requestCatalogLoads.delete(requestScope);
         }
     }
-    /** Return a cached catalog without performing storage or network I/O. */
-    peekTools(id) {
-        const connector = this.connectors.get(id);
-        if (connector?.staticTools)
-            return connector.staticTools;
-        const hit = this.cache.get(id);
-        return hit && hit.staleUntil > Date.now() ? hit.tools : undefined;
-    }
-    recordSuccess(id, latencyMs) {
-        this.health.recordSuccess(id, latencyMs);
-    }
-    recordFailure(id, latencyMs, error) {
-        this.health.recordFailure(id, latencyMs, error);
-    }
-    healthFor(id) {
-        return this.health.get(id);
-    }
-    /** Whether this deployment has seen a successful call to `id`. */
-    hasObservedSuccess(id) {
-        return this.observedSuccessAt(id) !== undefined;
-    }
-    /** The timestamp behind `hasObservedSuccess`. */
-    observedSuccessAt(id) {
-        return this.health.get(id)?.lastSuccessAt;
-    }
     async credentialDriftFor(id) {
         const credential = this.connectors.get(id)?.credential;
         const vault = this.opts.credentialVault;

package/dist/result-shapes.d.ts

@@ -0,0 +1,13 @@
+import type { JsonSchema, ToolDef } from "./types.js";
+/**
+ * Passive, process-local output-shape learning. Provider declarations always
+ * win; observations are an open, optional-field routing aid and never a
+ * replacement contract.
+ */
+export declare class ObservedOutputSchemas {
+    private readonly entries;
+    private cacheKey;
+    private set;
+    get(connectorId: string, definition: ToolDef): JsonSchema | undefined;
+    observe(connectorId: string, definition: ToolDef, value: unknown): void;
+}

package/dist/result-shapes.js

@@ -0,0 +1,331 @@
+import { isExplicitlyReadOnly } from "./tool-safety.js";
+const OBSERVATION_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHED_SHAPES = 256;
+const MAX_DEFINITION_BYTES = 64 * 1024;
+const MAX_SCHEMA_BYTES = 16 * 1024;
+const MAX_SCHEMA_DEPTH = 6;
+const MAX_SCHEMA_NODES = 128;
+const MAX_OBJECT_PROPERTIES = 48;
+const MAX_ARRAY_ITEMS = 32;
+const MAX_PROPERTY_NAME_BYTES = 128;
+const UNSAFE_PROPERTY_NAMES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+const encoder = new TextEncoder();
+function broadType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return typeof value;
+        case "number":
+            return Number.isFinite(value) ? "number" : undefined;
+        case "object":
+            return "object";
+        default:
+            return undefined;
+    }
+}
+function serializedSchema(schema) {
+    try {
+        const text = JSON.stringify(schema);
+        return encoder.encode(text).byteLength <= MAX_SCHEMA_BYTES
+            ? text
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function cloneSchema(schema) {
+    const serialized = serializedSchema(schema);
+    if (!serialized)
+        return undefined;
+    try {
+        return JSON.parse(serialized);
+    }
+    catch {
+        return undefined;
+    }
+}
+function definitionIdentity(definition) {
+    try {
+        const serialized = JSON.stringify(definition);
+        return encoder.encode(serialized).byteLength <= MAX_DEFINITION_BYTES
+            ? serialized
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function schemaType(schema) {
+    return typeof schema.type === "string" ? schema.type : undefined;
+}
+function safePropertyName(name) {
+    return (!UNSAFE_PROPERTY_NAMES.has(name) &&
+        encoder.encode(name).byteLength <= MAX_PROPERTY_NAME_BYTES);
+}
+function boundedPropertyNames(value) {
+    const names = [];
+    for (const name in value) {
+        if (!Object.hasOwn(value, name) || !safePropertyName(name))
+            continue;
+        names.push(name);
+        if (names.length >= MAX_OBJECT_PROPERTIES)
+            break;
+    }
+    return names.sort();
+}
+function unionBranches(schema) {
+    return Array.isArray(schema.anyOf)
+        ? schema.anyOf
+        : [schema];
+}
+function branchOrder(schema) {
+    return ["null", "boolean", "number", "string", "array", "object"].indexOf(schemaType(schema) ?? "");
+}
+function mergeSchemas(left, right) {
+    const leftType = schemaType(left);
+    const rightType = schemaType(right);
+    if (leftType === "object" && rightType === "object") {
+        const leftProperties = left.properties && typeof left.properties === "object"
+            ? left.properties
+            : {};
+        const rightProperties = right.properties && typeof right.properties === "object"
+            ? right.properties
+            : {};
+        const properties = Object.create(null);
+        for (const key of [...new Set([
+                ...Object.keys(leftProperties),
+                ...Object.keys(rightProperties),
+            ])].sort()) {
+            const leftProperty = leftProperties[key];
+            const rightProperty = rightProperties[key];
+            properties[key] =
+                leftProperty && rightProperty
+                    ? mergeSchemas(leftProperty, rightProperty)
+                    : (leftProperty ?? rightProperty);
+        }
+        return { type: "object", properties };
+    }
+    if (leftType === "array" && rightType === "array") {
+        const leftItems = left.items && typeof left.items === "object"
+            ? left.items
+            : undefined;
+        const rightItems = right.items && typeof right.items === "object"
+            ? right.items
+            : undefined;
+        return {
+            type: "array",
+            ...(leftItems || rightItems
+                ? {
+                    items: leftItems && rightItems
+                        ? mergeSchemas(leftItems, rightItems)
+                        : (leftItems ?? rightItems),
+                }
+                : {}),
+        };
+    }
+    if (leftType && leftType === rightType)
+        return left;
+    const byType = new Map();
+    for (const branch of [...unionBranches(left), ...unionBranches(right)]) {
+        const type = schemaType(branch);
+        if (!type)
+            continue;
+        const existing = byType.get(type);
+        byType.set(type, existing ? mergeSchemas(existing, branch) : branch);
+    }
+    const branches = [...byType.values()].sort((a, b) => branchOrder(a) - branchOrder(b));
+    return branches.length === 1 ? branches[0] : { anyOf: branches };
+}
+function inferSchema(value, budget, depth = 0) {
+    const type = broadType(value);
+    if (!type || depth > MAX_SCHEMA_DEPTH || budget.nodes >= MAX_SCHEMA_NODES) {
+        return undefined;
+    }
+    budget.nodes++;
+    if (type !== "object" && type !== "array")
+        return { type };
+    const object = value;
+    if (budget.seen.has(object))
+        return undefined;
+    budget.seen.add(object);
+    try {
+        if (type === "array") {
+            let items;
+            for (const item of value.slice(0, MAX_ARRAY_ITEMS)) {
+                const inferred = inferSchema(item, budget, depth + 1);
+                if (inferred)
+                    items = items ? mergeSchemas(items, inferred) : inferred;
+                if (budget.nodes >= MAX_SCHEMA_NODES)
+                    break;
+            }
+            return { type: "array", ...(items ? { items } : {}) };
+        }
+        const properties = Object.create(null);
+        const record = value;
+        for (const key of boundedPropertyNames(record)) {
+            const inferred = inferSchema(record[key], budget, depth + 1);
+            if (inferred)
+                properties[key] = inferred;
+            if (budget.nodes >= MAX_SCHEMA_NODES)
+                break;
+        }
+        return { type: "object", properties };
+    }
+    finally {
+        budget.seen.delete(object);
+    }
+}
+function boundSchema(schema, budget, depth = 0) {
+    if (depth > MAX_SCHEMA_DEPTH || budget.nodes >= MAX_SCHEMA_NODES) {
+        return undefined;
+    }
+    budget.nodes++;
+    if (Array.isArray(schema.anyOf)) {
+        const branches = schema.anyOf
+            .slice(0, 6)
+            .map((branch) => boundSchema(branch, budget, depth + 1))
+            .filter((branch) => Boolean(branch));
+        return branches.length >= 2 ? { anyOf: branches } : branches[0];
+    }
+    const type = schemaType(schema);
+    if (!type)
+        return undefined;
+    if (type === "array") {
+        const items = schema.items && typeof schema.items === "object"
+            ? boundSchema(schema.items, budget, depth + 1)
+            : undefined;
+        return { type: "array", ...(items ? { items } : {}) };
+    }
+    if (type === "object") {
+        const source = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        const properties = Object.create(null);
+        let included = 0;
+        for (const key of Object.keys(source).sort()) {
+            if (included >= MAX_OBJECT_PROPERTIES ||
+                !safePropertyName(key)) {
+                continue;
+            }
+            const property = boundSchema(source[key], budget, depth + 1);
+            if (property) {
+                properties[key] = property;
+                included++;
+            }
+            if (budget.nodes >= MAX_SCHEMA_NODES)
+                break;
+        }
+        return { type: "object", properties };
+    }
+    return { type };
+}
+function observedSchema(value) {
+    try {
+        const inferred = inferSchema(value, { nodes: 0, seen: new WeakSet() });
+        const schema = inferred
+            ? boundSchema(inferred, { nodes: 0 })
+            : undefined;
+        return schema && serializedSchema(schema) ? schema : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Passive, process-local output-shape learning. Provider declarations always
+ * win; observations are an open, optional-field routing aid and never a
+ * replacement contract.
+ */
+export class ObservedOutputSchemas {
+    entries = new Map();
+    cacheKey(connectorId, definition) {
+        return JSON.stringify([connectorId, definition.name]);
+    }
+    set(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        while (this.entries.size > MAX_CACHED_SHAPES) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+    get(connectorId, definition) {
+        try {
+            const key = this.cacheKey(connectorId, definition);
+            if (definition.outputSchema) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            if (!isExplicitlyReadOnly(definition)) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            const identity = definitionIdentity(definition);
+            if (!identity) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            const entry = this.entries.get(key);
+            if (!entry)
+                return undefined;
+            if (entry.definition !== identity || entry.expiresAt <= Date.now()) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            this.entries.delete(key);
+            this.entries.set(key, entry);
+            return cloneSchema(entry.schema);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    observe(connectorId, definition, value) {
+        try {
+            const key = this.cacheKey(connectorId, definition);
+            if (definition.outputSchema) {
+                this.entries.delete(key);
+                return;
+            }
+            if (!isExplicitlyReadOnly(definition)) {
+                this.entries.delete(key);
+                return;
+            }
+            const identity = definitionIdentity(definition);
+            const inferred = observedSchema(value);
+            if (!identity) {
+                this.entries.delete(key);
+                return;
+            }
+            if (!inferred)
+                return;
+            const current = this.entries.get(key);
+            const merged = boundSchema(current &&
+                current.definition === identity &&
+                current.expiresAt > Date.now()
+                ? mergeSchemas(current.schema, inferred)
+                : inferred, { nodes: 0 });
+            if (!merged || !serializedSchema(merged))
+                return;
+            this.set(key, {
+                definition: identity,
+                expiresAt: Date.now() + OBSERVATION_TTL_MS,
+                schema: merged,
+            });
+        }
+        catch {
+            // Observation is an optimization. A provider success stays successful.
+        }
+    }
+}

package/dist/routes/mcp.js

@@ -186,7 +186,7 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
             // it — without this line no host reads execute_code's _meta.ui, no host
             // fetches the shell, and the whole design is inert. This is the one
             // extension connecta advertises; the versioned extensions framework
-            // stays declined as a general surface (documentation/mcp-2026-07-28.md).
+            // stays declined as a general surface (https://github.com/zackbart/connecta/blob/main/records/mcp-2026-07-28.md).
             capabilities: {
                 extensions: {
                     [MCP_APPS_EXTENSION]: { mimeTypes: [PROGRAM_UI_MIME_TYPE] },

package/dist/routes/oauth.js

@@ -174,9 +174,9 @@ function html(body, status = 200, branding) {
  * list the flat 400 was meant to withhold. So zero-I/O refusals read the same
  * keys in the same `conn:<id>:` namespace, where an unconfigured id gets misses.
  *
- * This is deliberately *not* a constant-time claim, and documentation/connectors.md says
- * so in prose: a hit and a miss are not identical in a KV store, and a connector
- * shipping its own `verifyState` may do more or less work. What it
+ * This is deliberately *not* a constant-time claim: a hit and a miss are not
+ * identical in a KV store, and a connector shipping its own `verifyState` may
+ * do more or less work. What it
  * removes is the order-of-magnitude "no I/O versus a round trip" difference,
  * which is the only part of the signal that makes enumeration cheap.
  *

package/dist/routes/shared.d.ts

@@ -6,38 +6,39 @@ import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
 import type { ConnectaBranding, Executor, InboundAuth, Logger } from "../types.js";
+export { msg } from "../errors.js";
 export interface ServerOptions {
     registry: Registry;
     auth: InboundAuth[];
-    publicUrl?: string;
+    publicUrl?: string | undefined;
     serverInfo: Implementation;
     logger: Logger;
-    activity?: ActivityStore;
-    activityReadGate?: ActivityReadGate;
-    activityDeploymentId?: string;
-    deploymentInfo?: Record<string, unknown>;
+    activity?: ActivityStore | undefined;
+    activityReadGate?: ActivityReadGate | undefined;
+    activityDeploymentId?: string | undefined;
+    deploymentInfo?: Record<string, unknown> | undefined;
     /** Deadline for call_tool/call_destructive_tool calls that pass no timeoutMs. Off when unset. */
-    defaultToolTimeoutMs?: number;
+    defaultToolTimeoutMs?: number | undefined;
     /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
-    probeTimeoutMs?: number;
+    probeTimeoutMs?: number | undefined;
     /** Maximum simultaneous connector discovery operations. Default 4. */
-    discoveryConcurrency?: number;
+    discoveryConcurrency?: number | undefined;
     /** Aggregate serialized-byte budget for connecta.emit per run. Default 4_000_000. */
-    maxEmittedBytes?: number;
+    maxEmittedBytes?: number | undefined;
     /** Block-count budget for connecta.emit per run. Default 32. */
-    maxEmittedBlocks?: number;
+    maxEmittedBlocks?: number | undefined;
     /** Required sandbox backing the execute_code meta-tool. */
     executor: Executor;
     /** Sanitized identity of the configured sandbox, when it has one. */
-    executorName?: string;
+    executorName?: string | undefined;
     /** Global FIFO boundary for all non-preflight `/mcp` requests. */
     requestAdmission: AdmissionController;
     /** Encrypted connector-credential storage backing the Credentials page. */
-    credentialVault?: CredentialVault;
+    credentialVault?: CredentialVault | undefined;
     /** Hashed deployment access tokens backing MCP admission and the Tokens page. */
-    accessTokens?: AccessTokenManager;
+    accessTokens?: AccessTokenManager | undefined;
     /** Optional browser UI and OAuth result-page labels. */
-    branding?: ConnectaBranding;
+    branding?: ConnectaBranding | undefined;
 }
 export interface RuntimeExecutionContext {
     waitUntil(promise: Promise<unknown>): void;
@@ -51,7 +52,6 @@ export interface RouteContext {
     defer: DeferredWork | undefined;
     runtimeContext: RuntimeExecutionContext | undefined;
 }
-export declare function msg(err: unknown): string;
 export declare function privateJson(body: unknown, init?: ResponseInit): Response;
 /**
  * Bounded, escaped form of a caller-influenced value (an identity id or OAuth

package/dist/routes/shared.js

@@ -1,7 +1,5 @@
 import { operatorPageForPath } from "../ui.js";
-export function msg(err) {
-    return err instanceof Error ? err.message : String(err);
-}
+export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
     const headers = new Headers(init.headers);
     headers.set("Content-Type", "application/json");

package/dist/skills.js

@@ -23,13 +23,13 @@ The minimum guest API is:
 
 Search inside the run and finish the task there. A discovery-only program wastes a round trip. Use 2–4 distinctive action/object terms, not the full request. Use separate short searches for distinct operations.
 
-For top-level \`search_tools\`, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and declared output shapes. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
+For top-level \`search_tools\`, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An observed shape carries \`outputSchemaSource: "observed"\`; treat it as routing evidence rather than a provider contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
 
 - \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for program calls. These inputs filter discovery; they grant no authority.
-- Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and declared outputs. Never select only because a result ranks first or has fewer required inputs.
+- Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and available outputs. Never select only because a result ranks first or has fewer required inputs.
 - Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
 - Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
-- Reduce through declared output keys. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
+- Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
 
 Only tools explicitly annotated \`readOnlyHint: true\` are reachable. The catalog, credential, admission, and read-only gates run below the sandbox; code cannot widen its authority.