@zackbart/connecta 0.30.0 → 0.32.0

package/dist/connectors/guarded-fetch.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectorContext } from "../types.js";
 /** The methods a hand-written provider surface actually uses. */
-type GuardedMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type GuardedMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface GuardedRequest {
     method: GuardedMethod;
     /**
@@ -21,6 +21,14 @@ export interface GuardedRequest {
      * shadow it.
      */
     headers?: Record<string, string | undefined>;
+    /**
+     * Headers whose values the tool returns to its caller by contract, such as
+     * an idempotency key. They are added after the request's sent secrets are
+     * registered, so a name like `Idempotency-Key` does not mark the value a
+     * credential and redact it from the result that must carry it. They may not
+     * collide with any other header.
+     */
+    visibleHeaders?: Record<string, string>;
     /** JSON request body. Serialized here, with the `Content-Type` to match. */
     body?: unknown;
     /**
@@ -48,6 +56,8 @@ interface GuardedResponse {
     readonly status: number;
     readonly ok: boolean;
     readonly headers: Headers;
+    /** Cancel an unread body without waiting for the vendor to emit a chunk. */
+    cancel(): Promise<void>;
     /** The body as bytes. */
     bytes(): Promise<Uint8Array>;
     /** The body decoded as UTF-8. */
@@ -116,6 +126,13 @@ export interface GuardedFetchOptions {
      * absurd response is a fact about the API, not about HTTP.
      */
     maxResponseBytes: number;
+    /**
+     * Inspect the exact URL about to be fetched — confined, normalized, with its
+     * query encoded — and throw to refuse it. A policy that reads this URL reads
+     * what the downstream server will route, not a spelling of it. Runs before
+     * authentication, so a refused request never resolves a credential.
+     */
+    admit?: (url: URL, request: GuardedRequest) => void;
 }
 /** Sends one already-guarded request on behalf of one call's context. */
 type GuardedFetcher = (url: string, init: RequestInit, ctx: ConnectorContext) => Promise<Response>;

package/dist/connectors/guarded-fetch.js

@@ -181,6 +181,9 @@ function boundedResponse(provider, response, limit) {
             status: response.status,
             ok: response.ok,
             headers: response.headers,
+            cancel: async () => {
+                await response.body?.cancel();
+            },
             bytes: async () => new Uint8Array(),
             text: async () => "",
             json: emptyJson,
@@ -228,6 +231,9 @@ function boundedResponse(provider, response, limit) {
         status: response.status,
         ok: response.ok,
         headers: response.headers,
+        cancel: async () => {
+            await response.body?.cancel();
+        },
         bytes,
         text,
         json,
@@ -307,6 +313,7 @@ export function guardedFetch(options) {
             throw new Error(`A ${provider} request cannot carry both a JSON body and a raw body.`);
         }
         const url = confinedUrl(provider, base, basePath, request);
+        options.admit?.(url, request);
         const headers = { ...constantHeaders };
         for (const [name, value] of Object.entries(request.headers ?? {})) {
             if (value !== undefined)
@@ -343,6 +350,13 @@ export function guardedFetch(options) {
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             };
             sentSecretsFor(ctx).request(url, init);
+            for (const [name, value] of Object.entries(request.visibleHeaders ?? {})) {
+                const shadow = hasHeader(headers, name);
+                if (shadow) {
+                    throw new ConnectorCallError("invalid_args", `A ${provider} request sets the ${shadow} header twice.`);
+                }
+                headers[name] = value;
+            }
             response = await send(url.toString(), init, ctx);
         }
         catch (cause) {
@@ -356,8 +370,13 @@ export function guardedFetch(options) {
         }
         const declared = Number(response.headers.get("content-length"));
         // A prefix read takes only what it was asked for, so a long body is not
-        // a reason to refuse it; the ceiling still bounds what is read.
-        if (Number.isFinite(declared) && declared > limit && !(request.prefixOnly && response.ok)) {
+        // a reason to refuse it; the ceiling still bounds what is read. A HEAD
+        // response has no body: its Content-Length describes the GET
+        // representation, which is exactly what a HEAD asks about.
+        if (Number.isFinite(declared) &&
+            declared > limit &&
+            request.method !== "HEAD" &&
+            !(request.prefixOnly && response.ok)) {
             await response.body?.cancel().catch(() => { });
             throw oversized(provider, limit, `a declared ${declared} bytes`);
         }

package/dist/describe-config.d.ts

@@ -86,8 +86,10 @@ export interface ConnectaConfigDescription {
         execute: Record<keyof typeof CONFIG_DEFAULTS.execute, DescribedLimit>;
         requests: Record<keyof typeof CONFIG_DEFAULTS.admission.requests, DescribedLimit>;
     };
-    /** Trust and exact classification overrides from deployment code. */
-    trust: "trusted" | "read-only";
+    /** Whether the default /mcp endpoint refuses every write, and exact classification overrides from deployment code. */
+    readOnly: boolean;
+    /** Whether deployment code configures a grant for plain `/mcp`. */
+    hasGrant: boolean;
     classification: Record<string, Record<string, "read" | "write">>;
     /** Inbound auth providers in the order they are tried. */
     auth: Array<{
@@ -96,12 +98,13 @@ export interface ConnectaConfigDescription {
         ui?: string;
     }>;
     identity: Record<"connectorAccess" | "activityAccess" | "credentialAdministration" | "accessTokenManagement" | "personalConnection", "default" | "custom">;
+    /** `readOnly` is resolved: the pool's own value, else the deployment's. */
     pools: Array<{
         name: string;
         path: string;
         tools: string[];
         hasGrant: boolean;
-        trust: "trusted" | "read-only";
+        readOnly: boolean;
     }>;
     modules: {
         ui: {

package/dist/describe-config.js

@@ -240,7 +240,8 @@ export function describeConfig(input) {
             execute: limitGroup(config.execute, ownValue(raw, "execute"), Object.keys(D.execute)),
             requests: limitGroup(config.admission.requests, ownValue(ownValue(raw, "admission"), "requests"), Object.keys(D.admission.requests)),
         },
-        trust: config.trust,
+        readOnly: config.readOnly,
+        hasGrant: typeof config.grant === "function",
         classification: structuredClone(config.classification ?? {}),
         auth: config.auth.map((provider) => ({
             kind: String(provider.kind),
@@ -249,7 +250,7 @@ export function describeConfig(input) {
         })),
         identity: Object.fromEntries(IDENTITY_KEYS.map((key) => [key, typeof config.identity[key] === "function" ? "custom" : "default"])),
         pools: Object.entries(config.pools ?? {}).map(([name, pool]) => ({
-            trust: pool.trust,
+            readOnly: pool.readOnly ?? config.readOnly,
             name,
             path: `/mcp/${name}`,
             tools: pool.tools.map(String),

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" | "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" | "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;
 /** One bounded, payload-free explanation of an input-schema mismatch. */
@@ -282,6 +282,8 @@ export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
         args?: unknown;
         argsOmitted?: true;
         argsRedacted?: true;
+        /** Facts the connector recorded before dispatch, such as a generated `idempotencyKey`. */
+        recovery?: Readonly<Record<string, string>>;
     };
     /** Explicit retry guidance; recovery never retries or mutates by itself. */
     retry?: string;

package/dist/errors.js

@@ -28,6 +28,7 @@ const CLASSIFICATION_CODE_TABLE = {
     catalog_lookup_failed: true,
     result_too_large: true,
     destructive_tool_requires_approval: true,
+    read_only_endpoint: true,
     auth_replay_refused: true,
     write_outcome_unknown: true,
     result_processing_failed: true,

package/dist/execute.js

@@ -412,6 +412,8 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
     const catalog = new CatalogService(registry, baseUrl, {
         requestScope,
         requestSignal: hostAccessSignal,
+        // connecta.search and connecta.describe never show a read-only endpoint's writes.
+        readOnly: limits.readOnly,
         // A program that just missed an address cannot call search_tools.
         searchRoute: "connecta.search",
         concurrency: limits.discoveryConcurrency,
@@ -455,7 +457,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         }
         return value;
     };
-    /** Budget and account for writes admitted by the pool trust decision. */
+    /** Budget and account for writes a writable endpoint admits. */
     const invocationContext = (sending, timeoutMs) => ({
         source: "execute_code",
         sentSecrets,
@@ -463,9 +465,9 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         ...(signal !== undefined ? { requestSignal: signal } : {}),
         ...(limits.dispatchController ? { dispatchSignal: limits.dispatchController.signal } : {}),
         unwrapResult: true,
-        trust: limits.trust,
+        readOnly: limits.readOnly,
         processResult: async (value, resolved, secrets, format, raw) => {
-            const page = (data, valueFormat, wireBytes) => pageProgramResult(registry, baseUrl, resolved, data, valueFormat, secrets, limits.trust, requestScope, wireBytes);
+            const page = (data, valueFormat, wireBytes) => pageProgramResult(registry, baseUrl, resolved, data, valueFormat, secrets, requestScope, wireBytes);
             const envelope = resolved.connector.kind === "mcp" && raw !== null && typeof raw === "object"
                 ? raw
                 : undefined;
@@ -605,7 +607,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             normalizeTimeoutMs(limits.defaultToolTimeoutMs) ??
             hostCallTimeoutMs;
         const timeoutMs = Math.min(requestedMs, Math.max(1, (limits.programDeadlineAt ?? Infinity) - Date.now()));
-        // A trusted-pool write settles here — unknown if the call never returned an
+        // A program write settles here — unknown if the call never returned an
         // outcome. Credentials are filtered from arguments; submitted private values are not.
         const sending = {};
         const outcome = yield* invocation
@@ -656,7 +658,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 : Effect.raceAllFirst([reading, fromSignal(hostAccessSignal).pipe(Effect.mapError(cancelled))])).pipe(Effect.onExit((exit) => Effect.sync(() => diagnostics?.recordCatalog(operation, Date.now() - started, Exit.isSuccess(exit), Exit.isSuccess(exit) ? exit.value : undefined))));
     });
     const meta = createMetaTools(registry, baseUrl, {
-        trust: limits.trust,
+        readOnly: limits.readOnly,
         requestScope,
         onResultRead: (dependencies) => limits.resultDependencies?.push(...dependencies),
     });
@@ -1077,7 +1079,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 defaultToolTimeoutMs: config.defaultToolTimeoutMs,
                 programDeadlineAt: Date.now() + watchdog.ms,
                 defer: config.defer,
-                trust: config.trust,
+                readOnly: config.readOnly,
                 maxWrites: config.maxWrites,
                 programWrites,
                 resultDependencies,
@@ -1087,7 +1089,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 return yield* Effect.fail(new ExecutorAdmissionError("executor_cancelled", "Execution was cancelled during sandbox setup."));
             }
             const admitted = lease;
-            // A trusted-pool write may still be on the wire when the program settles:
+            // A program write may still be on the wire when the program settles:
             // close, so a write gated after this is not sent, then let the ones
             // already dispatched finish before the scope aborts them — an
             // abandoned write would be one whose outcome nobody knows.
@@ -1114,7 +1116,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             emitted,
             diagnostics,
             program,
-            guardResult: (value, maxChars) => guardProgramReturn(value, registry, baseUrl, [...new Map(resultDependencies.map((dependency) => [JSON.stringify(dependency), dependency])).values()], sentSecrets, config.trust, logger, maxChars, programWrites.hasSucceeded),
+            guardResult: (value, maxChars) => guardProgramReturn(value, registry, baseUrl, [...new Map(resultDependencies.map((dependency) => [JSON.stringify(dependency), dependency])).values()], sentSecrets, logger, maxChars, programWrites.hasSucceeded),
         };
         const exited = Effect.exit(Effect.scoped(run)).pipe(Effect.flatMap((exit) => 
         // Releasing a QuickJS lease ends its child and rejects execute() with
@@ -1336,7 +1338,7 @@ function connectorInventory(connectors) {
         return `${prefix}${shown.join(", ")}.`;
     return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
 }
-const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, trust) => `One known read: call_tool. One known write: call_destructive_tool. Everything else: execute_code. ${trust === "trusted" ? "Trusted pool: programs may read and write; the host approves the program as a write." : "Read-only pool: programs read; writes use call_destructive_tool."} Limits: ${hostLimits.maxHostCalls} host calls, ${maxWrites} writes, ${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
+const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, readOnly) => `${readOnly ? "One known read: call_tool. Everything else: execute_code. Read-only endpoint: search and describe omit write tools, and every write call is refused." : "One known read: call_tool. One known write: call_destructive_tool. Everything else: execute_code. Writable endpoint: programs may read and write; the client approves."} Limits: ${hostLimits.maxHostCalls} host calls, ${readOnly ? "" : `${maxWrites} writes, `}${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
 ${connectorInventory(connectors)}
 
 Use async () => { ... }, no arguments. No portable ambient capabilities. API:
@@ -1383,7 +1385,7 @@ export function registerExecuteTool(server, registry, ctx) {
         hostCallTimeoutMs: hostLimits.hostCallTimeoutMs,
         watchdogMs: ctx.watchdogMs,
         defer: ctx.defer,
-        trust: ctx.trust,
+        readOnly: ctx.readOnly,
         maxWrites,
         requestScope: ctx.requestScope,
     });
@@ -1391,13 +1393,13 @@ export function registerExecuteTool(server, registry, ctx) {
         description: executeDescription(emitBudgets, {
             ...hostLimits,
             hostCallTimeoutMs: normalizeTimeoutMs(ctx.defaultToolTimeoutMs) ?? hostLimits.hostCallTimeoutMs,
-        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.trust ?? "read-only"),
+        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.readOnly === true),
         inputSchema: EXECUTE_INPUT,
         outputSchema: EXECUTE_OUTPUT,
-        // The host sees execute_code as a write only on a trusted endpoint.
+        // The client sees execute_code as a write exactly when the endpoint writes.
         annotations: {
-            readOnlyHint: ctx.trust !== "trusted",
-            destructiveHint: ctx.trust === "trusted",
+            readOnlyHint: ctx.readOnly === true,
+            destructiveHint: ctx.readOnly !== true,
             openWorldHint: true,
         },
     }, (args, extra) => {

package/dist/index.js

@@ -16,7 +16,7 @@ export { defineConfig } from "./config.js";
  * catalog lacks it. Remote catalogs load lazily, so their addresses are
  * checked at catalog load instead and stay unreachable until they match.
  */
-function resolvePools(pools, registry) {
+function resolvePools(pools, readOnly, registry) {
     const resolved = new Map();
     if (!pools)
         return resolved;
@@ -52,7 +52,8 @@ function resolvePools(pools, registry) {
                 }
             }
         }
-        resolved.set(name, { access, trust: pool.trust, grant: pool.grant ?? (() => false) });
+        // A pool inherits the deployment value unless it sets its own, either way.
+        resolved.set(name, { access, readOnly: pool.readOnly ?? readOnly, grant: pool.grant ?? (() => false) });
     }
     return resolved;
 }
@@ -190,7 +191,7 @@ export function createConnecta(config) {
         results: resolved.results,
         classification: resolved.classification,
     });
-    const pools = resolvePools(resolved.pools, registry);
+    const pools = resolvePools(resolved.pools, resolved.readOnly, registry);
     warnInsecureConfig(resolved);
     const requestAdmission = new AdmissionController(resolved.admission.requests);
     let codeAdmission;

package/dist/invocation.js

@@ -1,6 +1,6 @@
 import { withAuthorizationHandoff } from "./authorization-handoff.js";
 import { hasControlCharacters } from "./tool-name.js";
-import { surfaceAllowsTool } from "./tool-safety.js";
+import { writeRefusal } from "./tool-safety.js";
 import { Cause, Effect, Exit } from "effect";
 import { isCallAdmissionError } from "./call-admission.js";
 import { boundedEchoText, classificationCode, classifyCallError, ConnectorCallError, echoedCallArgs, framingError, } from "./errors.js";
@@ -10,6 +10,8 @@ import { splitAddress } from "./registry.js";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { validateCatalogToolInput } from "./validate.js";
 import { sentSecretsFor, sentSecretsForRequest, trackCredentialReads } from "./sent-secrets.js";
+import { recoveryFor } from "./call-recovery.js";
+import { classifyWriteOutcome } from "./write-outcome.js";
 import { classificationDigest, recordAuthFailure, recordCallEntry, replayClassificationDigest, resolveInvocationAuth, } from "./invocation-auth.js";
 import { downstreamContinuation, recordDownstreamArgumentEcho, isDownstreamInputResult, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
 function defined(values) {
@@ -166,6 +168,9 @@ export class InvocationService {
             let attempts = 0;
             let resultBytes;
             let dispatchedToConnector = false;
+            // The context a dispatched call ran with, read for recovery facts the
+            // connector recorded before an interrupting deadline (call-recovery.ts).
+            let dispatchContext;
             let preInvocationAuthFailure = false;
             let answered = false;
             const sentSecrets = sentSecretsForRequest(this.catalog.requestScope);
@@ -217,6 +222,10 @@ export class InvocationService {
             const enrich = (error, target) => {
                 if (!target)
                     return error;
+                const recovery = recoveryFor(dispatchContext);
+                const recoveryRetry = recovery?.["idempotencyKey"]
+                    ? " A deliberate retry with uncertainCall.recovery.idempotencyKey and the exact original arguments cannot repeat the write while the vendor retains that key (Stripe keeps v1 keys at least 24 hours); after that, look the object up before retrying."
+                    : "";
                 if (isTimeoutFailure(error) && dispatchedToConnector && resolved?.definition.classification === "write") {
                     const echoed = argumentEcho;
                     return {
@@ -230,8 +239,10 @@ export class InvocationService {
                             address: `${target.connector.id}.${target.toolName}`,
                             ...echoed,
                             ...("args" in echoed ? {} : { argsOmitted: true }),
+                            ...(recovery ? { recovery } : {}),
                         },
                         retry: "Do not retry automatically. Check whether the write took effect first." +
+                            recoveryRetry +
                             (echoed.argsRedacted
                                 ? " Sensitive fields are omitted; use the original arguments if reconciliation requires another call."
                                 : "args" in echoed
@@ -239,6 +250,26 @@ export class InvocationService {
                                     : " The arguments could not be echoed safely; use the exact arguments you sent."),
                     };
                 }
+                // Any other dispatched write whose outcome is unknown (a lost response
+                // body, a 5xx, an unreadable reply) keeps the facts its connector
+                // recorded before dispatch, here and through program write accounting.
+                if (recovery &&
+                    !error.uncertainCall &&
+                    dispatchedToConnector &&
+                    resolved?.definition.classification === "write" &&
+                    classifyWriteOutcome({ ok: false, dispatched: true, answered, error }) === "unknown") {
+                    const echoed = argumentEcho;
+                    error = {
+                        ...error,
+                        uncertainCall: {
+                            address: `${target.connector.id}.${target.toolName}`,
+                            ...echoed,
+                            ...("args" in echoed ? {} : { argsOmitted: true }),
+                            recovery,
+                        },
+                        retry: error.retry ?? `Do not retry automatically. Check whether the write took effect first.${recoveryRetry}`,
+                    };
+                }
                 if (error.code === "auth_required" && target.connector.startAuth) {
                     error = { ...error, code: "downstream_oauth_required" };
                 }
@@ -358,7 +389,7 @@ export class InvocationService {
                 // Activity rows and this log line are both payload-free by
                 // construction: the line is the failure's typed record, never its
                 // message, which may be the downstream's own words (INV-6).
-                if (target && details.code !== "destructive_tool_requires_approval") {
+                if (target && details.code !== "destructive_tool_requires_approval" && details.code !== "read_only_endpoint") {
                     logFailure(this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope).logger, "call failed", failureRecord({
                         connector: target.connector.id,
                         // Named only when the catalog listed it (src/operator-record.ts).
@@ -432,8 +463,11 @@ export class InvocationService {
                         reconciliationRequired: true,
                     };
                 }
-                if (!surfaceAllowsTool(target.definition.classification, context.source, context.trust)) {
-                    const canonicalAddress = `${target.connector.id}.${target.toolName}`;
+                const refusal = writeRefusal(target.definition.classification, context.source, context.readOnly);
+                if (refusal === "read_only_endpoint") {
+                    return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and 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.`);
                 }
                 // Remote MCP tools advertise their input schema in the catalog. Validate
@@ -464,6 +498,7 @@ export class InvocationService {
                     const connectorContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs, defer: this.catalog.defer }));
                     trackCredentialReads(connectorContext);
                     sentSecrets.include(sentSecretsFor(connectorContext));
+                    dispatchContext = connectorContext;
                     try {
                         if (target.connector.credential) {
                             if (!connectorContext.credential) {

package/dist/meta-tools.js

@@ -210,12 +210,6 @@ async function stashResult(bytes, results, preview, rawText) {
             totalBytes,
             hint: `${results.write ? WRITE_ALREADY_RAN + " " : ""}Paging is unavailable: text contains unpaired surrogates and can't be paged as text; request the value as JSON (value mode or a JSON-returning call) to recover it.`,
         };
-    if (!results.pageable)
-        return {
-            truncated: true,
-            totalBytes,
-            hint: `${WRITE_ALREADY_RAN} Paging is unavailable for write results on read-only pools.`,
-        };
     const id = crypto.randomUUID();
     try {
         // Base64 permits byte-range decoding, and splitting the envelope across
@@ -270,7 +264,7 @@ async function stashResult(bytes, results, preview, rawText) {
     };
 }
 /** Program calls use the direct-call envelope, ledger, expiry and authority. */
-export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, trust, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
+export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
     const data = secrets.redact(value);
     const wire = JSON.stringify({ data, format });
     if (enc.encode(wire).length <= wireBytes)
@@ -279,7 +273,6 @@ export async function pageProgramResult(registry, baseUrl, resolved, value, form
     const bytes = enc.encode(text);
     const write = resolved.definition.classification !== "read";
     const notice = await stashResult(bytes, {
-        pageable: !write || trust === "trusted",
         binding: {
             identity: registry.resultIdentity(),
             baseUrl,
@@ -304,7 +297,7 @@ export async function pageProgramResult(registry, baseUrl, resolved, value, form
     };
 }
 /** Program returns share the direct stash, with all host-admitted call dependencies. */
-export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, trust, logger, maxChars, completedWrite) {
+export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite) {
     const serialized = serializeResultText(value);
     if (serialized.length <= maxChars)
         return value;
@@ -314,7 +307,6 @@ export async function guardProgramReturn(value, registry, baseUrl, dependencies,
     const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
     const results = {
         secrets,
-        pageable: !write || trust === "trusted",
         binding: {
             identity: registry.resultIdentity(),
             baseUrl,
@@ -522,6 +514,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     });
     const catalog = new CatalogService(registry, baseUrl, {
         requestScope,
+        // search_tools never shows a read-only endpoint's writes.
+        readOnly: opts.readOnly,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
         defer: opts.defer,
@@ -536,6 +530,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         const outcome = await invocation.invoke(call.address, call.args ?? {}, {
             source,
             sentSecrets,
+            readOnly: opts.readOnly,
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             ...(opts.requestSignal !== undefined ? { requestSignal: opts.requestSignal } : {}),
             unwrapResult: call.resultMode === "value",
@@ -557,7 +552,6 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
                 const results = {
                     secrets,
-                    pageable: resolved.definition.classification === "read" || opts.trust === "trusted",
                     binding: {
                         identity: registry.resultIdentity(),
                         baseUrl,
@@ -788,7 +782,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     if (binding.program &&
                         !(await registry.recheckResultAccess(undefined, binding.classification, options.signal)))
                         return false;
-                    if (binding.classification === "write" && opts.trust !== "trusted")
+                    if (binding.classification === "write" && opts.readOnly === true)
                         return false;
                     const dependencies = binding.program ?? [binding];
                     for (const dependency of dependencies) {
@@ -809,7 +803,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         if (!tool ||
                             !(dependency.access === "catalog" ||
                                 (dependency.classification === "read" && tool.classification === "read") ||
-                                opts.trust === "trusted"))
+                                opts.readOnly !== true))
                             return false;
                     }
                     return true;
@@ -915,9 +909,11 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required 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" finds tools that run unasked; "approvalRequired" finds the fail-closed complement. 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 = "Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a connecta.result action.";
+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 approval-required 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" finds tools that run unasked; "approvalRequired" finds the fail-closed complement. 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.`;
 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 AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. 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.";
 /**
@@ -1001,7 +997,7 @@ export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
         downstreamInput: Boolean(ctx.authElicitation),
         requestScope: ctx.requestScope,
-        trust: ctx.trust,
+        readOnly: ctx.readOnly,
         defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
         probeTimeoutMs: ctx.probeTimeoutMs,
         discoveryConcurrency: ctx.discoveryConcurrency,
@@ -1028,7 +1024,7 @@ export function registerMetaTools(server, registry, ctx) {
         return mt.skills(args);
     });
     server.registerTool("search_tools", {
-        description: describedFor(registry, SEARCH_DESC, "search"),
+        description: describedFor(registry, SEARCH_DESC(ctx.readOnly === true), "search"),
         inputSchema: SEARCH_INPUT,
         outputSchema: SEARCH_OUTPUT,
         annotations: READ_ONLY_REMOTE,
@@ -1037,7 +1033,7 @@ export function registerMetaTools(server, registry, ctx) {
         return mt.searchTools(args);
     });
     server.registerTool("call_tool", {
-        description: CALL_DESC,
+        description: CALL_DESC(ctx.readOnly === true),
         inputSchema: CALL_INPUT,
         // Default mode returns native content, so no structured result is promised.
         // call_tool admits only tools that are themselves explicitly read-only;
@@ -1050,7 +1046,9 @@ export function registerMetaTools(server, registry, ctx) {
             : mt.callTool(args);
     });
     server.registerTool("call_destructive_tool", {
-        description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
+        description: ctx.readOnly === true
+            ? CALL_DESTRUCTIVE_READ_ONLY_DESC
+            : describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
         inputSchema: CALL_DESTRUCTIVE_INPUT,
         annotations: {
             destructiveHint: true,

package/dist/operator-record.d.ts

@@ -8,7 +8,7 @@ type FailureStep = "MCP handshake" | "tools/list" | "tools/call" | "resources/re
  */
 export declare const OAUTH_ERROR_CODES: ReadonlySet<string>;
 /** Inbound denial facts, never identity text or provider diagnostics. */
-export type AuthDenialReason = "authentication_failed" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "pool_not_declared" | "pool_grant_denied" | "pool_grant_threw";
+export type AuthDenialReason = "authentication_failed" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "default_grant_denied" | "default_grant_threw" | "pool_not_declared" | "pool_grant_denied" | "pool_grant_threw";
 /**
  * Name `ctor`'s instances `label` in records and fixed text. Call once, at
  * module scope, beside the class. An error whose prototype chain reaches no
@@ -104,7 +104,7 @@ export declare function failureRecord(subject: FailureSubject, failure?: unknown
  * The events an operator log reports failures as. Closed: a new one is a
  * reviewed line here, never a string assembled at the call site.
  */
-export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "connectorAccess grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP pool request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
+export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "connectorAccess grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
 /**
  * Log one failure as `[connecta] <event>` and its record. A record
  * `failureRecord` did not build is replaced, whatever its shape, by a fixed

package/dist/operator-record.js

@@ -112,6 +112,8 @@ const AUTH_DENIAL_REASONS = new Set([
     "email_domain_denied",
     "gate_denied",
     "gate_failed",
+    "default_grant_denied",
+    "default_grant_threw",
     "pool_not_declared",
     "pool_grant_denied",
     "pool_grant_threw",

package/dist/operator-ui/contract.d.ts

@@ -2,7 +2,7 @@ import type { ActivityOutcome } from "../activity.js";
 import type { ConnectaConfigDescription } from "../describe-config.js";
 import type { ConnectorStatus, ConnectorToolDescription } from "../types.js";
 import type { UiProblem } from "./model.js";
-/** The registry's final verdict, independent of the viewer's pool trust. */
+/** The registry's final verdict, independent of whether the viewer's endpoint is read-only. */
 export interface OperatorTool extends ConnectorToolDescription {
     address: string;
     classification: "read" | "write";
@@ -36,15 +36,16 @@ export interface OperatorGrant {
 export interface OperatorPool {
     name: string;
     path: string;
-    trust: "trusted" | "read-only";
+    /** Whether this pool's endpoint refuses every write. */
+    readOnly: boolean;
     /** Pool access intersected with the caller's grants. */
     grants: OperatorGrant[];
 }
 export interface OperatorViewer {
     interactive: boolean;
     grants: OperatorGrant[];
-    /** Trust of the root /mcp endpoint. */
-    trust: "trusted" | "read-only";
+    /** Whether the root /mcp endpoint refuses every write. */
+    readOnly: boolean;
     pools: OperatorPool[];
     permissions: {
         activity: boolean;