@zackbart/connecta 0.37.1 → 0.39.0

package/dist/http/vendor.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // A vendor is an `HttpApi`: endpoints with Schemas for path params, query,
 // and payload, from which requests are encoded and the endpoint manifest is
@@ -13,13 +13,13 @@
 // empty 200. Every answer, from a declared operation or a hatch's path, takes
 // one route: bounded read, JSON, closed public classifier facts captured,
 // the request's sent secrets redacted from
-// every value of the whole body before anything can cut or extract from it
-// (#911), its keys kept for value safety to match by name, status (with
+// every value of the whole body before anything can cut or extract from it,
+// its keys kept for value safety to match by name, status (with
 // its operation, so value safety decides what a failure may quote), the
 // vendor's `result` hook, then the connection's ResultSafety. A provider
 // cannot reach a body earlier. A Content-Type redaction altered selects the
 // format the vendor reads as JSON, so no altered type routes a body around
-// ResultSafety as text or bytes (#703).
+// ResultSafety as text or bytes.
 import { Context, Effect } from "effect";
 import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import * as HttpApi from "effect/http-api/HttpApi";
@@ -233,12 +233,12 @@ export function connect(vendor, guarded, options) {
                     : defect)));
             });
             // Header-derived format decisions see only redacted Content-Type. Names are protocol
-            // constants `Headers` must accept, so only the values are redacted, together (#703).
+            // constants `Headers` must accept, so only the values are redacted, together.
             const entries = [...reply.headers];
             const values = secrets.redact(entries.map(([, value]) => value));
             const headers = new Headers(entries.map(([name], index) => [name, values[index]]));
             // Whole, before a detail line trims it or a projection extracts from it. Values only:
-            // result safety and projections match fields by their vendor names (#703).
+            // result safety and projections match fields by their vendor names.
             let classifierFacts;
             const parsed = reply.bytes !== undefined
                 ? {
@@ -400,7 +400,7 @@ export function connect(vendor, guarded, options) {
 /**
  * The Content-Type a format decision reads. One redaction altered reads as
  * `application/json`: a vendor's text or binary choice for it would hand
- * result safety a body it cannot read field by field (#703).
+ * result safety a body it cannot read field by field.
  */
 function formatType(redacted) {
     return redactionAltered(redacted) ? "application/json" : redacted.toLowerCase();

package/dist/identity.js

@@ -1,5 +1,5 @@
+import { sha256Hex } from "./bytes.js";
 const IDENTITY_PART_RE = /^[\x21-\x7e]{1,256}$/;
-const encoder = new TextEncoder();
 export function validIdentityReference(value) {
     return Boolean(value &&
         typeof value.namespace === "string" &&
@@ -7,11 +7,7 @@ export function validIdentityReference(value) {
         IDENTITY_PART_RE.test(value.namespace) &&
         IDENTITY_PART_RE.test(value.id));
 }
-function bytesToHex(bytes) {
-    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
 /** Deterministic pseudonymous partition; raw emails and ids do not enter keys. */
 export async function identityStorageKey(identity) {
-    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(`${identity.namespace}\n${identity.id}`));
-    return bytesToHex(new Uint8Array(digest));
+    return sha256Hex(`${identity.namespace}\n${identity.id}`);
 }

package/dist/index.d.ts

@@ -41,6 +41,6 @@ export type { Registry } from "./registry.js";
 export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRequestAuth, RemoteMcpRedirectPolicy, } from "./connectors/remote-mcp.js";
 export type { AgentRequestPrincipal, HumanRequestPrincipal, PrincipalForwarding, PrincipalRequestToken, RequestPrincipal, RequestPrincipalPolicy, RequestToken, RequestTokenInput, } from "./request-token.js";
 export type { ApiHandlerContext, ApiOAuthAccess, ApiOAuthClientAuthentication, ApiOAuthConfig, ApiOptions, ApiTool, } from "./connectors/api.js";
-export type { ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, ConnectorUsageGuide, ConnectorSkill, ConnectorSkillResourceContents, DescribedEndpoint, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
+export type { ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, AgentRouteNames, ConnectorContext, ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, ConnectorUsageGuide, ConnectorSkill, ConnectorSkillResourceContents, DescribedEndpoint, ConnectorStatus, CredentialFailureClass, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
 export type { ActivityActor, ActivityCatalogChange, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, ToolCallActivityEvent, } from "./activity.js";
 export { META_TOOL_NAMES } from "./meta-tool-names.js";

package/dist/index.js

@@ -1,10 +1,11 @@
+import { deploymentRoutes } from "./agent-routes.js";
 import { describeConfigSources } from "./config-value-sources.js";
 import { credentialTestRule, describeCredentialTestMismatch } from "./credential-rules.js";
 import { Registry } from "./registry.js";
 import { parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
 import { assertsAgents } from "./agent-identity.js";
 import { ConfigError } from "./config-schema.js";
-import { memberContext, resolveMaintainers, resolveMembers, } from "./membership.js";
+import { memberContext, peopleInSeveralPools, resolveMaintainers, resolvePoolMembers, } from "./membership.js";
 import { createFetchHandler } from "./server.js";
 import { droppedBrandingUrls, droppedThemeTokens, droppedUiAuthUrls } from "./branding.js";
 import { readConfig } from "./config.js";
@@ -68,7 +69,7 @@ function resolvePools(pools, readOnly, registry, members) {
         resolved.set(name, Object.freeze({
             access,
             readOnly: pool.readOnly ?? readOnly,
-            members: Object.freeze(resolveMembers(pool.members, path, members)),
+            members: Object.freeze(resolvePoolMembers(pool.members, path, members)),
             ...(pool.owner !== undefined ? { owner: pool.owner.trim() } : {}),
             ...(pool.description !== undefined ? { description: pool.description.trim() } : {}),
             ...(pool.surface === "native" ? { native: { executeCode: pool.executeCode ?? true } } : {}),
@@ -185,6 +186,7 @@ export function createConnecta(config) {
     // Every structural check runs here, before any work: what comes back is the
     // configuration the deployment runs with, defaults applied once.
     const { input, resolved } = readConfig(config);
+    const routes = deploymentRoutes(config);
     const { logger } = resolved;
     const storage = resolved.storage;
     const registry = new Registry([...resolved.connectors], {
@@ -208,10 +210,14 @@ export function createConnecta(config) {
         maxResultBytes: resolved.calls.maxResultBytes,
         results: resolved.results,
         classification: resolved.classification,
+        routes,
     });
     const members = memberContext(resolved.auth, resolved.agents);
     const maintainers = resolveMaintainers(input.maintainers, resolved.auth.some((provider) => !assertsAgents(provider)), members);
     const pools = resolvePools(resolved.pools, resolved.readOnly, registry, members);
+    for (const person of peopleInSeveralPools(pools, maintainers)) {
+        logger.warn("[connecta] Plain /mcp refuses a person in several pools", person);
+    }
     warnInsecureConfig(resolved);
     const requestAdmission = new AdmissionController(resolved.admission.requests);
     let codeAdmission;
@@ -249,6 +255,7 @@ export function createConnecta(config) {
         executor,
         executorName: configuredExecutorName,
         requestAdmission,
+        routes,
     });
     let closePromise;
     return {

package/dist/invocation-auth.js

@@ -1,3 +1,4 @@
+import { bytesToHex } from "./bytes.js";
 import { authCall, authFlow, registerAuth } from "./auth/native.js";
 import { upwardStep } from "./upward.js";
 import { runEdge } from "./runtime/run.js";
@@ -34,7 +35,7 @@ export async function classificationDigest(definition) {
             annotations,
             schema,
         }));
-        return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
     }
     catch {
         // A digest refusal blocks recovery, not an ordinary call.

package/dist/invocation.js

@@ -1,3 +1,4 @@
+import { routePhrases } from "./agent-routes.js";
 import { authCall, registerAuthMethod } from "./auth/native.js";
 import { withAuthorizationHandoffEffect } from "./authorization-handoff.js";
 import { hasControlCharacters } from "./tool-name.js";
@@ -9,7 +10,7 @@ import { downstreamValue } from "./mcp-result.js";
 import { carryFailureFacts, classifiedFailure, failureRecord, logFailure, recordedToolName, } from "./operator-record.js";
 import { splitAddress } from "./registry.js";
 import { causeError, runEdge, withDeadlineEffect } from "./runtime/run.js";
-import { validateCatalogToolInput } from "./validate.js";
+import { schemaExample, validateCatalogToolInput } from "./validate.js";
 import { sentSecretsFor, sentSecretsForRequest } from "./sent-secrets.js";
 import { recoveryRecord, recordRecoveryFacts } from "./call-recovery.js";
 import { callFromContext, contextView, viewServices, Credentials } from "./runtime/call.js";
@@ -141,6 +142,7 @@ export class InvocationFailure extends Error {
     }
 }
 keepErrorName(InvocationFailure, "InvocationFailure");
+const withoutExample = ({ example: _example, ...stated }) => stated;
 /**
  * Shared downstream invocation engine. Address/catalog resolution is delegated
  * to the request-local CatalogService; every remaining call semantic lives
@@ -406,6 +408,14 @@ export class InvocationService {
                             return error;
                         return {
                             ...error,
+                            // An example comes only from the published schema, never a connector's copy of the
+                            // call, unless the connector states why there is none.
+                            validation: {
+                                ...withoutExample(error.validation),
+                                ...(error.validation.exampleUnavailable === undefined && resolved?.definition.inputSchema
+                                    ? schemaExample(resolved.definition.inputSchema)
+                                    : {}),
+                            },
                             connector: target.connector.id,
                             operation: `${target.connector.id}.${target.toolName}`,
                             nextAction: this.catalog.searchRecovery({
@@ -552,7 +562,7 @@ export class InvocationService {
                     return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and ${connectorReadOnly ? `connector "${target.connector.id}"` : "this endpoint"} is read-only. Nothing here can send it.`);
                 }
                 if (refusal === "destructive_tool_requires_approval") {
-                    return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. Invoke it through call_destructive_tool so the MCP host can request approval.`);
+                    return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. ${routePhrases(context).writeNeedsApproval}`);
                 }
                 // Remote MCP tools advertise their input schema in the catalog. Validate
                 // against that same request-local definition before admission or provider
@@ -580,7 +590,12 @@ export class InvocationService {
                     return yield* Effect.fail(callSignal.reason);
                 attempts = 1;
                 const call = (permit) => Effect.gen({ self: this }, function* () {
-                    const operationContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs, defer: this.catalog.defer }));
+                    const operationContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({
+                        signal: callSignal,
+                        timeoutMs: context.timeoutMs,
+                        defer: this.catalog.defer,
+                        routes: context.routes,
+                    }));
                     const lease = callFromContext(operationContext, write ? "write" : "read", {
                         admitted: true,
                         // An invocation deadline aborts when its call finishes. A
@@ -604,11 +619,11 @@ export class InvocationService {
                     yield* Effect.gen(function* () {
                         if (target.connector.credential) {
                             if (!connectorContext.credential) {
-                                throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
-                                    `authorize_connector({ connector: "${target.connector.id}" }).`);
+                                throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. " +
+                                    routePhrases(connectorContext).authorizeCall(target.connector.id));
                             }
                             if (!(yield* Context.get(lease.services, Credentials).values)) {
-                                throw new ConnectorCallError("auth_required", `Connector "${target.connector.id}" has no stored credential. Call authorize_connector.`);
+                                throw new ConnectorCallError("auth_required", `Connector "${target.connector.id}" has no stored credential. ${routePhrases(connectorContext).authorizeCall()}`);
                             }
                         }
                         yield* resolveInvocationAuthEffect(connector, callTool, connectorContext);

package/dist/membership.d.ts

@@ -22,6 +22,7 @@ export interface ResolvedPool {
     readOnly: boolean;
     /** Exactly the pool's `tools`; nothing intersects or widens it. */
     access: ConnectorAccess;
+    /** Non-empty and homogeneous: all people or all agents. */
     members: readonly Member[];
     /** Trimmed `owner`: the Workspace address agents in this pool act as. */
     owner?: string;
@@ -40,11 +41,8 @@ export interface MemberContext {
 }
 /** The namespaces bare ids may resolve in, read from the resolved providers. */
 export declare function memberContext(auth: readonly InboundAuth[], agents: readonly string[]): MemberContext;
-/**
- * Resolve one list of references, throwing on any that is malformed,
- * ambiguous, unknown, or repeated (INV-11).
- */
-export declare function resolveMembers(value: unknown, path: string, context: MemberContext): Member[];
+/** Resolve a pool's members, which are all people or all agents (INV-11). */
+export declare function resolvePoolMembers(value: unknown, path: string, context: MemberContext): Member[];
 /**
  * `maintainers`: people only. Required whenever an inbound provider can admit
  * a person, which is any provider but the built-in agent-token adapter. With
@@ -53,5 +51,15 @@ export declare function resolveMembers(value: unknown, path: string, context: Me
 export declare function resolveMaintainers(value: unknown, admitsPeople: boolean, context: MemberContext): readonly IdentityReference[];
 /** Whether an admitted identity is this member. An agent never matches a person. */
 export declare function isMember(member: Member, identity: Readonly<AuthenticatedIdentity>): boolean;
+/**
+ * Non-maintainer people listed in several pools, in declaration order. Plain
+ * `/mcp` routes a person by their single pool, so it refuses each of these.
+ * An open deployment admits no people, so it has none.
+ */
+export declare function peopleInSeveralPools(pools: ReadonlyMap<string, ResolvedPool>, maintainers: readonly IdentityReference[]): Array<{
+    namespace: string;
+    id: string;
+    pools: string[];
+}>;
 /** Whether an admitted identity is a listed maintainer. */
 export declare function isMaintainer(maintainers: readonly IdentityReference[], identity: Readonly<AuthenticatedIdentity>): boolean;

package/dist/membership.js

@@ -65,7 +65,7 @@ const memberKey = (member) => member.kind === "agent" ? `agent\0${member.name}`
  * Resolve one list of references, throwing on any that is malformed,
  * ambiguous, unknown, or repeated (INV-11).
  */
-export function resolveMembers(value, path, context) {
+function resolveMembers(value, path, context) {
     if (!Array.isArray(value)) {
         throw new ConfigError(`${path} must be an array of principal ids, { namespace, id }, or "agent:<name>".`);
     }
@@ -79,6 +79,14 @@ export function resolveMembers(value, path, context) {
         return Object.freeze(member);
     });
 }
+/** Resolve a pool's members, which are all people or all agents (INV-11). */
+export function resolvePoolMembers(value, path, context) {
+    const members = resolveMembers(value, path, context);
+    if (!members.every((member) => member.kind === members[0].kind)) {
+        throw new ConfigError(`${path} mixes people and agents; list only one kind.`);
+    }
+    return members;
+}
 /**
  * `maintainers`: people only. Required whenever an inbound provider can admit
  * a person, which is any provider but the built-in agent-token adapter. With
@@ -88,7 +96,7 @@ export function resolveMaintainers(value, admitsPeople, context) {
     const path = "ConnectaConfig.maintainers";
     if (value === undefined || (Array.isArray(value) && value.length === 0)) {
         if (admitsPeople) {
-            throw new ConfigError(`${path} is required with inbound auth: list the people who may use plain /mcp, administer shared ` +
+            throw new ConfigError(`${path} is required with inbound auth: list the people who receive the whole catalog at plain /mcp, administer shared ` +
                 "credentials, manage agent tokens, and read activity.");
         }
         return Object.freeze([]);
@@ -115,6 +123,30 @@ export function isMember(member, identity) {
         principal.namespace === member.namespace &&
         principal.id === member.id);
 }
+/**
+ * Non-maintainer people listed in several pools, in declaration order. Plain
+ * `/mcp` routes a person by their single pool, so it refuses each of these.
+ * An open deployment admits no people, so it has none.
+ */
+export function peopleInSeveralPools(pools, maintainers) {
+    if (maintainers.length === 0)
+        return [];
+    const people = new Map();
+    for (const [name, pool] of pools) {
+        for (const member of pool.members) {
+            if (member.kind !== "human")
+                continue;
+            if (maintainers.some((m) => m.namespace === member.namespace && m.id === member.id))
+                continue;
+            const key = JSON.stringify([member.namespace, member.id]);
+            const person = people.get(key) ?? { namespace: member.namespace, id: member.id, pools: [] };
+            if (!person.pools.includes(name))
+                person.pools.push(name);
+            people.set(key, person);
+        }
+    }
+    return [...people.values()].filter((person) => person.pools.length > 1);
+}
 /** Whether an admitted identity is a listed maintainer. */
 export function isMaintainer(maintainers, identity) {
     return maintainers.some((maintainer) => isMember({ kind: "human", ...maintainer }, identity));

package/dist/meta-tools.js

@@ -1,3 +1,5 @@
+import { META_ROUTES } from "./agent-routes.js";
+import { toolError } from "./tool-error.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authMethod, authStorage, registerAuth } from "./auth/native.js";
 import { registryProgram } from "./runtime/registry.js";
@@ -20,7 +22,7 @@ import { AUTHORIZE_OUTPUT, SEARCH_OUTPUT, SKILLS_OUTPUT } from "./meta-output.js
 import { RESULT_TTL_SECONDS, resultKeys } from "./storage/keys.js";
 import { agentOutputOperations, sentSecretsForRequest } from "./sent-secrets.js";
 import { captureDownstreamInput } from "./downstream-input.js";
-import { PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
+import { PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
 // Each page is a slice of payload bytes, so a leading U+FEFF is data.
@@ -37,15 +39,7 @@ function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
 function discoveryErrorResult(error) {
-    const result = jsonResult({
-        error: {
-            code: error.code,
-            message: error.message,
-            retryable: false,
-        },
-    });
-    result.isError = true;
-    return result;
+    return toolError({ code: error.code, message: error.message, retryable: false });
 }
 const discoveryResult = function (operation, hint) {
     return authFlow(function* () {
@@ -86,8 +80,8 @@ function isValidResultOffset(value) {
  * Backwards, never forwards: re-serving a few bytes the caller already has is
  * recoverable, silently skipping the rest of a character is not. Offsets the
  * server itself produced (`nextOffset`) are already boundaries and come back
- * unchanged, so this only moves an offset a client computed on its own
- * (issue #38). An offset at or past `bytes.length` is left alone — there is no
+ * unchanged, so this only moves an offset a client computed on its own.
+ * An offset at or past `bytes.length` is left alone — there is no
  * character there to split.
  */
 function alignStartToCharBoundary(bytes, offset) {
@@ -149,6 +143,15 @@ function base64Of(bytes) {
     }
     return out;
 }
+/**
+ * The page a notice's nextAction asks a program to read: it fits the program's
+ * return even if every byte escapes to six JSON characters, with room for the
+ * page envelope, and never asks for more than the stash or bridge will serve.
+ */
+function programPageBytes(results) {
+    const fits = Math.floor(((results.programChars ?? MAX_EXECUTE_RESULT_CHARS) - 1024) / 6);
+    return Math.max(4, Math.min(fits, results.cap, PROGRAM_RESULT_PAGE_BYTES));
+}
 /** Opens a write's notice, ahead of any paging instruction. */
 const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see its result.";
 /** UTF-8 cannot represent lone UTF-16 surrogates without changing them. */
@@ -176,7 +179,7 @@ function isWellFormedText(text) {
  * reported the decoy near the top instead. A write never gets this: repeating
  * it is the one thing its notice forbids.
  */
-const READ_REDUCE_FIRST = "To find something specific, repeat this read inside execute_code with connecta.call and filter or search the result there, returning only what matters";
+const readReduceFirst = (routes) => `To find something specific, repeat this read inside ${routes.program} with connecta.call and filter or search the result there, returning only what matters`;
 function pagingHint(results, totalBytes, preview) {
     if (results.pagingTool === "read_result") {
         const shown = preview.kind === "prefix"
@@ -188,13 +191,13 @@ function pagingHint(results, totalBytes, preview) {
     }
     if (!results.write) {
         if (results.binding.program)
-            return "filter/map/slice data inside execute_code and return only what you need; page this completed return with connecta.result using nextAction.";
+            return `filter/map/slice data inside ${results.routes.program} and return only what you need; page this completed return with connecta.result using nextAction.`;
         const [shown, full] = preview.kind === "prefix"
             ? [`Bytes 0-${preview.bytes} of ${totalBytes} follow.`, "to read it in full, page the rest"]
             : preview.kind === "text-of-envelope"
                 ? ["Its text follows.", `to read the full ${totalBytes}-byte content array as JSON, page it`]
                 : [`The result is ${totalBytes} bytes.`, "to read it in full, page it"];
-        return `${shown} ${READ_REDUCE_FIRST}; ${full} with connecta.result using nextAction.`;
+        return `${shown} ${readReduceFirst(results.routes)}; ${full} with connecta.result using nextAction.`;
     }
     const body = preview.kind === "prefix"
         ? `Bytes 0-${preview.bytes} of ${totalBytes} follow; page the rest with connecta.result using nextAction.`
@@ -229,7 +232,7 @@ const stashResult = function (bytes, results, preview, rawText) {
         try {
             // Base64 permits byte-range decoding, and splitting the envelope across
             // keys keeps a page's storage read proportional to the page instead of to
-            // the whole result (issue #540). Chunk 0 carries the header; the connecta.result
+            // the whole result. Chunk 0 carries the header; the connecta.result
             // reader below maps a byte offset back to chunk index and base64 quad.
             const chunkBytes = resultChunkBytes(totalBytes);
             const binding = base64Of(enc.encode(JSON.stringify(results.binding)));
@@ -261,7 +264,7 @@ const stashResult = function (bytes, results, preview, rawText) {
                     ? `Paging is unavailable. ${WRITE_ALREADY_RAN}`
                     : results.pagingTool
                         ? "Paging is unavailable."
-                        : "Paging is unavailable. Use execute_code to reduce read-only results before returning them.",
+                        : `Paging is unavailable. Use ${results.routes.program} to reduce read-only results before returning them.`,
             };
         }
         return {
@@ -280,7 +283,7 @@ const stashResult = function (bytes, results, preview, rawText) {
                     // A byte may cost six JSON characters when escaped. Leave room for the
                     // result id, page counters, and continuation metadata in the returned page.
                     arguments: {
-                        code: `async () => await connecta.result(${JSON.stringify(id)}, { offset: ${preview.kind === "prefix" ? preview.bytes : 0}, maxBytes: ${Math.floor((MAX_EXECUTE_RESULT_CHARS - 1024) / 6)} })`,
+                        code: `async () => await connecta.result(${JSON.stringify(id)}, { offset: ${preview.kind === "prefix" ? preview.bytes : 0}, maxBytes: ${programPageBytes(results)} })`,
                     },
                 },
         };
@@ -300,6 +303,8 @@ const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult,
         const bytes = enc.encode(text);
         const write = resolved.definition.classification !== "read";
         const notice = yield* upwardStep(stashResult(bytes, {
+            // Program-call pages name only execute_code, listed wherever programs run.
+            routes: META_ROUTES,
             binding: {
                 identity: registry.resultIdentity(),
                 baseUrl,
@@ -325,10 +330,10 @@ const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult,
     });
 });
 /** Program returns share the direct stash, with all host-admitted call dependencies. */
-export function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite) {
-    return runEdge(guardProgramReturnNative(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite));
+export function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars) {
+    return runEdge(guardProgramReturnNative(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars));
 }
-const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn, function (value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite) {
+const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn, function (value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars) {
     return authFlow(function* () {
         const serialized = serializeResultText(value);
         if (serialized.length <= maxChars)
@@ -339,6 +344,8 @@ const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn
         const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
         const results = {
             secrets,
+            // A program return names only execute_code, which every surface running programs lists.
+            routes: META_ROUTES,
             binding: {
                 identity: registry.resultIdentity(),
                 baseUrl,
@@ -347,6 +354,7 @@ const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn
             },
             write: completedWrite,
             cap,
+            ...(programChars !== undefined ? { programChars } : {}),
             set: authMethod((id, chunks, ttl) => registryProgram(registry, "stashResult", id, chunks, ttl)),
             warn: () => logFailure(logger, "result paging unavailable", failureRecord({})),
         };
@@ -453,16 +461,11 @@ function escapedHeadOf(bytes, cap) {
  * Bound a downstream MCP `content` array by `cap`.
  *
  * A lone text block is measured, stashed, previewed, and paged as its text:
- * its envelope adds nothing but a wrapper and a second layer of JSON escaping,
- * which made a JSON payload's preview unreadable and inflated every page.
+ * its envelope adds nothing but a wrapper and a second layer of JSON escaping.
  *
  * Anything else is measured as the serialized envelope — the same string that
  * gets stashed and paged, and the one that counts every block rather than only
- * the text ones. Both halves matter (issue #43). Measuring only text blocks
- * meant an oversized all-image result scored zero bytes and was returned inline
- * unbounded, with no `resultId` to page from; and measuring one string while
- * truncating another left `totalBytes` describing something the cap was never
- * compared against.
+ * the text ones. Measure the same representation that gets truncated and paged.
  *
  * Over the cap, what a client gets depends on whether a preview is usable.
  * Several text blocks preview as their text joined by newlines, while
@@ -543,12 +546,13 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     // identity lets remote connectors reuse one downstream client inside that
     // request without leaking request-bound I/O into the next one.
     const requestScope = opts.requestScope ?? {};
+    const routes = opts.routes ?? META_ROUTES;
     if (opts.canManageAuth || opts.oauthConnectUrl || opts.credentialHandoffUrl || opts.oauthConnectUnavailable) {
         bindAuthorizationHandoffs(requestScope, authMethod((connector) => authCall(authorizationHandoff, [
             registry,
             baseUrl,
             requestScope,
-            opts,
+            { ...opts, routes },
             { connector },
         ])));
     }
@@ -569,6 +573,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         requestSignal: opts.requestSignal,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
+        routes,
     });
     const invocation = new InvocationService(registry, catalog, opts.activity);
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
@@ -586,6 +591,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     activitySource: opts.activitySource,
                     sentSecrets,
                     readOnly: opts.readOnly,
+                    routes,
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(opts.requestSignal !== undefined ? { requestSignal: opts.requestSignal } : {}),
                     unwrapResult: call.resultMode === "value",
@@ -614,6 +620,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
                         const results = {
                             secrets,
+                            routes,
                             binding: {
                                 identity: registry.resultIdentity(),
                                 baseUrl,
@@ -624,6 +631,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                             write: resolved.definition.classification !== "read",
                             cap,
                             ...(opts.pagingTool ? { pagingTool: opts.pagingTool } : {}),
+                            ...(opts.maxProgramResultChars !== undefined ? { programChars: opts.maxProgramResultChars } : {}),
                             set: authMethod((id, value, ttlSeconds) => registryProgram(registry, "stashResult", id, value, ttlSeconds)),
                             // The catalog entry, never `toolName`: a record names a tool
                             // only through the grammar check (src/operator-record.ts).
@@ -670,7 +678,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 const structuredRecovery = outcome.error.nextAction !== undefined;
                 const recoveryRequired = structuredRecovery ||
                     // Sanitized `unavailable` diagnostics ride the structured shape too;
-                    // the plain-text path would drop them (#539).
+                    // the plain-text path would drop them.
                     outcome.error.details !== undefined ||
                     // So does a conflict's `current`: where things stand is the retry.
                     outcome.error.current !== undefined ||
@@ -733,7 +741,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         content: [
                             {
                                 type: "text",
-                                text: 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
+                                text: "Available skills. Fetch one by exact name with this tool.\n\n" +
                                     listing.map((skill) => `- \`${skill.name}\` — ${skill.description}`).join("\n"),
                             },
                         ],
@@ -837,6 +845,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 binding.identity.subject !== identity.subject ||
                 binding.identity.principal !== identity.principal ||
                 binding.identity.endpoint !== identity.endpoint ||
+                binding.identity.pool !== identity.pool ||
                 binding.identity.origin !== identity.origin ||
                 (binding.program === undefined
                     ? typeof binding.connector !== "string" || typeof binding.tool !== "string"
@@ -949,7 +958,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // client that computes its own offsets can land inside a multi-byte
             // character, which would decode as U+FFFD; the offset actually served is
             // the boundary at or before it, and it is what the response reports back
-            // as `offset` (issue #38).
+            // as `offset`.
             const offset = start + alignStartToCharBoundary(bytes, requestedOffset - start);
             // Both sides of `maxBytes` are validated by now — the argument above, the
             // cap at intake — so `offset + maxBytes` always reaches past `offset`.
@@ -991,11 +1000,15 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         })),
     };
 }
-const SEARCH_DESC = (readOnly) => `${readOnly ? "Use top-level search for catalog inspection; this read-only endpoint omits write tools." : "Use top-level search for catalog inspection or write work before call_destructive_tool."} Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" selects reads; "approvalRequired" selects the fail-closed write complement. The host owns confirmation; these filters grant no authority. Empty query browses. Returns { catalogErrors, tools, total, offset, limit, hasMore }; read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
-const CALL_DESC = (readOnly) => `Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. ${readOnly ? "This endpoint is read-only and refuses every write." : "Unannotated or write-capable tools fail closed to call_destructive_tool."} A truncated result carries a connecta.result action.`;
+// Each description states only its own tool's scope; the full routing rule
+// lives once in the server instructions. A client that drops instructions
+// still routes correctly from these scopes plus execute_code's terse lead.
+// Only the meta surface lists these tools, so they use its names.
+const SEARCH_DESC = (readOnly) => `${readOnly ? "Catalog inspection; this read-only endpoint omits write tools." : `Catalog inspection, or finding a write before ${META_ROUTES.write}.`} For read work, search inside one ${META_ROUTES.program} program that also calls and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" selects reads; "approvalRequired" selects the fail-closed write complement; neither grants authority. Empty query browses. Read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
+const CALL_DESC = (readOnly) => `Call one known-address read: a tool explicitly annotated readOnlyHint: true. Other read work: ${META_ROUTES.program}. ${readOnly ? "This endpoint is read-only and refuses every write." : `Unannotated or write-capable tools fail closed to ${META_ROUTES.write}.`} A truncated result carries a connecta.result action.`;
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
 /** A read-only endpoint keeps the six-tool surface, so this tool says why it never writes here. */
-const CALL_DESTRUCTIVE_READ_ONLY_DESC = "This endpoint is read-only: search and describe omit write tools, and every write call here is refused. Reads still run; prefer call_tool or execute_code for them.";
+const CALL_DESTRUCTIVE_READ_ONLY_DESC = `This endpoint is read-only: search and describe omit write tools, and every write call here is refused. Reads still run; prefer ${META_ROUTES.read} or ${META_ROUTES.program} for them.`;
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or required deployment configuration. A configured credential reports presence only: if a call just failed with an authentication or operator-configuration error, give the retained handoff to the operator; otherwise proceed with the call. force=true requests an OAuth restart when the verified user opens the /connect URL; this tool never accepts credentials.";
 const SKILLS_DESC = "List or fetch on-demand guidance. Fetch usage only when the always-loaded instructions are insufficient or a program needs repair.";
 /**
@@ -1084,6 +1097,8 @@ const AUTHORIZE_INPUT = advertisedSchema(z.object({
  */
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
+        maxProgramResultChars: ctx.maxProgramResultChars,
+        routes: ctx.routes,
         ...(ctx.native && !ctx.native.executeCode ? { pagingTool: "read_result" } : {}),
         ...(ctx.native ? { activitySource: "native" } : {}),
         downstreamInput: Boolean(ctx.authElicitation),

package/dist/native-recovery.js

@@ -1,5 +1,5 @@
 /** Adapt only Connecta error envelopes; successful downstream payloads stay untouched. */
-export function nativeRecovery(result, executeCode, wireName) {
+export function nativeRecovery(result, wireName) {
     const response = result;
     const body = response?.structuredContent;
     if (!response?.isError || !body || typeof body.error !== "object" || !body.error)
@@ -28,22 +28,10 @@ export function nativeRecovery(result, executeCode, wireName) {
             }
             : { host: "search", purpose: action.purpose };
     }
-    // These are Connecta-authored recovery fields, never arbitrary downstream data.
-    const rewrite = (text) => text.replace(/authorize_connector|search_tools|call_(?:destructive_)?tool|execute_code/g, (tool) => tool === "authorize_connector"
-        ? "the returned authorization handoff"
-        : tool.startsWith("call_")
-            ? "the original native tool"
-            : tool === "execute_code" && executeCode
-                ? tool
-                : "your host's tool search");
-    for (const key of ["message", "instructions", "retry"])
-        if (typeof error[key] === "string")
-            error[key] = rewrite(error[key]);
+    // Recovery text already uses the native wording: native pools build it with
+    // native route names. Only the address in retry text becomes the wire name.
     if (wireName && typeof error.operation === "string" && typeof error.retry === "string")
-        error.retry = error.retry.replaceAll(rewrite(error.operation), wireName);
-    if (!executeCode && typeof error.instructions === "string") {
-        error.instructions = error.instructions.replace(/; connecta\.search[\s\S]*$/, ". Retry the original native call after recovery.");
-    }
+        error.retry = error.retry.replaceAll(error.operation, wireName);
     return {
         ...response,
         structuredContent: { ...body, error },