@zackbart/connecta 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,108 @@
 
 All notable changes to this package are documented here.
 
+## 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/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;
@@ -138,6 +139,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 +148,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

@@ -167,6 +167,7 @@ export class CatalogService {
     probeTimeoutMs;
     concurrency;
     searchRoute;
+    readOptions;
     loaded = new Map();
     loading = new Map();
     constructor(registry, baseUrl, options = {}) {
@@ -177,6 +178,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 +214,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;

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,5 +1,6 @@
 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";
@@ -157,6 +158,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 +167,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 +193,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 {};