@zackbart/connecta 0.41.0 → 0.42.0

package/dist/connectors/remote-mcp/catalog.js

@@ -5,7 +5,7 @@ import { SdkHttpError, specTypeSchemas, UnauthorizedError } from "@modelcontextp
 import { redactCatalog } from "../../sent-secrets.js";
 import { MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES } from "../../catalog-limits.js";
 import { catalogItems, observeCompletedCatalogRefresh, observeCatalogFetch, observeCatalogExpiry, } from "../../catalog-cache.js";
-import { ConnectorCallError, msg } from "../../errors.js";
+import { ConnectorCallError, isAccessRefusal, msg } from "../../errors.js";
 import { carryFailureFacts, failureRecord, logFailure } from "../../operator-record.js";
 import { assertDownstreamOutputSafe } from "../../downstream-input-context.js";
 import { hasSdkPayload, ownAbortReason, requiresAuthorization } from "./errors.js";
@@ -78,6 +78,10 @@ export function remoteMcpCatalog(rt) {
             listingContext(options),
             authMethod(() => authFlow(function* () {
                 const before = toolPages;
+                // The one write that follows no cache read, which is what
+                // otherwise captures the fence this listing may lift.
+                if (options?.cacheMode === "refresh")
+                    (yield authInvoke(cache, "captureFence", []));
                 let result;
                 try {
                     result = (yield authCall(listTools, [params, options]));
@@ -86,6 +90,9 @@ export function remoteMcpCatalog(rt) {
                     const bounded = rt.atMcpBoundary(cache.currentContext(), error, "tools/list", client.transport, [
                         cache.currentContext().signal,
                     ]);
+                    // Fenced as this listing was bound, whatever is current by now.
+                    if (requiresAuthorization(bounded) || isAccessRefusal(bounded))
+                        (yield authInvoke(cache, "fenceListing", []));
                     const transient = (error instanceof SdkHttpError && [502, 503, 504].includes(error.status)) ||
                         (bounded instanceof ConnectorCallError && bounded.code === "unavailable");
                     const fallback = transient && toolPages === before
@@ -247,32 +254,49 @@ export function remoteMcpCatalog(rt) {
             }
         }
         state.toolDefinitions = new Map(clean.map((tool) => [tool.name, tool]));
-        return clean.map((t) => ({
-            name: t.name,
-            ...(t.title !== undefined ? { title: t.title } : {}),
-            ...(t.icons !== undefined
-                ? {
-                    icons: t.icons.filter((icon) => !/^data:/i.test(icon.src)),
-                }
-                : {}),
-            ...(t.execution !== undefined ? { execution: t.execution } : {}),
-            ...(t.description !== undefined ? { description: t.description } : {}),
-            ...(t.inputSchema !== undefined
-                ? {
-                    inputSchema: t.inputSchema,
-                }
-                : {}),
-            ...(t.outputSchema !== undefined
-                ? {
-                    outputSchema: t.outputSchema,
-                }
-                : {}),
-            ...(t.annotations !== undefined
-                ? {
-                    annotations: t.annotations,
-                }
-                : {}),
-        }));
+        return toolDefinitions(clean);
+    }));
+    // Served by discovery only, marked by the caller; the listing above stays
+    // the only source a call resolves through.
+    const peekCatalogOperation = authMethod((ctx) => authFlow(function* () {
+        if (liveListings.has(ctx))
+            return undefined;
+        const entry = (yield authCall(rt.peekCatalog, [ctx]));
+        if (!entry)
+            return undefined;
+        return {
+            tools: toolDefinitions(redactCatalog(ctx, entry.result.tools)),
+            fetchedAt: entry.fetchedAt,
+            expiresAt: entry.expiresAt,
+        };
+    }));
+    return { installCatalogIntake, listingContexts, liveListings, listToolsOperation, peekCatalogOperation };
+}
+function toolDefinitions(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        ...(t.title !== undefined ? { title: t.title } : {}),
+        ...(t.icons !== undefined
+            ? {
+                icons: t.icons.filter((icon) => !/^data:/i.test(icon.src)),
+            }
+            : {}),
+        ...(t.execution !== undefined ? { execution: t.execution } : {}),
+        ...(t.description !== undefined ? { description: t.description } : {}),
+        ...(t.inputSchema !== undefined
+            ? {
+                inputSchema: t.inputSchema,
+            }
+            : {}),
+        ...(t.outputSchema !== undefined
+            ? {
+                outputSchema: t.outputSchema,
+            }
+            : {}),
+        ...(t.annotations !== undefined
+            ? {
+                annotations: t.annotations,
+            }
+            : {}),
     }));
-    return { installCatalogIntake, listingContexts, liveListings, listToolsOperation };
 }

package/dist/connectors/remote-mcp/connection.js

@@ -12,8 +12,8 @@ import { Deferred, Effect, Exit, Scope } from "effect";
 import { KvOAuthProvider, refreshCoordinatorsByPartition } from "../../auth/downstream-oauth.js";
 import { trackOAuthStartReset } from "../../auth/oauth-start-reset.js";
 import { sentSecretsFor } from "../../sent-secrets.js";
-import { catalogClientOptions, prefetchCatalog, observeCatalogChange } from "../../catalog-cache.js";
-import { ConnectorCallError, resendAdvice } from "../../errors.js";
+import { catalogClientOptions, observeCatalogChange, observeCatalogExpiry, observeCatalogFetch, prefetchCatalog, retainedCatalogIdentity, } from "../../catalog-cache.js";
+import { ConnectorCallError, isAccessRefusal, resendAdvice } from "../../errors.js";
 import { carryFailureFacts, failureRecord, logFailure } from "../../operator-record.js";
 import { CONNECTA_VERSION } from "../../version.js";
 import { oauthSealerFor } from "../../oauth-sealing.js";
@@ -288,7 +288,7 @@ export function remoteMcpConnection(rt) {
      * same cache through the SDK, so it skips this read. What was already read
      * is handed to that connect, so a resolver runs once per listing.
      */
-    const cachedCatalog = authMethod((ctx) => authFlow(function* () {
+    const readCatalog = authMethod((ctx, use) => authFlow(function* () {
         const principal = principalPolicy
             ? requestPrincipalFor(principalPolicy, ctx, (reason) => new rt.CredentialRequiredError(`Connector "${id}" ${reason}.`))
             : undefined;
@@ -340,7 +340,7 @@ export function remoteMcpConnection(rt) {
                 ]);
                 const prior = (yield authCall(readNegotiation, [ctx, digest]));
                 preread.negotiation = { digest, prior };
-                if (prior?.kind === "modern")
+                if (prior?.kind === "modern" && use === "list")
                     return preread;
             }
             const cache = (yield authCall(catalogClientOptions, [
@@ -354,6 +354,10 @@ export function remoteMcpConnection(rt) {
                 identity,
                 true,
             ]));
+            if (use === "peek") {
+                const entry = (yield authInvoke(cache, "peekTools", [ctx]));
+                return entry ? { ...preread, peek: entry } : preread;
+            }
             const result = (yield authInvoke(cache, "cachedTools", [ctx]));
             if (result)
                 return { tools: result.tools };
@@ -365,6 +369,34 @@ export function remoteMcpConnection(rt) {
         }
         return preread;
     }));
+    // A peek is the first half of the listing that may follow it: that listing
+    // takes what the peek read, once, so a discovery that peeks first still reads
+    // its stored entry and runs a credential resolver once. Nothing is taken if
+    // the catalog was invalidated or the credential changed in between, and the
+    // whole hand-off lives and dies with the request scope.
+    const peeks = new WeakMap();
+    const peekCatalog = authMethod((ctx) => authFlow(function* () {
+        // A connector known to need authorization is never listed from a cache.
+        if (stateFor(ctx).authRequired)
+            return undefined;
+        const read = (yield authCall(readCatalog, [ctx, "peek"]));
+        peeks.set(ctx.requestScope ?? ctx, { identity: retainedCatalogIdentity(ctx), read });
+        return read.peek;
+    }));
+    const cachedCatalog = authMethod((ctx) => authFlow(function* () {
+        const scope = ctx.requestScope ?? ctx;
+        const handed = peeks.get(scope);
+        peeks.delete(scope);
+        if (!handed || handed.identity !== retainedCatalogIdentity(ctx))
+            return (yield authCall(readCatalog, [ctx, "list"]));
+        const { peek, ...preread } = handed.read;
+        if (!peek || peek.expiresAt <= Date.now())
+            return preread;
+        // The listing's own view keeps the provenance a direct read would record.
+        observeCatalogFetch(ctx, peek.fetchedAt);
+        observeCatalogExpiry(ctx, "tools/list", typeof peek.result.ttlMs === "number" ? peek.result.ttlMs : peek.expiresAt - peek.fetchedAt, peek.expiresAt);
+        return { tools: peek.result.tools };
+    }));
     const ensureConnected = authMethod((ctx, state, preread) => authFlow(function* () {
         let joined = state.connecting;
         if (joined)
@@ -554,6 +586,25 @@ export function remoteMcpConnection(rt) {
                 ])));
                 if (!owned())
                     return yield* Effect.fail(rt.scopeEndedError());
+                // The generation a refused handshake is about, as it is now. Read from
+                // this connect's memo, so a connect that is not refused costs no I/O.
+                const handshakeBinding = yield* promised(authMethod(() => authInvoke(cacheOptions, "bindListing", [ctx, { credentialIdentity: undefined }]))).pipe(Effect.catch(() => Effect.succeed(undefined)));
+                if (!owned())
+                    return yield* Effect.fail(rt.scopeEndedError());
+                // What the attempt sent, in memory: never the grant as it is by now. A
+                // provider that read no tokens in this epoch sent none and has no catalog.
+                const fenceHandshake = authMethod(() => authFlow(function* () {
+                    let credentialIdentity;
+                    if (provider) {
+                        if (!provider.observedTokens || provider.observed?.epoch !== genAtStart)
+                            return;
+                        credentialIdentity = yield authCall(secretDigest, [ctx, JSON.stringify(provider.observedTokens)]);
+                    }
+                    (yield authInvoke(cacheOptions, "fenceTools", [
+                        ctx,
+                        { ...handshakeBinding, credentialIdentity },
+                    ]));
+                }));
                 const makeClient = () => {
                     const { intake: _intake, completeCatalogRefresh: _refresh, withListing: _listing, currentContext: _context, cachedTools: _cached, ...clientOptions } = cacheOptions;
                     const client = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
@@ -621,7 +672,12 @@ export function remoteMcpConnection(rt) {
                     }
                 }))).pipe(Effect.mapError((err) => rt.atMcpBoundary(ctx, 
                 // First, while the runtime's text can still be read for it.
-                rt.withoutCredential(ctx, err, credentialValue, credentialFramed), "MCP handshake", t, [ctx.signal, connectionAbort.signal, handshakeAbort.signal])));
+                rt.withoutCredential(ctx, err, credentialValue, credentialFramed), "MCP handshake", t, [ctx.signal, connectionAbort.signal, handshakeAbort.signal])), 
+                // Before the lease closes the signal this write runs under. Waiters see
+                // the failure after it, and it never replaces the refusal.
+                Effect.tapError((error) => handshakeBinding && (requiresAuthorization(error) || isAccessRefusal(error))
+                    ? promised(fenceHandshake).pipe(Effect.catch(() => Effect.void))
+                    : Effect.void));
                 held.client = c;
                 // A probe deadline can end its scope while connect is still in flight.
                 // The transport is closed immediately by closeScope; if connect wins
@@ -709,6 +765,7 @@ export function remoteMcpConnection(rt) {
         ensureConnected,
         requestOptions,
         cachedCatalog,
+        peekCatalog,
         cacheOwner,
         reset,
         states,

package/dist/connectors/remote-mcp.js

@@ -155,7 +155,7 @@ export function remoteMcp(id, opts) {
     Object.assign(rt, remoteMcpCatalog(rt));
     Object.assign(rt, remoteMcpResources(rt));
     Object.assign(rt, remoteMcpCall(rt));
-    const { listSkills, readSkill, liveListings, listToolsOperation, callToolOperation, readResourceOperation, entryFor, cacheOwner, reset, stateFor, newProvider, resourceTemplateRefusals, ensureConnected, granted, connectedProviders, CredentialRequiredError, OperatorDisconnectedError, UnresolvedTokenError, oauthSurface, activeContexts, states, isClosed, scopeEndedError, operatorDisconnectedError, authRequiredError, renewBeforeCall, } = rt;
+    const { listSkills, readSkill, liveListings, listToolsOperation, peekCatalogOperation, callToolOperation, readResourceOperation, entryFor, cacheOwner, reset, stateFor, newProvider, resourceTemplateRefusals, ensureConnected, granted, connectedProviders, CredentialRequiredError, OperatorDisconnectedError, UnresolvedTokenError, oauthSurface, activeContexts, states, isClosed, scopeEndedError, operatorDisconnectedError, authRequiredError, renewBeforeCall, } = rt;
     // Built once from construction-time values: names, framing, and public
     // URLs only. A static header's value and a stored credential never reach
     // it, and a URL keeps origin and path: a CIMD document's query may carry a
@@ -261,6 +261,7 @@ export function remoteMcp(id, opts) {
             }
             : {}),
         listTools: listToolsOperation,
+        peekCatalog: peekCatalogOperation,
         callTool: callToolOperation,
         readResource: readResourceOperation,
         closeScope: authMethod((ctx) => authFlow(function* () {
@@ -386,6 +387,11 @@ export function remoteMcp(id, opts) {
         ctx,
         authMethod(() => authCall(listTools, [ctx])),
     ]));
+    const peekCatalog = connector.peekCatalog;
+    connector.peekCatalog = authMethod((ctx) => authCall(withActiveSecrets, [
+        ctx,
+        authMethod(() => authCall(peekCatalog, [ctx])),
+    ]));
     const readResource = connector.readResource;
     connector.readResource = authMethod((uri, ctx) => authCall(withActiveSecrets, [
         ctx,
@@ -426,6 +432,7 @@ export function remoteMcp(id, opts) {
         return (yield authView(ctx, authMethod(() => authCall(operation, [...args])), requestOwned));
     }));
     connector.listTools = settlingOperation(connector.listTools, 0);
+    connector.peekCatalog = settlingOperation(connector.peekCatalog, 0);
     connector.readResource = settlingOperation(connector.readResource, 1);
     if (connector.downstreamSkills) {
         connector.downstreamSkills.list = settlingOperation(connector.downstreamSkills.list, 0);
@@ -445,6 +452,7 @@ export function remoteMcp(id, opts) {
         // a refresh flight exists. These operations do not take call admission.
         const retain = retainOperation;
         connector.listTools = retain(connector.listTools, 0);
+        connector.peekCatalog = retain(connector.peekCatalog, 0);
         connector.callTool = retain(connector.callTool, 2);
         connector.readResource = retain(connector.readResource, 1);
         if (connector.downstreamSkills) {
@@ -460,6 +468,7 @@ export function remoteMcp(id, opts) {
         connector.finishAuth = retain(connector.finishAuth, 1);
     }
     connector.listTools = payloadFree(connector.listTools);
+    connector.peekCatalog = payloadFree(connector.peekCatalog);
     connector.callTool = payloadFree(connector.callTool);
     connector.readResource = payloadFree(connector.readResource);
     if (connector.downstreamSkills) {

package/dist/describe-config.d.ts

@@ -1,3 +1,4 @@
+import type { ClassificationOverride } from "./tool-safety.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import type { ConnectaConfig, ResolvedConfig } from "./config.js";
 import { type ResolvedPool } from "./membership.js";
@@ -95,7 +96,7 @@ export interface ConnectaConfigDescription {
             maxResultBytes: DescribedLimit;
         };
         results: Record<keyof typeof CONFIG_DEFAULTS.results, DescribedLimit>;
-        execute: Record<keyof typeof CONFIG_DEFAULTS.execute, DescribedLimit>;
+        execute: Record<keyof typeof CONFIG_DEFAULTS.execute, DescribedLimit<number | boolean>>;
         requests: Record<keyof typeof CONFIG_DEFAULTS.admission.requests, DescribedLimit>;
     };
     /** Whether the default /mcp endpoint refuses every write, and exact classification overrides from deployment code. */
@@ -115,7 +116,7 @@ export interface ConnectaConfigDescription {
         id: string;
         pools: string[];
     }>;
-    classification: Record<string, Record<string, "read" | "write" | "hidden">>;
+    classification: Record<string, Record<string, ClassificationOverride>>;
     /** Inbound auth providers in the order they are tried. */
     auth: Array<{
         kind: string;

package/dist/discovery-health.js

@@ -5,9 +5,10 @@
 // the connector-health family's `discovery` key, a typed code, when it was
 // seen, and when to try again (INV-6: never downstream text, tools or
 // credentials). Unscoped search skips a connector whose record is current and
-// reports it as unavailable in `catalogErrors` with `retryAfterMs`; it never
-// serves tools from the failed or interrupted walk (INV-8). Scoped search,
-// describe and calls still reach the connector.
+// reports it as unavailable in `catalogErrors` with `retryAfterMs`, listing its
+// last complete catalog, marked stale, when one exists; it never serves tools
+// from the failed or interrupted walk (INV-8). Scoped search, describe and calls
+// still reach the connector.
 //
 // Records sit beside the catalog cache, in its store and owner partition:
 // principal, subject, caller identity and pool, origin, the admitted endpoint,
@@ -21,7 +22,9 @@
 //
 // After its retry time a record lingers, so exactly one request can claim the
 // next probe by compare-and-set as it dispatches it; the others keep skipping
-// until that probe settles or its lease lapses. A success, or an auth failure that proves the
+// until that probe settles or its lease lapses. Every write is conditional on
+// the record its request read, so concurrent failures record once and a lease
+// is never overwritten. A success, or an auth failure that proves the
 // connector answers, clears the record. A fast failure is not recorded:
 // asking again costs the next search nothing. Caller cancellation and a probe cut
 // short by the discovery budget record nothing.
@@ -32,7 +35,7 @@ import { classificationCode, classifyCallError } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
 import { causeError } from "./runtime/run.js";
 import { Storage } from "./runtime/services.js";
-import { storageCompareAndSet, storageGetMany, storageSet } from "./runtime/storage.js";
+import { storageCompareAndSet, storageGetMany } from "./runtime/storage.js";
 import { connectorHealthKeys, CONNECTOR_HEALTH_LINGER_MS } from "./storage/keys.js";
 /** How long unscoped search skips a connector after a failed discovery. */
 const DISCOVERY_RETRY_MS = 60_000;
@@ -123,13 +126,22 @@ export function readDiscoveryHealth(registry, ids, baseUrl, requestScope, option
  * dispatched: one compare-and-set against the record this request read, with
  * a lease to the absolute time `leaseUntil`, past the claimant's whole
  * discovery budget. Others keep skipping until the lease lapses or the probe
- * settles. False when another request holds it, or the record changed.
+ * settles. An absent record is claimed the same way, by creating it. False when
+ * another request holds it, or the record changed.
  */
 export function claimDiscoveryProbe(slot, leaseUntil) {
     return Effect.suspend(() => {
-        const fact = parseFact(slot.raw);
+        const fact = slot.raw === null
+            ? {
+                v: 1,
+                code: "timeout",
+                observedAt: Date.now(),
+                retryAt: leaseUntil,
+                generation: slot.generation,
+            }
+            : parseFact(slot.raw);
         if (!fact)
-            return Effect.succeed(slot.raw === null);
+            return Effect.succeed(false);
         const claim = encodeFact({ ...fact, retryAt: leaseUntil });
         return storageCompareAndSet(slot.key, slot.raw, claim.raw, { expiresAtMs: claim.expiresAtMs }).pipe(Effect.provideService(Storage, slot.storage), Effect.map((claimed) => {
             if (claimed)
@@ -188,9 +200,12 @@ export function settleDiscoveryHealth(slot, outcome) {
         }
         const encoded = encodeFact(fact);
         const skip = { code: fact.code, retryAt: fact.retryAt };
-        return storageSet(slot.key, encoded.raw, { expiresAtMs: encoded.expiresAtMs }).pipe(Effect.provideService(Storage, slot.storage), Effect.map(() => {
-            slot.raw = encoded.raw;
-            return { slot, skip };
+        // Against the record this request read: a concurrent failure or a held
+        // lease stays, and this request learns it does not own what follows.
+        return storageCompareAndSet(slot.key, slot.raw, encoded.raw, { expiresAtMs: encoded.expiresAtMs }).pipe(Effect.provideService(Storage, slot.storage), Effect.map((recorded) => {
+            if (recorded)
+                slot.raw = encoded.raw;
+            return { slot, skip, recorded };
         }), Effect.catchCause((cause) => Effect.sync(() => {
             logFailure(slot.logger, "discovery health write failed", failureRecord({}, causeError(cause)));
             return { slot, skip };

package/dist/errors.d.ts

@@ -33,7 +33,7 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "downstream_o
  * Adding a member fails typecheck until {@link CLASSIFICATION_CODE_TABLE}
  * lists it.
  */
-export type ClassificationCode = ConnectorCallErrorCode | ExecutorAdmissionErrorCode | "cancelled" | "unknown_address" | "unknown_tool" | "ambiguous_tool_alias" | "catalog_lookup_failed" | "result_too_large" | "destructive_tool_requires_approval" | "read_only_endpoint" | "auth_replay_refused" | "write_outcome_unknown" | "result_processing_failed" | "budget_exceeded" | "executor_failed" | "program_error";
+export type ClassificationCode = ConnectorCallErrorCode | ExecutorAdmissionErrorCode | "cancelled" | "unknown_address" | "unknown_tool" | "ambiguous_tool_alias" | "catalog_lookup_failed" | "result_too_large" | "result_not_retained" | "destructive_tool_requires_approval" | "read_only_endpoint" | "auth_replay_refused" | "write_outcome_unknown" | "result_processing_failed" | "budget_exceeded" | "executor_failed" | "program_error";
 /** `value` when it is a code connecta assigns, else undefined. */
 export declare function classificationCode(value: unknown): ClassificationCode | undefined;
 /**
@@ -101,12 +101,48 @@ export interface ArgumentRepairDetails {
  * finding stays a few hundred bytes inside the 4 KiB envelope below.
  */
 export declare const MAX_ARGUMENT_VALIDATION_ISSUES = 8;
+/** Whitespace and the quotes and brackets that delimit a link in text, HTML and JSON. Each is
+ * ASCII, so a cut before one splits no codepoint in UTF-8 or UTF-16. */
+export declare const TOKEN_END: Set<number>;
 /**
- * Clamp a string to a UTF-8 byte budget, appending `…` when it clipped.
- * Short strings — the common case, and the one that has to stay exact — are
+ * The first `units` UTF-16 units of `value`, less any unfinished token. Every cut of text
+ * that output redaction reads later goes through this or a sibling below: a remnant shorter
+ * than a fragment matches nothing, so a credential registered after the cut must not leave
+ * its opening behind. A whole token is the only tail a cut can prove finished.
+ */
+export declare function tokenPrefix(value: string, units: number): string;
+/**
+ * Clamp a string to a UTF-8 byte budget without cutting a token, appending `…` when it
+ * clipped. Short strings — the common case, and the one that has to stay exact — are
  * returned unchanged and untagged.
  */
 export declare function boundedEchoText(value: string, maxBytes?: number): string;
+/**
+ * Clamp a name for an operator's record, which no agent reads and no output redaction
+ * follows, to a UTF-8 byte budget. Its prefix is what identifies it, so it may end inside a
+ * token; agent-facing text goes through {@link boundedEchoText}.
+ */
+export declare function clampedRecordName(value: string, maxBytes: number): string;
+/**
+ * How much of a tool's own `isError` text reaches the agent. A refusal can be the
+ * only copy of what to do next: a paragraph of instructions, a request id and a
+ * signed approval URL, which alone commonly run to a couple of kilobytes. Four
+ * kilobytes holds those, and in a direct result's two copies stays well inside the
+ * default result cap; a tighter cap shrinks it further.
+ */
+export declare const MAX_TOOL_ERROR_BYTES = 4096;
+/**
+ * Clamp downstream prose to a UTF-8 byte budget, marker included, without cutting
+ * a token. The cut backs off to a byte no URL or credential holds, so a link arrives
+ * whole or not at all, and no prefix of a credential registered later stays behind.
+ * Each such byte is ASCII, so no codepoint is split.
+ */
+export declare function clipText(value: string, maxBytes?: number): string;
+/**
+ * Clamp text so its JSON string fits `maxChars` serialized characters, quotes and marker
+ * included, without cutting a token. Escapes make a character cost up to six.
+ */
+export declare function clipSerialized(value: string, maxChars: number): string;
 /**
  * Snapshot the caller's arguments after bounded schema-aware writeOnly omission,
  * then apply the shared byte budget without clipping. Unresolved sensitivity
@@ -179,6 +215,8 @@ export declare class WithheldTextError extends Error {
 }
 /** Agent-visible recovery class for downstream credential failures. */
 export type AuthRecoveryMode = "oauth" | "operator_config" | "unavailable";
+/** The downstream said this caller has no access: affirmative evidence, unlike a failure to answer. */
+export declare function isAccessRefusal(error: unknown): boolean;
 /** Runtime membership in the closed connector taxonomy, checked against its exhaustive table. */
 export declare function isConnectorCallErrorCode(value: unknown): value is ConnectorCallErrorCode;
 /**
@@ -283,6 +321,13 @@ export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
      * {@link ConnectorCallError.writeOutcome}). Check its target before repeating it.
      */
     writeOutcome?: "unknown";
+    /**
+     * A write's downstream tool answered `isError` itself, so `message` holds its
+     * words. They do not prove the write unapplied: its handler ran before it answered.
+     */
+    toolAnswered?: true;
+    /** On `unknown_tool`: nearby canonical addresses on the same connector. */
+    suggestions?: string[];
     /** The single model-facing entry point for every credential class. */
     nextAction?: {
         tool: "skills";
@@ -297,6 +342,10 @@ export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
             connector: string;
         };
         operatorHandoff: string;
+    } | {
+        /** An error that carries its handoff: pass this link on; no tool call is needed. */
+        url: string;
+        purpose: string;
     } | {
         tool: "search_tools";
         arguments: {

package/dist/errors.js

@@ -29,6 +29,7 @@ const CLASSIFICATION_CODE_TABLE = {
     ambiguous_tool_alias: true,
     catalog_lookup_failed: true,
     result_too_large: true,
+    result_not_retained: true,
     destructive_tool_requires_approval: true,
     read_only_endpoint: true,
     auth_replay_refused: true,
@@ -58,7 +59,7 @@ function boundedIssueText(value, maxChars) {
     if (value.length <= maxChars)
         return { value, truncated: false };
     return {
-        value: `${value.slice(0, Math.max(0, maxChars - 1))}…`,
+        value: `${tokenPrefix(value, maxChars - 1)}…`,
         truncated: true,
     };
 }
@@ -91,12 +92,43 @@ const MAX_ECHOED_BYTES = 512;
  */
 const echoEncoder = new TextEncoder();
 const echoDecoder = new TextDecoder();
+/** Whitespace and the quotes and brackets that delimit a link in text, HTML and JSON. Each is
+ * ASCII, so a cut before one splits no codepoint in UTF-8 or UTF-16. */
+export const TOKEN_END = new Set([0x09, 0x0a, 0x0d, 0x20, 0x22, 0x3c, 0x3e, 0x60]);
 /**
- * Clamp a string to a UTF-8 byte budget, appending `…` when it clipped.
- * Short strings — the common case, and the one that has to stay exact — are
+ * The first `units` UTF-16 units of `value`, less any unfinished token. Every cut of text
+ * that output redaction reads later goes through this or a sibling below: a remnant shorter
+ * than a fragment matches nothing, so a credential registered after the cut must not leave
+ * its opening behind. A whole token is the only tail a cut can prove finished.
+ */
+export function tokenPrefix(value, units) {
+    if (units >= value.length)
+        return value;
+    let end = Math.max(0, units);
+    while (end > 0 && !TOKEN_END.has(value.charCodeAt(end)))
+        end--;
+    return value.slice(0, end).trimEnd();
+}
+/**
+ * Clamp a string to a UTF-8 byte budget without cutting a token, appending `…` when it
+ * clipped. Short strings — the common case, and the one that has to stay exact — are
  * returned unchanged and untagged.
  */
 export function boundedEchoText(value, maxBytes = MAX_ECHOED_BYTES) {
+    const bytes = echoEncoder.encode(value);
+    if (bytes.length <= maxBytes)
+        return value;
+    let end = Math.max(0, maxBytes);
+    while (end > 0 && !TOKEN_END.has(bytes[end]))
+        end--;
+    return `${echoDecoder.decode(bytes.slice(0, end)).trimEnd()}…`;
+}
+/**
+ * Clamp a name for an operator's record, which no agent reads and no output redaction
+ * follows, to a UTF-8 byte budget. Its prefix is what identifies it, so it may end inside a
+ * token; agent-facing text goes through {@link boundedEchoText}.
+ */
+export function clampedRecordName(value, maxBytes) {
     const bytes = echoEncoder.encode(value);
     if (bytes.length <= maxBytes)
         return value;
@@ -107,6 +139,50 @@ export function boundedEchoText(value, maxBytes = MAX_ECHOED_BYTES) {
         end--;
     return `${echoDecoder.decode(bytes.slice(0, end))}…`;
 }
+/**
+ * How much of a tool's own `isError` text reaches the agent. A refusal can be the
+ * only copy of what to do next: a paragraph of instructions, a request id and a
+ * signed approval URL, which alone commonly run to a couple of kilobytes. Four
+ * kilobytes holds those, and in a direct result's two copies stays well inside the
+ * default result cap; a tighter cap shrinks it further.
+ */
+export const MAX_TOOL_ERROR_BYTES = 4_096;
+const CLIPPED = "… [truncated]";
+const CLIPPED_BYTES = echoEncoder.encode(CLIPPED).length;
+/**
+ * Clamp downstream prose to a UTF-8 byte budget, marker included, without cutting
+ * a token. The cut backs off to a byte no URL or credential holds, so a link arrives
+ * whole or not at all, and no prefix of a credential registered later stays behind.
+ * Each such byte is ASCII, so no codepoint is split.
+ */
+export function clipText(value, maxBytes = MAX_TOOL_ERROR_BYTES) {
+    const bytes = echoEncoder.encode(value);
+    if (bytes.length <= maxBytes)
+        return value;
+    let end = Math.max(0, maxBytes - CLIPPED_BYTES);
+    while (end > 0 && !TOKEN_END.has(bytes[end]))
+        end--;
+    return `${echoDecoder.decode(bytes.slice(0, end)).trimEnd()}${end > 0 ? " " : ""}${CLIPPED}`;
+}
+/**
+ * Clamp text so its JSON string fits `maxChars` serialized characters, quotes and marker
+ * included, without cutting a token. Escapes make a character cost up to six.
+ */
+export function clipSerialized(value, maxChars) {
+    if (JSON.stringify(value).length <= maxChars)
+        return value;
+    const marked = (kept) => `${kept}${kept ? " " : ""}${CLIPPED}`;
+    let low = 0;
+    let high = Math.min(value.length, maxChars);
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (JSON.stringify(marked(value.slice(0, mid))).length <= maxChars)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return marked(tokenPrefix(value, low));
+}
 /**
  * Snapshot the caller's arguments after bounded schema-aware writeOnly omission,
  * then apply the shared byte budget without clipping. Unresolved sensitivity
@@ -344,6 +420,13 @@ const RETRYABLE_BY_CODE = {
     input_required_limit: false,
     connector_call_failed: false,
 };
+/** The downstream said this caller has no access: affirmative evidence, unlike a failure to answer. */
+export function isAccessRefusal(error) {
+    return (error instanceof ConnectorCallError &&
+        (error.code === "auth_required" ||
+            error.code === "downstream_oauth_required" ||
+            error.code === "provider_permission_denied"));
+}
 /** Runtime membership in the closed connector taxonomy, checked against its exhaustive table. */
 export function isConnectorCallErrorCode(value) {
     return typeof value === "string" && Object.hasOwn(RETRYABLE_BY_CODE, value);