@zackbart/connecta 0.7.1 → 0.7.4

package/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 All notable changes to this package are documented here.
 
+## 0.7.4 — 2026-07-27
+
+0.7.4 moves the built-in QuickJS executor out of the HTTP-serving process. A
+runaway guest used to occupy Node's event loop for its entire wall budget —
+health checks, ordinary tool calls, timers, and shutdown all waited behind it.
+Guest code now runs in a bounded pool of replaceable child processes behind
+FIFO admission, so the serving thread stays responsive regardless of what the
+model wrote, and a WASM abort or interpreter OOM kills a disposable child
+instead of the server. Deployments without an `executor`, and Workers
+deployments on `DynamicWorkerExecutor`, can take this release without reading
+further — the nine base meta-tools and every package entrypoint are untouched.
+Node code-mode deployments should note two intentional guest-visible changes:
+synchronous guest CPU gets its own 250 ms default budget separate from the
+30 s wall clock, and connector namespaces are lazy proxies, so
+`Object.keys(github)` is empty and an unknown function fails through the host
+bridge rather than at property access. Neither grants any authority.
+
+### Added
+
+- **QuickJS child-process pool with bounded admission** (issue #83, PR #116).
+  `quickJsExecutor()` gains `cpuTimeMs`, `concurrency`, `maxQueueSize`, and
+  `queueTimeoutMs` beside the existing wall/memory/stack caps. Admission is
+  acquired before provider construction, so queued calls retain no catalogs or
+  request-scoped closures; overflow and queue expiry return the stable,
+  retryable `executor_overloaded` error with `retryAfterMs`, and cancellation
+  and shutdown report `executor_cancelled` / `executor_closed`. Every
+  parent/child IPC envelope is byte-bounded, the parent treats child messages
+  as untrusted input, and a wall timeout retires the child on a structural
+  flag rather than error text a guest could fabricate.
+- **`Connecta.close()`** drains and releases executor resources, idempotently.
+  The Node `listen()` adapter calls it the moment graceful shutdown begins, so
+  sandbox children stop holding open the very requests shutdown waits on.
+- **`AdmittingExecutor` and `ExecutorLease`** extend the one-method `Executor`
+  seam for bounded executors. The lease carries execution so an
+  already-admitted caller cannot acquire twice and deadlock a pool of one;
+  `DynamicWorkerExecutor` remains structurally compatible unchanged.
+- **HTTP client disconnects now cancel in-flight work** in the Node adapter:
+  the abort propagates through the Web `Request` into `execute_code` catalog
+  construction, queued admission, host calls, and the running child.
+
+### Fixed
+
+- **Downstream session termination gets a realistic acknowledgement window and
+  an operator-visible failure signal** (issue #96, PR #117). Probe callers
+  retain their 100 ms teardown cap while the headers-only `DELETE` gets one
+  second for a cross-internet round trip; Workers keep that bounded tail alive
+  with `waitUntil`. Refusals and transport failures now warn through the
+  deployment logger, and expiry is reported honestly as unacknowledged because
+  the downstream may still complete a request that was already sent.
+
+## 0.7.3 — 2026-07-27
+
+0.7.3 is the first published package after 0.7.1. It consolidates the
+unpublished 0.7.2 candidate with the hardening and operator work that followed:
+catalog deadlines and authorization recovery, session-safe operator pages,
+terminal probe and QuickJS cleanup, decisive credential-shape drift, stronger
+documentation checks, and a read-only toolkit map. There are no dependency,
+configuration, storage-schema, or breaking TypeScript changes. The authenticated
+`/ui/data` response gains one additive `toolkits` array; existing fields and
+package entrypoints are unchanged.
+
+### Added
+
+- **Connections shows the configured toolkit views** (PR #112). Unrestricted
+  operators can inspect connector membership, tool inclusions/exclusions,
+  currently loaded effective tool counts, and copyable scoped MCP URLs without
+  gaining any mutation or persistence path. Toolkit-restricted identities still
+  cannot enumerate deployment-wide data, the open HTML shell remains data-free,
+  and config-only toolkit descriptions never leave the server.
+
+### Changed
+
+- **Discovery deadlines now govern the catalog work, not only the caller's
+  wait** (issue #98). `list_connectors`, `search_tools`, and `describe_tools`
+  pass `discovery.probeTimeoutMs` into a full downstream `tools/list` walk.
+  Expiry cancels the in-flight page where the transport supports it and prevents
+  another page from starting; existing tool/page bounds remain as backstops,
+  partial catalogs are never published, and the last complete stale catalog
+  remains eligible.
+- **`nextCursor: null` is accepted as end-of-pagination** (issue #99). This
+  narrow compatibility concession treats the common JSON null spelling like an
+  absent cursor while preserving empty string as a real cursor and retaining
+  the SDK's validation for every tool and other result field.
+
+### Fixed
+
+- **Authorization expiry is classified consistently across a catalog walk**
+  (issue #97). A downstream 401 on any `tools/list` page now reports
+  `auth_required` with the pending authorization URL, latches that verdict for
+  the request scope, and never publishes the prefix collected before failure.
+  Network, protocol, and malformed-page failures remain ordinary errors.
+- **Operator pages clear stale identity data when Clerk changes in another tab
+  or outside the page** (issue #92). Connector inventory, masked credential
+  metadata and notices, activity rows, toolkit rows, and capability navigation
+  are discarded together, and the next navigation fetches under the new session
+  rather than repainting cached data.
+- **The three operator routes handle HEAD and small navigation-state edges
+  correctly** (issue #93). `/`, `/credentials`, and `/activity` return their GET
+  headers with no HEAD body; Back/Forward focus stays visible while gated;
+  credential notices clear on page changes; and credential controls use the
+  same Clerk capability predicate as the mutation API.
+- **Stored credential-shape drift is decisive on both status and calls** (issue
+  #90). The fast connector inventory reports the existing `auth_required`
+  replacement state instead of a stale `ok`, while `ctx.credential.get()` and
+  `getAll()` reject the obsolete shape before returning any value. Generic
+  failed health checks remain non-decisive, valid stored supersets remain
+  readable, and replacement/removal remains the recovery path.
+- **Probe teardown cannot be skipped or resurrect a closed request scope**
+  (issue #91). Sibling work settles before shared teardown, cleanup no longer
+  short-circuits on the first rejection, and a closed scope remains terminal.
+  The formerly exported scope-borrowing option remains accepted as deprecated
+  and ignored so the fix does not create a TypeScript compatibility break.
+- **QuickJS host-result cleanup is deterministic under timeout and load**
+  (issue #84). Settled bridge results are bounded, consumed exactly once, and
+  released when execution completes or its deadline wins, preventing late work
+  from retaining unobservable values.
+- **The documentation guard catches the legacy syntax it was meant to prevent**
+  (issue #94). Bare `§N` citations now fail on live source, docs, examples, and
+  README surfaces—including extensionless files—while historical changelog
+  entries remain explicitly exempt. Negative fixtures cover every structural
+  invariant.
+
 ## 0.7.1 — 2026-07-27
 
 0.7.1 is a security-and-bounds patch. It closes both redirect paths that could

package/README.md

@@ -50,7 +50,9 @@ An optional tenth meta-tool, `execute_code`, runs model-written async JavaScript
 in a sandbox with no network, filesystem, or environment access — only the
 explicitly read-only tools as callable globals — turning a loop, a join across
 connectors, or a filter over a large response into one round trip instead of a
-dozen. Configure no `executor` and connecta is exactly the nine-tool server.
+dozen. The built-in Node executor runs QuickJS in bounded, replaceable child
+processes so guest CPU never occupies the HTTP event loop. Configure no
+`executor` and connecta is exactly the nine-tool server.
 
 ## Why it's shaped this way
 
@@ -95,7 +97,8 @@ rather than a redaction pass: the event type has nowhere to put a payload, which
 is what keeps an operations log from becoming something worth stealing.
 
 **Operator pages that cannot administer the deployment.** Connections at `GET /`
-shows connector health, tool counts, and downstream authorization links;
+shows connector health, tool counts, downstream authorization links, and a
+read-only map of the toolkit views declared in deployment config;
 `/credentials` rotates stored secrets; and `/activity` shows the optional
 payload-free ledger. They share one data-free shell with no build step and use
 authenticated private APIs for deployment data. They cannot add a connector,

package/dist/connector-scope.d.ts

@@ -1,13 +1,16 @@
 import type { Connector, ConnectorContext } from "./types.js";
+/** Runtime hook for work that may safely continue after a response is ready. */
+export type DeferredWork = (promise: Promise<unknown>) => void;
 /**
  * Tell a connector that a scope owned by the core has ended.
  *
  * Scope teardown is deliberately best-effort: a missing hook is a no-op and a
  * rejected hook is swallowed so cleanup can never replace the probe result that
  * caused it. The hook gets a small, fixed completion window so edge runtimes do
- * not cut off a real close as the response ends, but one that never settles
- * cannot hold the completed probe open indefinitely. Callers own the
- * at-most-once guarantee and must not use the scope again after this returns.
+ * not cut off a real close as the response ends. When the runtime supplies
+ * `defer`, the bounded tail is handed to it without extending the caller-facing
+ * window. Callers own the at-most-once guarantee and must not use the scope
+ * again after this returns.
  */
-export declare function closeConnectorScope(connector: Connector, ctx: ConnectorContext): Promise<void>;
+export declare function closeConnectorScope(connector: Connector, ctx: ConnectorContext, defer?: DeferredWork): Promise<void>;
 //# sourceMappingURL=connector-scope.d.ts.map

package/dist/connector-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector-scope.d.ts","sourceRoot":"","sources":["../src/connector-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAK9D;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,IAAI,CAAC,CAsBf"}
+{"version":3,"file":"connector-scope.d.ts","sourceRoot":"","sources":["../src/connector-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAe9D,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAa/D;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,gBAAgB,EACrB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/connector-scope.js

@@ -1,32 +1,52 @@
 /** Enough for local transport abort/close without letting cleanup own latency. */
 const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
+/**
+ * Bound on cleanup continued after the caller-facing window expires.
+ *
+ * `remoteMcp` spends at most one second asking the downstream to terminate its
+ * session, leaving another second for the local close. Custom hooks still get a
+ * finite background window: handing a never-settling promise to a Worker's
+ * `waitUntil` would otherwise keep the invocation alive until the platform cap.
+ */
+const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
+/** Resolve when `work` settles or `budgetMs` expires; never reject. */
+function waitAtMost(work, budgetMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, budgetMs);
+        work.then(() => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
 /**
  * Tell a connector that a scope owned by the core has ended.
  *
  * Scope teardown is deliberately best-effort: a missing hook is a no-op and a
  * rejected hook is swallowed so cleanup can never replace the probe result that
  * caused it. The hook gets a small, fixed completion window so edge runtimes do
- * not cut off a real close as the response ends, but one that never settles
- * cannot hold the completed probe open indefinitely. Callers own the
- * at-most-once guarantee and must not use the scope again after this returns.
+ * not cut off a real close as the response ends. When the runtime supplies
+ * `defer`, the bounded tail is handed to it without extending the caller-facing
+ * window. Callers own the at-most-once guarantee and must not use the scope
+ * again after this returns.
  */
-export async function closeConnectorScope(connector, ctx) {
+export async function closeConnectorScope(connector, ctx, defer) {
     try {
         const closing = connector.closeScope?.(ctx);
         if (!closing)
             return;
-        await new Promise((resolve) => {
-            const timer = setTimeout(resolve, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
-            // Both handlers stay attached after the timer wins, so a late rejection
-            // is still consumed rather than becoming an unhandled rejection.
-            closing.then(() => {
-                clearTimeout(timer);
-                resolve();
-            }, () => {
-                clearTimeout(timer);
-                resolve();
-            });
-        });
+        // Attach both handlers before either timer can win, so a late rejection is
+        // consumed rather than becoming an unhandled rejection.
+        const settled = closing.then(() => { }, () => { });
+        if (defer) {
+            try {
+                defer(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS));
+            }
+            catch {
+                // A runtime hook is best-effort too; the caller cap still applies.
+            }
+        }
+        await waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
     }
     catch {
         // The scope is over whether or not the connector managed to clean it up.

package/dist/connector-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"connector-scope.js","sourceRoot":"","sources":["../src/connector-scope.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAoB,EACpB,GAAqB;IAErB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,+BAA+B,CAAC,CAAC;YACnE,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,CAAC,IAAI,CACV,GAAG,EAAE;gBACH,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,EAAE,CAAC;YACZ,CAAC,EACD,GAAG,EAAE;gBACH,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,EAAE,CAAC;YACZ,CAAC,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC"}
+{"version":3,"file":"connector-scope.js","sourceRoot":"","sources":["../src/connector-scope.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,+BAA+B,GAAG,KAAK,CAAC;AAK9C,uEAAuE;AACvE,SAAS,UAAU,CAAC,IAAmB,EAAE,QAAgB;IACvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YACb,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAoB,EACpB,GAAqB,EACrB,KAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,2EAA2E;QAC3E,wDAAwD;QACxD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAC1B,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;QACF,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC;gBACH,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,+BAA+B,CAAC,CAAC,CAAC;YAC9D,CAAC;YAAC,MAAM,CAAC;gBACP,mEAAmE;YACrE,CAAC;QACH,CAAC;QACD,MAAM,UAAU,CAAC,OAAO,EAAE,+BAA+B,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC"}

package/dist/connectors/remote-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-mcp.d.ts","sourceRoot":"","sources":["../../src/connectors/remote-mcp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACV,MAAM,+CAA+C,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,MAAM,EAEP,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,aAAa,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAC1D;AAwJD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAW1C,qBAAa,sBAAuB,SAAQ,kBAAkB;gBAChD,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOhD;AAaD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,uBAAgC,EACxC,SAAS,GAAE,SAAiB,GAC3B,SAAS,CA2EX;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAwfvE"}
+{"version":3,"file":"remote-mcp.d.ts","sourceRoot":"","sources":["../../src/connectors/remote-mcp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACV,MAAM,+CAA+C,CAAC;AAKvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,MAAM,EAEP,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,aAAa,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAC1D;AAmMD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAW1C,qBAAa,sBAAuB,SAAQ,kBAAkB;gBAChD,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOhD;AAaD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,uBAAgC,EACxC,SAAS,GAAE,SAAiB,GAC3B,SAAS,CA2EX;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,SAAS,CA6hBvE"}