@zackbart/connecta 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 All notable changes to this package are documented here.
 
+## 0.18.0 — 2026-08-13
+
+This minor release spends fewer tokens before the first call and answers
+better when a call goes wrong. The always-loaded MCP instructions and tool
+definitions are 44.6% lighter, the `execute_code` description now names the
+deployment's configured connector IDs before the first catalog search, and a
+failed `connecta.describe` entry carries the same typed recovery as a failed
+call. The compatibility change is the floor: Node 22 is now the minimum
+supported release, matching the shipped Docker template, and CI runs one job
+per pull request against it; the Cloudflare Worker target is unchanged. Stripe
+OAuth deployments must drop the connector-wide `mode` — each returned account
+now carries its own. An evaluation of erasable TypeScript syntax in
+`execute_code` programs ended in a recorded refusal, so portable programs
+remain plain JavaScript. A deployment already on Node 22 that lets accounts
+carry their Stripe mode needs no configuration change.
+
+### Added
+
+- **`execute_code` now names the deployment's connectors up front.** Its
+  description carries a connector inventory derived only from the configured
+  registry: canonical IDs in registry order, the executable shortcut when
+  sanitization changes the ID, bounded to 256 serialized bytes with an exact
+  omitted count. A cold model can scope its first catalog search without
+  guessing, and rendering the inventory performs no catalog request and no
+  credential access (#416).
+
+- **Failed `connecta.describe` entries are now as repairable as failed calls.**
+  Each failed entry carries `errorDetails` beside the preserved human text: the
+  invocation path's stable `code` and `retryable`, a route-aware `nextAction`,
+  and up to three deterministic nearby canonical addresses when the connector
+  is known. Caller-authored addresses are clamped everywhere they echo, so
+  hostile input can no longer displace partial results (#417).
+
+### Changed
+
+- **The always-loaded surface got 44.6% lighter.** The MCP instructions and the
+  seven tool definitions now carry route selection, the fail-closed read-only
+  boundary, and the minimum guest syntax — 6,850 bytes instead of 12,358.
+  Selection discipline, runtime differences, worked examples, direct-call
+  options, `get_result` rules, the `connecta.ui` reads-binding shape, and
+  repair guidance moved into the on-demand `usage` skill, which grew to a
+  deliberate 9,000-byte cap and stays byte-identical across deployments.
+  Clients that never fetch the skill keep correct routing from the compact
+  definitions alone (#418).
+
+- **Node 22 is now the minimum supported Node release.** CI and the published
+  engine range now match the Node 22 runtime used by the shipped deployment
+  template. The Worker test project continues to cover the other deployment
+  target (#422).
+
+- **Stripe OAuth mode now belongs to each returned account.** OAuth-backed
+  connectors no longer accept a connector-wide `mode`. Their neutral metadata
+  and guide support mixed live and sandbox accounts, require
+  `list_available_accounts_or_orgs`, and carry its exact `stripe_context` and
+  `livemode` into each account-scoped call. They use the stricter sandbox
+  admission ceiling. Header credentials still require one fixed mode, retain
+  key-prefix contradiction checks, and keep Stripe Connect behavior (#414).
+
+- **The reviewed Notion writes stay narrow.** Newly published workspace-private
+  creation, templates, placement, richer media, locking, and irreversible
+  content erasure do not join the maintained surface. They are distinct
+  ownership, asynchronous, ordering, file, coordination, or deletion workflows,
+  not extra fields on `create_page` or `update_page_properties`. The existing
+  request subsets remain valid, and `trash_page` stays isolated and reversible
+  (#408, #409).
+
+### Fixed
+
+- **The Node template now declares its one reviewed install script.** npm 11 no
+  longer warns that esbuild's install is unreviewed, and npm 12 will not block
+  it. The approval is pinned to `esbuild@0.28.2`; the package smoke reads the
+  generated lockfile and fails if any resolved dependency has an unapproved
+  install script, including a future esbuild version. Local and container
+  installs keep the same `tsx` runtime path (#375).
+
+- The documentation gate now ignores `.claude`, whose nested agent worktrees
+  are separate historical checkouts rather than source in the current tree.
+
 ## 0.17.0 — 2026-08-13
 
 This minor release makes catalog discovery faster and its answers more exact.

package/README.md

@@ -110,6 +110,10 @@ connector tools are reachable. Unannotated or write-capable calls stay
 individual and cross `call_destructive_tool`, where the MCP host can ask the
 operator for approval.
 
+The Node template also pins its one approved dependency install script:
+esbuild, which `tsx` needs to run the deployment source. A dependency update
+that adds or changes an install script fails the package smoke until reviewed.
+
 There are two deployment shapes and no others:
 
 - [Node, local or Docker](./templates/node/) — what `init` copies

package/dist/catalog-service.d.ts

@@ -72,6 +72,11 @@ interface CatalogFailureDetail {
     retryable: boolean;
     retryAfterMs?: number;
 }
+interface CatalogDescriptionFailureDetail extends CatalogFailureDetail {
+    nextAction?: NonNullable<CallErrorDetails["nextAction"]>;
+    /** Nearby canonical addresses, ranked deterministically by tool name. */
+    suggestions?: string[];
+}
 export interface CatalogSearchPage {
     entries: CatalogSearchEntry[];
     total: number;
@@ -109,6 +114,7 @@ export interface CatalogDescription {
     outputSchema?: unknown;
     annotations?: ToolDef["annotations"];
     error?: string;
+    errorDetails?: CatalogDescriptionFailureDetail;
 }
 export interface ResolvedCatalogTool {
     connector: Connector;

package/dist/catalog-service.js

@@ -16,6 +16,7 @@ const MAX_QUERY_TERM_LENGTH = 64;
  * of the deployment.
  */
 const MAX_IDENTITY_CONNECTORS = 3;
+const MAX_DESCRIBE_SUGGESTIONS = 3;
 const encoder = new TextEncoder();
 /** Clip one echoed query term without splitting a non-BMP code point. */
 function boundedQueryTerm(term) {
@@ -80,6 +81,39 @@ function recoveryQuery(address) {
     const candidate = separator >= 0 ? address.slice(separator + 1) : address;
     return boundedEchoText(candidate.replaceAll(/[._-]+/g, " ").trim() || address);
 }
+function editDistance(left, right) {
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        const current = [leftIndex + 1];
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            current.push(Math.min(previous[rightIndex + 1] + 1, current[rightIndex] + 1, previous[rightIndex] +
+                (left[leftIndex] === right[rightIndex] ? 0 : 1)));
+        }
+        previous = current;
+    }
+    return previous[right.length];
+}
+/** Nearby names only; descriptions never influence describe-miss recovery. */
+function describeSuggestions(connectorId, attemptedName, tools) {
+    const attempted = attemptedName.toLowerCase();
+    return tools
+        .map((tool, order) => {
+        const name = tool.name.toLowerCase();
+        return { tool, order, distance: editDistance(attempted, name) };
+    })
+        .filter(({ tool, distance }) => {
+        const longest = Math.max(attempted.length, tool.name.length);
+        return (attempted.includes(tool.name.toLowerCase()) ||
+            tool.name.toLowerCase().includes(attempted) ||
+            distance <= Math.max(2, Math.floor(longest * 0.4)));
+    })
+        .sort((left, right) => left.distance - right.distance || left.order - right.order)
+        .map(({ tool }) => `${connectorId}.${tool.name}`)
+        // A clipped address would no longer be canonical. Omit an implausibly
+        // large catalog name instead of letting one suggestion erase the page.
+        .filter((address) => boundedEchoText(address) === address)
+        .slice(0, MAX_DESCRIBE_SUGGESTIONS);
+}
 /** Serialize once and count the exact bytes the MCP adapter would emit. */
 export function boundedDiscoveryText(value, hint) {
     const text = JSON.stringify(value);
@@ -734,17 +768,48 @@ export class CatalogService {
         });
         return resolved.map(({ address, resolved: addressResolution }) => {
             if (!addressResolution) {
-                return { address, error: `Unknown address "${address}"` };
+                const message = `Unknown address "${boundedEchoText(address)}"`;
+                return {
+                    address: boundedEchoText(address),
+                    error: message,
+                    errorDetails: {
+                        ...framingError("unknown_address", message),
+                        nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
+                    },
+                };
             }
             const catalog = catalogs.get(addressResolution.connector.id);
             if (catalog instanceof Error) {
-                return { address, error: catalog.message };
+                const classified = classifyCallError(catalog, "catalog_lookup_failed");
+                const message = boundedEchoText(classified.message);
+                return {
+                    address: boundedEchoText(address),
+                    error: message,
+                    errorDetails: {
+                        code: classified.code,
+                        message,
+                        retryable: classified.retryable,
+                        ...(classified.retryAfterMs === undefined
+                            ? {}
+                            : { retryAfterMs: classified.retryAfterMs }),
+                    },
+                };
             }
             const tool = catalog?.find((item) => item.name === addressResolution.toolName);
             if (!tool) {
+                const message = `Unknown tool "${boundedEchoText(addressResolution.toolName)}" on connector "${addressResolution.connector.id}"`;
+                const suggestions = describeSuggestions(addressResolution.connector.id, addressResolution.toolName, catalog ?? []);
                 return {
-                    address,
-                    error: `Unknown tool "${addressResolution.toolName}" on connector "${addressResolution.connector.id}"`,
+                    address: boundedEchoText(address),
+                    error: message,
+                    errorDetails: {
+                        ...framingError("unknown_tool", message),
+                        nextAction: this.searchRecovery({
+                            query: recoveryQuery(addressResolution.toolName),
+                            connector: addressResolution.connector.id,
+                        }, "Find the connector's current canonical tool address."),
+                        ...(suggestions.length > 0 ? { suggestions } : {}),
+                    },
                 };
             }
             const input = tool.inputSchema ?? { type: "object" };

package/dist/execute.d.ts

@@ -6,6 +6,8 @@ import { InvocationFailure } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type { Executor, ExecutorProvider, Logger } from "./types.js";
 export declare const EXECUTE_MAX_BATCH_CALLS = 10;
+/** Complete entries plus an exact omission count, all inside this byte cap. */
+export declare const CONNECTOR_INVENTORY_MAX_BYTES = 256;
 /**
  * Default budgets for `connecta.emit`. The byte budget is a transport bound,
  * not a context bound — emitted image/audio blocks reach the model as media,

package/dist/execute.js

@@ -4,7 +4,7 @@ import { boundedDiscoveryText, CatalogService, DiscoveryPolicyError, flatSearchR
 import { errorResult, jsonResult } from "./meta-tools.js";
 import { guardExecuteResultValue, MAX_EXECUTE_LOG_CHARS, truncateExecuteText, } from "./executor-result.js";
 import { ExecutorAdmissionError, ExecutorExecutionError, isAdmittingExecutor, } from "./executor-admission.js";
-import { classifyCallError } from "./errors.js";
+import { boundedEchoText, classifyCallError } from "./errors.js";
 import { InvocationFailure, InvocationService, } from "./invocation.js";
 import { hasConnectorGuides } from "./skills.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
@@ -12,6 +12,8 @@ import { isExplicitlyReadOnly } from "./tool-safety.js";
 const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
 const EXECUTE_HOST_CALL_TIMEOUT_MS = 15_000;
+/** Complete entries plus an exact omission count, all inside this byte cap. */
+export const CONNECTOR_INVENTORY_MAX_BYTES = 256;
 /**
  * Default budgets for `connecta.emit`. The byte budget is a transport bound,
  * not a context bound — emitted image/audio blocks reach the model as media,
@@ -996,24 +998,47 @@ function discardedEmitsText(emitted) {
     ];
     return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
 }
-const executeDescription = (emitBudgets, connectorGuides) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool. execute_code is the primary surface for everything wider: make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
+function connectorInventory(connectors) {
+    const prefix = "Connectors: ";
+    if (connectors.length === 0)
+        return `${prefix}none.`;
+    const entries = connectors.map((connector) => {
+        const shortcut = sanitizeIdentifier(connector.id);
+        return shortcut === connector.id
+            ? connector.id
+            : `${connector.id} (shortcut ${shortcut})`;
+    });
+    const shown = [];
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (entry === undefined)
+            break;
+        const candidate = [...shown, entry].join(", ");
+        const omitted = entries.length - index - 1;
+        const suffix = omitted > 0 ? `; +${omitted} more.` : ".";
+        const serialized = prefix + candidate + suffix;
+        if (boundedEchoText(serialized, CONNECTOR_INVENTORY_MAX_BYTES) !== serialized) {
+            break;
+        }
+        shown.push(entry);
+    }
+    const omitted = entries.length - shown.length;
+    if (omitted === 0)
+        return `${prefix}${shown.join(", ")}.`;
+    return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
+}
+const executeDescription = (emitBudgets, connectorGuides, connectors) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool. execute_code is the primary surface for everything wider: make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
+
+${connectorInventory(connectors)}
 
-Write an async arrow function. Portable programs use no ambient capabilities. Use only:
-- Connector globals call sanitized <connectorId>.<toolName>(args): non-identifier characters become "_"; prefix a leading digit; suffix a reserved word.
-- connecta.call(address, args) and connecta.batch(calls) use canonical addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure it.
-- top-level search_tools returns { connectors: [{ id, tools }], total, offset, limit, hasMore }; connecta.search returns { tools, total, offset, limit, hasMore }; connecta.describe returns { tools }.
-- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Check address, description, requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Select by fit; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Every required key needs task or prior-result data; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. Describe one address or an addresses array. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute.${connectorGuides ? " guideRequired: true = stop. Describe clears only schema_truncated; otherwise return its exact guide, fetch with top-level skills, then write the informed call." : ""}
+Write one plain-JavaScript async arrow function. Use only:
+- <connectorId>.<toolName>(args) for a sanitized shortcut, or connecta.call(address, args) for a canonical address.
+- connecta.search(args), connecta.describe(args), and connecta.batch(calls) for discovery and independent read-only calls.
 - connecta.emit(block) — { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only; ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid/over-budget throws.
-- connecta.ui(html, options?) — one success-only view. One arg is display-only; reads use { reads: { name: { address, fixedArgs?, viewArgs? } } } and markup calls connecta.read(name, args). Admission and one budget, not two, apply; a second, over-budget, or invalid call throws catchably; the model reads the return value, not the view; return the initial summary from its variables.
+- connecta.ui(html, options?) for one success-only view; return the same initial summary the HTML renders.
 - console.log(...) — captured.
 
-QuickJS blocks imports and has no fetch, process, timers, crypto, or WebSocket. Dynamic Workers require only { loader }; bindings/modules/globalOutbound violate the contract. Then env maps are empty; node:fs/http/https are absent; outbound fetch/WebSocket/node:net/tls are denied; DNS is unresolved. Runtime builtins remain through import() and process.getBuiltinModule(), including node:path and cloudflare:workers; the set can drift. Timers/process/crypto/WebSocket and data: fetch remain. Avoid runtime-only capabilities; QuickJS fails.
-
-Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }
-
-A caught Connecta failure keeps its message and exposes code, retryable, and details; batch uses the same fields. Branch on fields, never prose. Never retry retryable: false, or rate_limited immediately; portable code cannot wait. Return JSON; reduce large results before they truncate.
-
-Plain JS. Compact schemas are TypeScript-like: write the property names they display; never guess positions or aliases.`;
+Programs have no portable ambient capabilities. Return JSON and reduce large results before they truncate. Fetch skills({ name: "usage" }) once for selection rules, exact result shapes, repair, examples, guide handling${connectorGuides ? ", connector-guide rules" : ""}, and runtime differences.`;
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(server, registry, ctx) {
     // Resolved once so the description and the collector cannot disagree about
@@ -1022,6 +1047,7 @@ export function registerExecuteTool(server, registry, ctx) {
         maxBytes: resolveEmitBudget(ctx.maxEmittedBytes, EXECUTE_MAX_EMITTED_BYTES),
         maxBlocks: resolveEmitBudget(ctx.maxEmittedBlocks, EXECUTE_MAX_EMITTED_BLOCKS),
     };
+    const connectors = registry.listConnectors();
     const handler = createExecuteTool(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, {
         ...(ctx.discoveryConcurrency !== undefined
             ? { discoveryConcurrency: ctx.discoveryConcurrency }
@@ -1034,11 +1060,11 @@ export function registerExecuteTool(server, registry, ctx) {
         ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
     });
     server.registerTool("execute_code", {
-        description: executeDescription(emitBudgets, hasConnectorGuides(registry.listConnectors())),
+        description: executeDescription(emitBudgets, hasConnectorGuides(connectors), connectors),
         inputSchema: z.object({
             code: z
                 .string()
-                .describe("One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing. So does aborting on a missing tool match or result key — re-search, describe, or read the result's actual keys here instead."),
+                .describe("One complete JavaScript async arrow function that discovers, calls, and returns the reduced answer."),
             diagnostics: z
                 .boolean()
                 .optional()

package/dist/meta-tools.js

@@ -1044,13 +1044,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search only for exactly one unreduced read, then call_tool, or for write-capable work, then call_destructive_tool. For read-only reduction, dependent or multiple calls, never search here: make one execute_code program that searches and calls. Use 2–4 distinctive action/object terms, not the full request; set connector to the obvious integration id to load one catalog instead of all; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}), page to ${MAX_SEARCH_LIMIT} if needed. safety="readOnly" returns only calls available to call_tool/code; "approvalRequired" returns the rest; omitted/"all" returns all. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, bounded; plain objects expose inputKeys, requiredInputKeys, and outputKeys; truncation flags mark incomplete shapes; matches also carry declared annotations. Require purpose/address fit plus compatible inputs, truncation, safety, and outputs — never the first lexical match. Empty or whitespace-only query browses all; non-empty input with no ASCII terms returns no match.`;
-const CALL_DESC = 'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
-const CALL_DESTRUCTIVE_DESC = "Invoke any tool that is not explicitly annotated readOnlyHint: true, including unannotated, write-capable, or destructive tools. Include a short reason explaining the intended consequence for the human reviewer; it grants no authority and is never passed downstream. The MCP destructiveHint on this meta-tool lets the host request human approval before execution. Use only after reviewing the downstream tool schema and consequences.";
-const GET_RESULT_DESC = "Page a truncated result stashed by call_tool or call_destructive_tool; a program's oversized return is not paged, so reduce it in code instead. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
+const SEARCH_DESC = `Use top-level search for one unknown-address read before call_tool, or for approval-required work before call_destructive_tool. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. For multiple, dependent, or reduced read-only calls, use one execute_code program instead. Empty query browses.`;
+const CALL_DESC = 'Call one tool explicitly annotated readOnlyHint: true. Use execute_code for multiple, dependent, or reduced read-only calls. Unannotated or write-capable tools fail closed to call_destructive_tool. fields projects JSON dot-paths; use [] through arrays. A truncated result carries a get_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.";
+const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns text, offset, nextOffset when more remains, and totalBytes.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
-const SKILLS_DESC = 'List or fetch concise guidance for choosing among Connecta meta-tools. Call skills({ name: "usage" }) once when the routing workflow is unfamiliar; do not refetch it in the same task.';
-const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact shape, or read exact JSON constraints, with connecta.describe inside execute_code.`;
+const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage once per task for program syntax, selection, repair, examples, and runtime details.';
+const SEARCH_WITH_DESCRIBE_DESC = SEARCH_DESC;
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -1060,9 +1060,9 @@ const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact sh
  * Registration is per connection and reads the configured connector set.
  */
 const GUIDE_NOTES = {
-    skills: " skills({}) also lists this deployment's scoped connector guides; fetch only an exact name listed there or carried by discovery, never one inferred from a connector id.",
-    search: " A result carrying `guide` also carries a bounded `guideSummary`. `guideRequired: true` is a hard stop: fetch that exact guide before calling. `guideRequiredReasons` explains why — `connector_required` and `approval_required` stand however you expand the schema; `schema_truncated` clears once describe returns the exact one. Otherwise fetch only when the summary names a connector convention relevant to the task. A complete, unambiguous read-only schema needs no otherwise-irrelevant guide fetch.",
-    destructive: " Before a consequential call, inspect the address through discovery or describe and fetch any connector guide it names.",
+    skills: " Also lists this deployment's connector guides by exact name.",
+    search: " A result with guideRequired: true requires its exact named connector guide before the call.",
+    destructive: " Fetch any exact connector guide named by discovery before the call.",
 };
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
 function describedFor(registry, base, note) {

package/dist/providers/stripe.d.ts

@@ -1,37 +1,37 @@
 import { type RemoteMcpAuth } from "../connectors/remote-mcp.js";
 import type { Connector } from "../types.js";
-/**
- * Which Stripe environment this instance speaks to. Required, and deliberately
- * undefaulted: there is no safe guess between an account that moves real money
- * and one that does not.
- */
+/** Which Stripe environment a static credential reaches. */
 export type StripeMode = "production" | "sandbox";
-/** Stripe publishes one hosted MCP endpoint; the credential selects the mode. */
+/** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export declare const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
-export interface StripeOptions {
-    /**
-     * Which Stripe environment this connector reaches. Shapes the title,
-     * description, guide, and admission budget, and is checked against a
-     * recognizable key prefix in `auth` headers.
-     */
-    mode: StripeMode;
-    /** Human-readable display name; defaults to "Stripe (<mode>)". */
+interface StripeCommonOptions {
+    /** Human-readable display name; defaults to "Stripe" for OAuth. */
     title?: string;
     /** Which business purpose and Stripe context this connector is for. */
     purpose: string;
-    /** OAuth by default; static headers support restricted API keys. */
-    auth?: RemoteMcpAuth;
-    /**
-     * Connect platform only: act as this connected account (`acct_...`) by
-     * sending Stripe's `Stripe-Account` header. Stripe does not support OAuth on
-     * connected-account calls, so this requires `headers` auth.
-     */
-    connectedAccount?: string;
     /** Connector-specific conventions appended to the maintained provider guide. */
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
 }
+/** OAuth sessions discover account and mode together from Stripe's live tools. */
+export interface StripeOAuthOptions extends StripeCommonOptions {
+    auth?: {
+        type: "oauth";
+    };
+    mode?: never;
+    connectedAccount?: never;
+}
+/** Static credentials have one fixed mode, including Stripe Connect calls. */
+export interface StripeHeaderOptions extends StripeCommonOptions {
+    auth: Extract<RemoteMcpAuth, {
+        type: "headers";
+    }>;
+    mode: StripeMode;
+    /** Act as one Connect account by sending Stripe's `Stripe-Account` header. */
+    connectedAccount?: string;
+}
+export type StripeOptions = StripeOAuthOptions | StripeHeaderOptions;
 /**
  * The manifest this release reviewed: both lists in one place, which is what
  * makes the classification the connector applies and the drift check that runs
@@ -47,3 +47,4 @@ export interface StripeOptions {
 export declare const STRIPE_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Stripe hosted-MCP connection. */
 export declare function stripe(id: string, options: StripeOptions): Connector;
+export {};

package/dist/providers/stripe.js

@@ -1,6 +1,6 @@
 import { remoteMcp, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
-/** Stripe publishes one hosted MCP endpoint; the credential selects the mode. */
+/** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
 /**
  * Stripe documents no MCP-specific rate limit, so this transcribes the account
@@ -89,9 +89,9 @@ const TEST_KEY = /\b(?:sk|rk|pk)_test_/;
  * Refuse a deployment whose declared mode and supplied key disagree.
  *
  * This is the one half of production/sandbox routing connecta can actually
- * enforce. Nothing here reads or reports key material: an unrecognizable
- * credential (OAuth, or a key shape this release does not know) is left alone
- * rather than guessed at, and a mismatch names only the two modes.
+ * enforce. Nothing here reads or reports key material: an unrecognizable key
+ * shape is left alone rather than guessed at, and a mismatch names only the
+ * two modes.
  */
 function assertModeMatchesKey(id, mode, auth) {
     if (auth.type !== "headers")
@@ -125,6 +125,22 @@ function resolveAuth(id, options) {
         headers: { ...auth.headers, "Stripe-Account": connectedAccount },
     };
 }
+const OAUTH_ADMISSION = STRIPE_ADMISSION.sandbox;
+function oauthUsageGuide(purpose, instructions) {
+    const accountInstructions = instructions?.trim();
+    return `# Stripe usage
+
+Scope: live and sandbox accounts. Connector purpose: ${purpose}
+
+This OAuth session may expose both live and sandbox Stripe accounts. Call \`list_available_accounts_or_orgs\`, then carry its exact \`stripe_context\` and \`livemode\` into every account-scoped call. A live-mode write moves real money; a sandbox write changes test data. Never infer the account or mode from connector metadata.
+
+- Call \`list_available_accounts_or_orgs\` before every account-scoped read or write. Select the intended result, then carry its \`stripe_context\` and \`livemode\` unchanged. If the account, mode, or supported selector is ambiguous, stop and ask; never guess.
+- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a separate connector with a deployment-configured restricted key plus Stripe's documented \`Stripe-Account\` header; OAuth does not support that path.
+${sharedUsageGuide("100 requests per second in live mode and 25 in sandbox mode")}
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
 const MODE_COPY = {
     production: {
         title: "Stripe (production)",
@@ -137,19 +153,23 @@ const MODE_COPY = {
         warning: "This is a SANDBOX Stripe connection. Nothing here is real money and none of these objects exist in production, so never answer a question about live revenue, payouts, or a named customer from this connector.",
     },
 };
-function usageGuide(mode, purpose, instructions) {
+function fixedModeUsageGuide(mode, purpose, instructions) {
     const copy = MODE_COPY[mode];
     const accountInstructions = instructions?.trim();
-    const rate = mode === "production" ? "100" : "25";
     return `# Stripe usage
 
 Mode: ${mode}. Connector purpose: ${purpose}
 
 ${copy.warning}
 
-- One OAuth session may cover more than one account in the same Stripe organization. The connector id, title, and purpose state routing intent; they do not prove which account a call will use.
-- Before every account-scoped read or write, resolve the intended organization account. Inspect the chosen tool's live input schema and carry the exact account or context field it exposes. If the account or its supported selection mechanism is ambiguous, stop and ask; never guess from the connector metadata, invent an MCP argument, or add a request header the live contract does not expose.
 - Organization accounts are not Stripe Connect connected accounts. A Connect call requires a deployment-configured restricted key plus Stripe's documented \`Stripe-Account\` header; OAuth does not support that path. Do not try to turn an organization-account call into a Connect call inside tool arguments.
+${sharedUsageGuide(`${mode === "production" ? "100" : "25"} requests per second`)}
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
+function sharedUsageGuide(rate) {
+    return `
 - Four generic tools reach any Stripe API method. Find the method with \`stripe_api_search\`, read its parameters with \`stripe_api_details\`, then call \`stripe_api_read\` (GET) or \`stripe_api_write\` (POST/PATCH/PUT/DELETE). Never guess a path or a parameter name — \`stripe_api_details\` is cheaper than a rejected write.
 - Prefer a dedicated tool when one covers the task: \`get_stripe_account_info\` for account information, \`get_balance_summary\` for balances, \`create_refund\` for refunds, \`stripe_report\` for reports. One call instead of three, and a refund named \`create_refund\` reads far more clearly in the approval a human sees than the same refund buried in \`stripe_api_write\` arguments.
 - \`stripe_api_write\` carries the blast radius of the entire write API — every POST, PATCH, PUT, and DELETE, from a customer edit to a subscription cancellation. State the method and path explicitly; expect approval on every call.
@@ -158,13 +178,11 @@ ${copy.warning}
 - This connection's tool list is not a fixed set. Stripe gates parts of its MCP catalog by account, integration, and beta enrollment, so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - Amounts are integers in the currency's minor unit: \`1099\` is 10.99 USD, and zero-decimal currencies like JPY take \`10\` for 10 JPY. Never send a decimal.
 - Send an \`Idempotency-Key\` on every write you might retry, if the tool accepts it, and reuse the same key for the retry. A retry with a fresh key is a second charge, not a second attempt.
-- Stripe answers a rate limit with \`429\` and a \`Stripe-Rate-Limited-Reason\` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ${rate} requests per second, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.
+- Stripe answers a rate limit with \`429\` and a \`Stripe-Rate-Limited-Reason\` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ${rate}, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.
 - Use \`search_stripe_documentation\` when the shape of an object or a flow is unclear; it is a read and costs nothing but a call.
 - Treat every create, update, delete, refund, and report run as a write. Connecta routes the maintained write catalog through \`call_destructive_tool\`; newly added tools also fail closed until classified.
 - An \`auth_required\` failure means this connector's Stripe authorization is missing or expired: run \`authorize_connector\` for this connector id, then retry the same call unchanged. A rejected argument or a plan restriction comes back in Stripe's own words instead — read it rather than re-authorizing.
-${accountInstructions
-        ? `\n## Account instructions\n\n${accountInstructions}\n`
-        : ""}`;
+`;
 }
 /** A maintained Stripe hosted-MCP connection. */
 export function stripe(id, options) {
@@ -172,31 +190,40 @@ export function stripe(id, options) {
     if (!purpose) {
         throw new Error("stripe() requires a non-empty account purpose.");
     }
-    const mode = options.mode;
-    if (mode !== "production" && mode !== "sandbox") {
-        throw new Error(`stripe("${id}") requires mode "production" or "sandbox".`);
-    }
     const auth = resolveAuth(id, options);
-    assertModeMatchesKey(id, mode, auth);
-    const copy = MODE_COPY[mode];
+    const mode = "mode" in options ? options.mode : undefined;
+    if (auth.type === "oauth" && mode !== undefined) {
+        throw new Error(`stripe("${id}") cannot declare a connector-wide mode for OAuth; Stripe returns mode with each account.`);
+    }
+    if (auth.type === "headers" && mode !== "production" && mode !== "sandbox") {
+        throw new Error(`stripe("${id}") with headers auth requires mode "production" or "sandbox".`);
+    }
+    if (auth.type === "headers") {
+        assertModeMatchesKey(id, mode, auth);
+    }
+    const copy = mode === undefined ? undefined : MODE_COPY[mode];
     const connector = remoteMcp(id, {
         url: STRIPE_MCP_ENDPOINT,
-        title: options.title ?? copy.title,
-        description: `Stripe payments (${copy.blurb}) — ${purpose}`,
+        title: options.title ?? copy?.title ?? "Stripe",
+        description: mode === undefined
+            ? `Stripe payments (live and sandbox accounts) — ${purpose}`
+            : `Stripe payments (${copy?.blurb}) — ${purpose}`,
         auth,
         requireHttps: true,
-        callAdmission: STRIPE_ADMISSION[mode],
+        callAdmission: mode === undefined ? OAUTH_ADMISSION : STRIPE_ADMISSION[mode],
         usageGuide: {
-            content: usageGuide(mode, purpose, options.instructions),
-            // Explicit rather than derived: production versus sandbox is the fact an
-            // agent must not get wrong. Multi-account OAuth also has to reach browse
-            // before connector metadata can be mistaken for authenticated identity.
-            summary: mode === "production"
-                ? "PRODUCTION: real money. OAuth may span organization accounts; resolve the account from live schemas before acting."
-                : "Sandbox: test data only. OAuth may span organization accounts; resolve the account from live schemas before acting.",
-            // Not `required`. The four generic tools are the routing decision, and
-            // the mode warning already rides the title and description; a guide
-            // forced into every call would pay for the same paragraph repeatedly.
+            content: mode === undefined
+                ? oauthUsageGuide(purpose, options.instructions)
+                : fixedModeUsageGuide(mode, purpose, options.instructions),
+            // Explicit rather than derived: fixed credentials must lead with mode,
+            // while OAuth must lead with its account-scoped selector pair.
+            summary: mode === undefined
+                ? "Live and sandbox Stripe accounts. List accounts; carry the returned stripe_context and livemode before acting."
+                : mode === "production"
+                    ? "PRODUCTION: real money. This static credential has one fixed live-mode scope."
+                    : "Sandbox: test data only. This static credential has one fixed sandbox scope.",
+            // Not `required`. The four generic tools are the routing decision; a
+            // guide forced into every call would pay for the same prose repeatedly.
         },
         ...(options.maxResultBytes !== undefined
             ? { maxResultBytes: options.maxResultBytes }

package/dist/routes/ui.js

@@ -28,7 +28,7 @@ const INERT_ICON_HEADERS = {
     "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
     "X-Content-Type-Options": "nosniff",
 };
-/** Per-request base64 nonce for an operator shell's scripts (Node 20+ and Workers). */
+/** Per-request base64 nonce for an operator shell's scripts (Node 22+ and Workers). */
 function uiScriptNonce() {
     const bytes = crypto.getRandomValues(new Uint8Array(16));
     let binary = "";

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Connecta exposes seven meta-tools. For one read at an unknown address, search_tools with 2\u20134 distinctive action/object terms and includeSchemas=\"compact\", then one call_tool \u2014 a lone cold call is cheaper direct than a program. For read-only reduction, multiple or dependent calls, loops, joins, or branches, do not call top-level search_tools: make one execute_code call whose program searches, selects, calls, and reduces; never return discovery for another call. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. Unannotated, write-capable, or destructive tools stay top level: search_tools, then call_destructive_tool; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: \"usage\" }).";
+export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use fields or get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: \"usage\" }) once for program syntax, selection, repair, examples, and runtime details.";
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export declare const USAGE_SKILL: string;
 /** The always-loaded MCP `instructions` string. */