@zackbart/connecta 0.7.1 → 0.7.4

package/src/execute.ts

@@ -8,10 +8,18 @@ import {
   discoverySearchLimit,
   errorResult,
   jsonResult,
-  serializeResultText,
   type ToolResult,
 } from "./meta-tools.js";
+import {
+  guardExecuteResultValue,
+  MAX_EXECUTE_LOG_CHARS,
+  truncateExecuteText,
+} from "./executor-result.js";
 import { classifyCallError, ConnectorCallError } from "./errors.js";
+import {
+  ExecutorAdmissionError,
+  isAdmittingExecutor,
+} from "./executor-admission.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import type { RegistryView } from "./registry.js";
 import type {
@@ -22,9 +30,6 @@ import type {
   ToolDef,
 } from "./types.js";
 
-/** ~6k tokens. Sandbox code should filter data down before returning. */
-const MAX_RESULT_CHARS = 24_000;
-const MAX_LOG_CHARS = 4_000;
 /** Keep one model-written program from amplifying into an unbounded fan-out. */
 export const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
@@ -136,6 +141,7 @@ export async function buildSandboxProviders(
     "connecta",
     "console",
     "__invoke",
+    "__namespace",
     "__call",
     "__log",
   ]);
@@ -143,9 +149,17 @@ export async function buildSandboxProviders(
   const catalogStarted = Date.now();
   const loaded = await Promise.allSettled(
     connectors.map((connector) =>
-      registry.getTools(connector.id, baseUrl, requestScope),
+      registry.getTools(connector.id, baseUrl, requestScope, {
+        signal: limits.signal,
+      }),
     ),
   );
+  if (limits.signal?.aborted) {
+    throw new ExecutorAdmissionError(
+      "executor_cancelled",
+      "Execution was cancelled during catalog construction.",
+    );
+  }
   const catalogs = new Map<string, ToolDef[]>();
   const callAddress = async (address: unknown, args: unknown) => {
     const resolved = registry.resolveAddress(String(address));
@@ -474,24 +488,6 @@ export async function buildSandboxProviders(
   return providers;
 }
 
-function truncate(text: string, max: number): string {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max)}\n--- TRUNCATED (${text.length} chars total) — filter/map/slice data inside your code and return only what you need ---`;
-}
-
-function guardResultValue(value: unknown): unknown {
-  // Same serialization the call_tool guards measure, so a program returning
-  // nothing is rendered one way across every result path (issue #42).
-  const text = serializeResultText(value);
-  if (text.length <= MAX_RESULT_CHARS) return value;
-  return {
-    truncated: true,
-    preview: text.slice(0, MAX_RESULT_CHARS),
-    totalChars: text.length,
-    hint: "filter/map/slice data inside execute_code and return only what you need",
-  };
-}
-
 /** The execute_code handler. Exported for direct testing. */
 export function createExecuteTool(
   registry: RegistryView,
@@ -500,28 +496,69 @@ export function createExecuteTool(
   logger: Logger,
   activity?: ActivityRequestContext,
 ) {
-  return async ({ code }: { code: string }): Promise<ToolResult> => {
+  return async (
+    { code }: { code: string },
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ToolResult> => {
     const controller = new AbortController();
-    const providers = await buildSandboxProviders(
-      registry,
-      baseUrl,
-      logger,
-      activity,
-      { signal: controller.signal },
-    );
+    const forwardAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted) forwardAbort();
+    else {
+      options.signal?.addEventListener("abort", forwardAbort, { once: true });
+    }
+    let lease;
     let outcome;
     try {
-      outcome = await executor.execute(code, providers);
+      // Admission comes before provider construction: queued calls retain no
+      // catalogs, request scopes, or one-closure-per-tool provider arrays.
+      if (isAdmittingExecutor(executor)) {
+        lease = await executor.acquire({ signal: controller.signal });
+      }
+      const providers = await buildSandboxProviders(
+        registry,
+        baseUrl,
+        logger,
+        activity,
+        { signal: controller.signal },
+      );
+      if (controller.signal.aborted) {
+        throw new ExecutorAdmissionError(
+          "executor_cancelled",
+          "Execution was cancelled during sandbox setup.",
+        );
+      }
+      outcome = lease
+        ? await lease.execute(code, providers)
+        : await executor.execute(code, providers);
     } catch (err) {
+      if (err instanceof ExecutorAdmissionError) {
+        const result = jsonResult({
+          error: {
+            code: err.code,
+            message: err.message,
+            retryable: err.retryable,
+            ...(err.retryAfterMs !== undefined
+              ? { retryAfterMs: err.retryAfterMs }
+              : {}),
+          },
+        });
+        result.isError = true;
+        return result;
+      }
       return errorResult(`Executor failed: ${msg(err)}`);
     } finally {
       // A sandbox timeout or early return must also release any outstanding
       // host waits and signal cooperative connectors to stop their work.
       controller.abort();
+      lease?.release();
+      options.signal?.removeEventListener("abort", forwardAbort);
     }
     const logs =
       outcome.logs && outcome.logs.length > 0
-        ? truncate(outcome.logs.join("\n"), MAX_LOG_CHARS)
+        ? truncateExecuteText(
+            outcome.logs.join("\n"),
+            MAX_EXECUTE_LOG_CHARS,
+          )
         : undefined;
     if (outcome.error) {
       return errorResult(
@@ -533,7 +570,7 @@ export function createExecuteTool(
     // error path so captured logs survive instead of a raw SDK 500.
     let result: unknown;
     try {
-      result = guardResultValue(outcome.result);
+      result = guardExecuteResultValue(outcome.result);
     } catch (err) {
       return errorResult(
         `Error: result is not JSON-serializable: ${msg(err)}${logs ? `\n\nLogs:\n${logs}` : ""}`,
@@ -568,6 +605,7 @@ export function registerExecuteTool(
     executor: Executor;
     logger: Logger;
     activity?: ActivityRequestContext;
+    requestSignal?: AbortSignal;
   },
 ): void {
   const handler = createExecuteTool(
@@ -594,6 +632,26 @@ export function registerExecuteTool(
         openWorldHint: true,
       },
     },
-    async (args) => handler(args as { code: string }),
+    async (args, extra) => {
+      const controller = new AbortController();
+      const signals = [extra.signal, ctx.requestSignal].filter(
+        (signal): signal is AbortSignal => signal !== undefined,
+      );
+      const forwarders = signals.map((signal) => {
+        const forward = () => controller.abort(signal.reason);
+        if (signal.aborted) forward();
+        else signal.addEventListener("abort", forward, { once: true });
+        return { signal, forward };
+      });
+      try {
+        return await handler(args as { code: string }, {
+          signal: controller.signal,
+        });
+      } finally {
+        for (const { signal, forward } of forwarders) {
+          signal.removeEventListener("abort", forward);
+        }
+      }
+    },
   );
 }

package/src/executor-admission.ts

@@ -0,0 +1,229 @@
+import type {
+  AdmittingExecutor,
+  Executor,
+} from "./types.js";
+
+export type ExecutorAdmissionErrorCode =
+  | "executor_overloaded"
+  | "executor_cancelled"
+  | "executor_closed";
+
+/**
+ * A stable, machine-readable admission failure. Overload is retryable; caller
+ * cancellation and shutdown are terminal for this invocation.
+ */
+export class ExecutorAdmissionError extends Error {
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+
+  constructor(
+    readonly code: ExecutorAdmissionErrorCode,
+    message: string,
+    opts: { retryAfterMs?: number } = {},
+  ) {
+    super(message);
+    this.name = "ExecutorAdmissionError";
+    this.retryable = code === "executor_overloaded";
+    if (
+      opts.retryAfterMs !== undefined &&
+      Number.isFinite(opts.retryAfterMs) &&
+      opts.retryAfterMs >= 0
+    ) {
+      this.retryAfterMs = Math.trunc(opts.retryAfterMs);
+    }
+  }
+}
+
+export interface AdmissionLease {
+  release(): void;
+}
+
+interface Waiter {
+  resolve: (lease: AdmissionLease) => void;
+  reject: (error: ExecutorAdmissionError) => void;
+  signal?: AbortSignal;
+  onAbort?: () => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export interface AdmissionControllerOptions {
+  concurrency: number;
+  maxQueueSize: number;
+  queueTimeoutMs: number;
+  /** Suggested delay exposed with retryable overload failures. */
+  retryAfterMs?: number;
+}
+
+function positiveWhole(value: number, name: string): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
+    throw new TypeError(`${name} must be a positive whole number.`);
+  }
+  return value;
+}
+
+function nonNegativeWhole(value: number, name: string): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative whole number.`);
+  }
+  return value;
+}
+
+/**
+ * Runtime-portable bounded admission. It deliberately owns no executor or
+ * request state: queued requests retain only a resolver and AbortSignal, while
+ * provider catalogs are constructed after the returned lease is granted.
+ */
+export class AdmissionController {
+  readonly concurrency: number;
+  readonly maxQueueSize: number;
+  readonly queueTimeoutMs: number;
+  readonly retryAfterMs: number;
+
+  private active = 0;
+  private closed = false;
+  private readonly waiters: Waiter[] = [];
+
+  constructor(options: AdmissionControllerOptions) {
+    this.concurrency = positiveWhole(options.concurrency, "concurrency");
+    this.maxQueueSize = nonNegativeWhole(
+      options.maxQueueSize,
+      "maxQueueSize",
+    );
+    this.queueTimeoutMs = positiveWhole(
+      options.queueTimeoutMs,
+      "queueTimeoutMs",
+    );
+    this.retryAfterMs = nonNegativeWhole(
+      options.retryAfterMs ?? this.queueTimeoutMs,
+      "retryAfterMs",
+    );
+  }
+
+  get activeCount(): number {
+    return this.active;
+  }
+
+  get queuedCount(): number {
+    return this.waiters.length;
+  }
+
+  acquire(options: { signal?: AbortSignal } = {}): Promise<AdmissionLease> {
+    if (this.closed) {
+      return Promise.reject(
+        new ExecutorAdmissionError(
+          "executor_closed",
+          "Executor is shutting down.",
+        ),
+      );
+    }
+    if (options.signal?.aborted) {
+      return Promise.reject(
+        new ExecutorAdmissionError(
+          "executor_cancelled",
+          "Execution was cancelled before admission.",
+        ),
+      );
+    }
+    if (this.active < this.concurrency) {
+      this.active++;
+      return Promise.resolve(this.makeLease());
+    }
+    if (this.waiters.length >= this.maxQueueSize) {
+      return Promise.reject(this.overloaded("Executor queue is full."));
+    }
+
+    return new Promise<AdmissionLease>((resolve, reject) => {
+      const waiter: Waiter = {
+        resolve,
+        reject,
+        ...(options.signal ? { signal: options.signal } : {}),
+      };
+      waiter.onAbort = () => {
+        if (!this.remove(waiter)) return;
+        this.cleanup(waiter);
+        reject(
+          new ExecutorAdmissionError(
+            "executor_cancelled",
+            "Execution was cancelled while queued.",
+          ),
+        );
+      };
+      options.signal?.addEventListener("abort", waiter.onAbort, { once: true });
+      waiter.timer = setTimeout(() => {
+        if (!this.remove(waiter)) return;
+        this.cleanup(waiter);
+        reject(
+          this.overloaded(
+            `Executor admission timed out after ${this.queueTimeoutMs}ms.`,
+          ),
+        );
+      }, this.queueTimeoutMs);
+      this.waiters.push(waiter);
+    });
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      this.cleanup(waiter);
+      waiter.reject(
+        new ExecutorAdmissionError(
+          "executor_closed",
+          "Executor is shutting down.",
+        ),
+      );
+    }
+  }
+
+  private overloaded(message: string): ExecutorAdmissionError {
+    return new ExecutorAdmissionError("executor_overloaded", message, {
+      retryAfterMs: this.retryAfterMs,
+    });
+  }
+
+  private makeLease(): AdmissionLease {
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        this.release();
+      },
+    };
+  }
+
+  private release(): void {
+    if (this.active > 0) this.active--;
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (!waiter) return;
+    this.cleanup(waiter);
+    this.active++;
+    waiter.resolve(this.makeLease());
+  }
+
+  private remove(waiter: Waiter): boolean {
+    const index = this.waiters.indexOf(waiter);
+    if (index < 0) return false;
+    this.waiters.splice(index, 1);
+    return true;
+  }
+
+  private cleanup(waiter: Waiter): void {
+    if (waiter.timer !== undefined) clearTimeout(waiter.timer);
+    if (waiter.onAbort) {
+      waiter.signal?.removeEventListener("abort", waiter.onAbort);
+    }
+  }
+}
+
+/** Preserve the one-method Workers seam while recognizing richer Node executors. */
+export function isAdmittingExecutor(
+  executor: Executor,
+): executor is AdmittingExecutor {
+  return (
+    "acquire" in executor &&
+    typeof (executor as { acquire?: unknown }).acquire === "function"
+  );
+}

package/src/executor-result.ts

@@ -0,0 +1,63 @@
+import type { ExecuteResult } from "./types.js";
+
+/** ~6k tokens. Sandbox code should filter data down before returning. */
+export const MAX_EXECUTE_RESULT_CHARS = 24_000;
+export const MAX_EXECUTE_LOG_CHARS = 4_000;
+
+function msg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export function serializeExecuteValue(value: unknown): string {
+  const serialized = JSON.stringify(value, null, 2);
+  return serialized === undefined ? String(value) : serialized;
+}
+
+export function guardExecuteResultValue(value: unknown): unknown {
+  const text = serializeExecuteValue(value);
+  if (text.length <= MAX_EXECUTE_RESULT_CHARS) return value;
+  return {
+    truncated: true,
+    preview: text.slice(0, MAX_EXECUTE_RESULT_CHARS),
+    totalChars: text.length,
+    hint: "filter/map/slice data inside execute_code and return only what you need",
+  };
+}
+
+export function truncateExecuteText(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n--- TRUNCATED (${text.length} chars total) — filter/map/slice data inside your code and return only what you need ---`;
+}
+
+/**
+ * Apply the public execute_code result/log policy before a child result enters
+ * IPC. The parent repeats the guard for third-party Executor implementations.
+ */
+export function prepareExecuteResultForTransport(
+  outcome: ExecuteResult,
+): ExecuteResult {
+  // QuickJS already bounds captured logs at source (entries + cumulative
+  // characters). Preserve that Executor-level shape; createExecuteTool applies
+  // the smaller model-facing 4k presentation cap in the parent.
+  const logs =
+    outcome.logs && outcome.logs.length > 0 ? outcome.logs : undefined;
+  if (outcome.error) {
+    return {
+      result: undefined,
+      error: outcome.error,
+      ...(logs ? { logs } : {}),
+    };
+  }
+  try {
+    return {
+      result: guardExecuteResultValue(outcome.result),
+      ...(logs ? { logs } : {}),
+    };
+  } catch (err) {
+    return {
+      result: undefined,
+      error: `result is not JSON-serializable: ${msg(err)}`,
+      ...(logs ? { logs } : {}),
+    };
+  }
+}

package/src/executors/quickjs-child.ts

@@ -0,0 +1,168 @@
+import { prepareExecuteResultForTransport } from "../executor-result.js";
+import type { ExecutorProvider } from "../types.js";
+import {
+  MAX_QUICKJS_IPC_BYTES,
+  MAX_QUICKJS_HOST_RPC_BYTES,
+  type ChildToParentMessage,
+  type ExecutionPayload,
+  type HostCallPayload,
+  type HostResultPayload,
+  type ParentToChildMessage,
+  type RunPayload,
+  serializedBytes,
+  stringifyBounded,
+} from "./quickjs-protocol.js";
+import { executeQuickJs, prepareQuickJs } from "./quickjs-runtime.js";
+
+let activeJobId: number | undefined;
+let nextCallId = 1;
+const pending = new Map<
+  number,
+  {
+    resolve: (value: unknown) => void;
+    reject: (error: Error) => void;
+  }
+>();
+
+function msg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function send(message: ChildToParentMessage): void {
+  if (!process.send) throw new Error("QuickJS child IPC channel is unavailable.");
+  // Bound the actual process.send envelope, not only its nested payloadJson.
+  // Guest-controlled strings must be rejected while they are still isolated
+  // in this disposable process, before Node materializes them in the parent.
+  stringifyBounded(message, "QuickJS child IPC envelope");
+  process.send(message);
+}
+
+function provider(name: string, jobId: number): ExecutorProvider {
+  const functions = new Proxy(
+    Object.create(null) as ExecutorProvider["fns"],
+    {
+      get: (_target, key) => {
+        if (typeof key !== "string") return undefined;
+        return async (...args: unknown[]): Promise<unknown> => {
+          const callId = nextCallId++;
+          const payloadJson = stringifyBounded(
+            {
+              namespace: name,
+              functionName: key,
+              args,
+            } satisfies HostCallPayload,
+            "Host call payload",
+            MAX_QUICKJS_HOST_RPC_BYTES,
+          );
+          const result = new Promise<unknown>((resolve, reject) => {
+            pending.set(callId, { resolve, reject });
+          });
+          send({
+            type: "host-call",
+            jobId,
+            callId,
+            payloadJson,
+          });
+          return result;
+        };
+      },
+      getOwnPropertyDescriptor: (_target, key) =>
+        typeof key === "string"
+          ? { configurable: true, enumerable: false }
+          : undefined,
+    },
+  );
+  return { name, fns: functions };
+}
+
+function fixedTransportFailure(message: string): ExecutionPayload {
+  return {
+    outcome: {
+      result: undefined,
+      error: message.slice(0, 4_000),
+    },
+  };
+}
+
+async function run(payload: RunPayload): Promise<void> {
+  if (activeJobId !== undefined) {
+    throw new Error("QuickJS child received overlapping executions.");
+  }
+  activeJobId = payload.id;
+  try {
+    const providers = payload.providerNames.map((name) =>
+      provider(name, payload.id),
+    );
+    const raw = await executeQuickJs(
+      payload.code,
+      providers,
+      payload.options,
+    );
+    const prepared: ExecutionPayload = {
+      outcome: prepareExecuteResultForTransport(raw),
+      ...(raw.timedOut ? { timedOut: true } : {}),
+    };
+    let payloadJson: string;
+    try {
+      payloadJson = stringifyBounded(prepared, "QuickJS execution result");
+    } catch (err) {
+      payloadJson = JSON.stringify(
+        fixedTransportFailure(
+          `QuickJS execution result exceeded the ${MAX_QUICKJS_IPC_BYTES}-byte IPC limit: ${msg(err)}`,
+        ),
+      );
+    }
+    send({ type: "result", jobId: payload.id, payloadJson });
+  } finally {
+    activeJobId = undefined;
+    for (const request of pending.values()) {
+      request.reject(new Error("Execution ended before the host call settled."));
+    }
+    pending.clear();
+  }
+}
+
+process.on("message", (message: ParentToChildMessage) => {
+  if (!message || typeof message !== "object") return;
+  if (message.type === "host-result") {
+    if (message.jobId !== activeJobId) return;
+    const request = pending.get(message.callId);
+    if (!request) return;
+    pending.delete(message.callId);
+    if (
+      serializedBytes(message.payloadJson) > MAX_QUICKJS_HOST_RPC_BYTES
+    ) {
+      request.reject(new Error("Host result exceeded the IPC limit."));
+      return;
+    }
+    try {
+      const result = JSON.parse(message.payloadJson) as HostResultPayload;
+      if (result.ok) request.resolve(result.value);
+      else request.reject(new Error(result.error));
+    } catch (err) {
+      request.reject(new Error(`Invalid host result: ${msg(err)}`));
+    }
+    return;
+  }
+  if (message.type !== "run") return;
+  if (serializedBytes(message.payloadJson) > MAX_QUICKJS_IPC_BYTES) {
+    throw new Error("Run payload exceeded the IPC limit.");
+  }
+  const payload = JSON.parse(message.payloadJson) as RunPayload;
+  void run(payload).catch((err) => {
+    const payloadJson = JSON.stringify(
+      fixedTransportFailure(`QuickJS child failed: ${msg(err)}`),
+    );
+    send({ type: "result", jobId: payload.id, payloadJson });
+    activeJobId = undefined;
+  });
+});
+
+process.on("disconnect", () => process.exit(0));
+
+// The parent does not start an execution's wall budget until the trusted WASM
+// module is loaded. This keeps cold-start latency from being misclassified as
+// guest CPU/wall failure while the parent's startup timeout still bounds a
+// child that never becomes ready.
+await prepareQuickJs();
+send({ type: "ready" });