@zackbart/connecta 0.16.1 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,186 @@
 
 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.
+Agent reads can use a verified stale catalog while one bounded refresh runs,
+guide summaries now read Markdown as prose, compact schemas retain more declared
+constraints, array projection distinguishes misses from genuine nulls, and
+Mixpanel carries the conditional rules its live tools enforce. One construction
+contract tightens: an explicit `usageGuide.summary` over 120 characters now
+refuses to boot. Deployments whose summaries fit, or which let Connecta derive
+them, need no configuration change. Operator catalog reads retain their blocking
+freshness behavior. This release also makes the two code sandboxes' runtime
+differences explicit. The shipped
+Worker example is already loader-only; deployments that added executor
+`bindings`, `modules`, or `globalOutbound` must remove them. Existing portable
+`execute_code` programs keep their behavior. Programs can now classify a caught
+Connecta failure without parsing its message.
+
+### Changed
+
+- An explicit `usageGuide.summary` longer than 120 characters after whitespace
+  normalization now throws during registry construction. Exactly 120 remains
+  valid, and a blank explicit summary still falls back to derivation (#392).
+
+- **Agent catalog reads now serve a verified stale entry while they refresh it.**
+  Search, describe, and code-mode calls no longer await a downstream listing
+  when the runtime already holds a complete catalog inside its stale window.
+  The inbound request still causes the refresh; there is no timer, warmup, or
+  credential probe. One bounded refresh per connector owns and closes a fresh
+  scope, while operator status stays blocking and shows whether the last agent
+  read in this runtime was fresh or stale (#396).
+
+### Fixed
+
+- **Caught `execute_code` failures now keep their machine-readable type.**
+  Calls, connector shortcuts, discovery, emitted-output and UI validation,
+  batch validation, and host-call budgets still throw with the same human
+  message, but now expose `code`, `retryable`, and full `details`. Batch entries
+  use the same codes. A per-run authenticated frame prevents connector prose or
+  guest code from forging the host transport on either executor (#393).
+
+- **`execute_code` now tells the truth about each shipped sandbox.** QuickJS
+  has no `fetch`, `process`, timers, `crypto`, or `WebSocket`, and blocks
+  imports. Loader-only Dynamic Workers deny outbound fetch, WebSocket,
+  `node:net`, and `node:tls`; leave DNS unresolved; expose no environment
+  bindings or filesystem/HTTP builtins; but retain local `data:` fetch,
+  runtime globals, and a non-contract builtin set that can drift. The example
+  pins the required loader-only construction, and agent guidance tells portable
+  programs to use none of that Dynamic-only authority (#390).
+
+- **Clerk-authenticated operator pages now wait for ClerkJS before booting.**
+  The loader runs before the later inline operator bundle instead of deferring
+  until after parsing, so a fresh page no longer mistakes normal script order
+  for a network failure. Clerk's major-to-pinned version redirect remains
+  supported, and a real loader failure keeps the existing clear error (#403).
+
+- **Stripe's guide now treats connector identity as routing intent, not account
+  proof.** One OAuth session may cover several accounts in one organization,
+  so agents resolve the intended account through the live tool schema and stop
+  when the target or selector is ambiguous. The guide also keeps organization
+  accounts separate from the restricted-key-only Stripe Connect path (#404).
+
+- **The no-account-model constitution now matches provider-owned sessions.**
+  Connecta still has no account dimension: credentials, storage, admission,
+  and health remain connector-scoped. A provider may expose its own account
+  scope only through its live schema; metadata never proves identity, and an
+  ambiguous target or selector stops instead of becoming a guess (#410).
+
+- **The reviewed Notion page contracts are current again.** Notion added
+  create-page template and placement options plus update-page locking,
+  template, and erase options. The existing parent, properties, Markdown,
+  children, emoji, and trash request subsets remain valid, so this release
+  records the two changed endpoint digests without adding the new capabilities.
+  Their product decisions remain in #408 and #409.
+
+- **Array field misses now report what happened.** A path that misses every
+  element appears in `unmatchedFields` instead of returning a clean array of
+  false nulls. A heterogeneous array keeps its positional result and names the
+  path in `partialFields`, so genuine downstream nulls remain distinguishable.
+  Schema-backed misses keep the same bounded guidance through nested arrays;
+  schema-free projections still report their observed misses (#394).
+- Derived guide summaries now join a hard-wrapped opening paragraph before
+  selecting a complete sentence or shortening at a clause or word boundary.
+  Frontmatter, fences, headings, rules, tables, and description fallbacks keep
+  their prior roles; multi-line HTML comments are now skipped whole (#392).
+
+- **Compact schemas now carry declared numeric and string constraints.** Search
+  and compact describe show numeric bounds, multiples, string length bounds,
+  patterns, and formats beside the affected type. Search keeps its 1,024-byte
+  schema ceiling and 256-byte node budget: a constraint that does not fit is
+  dropped whole, and the existing truncation flag sends the caller to describe
+  for the complete shape (#391).
+
+- **Carry Mixpanel's three enforced conditional-input rules in its maintained
+  guide.** A live read-only audit confirmed that `Get-Business-Context`,
+  `Get-Property-Values`, and `List-Properties` accept shapes in their advertised
+  schemas that their implementations reject. Connecta still preserves the
+  hosted schemas unchanged; the guide now prevents those rejected calls, the
+  vetted manifest records schema digests for all 63 tools, and the provider
+  defect is tracked upstream. The maintainer drift check also frames
+  Mixpanel's service account as its documented `Bearer Basic` value instead of
+  ordinary HTTP Basic (#395).
+
 ## 0.16.1 — 2026-08-13
 
 This is the cleanup that follows 0.16.0 out the door: the packaging housekeeping

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

@@ -1,5 +1,6 @@
 import type { CallErrorDetails } from "./errors.js";
 import type { ConnectorOperationOptions, RegistryView } from "./registry.js";
+import type { DeferredWork } from "./connector-scope.js";
 import type { Connector, ToolDef } from "./types.js";
 export declare const DEFAULT_SEARCH_LIMIT = 8;
 export declare const MAX_SEARCH_LIMIT = 100;
@@ -71,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;
@@ -108,6 +114,7 @@ export interface CatalogDescription {
     outputSchema?: unknown;
     annotations?: ToolDef["annotations"];
     error?: string;
+    errorDetails?: CatalogDescriptionFailureDetail;
 }
 export interface ResolvedCatalogTool {
     connector: Connector;
@@ -138,6 +145,7 @@ export declare class CatalogService {
     private readonly probeTimeoutMs;
     private readonly concurrency;
     private readonly searchRoute;
+    private readonly readOptions;
     private readonly loaded;
     private readonly loading;
     constructor(registry: RegistryView, baseUrl: string, options?: {
@@ -146,6 +154,8 @@ export declare class CatalogService {
         concurrency?: number;
         /** The discovery route recovery records name. Default `search_tools`. */
         searchRoute?: SearchRoute;
+        /** Runtime-owned tail for stale-while-revalidate catalog reads. */
+        defer?: DeferredWork;
     });
     /**
      * Send a caller back to discovery through the surface it can actually reach.

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);
@@ -167,6 +201,7 @@ export class CatalogService {
     probeTimeoutMs;
     concurrency;
     searchRoute;
+    readOptions;
     loaded = new Map();
     loading = new Map();
     constructor(registry, baseUrl, options = {}) {
@@ -177,6 +212,12 @@ export class CatalogService {
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
         this.searchRoute = options.searchRoute ?? "search_tools";
+        this.readOptions = options.defer
+            ? {
+                defer: options.defer,
+                refreshTimeoutMs: this.probeTimeoutMs,
+            }
+            : undefined;
     }
     /**
      * Send a caller back to discovery through the surface it can actually reach.
@@ -207,7 +248,7 @@ export class CatalogService {
         if (inFlight)
             return inFlight;
         const loading = this.registry
-            .getTools(id, this.baseUrl, this.requestScope, callOptions)
+            .getTools(id, this.baseUrl, this.requestScope, callOptions, this.readOptions)
             .then((tools) => {
             this.loaded.set(id, tools);
             return tools;
@@ -727,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/catalog.js

@@ -2,6 +2,7 @@ const DEFAULT_DESCRIPTION_LENGTH = 240;
 const DISCOVERY_DESCRIPTION_LENGTH = 160;
 export const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1_024;
 const MAX_COMPACT_DISCOVERY_ENUM_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
+const MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
 const schemaEncoder = new TextEncoder();
 const COMPACT_DISCOVERY_TRUNCATION = " /* truncated */";
 export function summarizeDescription(text, full) {
@@ -323,7 +324,8 @@ function declaresShape(s) {
         s.const !== undefined ||
         s.items !== undefined ||
         s.properties !== undefined ||
-        s.type !== undefined);
+        s.type !== undefined ||
+        constraintEntries(s).length > 0);
 }
 /**
  * Parenthesize a top-level union so it doesn't read as part of a surrounding
@@ -366,6 +368,56 @@ function renderEnum(values, byteLimit, onTruncated) {
     }
     return rendered;
 }
+function safeConstraintValue(value) {
+    return JSON.stringify(value).replaceAll("*/", "*\\/");
+}
+function constraintEntries(schema) {
+    const entries = [];
+    const number = (keyword, label) => {
+        const value = schema[keyword];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            entries.push(`${label} ${value}`);
+        }
+    };
+    const integer = (keyword, label) => {
+        const value = schema[keyword];
+        if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+            entries.push(`${label} ${value}`);
+        }
+    };
+    number("minimum", ">=");
+    number("exclusiveMinimum", ">");
+    number("maximum", "<=");
+    number("exclusiveMaximum", "<");
+    number("multipleOf", "multiple of");
+    integer("minLength", "length >=");
+    integer("maxLength", "length <=");
+    if (typeof schema.format === "string") {
+        entries.push(`format ${safeConstraintValue(schema.format)}`);
+    }
+    if (typeof schema.pattern === "string") {
+        entries.push(`pattern ${safeConstraintValue(schema.pattern)}`);
+    }
+    return entries;
+}
+function renderConstraints(base, schema, byteLimit, onTruncated) {
+    const entries = constraintEntries(schema);
+    if (entries.length === 0)
+        return base;
+    const kept = [];
+    for (const entry of entries) {
+        const candidate = ` /* ${[...kept, entry].join("; ")} */`;
+        if (byteLimit !== undefined &&
+            schemaEncoder.encode(candidate).length > byteLimit) {
+            onTruncated?.();
+            continue;
+        }
+        kept.push(entry);
+    }
+    return kept.length === 0
+        ? base
+        : `${grouped(base)} /* ${kept.join("; ")} */`;
+}
 function renderSchema(schema, defs, seen, depth, options) {
     if (depth > 4)
         return "…";
@@ -405,24 +457,36 @@ function renderSchema(schema, defs, seen, depth, options) {
         seen.add(name);
         const rendered = renderSchema(target, defs, seen, depth, options);
         seen.delete(name);
-        return rendered;
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
     }
     const union = (s.oneOf ?? s.anyOf);
     if (Array.isArray(union)) {
-        return (union
+        const rendered = union
             .map((u) => renderSchema(u, defs, seen, depth + 1, options))
             .join(" | ") ||
-            "unknown");
+            "unknown";
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
     }
     if (Array.isArray(s.enum)) {
-        return renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
+        const rendered = renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
     }
     // Checked before type/properties so a discriminator like
     // { type: "string", const: "emoji" } renders as "emoji" rather than string.
     // JSON.stringify(undefined) returns undefined (not a string), so an explicit
     // `const: undefined` must fall through to the regular type rendering.
-    if (s.const !== undefined)
-        return JSON.stringify(s.const);
+    if (s.const !== undefined) {
+        const rendered = JSON.stringify(s.const);
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
+    }
     const type = s.type;
     if (type === "array" || s.items) {
         const items = s.items
@@ -454,10 +518,20 @@ function renderSchema(schema, defs, seen, depth, options) {
         })
             .join(", ")} }`;
     }
-    if (typeof type === "string")
-        return type;
-    if (Array.isArray(type))
-        return type.join(" | ");
+    if (typeof type === "string") {
+        return options.renderConstraints
+            ? renderConstraints(type, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : type;
+    }
+    if (Array.isArray(type)) {
+        const rendered = type.join(" | ");
+        return options.renderConstraints
+            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+            : rendered;
+    }
+    if (options.renderConstraints && constraintEntries(s).length > 0) {
+        return renderConstraints("unknown", s, options.constraintByteLimit, options.onConstraintTruncated);
+    }
     return JSON.stringify(schema);
 }
 const compactSchemas = new WeakMap();
@@ -475,6 +549,7 @@ export function compactSchema(schema) {
         rendered = renderSchema(schema, defs, new Set(), 0, {
             propertyDescriptions: true,
             requiredFirst: false,
+            renderConstraints: true,
         });
     }
     catch {
@@ -534,6 +609,7 @@ export function compactDiscoverySchema(schema) {
     };
     let rendered;
     let enumTruncated = false;
+    let constraintTruncated = false;
     try {
         rendered = renderSchema(schema, defs, new Set(), 0, {
             propertyDescriptions: false,
@@ -545,15 +621,41 @@ export function compactDiscoverySchema(schema) {
             onEnumTruncated: () => {
                 enumTruncated = true;
             },
+            renderConstraints: true,
+            constraintByteLimit: MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
+            onConstraintTruncated: () => {
+                constraintTruncated = true;
+            },
         });
     }
     catch {
         rendered = JSON.stringify(schema);
     }
+    if (schemaEncoder.encode(rendered).length >
+        MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
+        try {
+            rendered = renderSchema(schema, defs, new Set(), 0, {
+                propertyDescriptions: false,
+                requiredFirst: true,
+                enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
+                onEnumTruncated: () => {
+                    enumTruncated = true;
+                },
+                renderConstraints: false,
+            });
+            constraintTruncated = true;
+        }
+        catch {
+            rendered = JSON.stringify(schema);
+        }
+    }
     const bytes = schemaEncoder.encode(rendered);
     let result;
     if (bytes.length <= MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
-        result = { text: rendered, truncated: enumTruncated };
+        result = {
+            text: rendered,
+            truncated: enumTruncated || constraintTruncated,
+        };
     }
     else {
         result = {

package/dist/errors.d.ts

@@ -11,12 +11,10 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited
  * Its own code because the next move is none of the others': not a retry,
  * not `authorize_connector`, not a reshaped argument object, but
  * re-addressing — look the identifier up again, or accept the absence and
- * carry on. Inside `execute_code` a program reads that difference off a
- * `connecta.batch` entry's `errorDetails.code` — continue past this one,
- * abort on `connector_call_failed` — or lets the failure escape uncaught so
- * the model sees the typed envelope. Never off a caught error: the guest
- * bridge reduces a rejected host call to `new Error(message)` and drops
- * every own property, and message prose cannot be classified.
+ * carry on. Inside `execute_code` a program reads that difference from a
+ * caught error's `code` or a `connecta.batch` entry's `errorDetails.code` —
+ * continue past this one, abort on `connector_call_failed`. Message prose
+ * cannot be classified.
  *
  * Use it only where the provider distinguishes absence from a permission
  * gap. A status that means both "it is not there" and "you cannot see it" —

package/dist/execute.d.ts

@@ -1,10 +1,13 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import type { ActivityRequestContext } from "./activity.js";
+import type { DeferredWork } from "./connector-scope.js";
 import { type ToolResult } from "./meta-tools.js";
 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,
@@ -157,6 +160,8 @@ export declare function buildSandboxProviders(registry: RegistryView, baseUrl: s
      * blocks nobody will ever return.
      */
     emitCollector?: EmitCollector;
+    /** Runtime-owned tail for stale catalog refreshes. */
+    defer?: DeferredWork;
 }): Promise<ExecutorProvider[]>;
 /** The execute_code handler. Exported for direct testing. */
 export declare function createExecuteTool(registry: RegistryView, baseUrl: string, executor: Executor, logger: Logger, activity?: ActivityRequestContext, config?: {
@@ -164,6 +169,7 @@ export declare function createExecuteTool(registry: RegistryView, baseUrl: strin
     probeTimeoutMs?: number;
     maxEmittedBytes?: number;
     maxEmittedBlocks?: number;
+    defer?: DeferredWork;
 }): ({ code, diagnostics: diagnosticsRequested }: {
     code: string;
     diagnostics?: boolean;
@@ -189,5 +195,6 @@ export declare function registerExecuteTool(server: McpServer, registry: Registr
     maxEmittedBytes?: number;
     /** Block-count budget for connecta.emit. Default 32. */
     maxEmittedBlocks?: number;
+    defer?: DeferredWork;
 }): void;
 export {};