@zackbart/connecta 0.7.3 → 0.7.5

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" });

package/src/executors/quickjs-protocol.ts

@@ -0,0 +1,77 @@
+import type { ExecuteResult } from "../types.js";
+import type { QuickJsRuntimeOptions } from "./quickjs-runtime.js";
+
+// The guest result is shaped to 24k characters before transport and QuickJS
+// capture already bounds logs to 256k characters. Every complete message is
+// measured against this ceiling before process.send; one MiB leaves room for
+// multibyte log text and envelope escaping while remaining a hard IPC bound.
+export const MAX_QUICKJS_IPC_BYTES = 1024 * 1024;
+/** Preserve #84's stopgap before a host value enters the child/WASM process. */
+export const MAX_QUICKJS_HOST_RPC_BYTES = 256 * 1024;
+
+export interface RunPayload {
+  id: number;
+  code: string;
+  providerNames: string[];
+  options: QuickJsRuntimeOptions;
+}
+
+export type ParentToChildMessage =
+  | { type: "run"; payloadJson: string }
+  | {
+      type: "host-result";
+      jobId: number;
+      callId: number;
+      payloadJson: string;
+    };
+
+export type ChildToParentMessage =
+  | { type: "ready" }
+  | {
+      type: "host-call";
+      jobId: number;
+      callId: number;
+      payloadJson: string;
+    }
+  | { type: "result"; jobId: number; payloadJson: string };
+
+export interface HostCallPayload {
+  namespace: string;
+  functionName: string;
+  args: unknown[];
+}
+
+export type HostResultPayload =
+  | { ok: true; value: unknown }
+  | { ok: false; error: string };
+
+export interface ExecutionPayload {
+  outcome: ExecuteResult;
+  /**
+   * Set by the runtime on wall-clock expiry. The parent recycles the child on
+   * this flag, never on error text a guest can fabricate.
+   */
+  timedOut?: boolean;
+}
+
+export function serializedBytes(text: string): number {
+  return new TextEncoder().encode(text).length;
+}
+
+export function stringifyBounded(
+  value: unknown,
+  label: string,
+  limit = MAX_QUICKJS_IPC_BYTES,
+): string {
+  const json = JSON.stringify(value);
+  if (json === undefined) {
+    throw new TypeError(`${label} is not JSON-serializable.`);
+  }
+  const bytes = serializedBytes(json);
+  if (bytes > limit) {
+    throw new RangeError(
+      `${label} is ${bytes} UTF-8 bytes, over the ${limit}-byte IPC limit.`,
+    );
+  }
+  return json;
+}