@zackbart/connecta 0.31.0 → 0.32.0

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";
@@ -389,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).
@@ -463,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

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;