@zackbart/connecta 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -2,6 +2,141 @@
 
 All notable changes to this package are documented here.
 
+## 0.10.6 — 2026-07-31
+
+Programs gained a rich-output channel. `execute_code` code can now call
+`connecta.emit(block)` to deliver text, image, and audio MCP content blocks
+alongside its JSON return value — the piece code mode was missing for output
+that cannot be projected, like a screenshot a downstream tool returned. The
+channel is additive: a program that never emits produces the byte-for-byte
+prior response, no executor changed to carry it, and deployments that do
+nothing get sensible budgets. The design record is
+`documentation/rich-output-design.md` (#267); the contract is `code-mode.md`'s
+"Emitted output" clauses (#270).
+
+Agent recovery is now executable data instead of prose at the remaining local
+failure points. Address mistakes, approval reroutes, shortcut collisions, and
+paged results identify their next call directly; activity classifies those
+moments without retaining payloads. Connector behavior and approval authority
+are unchanged.
+
+Alongside both, three pieces of runtime text stop naming tools the receiving
+surface does not serve — a routing failure connecta authored itself, and one the
+always-loaded-text sweep missed because it only reads descriptions, not error
+strings and tool results. All three fixes are agent-visible wording; no wire
+shape, tool surface, or policy changes. Operators who tightened
+`discovery.probeTimeoutMs` also get that deadline honored inside `execute_code`,
+which had been probing at the 30-second default no matter what was configured.
+
+### Added
+
+- **`connecta.emit(block)` inside `execute_code`.** Strictly validated
+  `text` / `image` / `audio` blocks, collected host-side and appended to the
+  result after the JSON envelope on success only; a failed program discards
+  them visibly (`emittedDiscarded`). Budgets fail loudly at the emit call and
+  spend no host-call budget.
+- **`ConnectaConfig.execute.maxEmittedBytes` / `.maxEmittedBlocks`.** The
+  emission budgets, defaulting to 4,000,000 serialized bytes and 32 blocks per
+  run.
+- **`diagnostics.emitted`.** With `diagnostics: true`, one payload-free
+  aggregate (block count and serialized bytes) when a program emitted.
+- **Local routing failures carry structured recovery.** Unknown addresses and
+  tools suggest scoped discovery, read-path policy refusals preserve the
+  canonical address for `call_destructive_tool` — with the original arguments
+  when they fit a 512-byte echo budget, and an instruction to re-send them when
+  they do not — and ambiguous code-mode aliases list every canonical
+  `connecta.call` candidate. The suggested discovery route follows the caller's
+  own surface: `search_tools` for a top-level call, `connecta.search` with the
+  same arguments for a miss inside `execute_code`, which cannot call a tool.
+  The address gets the same 512-byte budget as the argument echo but the
+  opposite rule — clamped with a `…` marker rather than dropped, since the
+  address is the thing being corrected. Short addresses, which is all real
+  ones, come back exact.
+- **Destructive calls accept explanatory context.** An optional `reason` of at
+  most 500 characters gives the MCP host human-readable intent without entering
+  downstream arguments or granting authority. An empty or whitespace-only one
+  is treated as absent rather than failing the call.
+- **Activity exposes coarse agent friction.** Typed codes derive
+  `tool_not_found`, `schema_retry`, `destructive_reroute`, `auth_required`, or
+  `result_too_large`; no payload or raw error text is added.
+
+### Changed
+
+- **Paged results name the exact next call.** `call_tool` and `batch_call`
+  truncation notices include `get_result` arguments with the generated id and
+  byte offset zero. Program results and oversized discovery responses still
+  carry no `get_result` route: paging a program's return value is refused by
+  design, and a program can shrink anything.
+- **`nextAction` is a wider union than it was.** `search_tools` routes may now
+  omit `arguments.connector` (an unknown *connector* cannot scope discovery to
+  itself), the ambiguous-alias route is keyed `function: "connecta.call"` with
+  no `tool` at all, and in-program discovery recovery is keyed
+  `function: "connecta.search"` carrying the same `{ query, connector?,
+  includeSchemas }` arguments the tool route does. A consumer that narrowed on
+  `nextAction.tool` must handle the function-keyed shapes too.
+- **An address that resolves to nothing is now recorded.** A call to a
+  connector id that does not exist emits one activity event at the address as
+  written, with `unknown_address` and `tool_not_found` friction — provided the
+  address splits into the `<connectorId>.<toolName>` shape activity keeps; one
+  with no interior dot still records nothing. Previously the single most common
+  address mistake left no trace at all. Addresses were already a first-class
+  activity field; nothing new is retained. Because those fields now hold
+  caller-authored text, the recording seam clamps `connectorId` and `toolName`
+  at 128 UTF-8 bytes each and `address` at 257, marked with `…` — far past any
+  real id, far short of an invented 40 KB one.
+- **A truncated result is friction, not an error.** An oversized result reports
+  `friction: "result_too_large"` on an `outcome: "success"` event and writes no
+  `errorCode`, so consumers counting error codes stop counting truncated
+  successes as failures. The Worker D1 example gains a `friction` column;
+  existing tables need `ALTER TABLE tool_call_activity ADD COLUMN friction
+  TEXT` before deploying it.
+
+### Fixed
+
+- **Discovery errors stay on their advertised surface.** The over-100-address
+  rejection and the catalog-probe timeout label now name `describe_tools` or
+  `connecta.describe` according to the route the caller actually took, so a
+  program is never told to split its list across a tool it cannot call. The
+  route is passed in explicitly rather than inferred from the deployment's
+  surface: a classic deployment with an executor serves `describe_tools` at top
+  level while every in-program describe still arrives through
+  `connecta.describe`.
+- **The OAuth handoff points at a check the caller can run.** `authorize_connector`
+  is registered on both surfaces, but its success instructions told every agent
+  to "re-run `list_connectors`" — a tool the code-first surface folded away. A
+  code-first deployment is now told to retry the original call and confirm the
+  catalog loads with `connecta.search` inside `execute_code`; the classic
+  wording is unchanged.
+- **`discovery.probeTimeoutMs` reaches code mode.** The sandbox's catalog
+  service received the deployment's discovery concurrency but not its probe
+  deadline, so an in-program `connecta.describe` against a hung connector waited
+  the 30-second default regardless of operator configuration.
+
+## 0.10.5 — 2026-07-30
+
+A consumer-audit recovery release. Schema discovery now provides the bounded
+key contracts an agent needs before its first read, a single-address describe
+no longer requires plural ceremony, and field-projection failures teach the
+array syntax when that is the likely mistake. Discovery payload ceilings and
+write admission are unchanged.
+
+### Changed
+
+- **Schema search exposes usable key contracts on both surfaces.**
+  `search_tools` now includes `inputKeys`, `requiredInputKeys`, and `outputKeys`
+  alongside bounded plain-object schemas, matching code-mode discovery.
+  Truncated shapes omit their corresponding key list instead of repeating a
+  large partial inventory.
+- **One address has a singular describe form.**
+  `connecta.describe({ address: "connector.tool" })` complements the bounded
+  plural form. Supplying both forms is rejected with a direct conflict error.
+
+### Fixed
+
+- **Projection misses teach array traversal when applicable.** Tool guidance
+  documents `results[].id`, and a plausible `results.id` miss gains a targeted
+  hint when the declared output schema confirms the array path.
+
 ## 0.10.4 — 2026-07-30
 
 A small code-mode recovery release. The `execute_code` contract now shows the

package/dist/activity.d.ts

@@ -1,6 +1,9 @@
 import type { Logger } from "./types.js";
 export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code";
 export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled";
+export type AgentFriction = "tool_not_found" | "schema_retry" | "destructive_reroute" | "auth_required" | "result_too_large";
+/** Coarse recovery class derived without inspecting payloads or error prose. */
+export declare function agentFrictionForCode(code: string | undefined): AgentFriction | undefined;
 /**
  * Authenticated identity attached to an activity event. `id` is intentionally
  * optional: open deployments and shared bearer tokens cannot honestly identify
@@ -36,7 +39,14 @@ export interface ToolCallActivityEvent {
     outcome: ActivityOutcome;
     durationMs: number;
     attempts: number;
+    /** Set only when the call actually failed; a truncated success has none. */
     errorCode?: string;
+    /**
+     * Payload-free recovery class. Usually derived from `errorCode`, but it can
+     * also stand alone: a result too large to return inline is friction for the
+     * agent while remaining an `outcome: "success"` call with no error code.
+     */
+    friction?: AgentFriction;
     serverName: string;
     serverVersion: string;
     deploymentId?: string;
@@ -89,7 +99,7 @@ export interface ActivityRequestContext {
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode">;
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction">;
 /**
  * Best-effort by design: activity storage can never change a tool result.
  * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics

package/dist/activity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}

package/dist/activity.js

@@ -1,3 +1,40 @@
+import { boundedEchoText } from "./errors.js";
+/**
+ * How long an identity field may be before the store stops believing it.
+ *
+ * `connectorId` and `toolName` are ordinarily operator- and connector-authored,
+ * and 128 bytes is far past any real one. But an address that resolved to
+ * nothing is recorded *as written*, which puts a caller-authored string in both
+ * fields — and "payload-free by construction" has to mean the event type has
+ * nowhere to put a payload, not merely that connecta declines to. A 40 KB
+ * invented connector id is a payload wearing an id's clothing.
+ *
+ * Clamped rather than dropped: the invented id is precisely what an operator
+ * needs to see, and its first 128 bytes identify the mistake as well as all
+ * 40,000 would. The `…` marker keeps a clamped value from reading as a real one.
+ */
+const MAX_ACTIVITY_NAME_BYTES = 128;
+/** Two names and the dot between them. */
+const MAX_ACTIVITY_ADDRESS_BYTES = MAX_ACTIVITY_NAME_BYTES * 2 + 1;
+/** Coarse recovery class derived without inspecting payloads or error prose. */
+export function agentFrictionForCode(code) {
+    switch (code) {
+        case "unknown_address":
+        case "unknown_tool":
+        case "ambiguous_tool_alias":
+            return "tool_not_found";
+        case "invalid_args":
+            return "schema_retry";
+        case "destructive_tool_requires_approval":
+            return "destructive_reroute";
+        case "auth_required":
+            return "auth_required";
+        case "result_too_large":
+            return "result_too_large";
+        default:
+            return undefined;
+    }
+}
 /** Reader implementations throw this for an opaque cursor they cannot decode. */
 export class InvalidActivityCursorError extends Error {
     name = "InvalidActivityCursorError";
@@ -13,20 +50,24 @@ export class InvalidActivityCursorError extends Error {
 export function recordToolActivity(context, input) {
     if (!context)
         return;
+    // A caller-supplied class wins because it knows something the code table
+    // cannot: friction that belongs to a call which did not fail.
+    const friction = input.friction ?? agentFrictionForCode(input.errorCode);
     const event = {
         schemaVersion: 1,
         id: crypto.randomUUID(),
         occurredAt: new Date().toISOString(),
         requestId: context.requestId,
         actor: context.actor,
-        connectorId: input.connectorId,
-        toolName: input.toolName,
-        address: input.address,
+        connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
+        toolName: boundedEchoText(input.toolName, MAX_ACTIVITY_NAME_BYTES),
+        address: boundedEchoText(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
         source: input.source,
         outcome: input.outcome,
         durationMs: Math.max(0, Math.trunc(input.durationMs)),
         attempts: Math.max(1, Math.trunc(input.attempts)),
         ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+        ...(friction ? { friction } : {}),
         serverName: context.serverInfo.name,
         serverVersion: context.serverInfo.version,
         ...(context.deploymentId

package/dist/activity.js.map

@@ -1 +1 @@
-{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAyFA,iFAAiF;AACjF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,GAAG,4BAA4B,CAAC;IAE7C;QACE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACnC,CAAC;CACF;AA6BD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA2C,EAC3C,KAAyB;IAEzB,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,KAAK,GAA0B;QACnC,aAAa,EAAE,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI;QACnC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO;QACzC,GAAG,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE;YACxC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAQ,MAA2B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACvE,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACtD,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}

package/dist/catalog-service.d.ts

@@ -5,6 +5,24 @@ export declare const DEFAULT_SEARCH_LIMIT = 8;
 export declare const MAX_SEARCH_LIMIT = 100;
 export declare const MAX_DESCRIBE_ADDRESSES = 100;
 export declare const MAX_DISCOVERY_RESULT_BYTES = 256000;
+/**
+ * The tool a describe-path error should name when it tells a caller to retry.
+ * This is the route the *caller* took, not the deployment's advertised surface:
+ * a classic deployment with an executor serves `describe_tools` at top level
+ * while every in-program describe still arrives through `connecta.describe`, so
+ * one CatalogService cannot infer the answer from `surface` alone. Callers pass
+ * the route they own.
+ */
+export type DescribeRoute = "describe_tools" | "connecta.describe";
+/**
+ * The discovery route a routing failure should send a caller back through. Same
+ * rule as {@link DescribeRoute} — the route the *caller* took, not the
+ * deployment's advertised surface — with one difference worth keeping the two
+ * options separate for: `search_tools` exists on both advertised surfaces, so a
+ * top-level handler never has to derive this one, while an in-program caller
+ * still has to be told about `connecta.search` because it cannot call a tool.
+ */
+export type SearchRoute = "search_tools" | "connecta.search";
 export declare class DiscoveryPolicyError extends Error {
     readonly code: "invalid_args" | "result_too_large";
     constructor(code: "invalid_args" | "result_too_large", message: string);
@@ -27,6 +45,7 @@ export interface CatalogSearchArgs {
     includeSchemaKeys?: boolean;
 }
 export interface CatalogDescribeArgs {
+    address?: unknown;
     addresses?: unknown;
     format?: "compact" | "json";
     fullDescriptions?: boolean;
@@ -105,13 +124,34 @@ export declare class CatalogService {
     readonly requestScope: object;
     private readonly probeTimeoutMs;
     private readonly concurrency;
+    private readonly describeRoute;
+    private readonly searchRoute;
     private readonly loaded;
     private readonly loading;
     constructor(registry: RegistryView, baseUrl: string, options?: {
         requestScope?: object;
         probeTimeoutMs?: number;
         concurrency?: number;
+        /** The tool describe-path errors name. Default `describe_tools`. */
+        describeRoute?: DescribeRoute;
+        /** The discovery route recovery records name. Default `search_tools`. */
+        searchRoute?: SearchRoute;
     });
+    /**
+     * Send a caller back to discovery through the surface it can actually reach.
+     * Both variants carry the same scoping arguments because `connecta.search`
+     * takes the same ones `search_tools` does; only the key naming the callable
+     * differs, the way the ambiguous-alias record already names a function.
+     *
+     * Not private: `InvocationService` builds the same class of record when a
+     * call fails schema validation, and it is this catalog's route that decides
+     * which key that record carries. Duplicating the branch there would let the
+     * two drift.
+     */
+    searchRecovery(args: {
+        query: string;
+        connector?: string;
+    }, purpose: string): NonNullable<CallErrorDetails["nextAction"]>;
     loadConnector(id: string, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
     private loadForDiscovery;
     resolveTool(address: string, callOptions?: ConnectorOperationOptions): Promise<CatalogResolution>;

package/dist/catalog-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"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"}

package/dist/catalog-service.js

@@ -1,6 +1,6 @@
 import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
-import { classifyCallError, framingError } from "./errors.js";
+import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorSkillName, } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
@@ -31,16 +31,35 @@ function discoverySearchLimit(value) {
     }
     return value;
 }
-/** Validate the raw list so duplicate addresses consume the same bound. */
-function discoveryAddresses(value) {
+/** Normalize the single-address convenience form, then validate the bounded list. */
+function discoveryAddresses(args, describeRoute) {
+    if (args.address !== undefined && args.addresses !== undefined) {
+        throw new DiscoveryPolicyError("invalid_args", "describe takes either address or addresses, not both.");
+    }
+    const value = args.address !== undefined
+        ? typeof args.address === "string"
+            ? [args.address]
+            : undefined
+        : args.addresses;
     if (!Array.isArray(value)) {
-        throw new DiscoveryPolicyError("invalid_args", 'describe takes { addresses: ["<connectorId>.<toolName>", ...] }; addresses must be an array.');
+        throw new DiscoveryPolicyError("invalid_args", 'describe takes { address: "<connectorId>.<toolName>" } or { addresses: ["<connectorId>.<toolName>", ...] }.');
     }
     if (value.length > MAX_DESCRIBE_ADDRESSES) {
-        throw new DiscoveryPolicyError("invalid_args", `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across describe_tools calls.`);
+        throw new DiscoveryPolicyError("invalid_args", `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across ${describeRoute} calls.`);
     }
     return value;
 }
+/**
+ * Search terms derived from an address the catalog could not resolve. Bounded
+ * because the address is entirely caller-authored: an invented one can be any
+ * length, and this string is copied into a recovery record that is itself
+ * copied into both halves of the result envelope.
+ */
+function recoveryQuery(address) {
+    const separator = address.indexOf(".");
+    const candidate = separator >= 0 ? address.slice(separator + 1) : address;
+    return boundedEchoText(candidate.replaceAll(/[._-]+/g, " ").trim() || address);
+}
 /** Serialize once and count the exact bytes the MCP adapter would emit. */
 export function boundedDiscoveryText(value, hint) {
     const text = JSON.stringify(value);
@@ -108,6 +127,8 @@ export class CatalogService {
     requestScope;
     probeTimeoutMs;
     concurrency;
+    describeRoute;
+    searchRoute;
     loaded = new Map();
     loading = new Map();
     constructor(registry, baseUrl, options = {}) {
@@ -117,6 +138,29 @@ export class CatalogService {
         this.probeTimeoutMs =
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
+        this.describeRoute = options.describeRoute ?? "describe_tools";
+        this.searchRoute = options.searchRoute ?? "search_tools";
+    }
+    /**
+     * Send a caller back to discovery through the surface it can actually reach.
+     * Both variants carry the same scoping arguments because `connecta.search`
+     * takes the same ones `search_tools` does; only the key naming the callable
+     * differs, the way the ambiguous-alias record already names a function.
+     *
+     * Not private: `InvocationService` builds the same class of record when a
+     * call fails schema validation, and it is this catalog's route that decides
+     * which key that record carries. Duplicating the branch there would let the
+     * two drift.
+     */
+    searchRecovery(args, purpose) {
+        const searchArgs = {
+            query: args.query,
+            ...(args.connector !== undefined ? { connector: args.connector } : {}),
+            includeSchemas: "compact",
+        };
+        return this.searchRoute === "connecta.search"
+            ? { function: "connecta.search", arguments: searchArgs, purpose }
+            : { tool: "search_tools", arguments: searchArgs, purpose };
     }
     async loadConnector(id, callOptions = {}) {
         const cached = this.loaded.get(id);
@@ -149,7 +193,10 @@ export class CatalogService {
         if (!resolved) {
             return {
                 ok: false,
-                error: framingError("unknown_address", `Unknown address "${address}"`),
+                error: {
+                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
+                    nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
+                },
                 catalogMs: 0,
             };
         }
@@ -172,7 +219,13 @@ export class CatalogService {
         if (!definition) {
             return {
                 ok: false,
-                error: framingError("unknown_tool", `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`),
+                error: {
+                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(resolved.toolName)}" on connector "${resolved.connector.id}"`),
+                    nextAction: this.searchRecovery({
+                        query: recoveryQuery(resolved.toolName),
+                        connector: resolved.connector.id,
+                    }, "Find the connector's current canonical tool address."),
+                },
                 catalogMs: Date.now() - started,
                 connector: resolved.connector,
                 toolName: resolved.toolName,
@@ -198,7 +251,10 @@ export class CatalogService {
         if (!connector) {
             return {
                 ok: false,
-                error: framingError("unknown_address", `Unknown address "${connectorId}.${alias}"`),
+                error: {
+                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(`${connectorId}.${alias}`)}"`),
+                    nextAction: this.searchRecovery({ query: recoveryQuery(alias) }, "Find the configured canonical address before retrying."),
+                },
                 catalogMs: 0,
             };
         }
@@ -221,7 +277,10 @@ export class CatalogService {
         if (!definition) {
             return {
                 ok: false,
-                error: framingError("unknown_tool", `Unknown tool "${alias}" on connector "${connector.id}"`),
+                error: {
+                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(alias)}" on connector "${connector.id}"`),
+                    nextAction: this.searchRecovery({ query: recoveryQuery(alias), connector: connector.id }, "Find the connector's current canonical tool address."),
+                },
                 catalogMs: Date.now() - started,
                 connector,
                 toolName: alias,
@@ -235,8 +294,13 @@ export class CatalogService {
                 ok: false,
                 error: {
                     code: "ambiguous_tool_alias",
-                    message: `Tool alias "${alias}" is ambiguous on connector "${connector.id}" because ${names} sanitize to the same name. Use connecta.call with an exact address.`,
+                    message: `Tool alias "${boundedEchoText(alias)}" is ambiguous on connector "${connector.id}" because ${names} sanitize to the same name. Use connecta.call with an exact address.`,
                     retryable: false,
+                    nextAction: {
+                        function: "connecta.call",
+                        addresses: [definition, ...collisions].map((tool) => `${connector.id}.${tool.name}`),
+                        purpose: "Choose the intended canonical address and call it with the original arguments.",
+                    },
                 },
                 catalogMs: Date.now() - started,
                 connector,
@@ -267,7 +331,12 @@ export class CatalogService {
                 ? [scopedConnector]
                 : []
             : this.registry.listConnectors();
-        const catalogs = await mapSettledWithConcurrency(connectors, this.concurrency, (connector) => this.loadForDiscovery(connector.id, `search_tools probe of "${connector.id}"`));
+        const catalogs = await mapSettledWithConcurrency(connectors, this.concurrency, (connector) => 
+        // Unlike the describe path, this label never reaches a caller: search
+        // only counts rejected catalogs (`unavailableCatalogs` below) and
+        // renders its own guidance, so the folded name here stays internal and
+        // needs no surface awareness.
+        this.loadForDiscovery(connector.id, `search_tools probe of "${connector.id}"`));
         const searchableCatalogs = catalogs.map((catalog) => catalog.status === "fulfilled"
             ? {
                 status: "fulfilled",
@@ -314,6 +383,9 @@ export class CatalogService {
             const renderedOutput = args.includeSchemas && match.tool.outputSchema
                 ? renderSearchSchema(match.tool.outputSchema, args.includeSchemas)
                 : undefined;
+            const schemaKeys = args.includeSchemas && args.includeSchemaKeys
+                ? schemaKeyMetadata(input, match.tool.outputSchema)
+                : undefined;
             const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
             return {
                 connector: match.connector,
@@ -340,8 +412,18 @@ export class CatalogService {
                     ...(renderedOutput?.truncated
                         ? { outputSchemaTruncated: true }
                         : {}),
-                    ...(args.includeSchemas && args.includeSchemaKeys
-                        ? schemaKeyMetadata(input, match.tool.outputSchema)
+                    ...(schemaKeys && !renderedInput?.truncated
+                        ? {
+                            ...(schemaKeys.inputKeys
+                                ? { inputKeys: schemaKeys.inputKeys }
+                                : {}),
+                            ...(schemaKeys.requiredInputKeys
+                                ? { requiredInputKeys: schemaKeys.requiredInputKeys }
+                                : {}),
+                        }
+                        : {}),
+                    ...(schemaKeys?.outputKeys && !renderedOutput?.truncated
+                        ? { outputKeys: schemaKeys.outputKeys }
                         : {}),
                     ...(match.tool.annotations
                         ? { annotations: match.tool.annotations }
@@ -437,7 +519,7 @@ export class CatalogService {
         };
     }
     async describe(args) {
-        const addresses = discoveryAddresses(args.addresses);
+        const addresses = discoveryAddresses(args, this.describeRoute);
         const format = args.format ?? "compact";
         const resolved = addresses.map((rawAddress) => {
             const address = String(rawAddress);
@@ -448,7 +530,7 @@ export class CatalogService {
                 .map((entry) => entry.resolved?.connector.id)
                 .filter((id) => Boolean(id))),
         ];
-        const loaded = await mapSettledWithConcurrency(connectorIds, this.concurrency, (id) => this.loadForDiscovery(id, `describe_tools probe of "${id}"`));
+        const loaded = await mapSettledWithConcurrency(connectorIds, this.concurrency, (id) => this.loadForDiscovery(id, `${this.describeRoute} probe of "${id}"`));
         const catalogs = new Map();
         loaded.forEach((result, index) => {
             const connectorId = connectorIds[index];