@zackbart/connecta 0.40.0 → 0.42.0

package/dist/connectors/remote-mcp.js

@@ -5,7 +5,7 @@ import { authFlow, authCall, authInvoke, authValue, authMethod, authCatch } from
 import { viewServices, viewSignal } from "../runtime/call.js";
 import { declareSelfHostedClient } from "../auth/downstream-client-metadata.js";
 import { isInputRequiredResult } from "@modelcontextprotocol/client";
-import { Duration, Effect, Exit, Scope } from "effect";
+import { Duration, Effect } from "effect";
 import { byteReadResponse } from "../byte-read-response.js";
 import { redactSentSecrets, requestSentSecrets, sentSecretsFor } from "../sent-secrets.js";
 import { closeCatalogCacheScope } from "../catalog-cache.js";
@@ -28,7 +28,7 @@ import { providerBoundary } from "../provider-call.js";
 import { downstreamCallError, hasSdkPayload, payloadFree, remoteMcpErrors } from "./remote-mcp/errors.js";
 import { LOCAL_CLOSE_BUDGET_MS, REDIRECT_STATUSES, remoteMcpTransport } from "./remote-mcp/transport.js";
 import { remoteMcpConfig } from "./remote-mcp/config.js";
-import { remoteMcpConnection } from "./remote-mcp/connection.js";
+import { closeConnectionScope, remoteMcpConnection } from "./remote-mcp/connection.js";
 import { remoteMcpOAuth } from "./remote-mcp/oauth.js";
 import { remoteMcpCatalog } from "./remote-mcp/catalog.js";
 import { remoteMcpResources } from "./remote-mcp/resources.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,17 +261,18 @@ export function remoteMcp(id, opts) {
             }
             : {}),
         listTools: listToolsOperation,
+        peekCatalog: peekCatalogOperation,
         callTool: callToolOperation,
         readResource: readResourceOperation,
         closeScope: authMethod((ctx) => authFlow(function* () {
             // Revocation and all finalizers start before any caller guard. Cleanup
             // retains its own bounded settlement even after the request has closed.
             const state = entryFor(ctx);
-            const release = Scope.closeUnsafe(state.scope, Exit.void);
+            const release = closeConnectionScope(state);
             const cacheClosing = closeCatalogCacheScope(ctx, id, cacheOwner);
             reset(state);
             const closing = runEdge(Effect.all([
-                release ?? Effect.void,
+                Effect.promise(() => release),
                 cacheClosing
                     ? Effect.raceAllFirst([
                         Effect.promise(() => cacheClosing),
@@ -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/credential-contract.d.ts

@@ -39,7 +39,9 @@ export interface CredentialVault {
      * Encrypt downstream OAuth state (tokens, a registered client, a PKCE
      * verifier) before it enters storage. `purpose` is the storage key the value
      * is written under, so the result is bound to one connector, owner, and key.
-     * Without both `seal` and `open`, that state is stored as plaintext.
+     * Construction refuses a vault without both `seal` and `open` when any
+     * connector has `startAuth`, so that state is never left plaintext beside
+     * credentials this vault encrypts.
      */
     seal?(connectorId: string, purpose: string, plaintext: string, owner?: string): Promise<string>;
     /** Sign browser OAuth handoffs with a purpose-specific key; nothing is stored. */

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;
@@ -151,6 +152,7 @@ export interface ConnectaConfigDescription {
         };
         activity: {
             enabled: boolean;
+            operations?: true;
             readable?: boolean;
             deploymentId?: string;
             store?: {

package/dist/describe-config.js

@@ -269,6 +269,7 @@ export function describeConfig(input) {
                 ? {
                     enabled: true,
                     readable: typeof config.activity.store.list === "function",
+                    ...(config.activity.operations ? { operations: true } : {}),
                     ...(str(config.activity.deploymentId) !== undefined ? { deploymentId: config.activity.deploymentId } : {}),
                     store: {
                         kind: storeKind(activityStore),

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/downstream-input.js

@@ -316,12 +316,21 @@ export class DownstreamElicitation {
                     // The nonce is spent even when the downstream failure would normally
                     // allow a retry. Preserve write reconciliation and auth prerequisites.
                     const echoed = downstreamArgumentEcho(self.options.requestScope);
+                    const recoveryError = { ...error };
+                    const freshRead = state.tool === "call_tool" &&
+                        error.code !== "provider_permission_denied" &&
+                        error.nextAction === undefined &&
+                        error.recovery === undefined &&
+                        error.writeOutcome !== "unknown" &&
+                        error.uncertainCall === undefined;
+                    if (freshRead)
+                        delete recoveryError.retry;
                     const structuredContent = {
                         ...result.structuredContent,
                         error: {
-                            ...error,
+                            ...recoveryError,
                             retryable: false,
-                            ...(state.tool === "call_tool" && error.nextAction === undefined && error.retry === undefined
+                            ...(freshRead
                                 ? {
                                     nextAction: {
                                         tool: state.tool,

package/dist/errors.d.ts

@@ -24,7 +24,7 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "downstream_o
  * change, and retries with the base `current` reports — repeating the same
  * call can never succeed, and waiting will not help either.
  */
- | "conflict" | "resource_template_ambiguous" | "resource_match_budget_exceeded" | "input_required_unsupported" | "input_required_invalid" | "input_required_limit" | "connector_call_failed";
+ | "conflict" | "resource_template_ambiguous" | "resource_match_budget_exceeded" | "unsupported_capability" | "input_required_unsupported" | "input_required_invalid" | "input_required_limit" | "connector_call_failed";
 /**
  * Every classification code connecta assigns: a connector's typed codes, the
  * executor's admission codes, and the refusals connecta frames itself.
@@ -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,13 +321,31 @@ 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";
+        arguments: Record<string, never>;
+        purpose: string;
+    } | {
+        action: "reconnect_host" | "contact_operator" | "inspect_capabilities" | "recover_result";
+        purpose: string;
+    } | {
         tool: "authorize_connector";
         arguments: {
             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

@@ -15,6 +15,7 @@ const CLASSIFICATION_CODE_TABLE = {
     conflict: true,
     resource_template_ambiguous: true,
     resource_match_budget_exceeded: true,
+    unsupported_capability: true,
     input_required_unsupported: true,
     input_required_invalid: true,
     input_required_limit: true,
@@ -28,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,
@@ -57,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,
     };
 }
@@ -90,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;
@@ -106,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
@@ -337,11 +414,19 @@ const RETRYABLE_BY_CODE = {
     conflict: false,
     resource_template_ambiguous: false,
     resource_match_budget_exceeded: false,
+    unsupported_capability: false,
     input_required_unsupported: false,
     input_required_invalid: false,
     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);