@zackbart/connecta 0.10.5 → 0.11.0

package/AGENTS.md

@@ -4,10 +4,10 @@ This is the canonical instruction file for coding agents. `CLAUDE.md` is a
 symlink to this file so every agent works from the same conventions.
 
 A single MCP endpoint aggregating downstream connectors (remote MCP servers and
-plain HTTP APIs) behind a small fixed set of meta-tools. A deployment with an
-executor serves seven, `execute_code` among them, and agents reach connectors by
-writing JavaScript against it; one without an executor serves the nine classic
-tools. One fetch-native core, running on both Node and Cloudflare Workers.
+plain HTTP APIs) behind seven meta-tools, `execute_code` among them. Every
+deployment configures an executor, and agents reach connectors by writing
+JavaScript against it. One fetch-native core, running on both Node and
+Cloudflare Workers.
 
 - **[`ethos.md`](./ethos.md) is the constitution.** It states what connecta is
   and isn't, and its decisions table carries a verdict for every shape already
@@ -15,8 +15,10 @@ tools. One fetch-native core, running on both Node and Cloudflare Workers.
   designing or building anything: a `refused` row is a "no" with the reason
   attached, and a `removed` row (toolkits
   [#178](https://github.com/zackbart/connecta/issues/178), proactive credential
-  liveness [#179](https://github.com/zackbart/connecta/issues/179)) records a
-  surface that no longer exists — do not reintroduce it without a new decision.
+  liveness [#179](https://github.com/zackbart/connecta/issues/179), the classic
+  executor-free surface
+  [#273](https://github.com/zackbart/connecta/issues/273)) records a surface
+  that no longer exists — do not reintroduce it without a new decision.
 - There is no TODO.md — the roadmap lives in
   [GitHub issues](https://github.com/zackbart/connecta/issues). When you find
   TODO items (in code comments, docs, or conversation), don't accumulate them

package/CHANGELOG.md

@@ -2,6 +2,156 @@
 
 All notable changes to this package are documented here.
 
+## 0.11.0 — 2026-07-31
+
+**This is a breaking deployment release.** Connecta no longer carries the old
+executor-free compatibility surface. Every deployment must configure an
+executor and now exposes the same seven tools; construction refuses to boot
+without one. Existing code-first deployments keep their model-facing surface.
+Node deployments that omitted an executor must add `quickJsExecutor()`, while
+Workers deployments must configure a `DynamicWorkerExecutor` and its paid-plan
+Worker Loader binding. Remove any `surface` setting during the upgrade. (#273)
+
+The consolidation also removes the classic-only handlers and configuration
+that had become two implementations of the same work. Discovery and batching
+now have one home inside `execute_code`, while `call_tool`,
+`call_destructive_tool`, and result retrieval remain explicit host boundaries.
+The superseded code-first gate has been reduced to its surviving measurement
+record instead of retaining a second executable version of the product.
+
+### Changed
+
+- **An executor is required.** `ConnectaConfig.executor` is no longer optional;
+  use `quickJsExecutor()` from `@zackbart/connecta/quickjs` on Node or
+  `DynamicWorkerExecutor` from `@cloudflare/codemode` on Workers. The CLI
+  template, examples, doctor, documentation, and package smoke test all enforce
+  the same deployment shape.
+- **Every MCP connection advertises exactly seven tools.** The former
+  top-level `list_connectors`, `describe_tools`, and `batch_call` registrations
+  are removed. Their supported equivalents are `connecta.search`,
+  `connecta.describe`, and `connecta.batch` inside `execute_code`.
+- **The old surface controls fail explicitly.** Supplying the removed
+  `ConnectaConfig.surface` option throws instead of being ignored. The
+  classic-only `calls.maxBatchResultBytes` option also throws; program batching
+  is bounded by the executor and `connecta.batch` limits, while individual
+  calls still honor `calls.maxResultBytes` and connector overrides.
+- **Cloudflare deployments require code mode.** The Worker example now requires
+  its `worker_loaders` binding and the Workers Paid plan rather than falling
+  back to the classic surface when the binding is absent.
+- **The retired code-first gate is archival.** Its executable harness is
+  removed now that code-first is the sole product surface; the current-version
+  audit remains the live measurement path.
+
+## 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

package/README.md

@@ -69,7 +69,8 @@ my-connecta/
 For an agent setting this up, the contract is:
 
 1. Edit `src/index.ts`; do not copy Connecta internals into the deployment.
-2. Keep `executor: quickJsExecutor()` for the prescribed seven-tool surface.
+2. Keep the required `executor: quickJsExecutor()` configuration; without an
+   executor the deployment refuses to boot.
 3. Keep secrets in environment variables or a secret store, never source.
 4. Add code only for deliberate `api()` connectors.
 5. Run `npm run typecheck`, start the server, and run
@@ -92,9 +93,9 @@ Other supported deployment shapes:
 - [Cloudflare Worker deployment](./examples/worker/)
 - [Subsystem documentation](./documentation/)
 
-Configuring a sandbox — QuickJS on Node or a Dynamic Worker on Cloudflare — is
-what selects the code-first surface and is the assumed posture. A deployment
-without one keeps the earlier nine-tool compatibility interface.
+Every deployment configures a sandbox: QuickJS on Node or a Dynamic Worker on
+Cloudflare. Construction fails with an actionable error when the executor is
+missing, so the model-facing interface is always the same seven tools.
 
 ## Project status
 

package/bin/connecta.mjs

@@ -186,13 +186,6 @@ async function doctor() {
   if (health.status !== "ok") {
     throw new Error(`Unexpected health status: ${String(health.status)}`);
   }
-  if (health.admission?.code === null) {
-    throw new Error(
-      "The server has no executor and is serving classic compatibility. " +
-        "Keep executor: quickJsExecutor() for the prescribed surface.",
-    );
-  }
-
   let requestId = 0;
   const mcp = async (method, params) =>
     jsonResponse(

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,12 @@ 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 discovery route a routing failure should send a caller back through. Same
+ * catalog logic serves both the top-level `search_tools` path and the
+ * in-program `connecta.search` path, so callers pass the route they own.
+ */
+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);
@@ -106,13 +112,31 @@ export declare class CatalogService {
     readonly requestScope: object;
     private readonly probeTimeoutMs;
     private readonly concurrency;
+    private readonly searchRoute;
     private readonly loaded;
     private readonly loading;
     constructor(registry: RegistryView, baseUrl: string, options?: {
         requestScope?: object;
         probeTimeoutMs?: number;
         concurrency?: number;
+        /** 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";
@@ -45,10 +45,21 @@ function discoveryAddresses(args) {
         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 connecta.describe 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);
@@ -116,6 +127,7 @@ export class CatalogService {
     requestScope;
     probeTimeoutMs;
     concurrency;
+    searchRoute;
     loaded = new Map();
     loading = new Map();
     constructor(registry, baseUrl, options = {}) {
@@ -125,6 +137,28 @@ export class CatalogService {
         this.probeTimeoutMs =
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
+        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);
@@ -157,7 +191,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,
             };
         }
@@ -180,7 +217,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,
@@ -206,7 +249,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,
             };
         }
@@ -229,7 +275,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,
@@ -243,8 +292,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,
@@ -275,7 +329,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",
@@ -469,7 +528,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, `connecta.describe probe of "${id}"`));
         const catalogs = new Map();
         loaded.forEach((result, index) => {
             const connectorId = connectorIds[index];