@zackbart/connecta 0.15.1 → 0.16.1

package/src/executor-admission.ts

@@ -1,328 +0,0 @@
-import type {
-  AdmittingExecutor,
-  AdmissionSnapshot,
-  Executor,
-  ExecutorLease,
-} 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);
-    }
-  }
-}
-
-/**
- * A lifecycle failure after the sandbox started running. It keeps the stable
- * admission-error envelope while letting response assembly distinguish work
- * torn down in flight from work that never entered the executor.
- */
-export class ExecutorExecutionError extends ExecutorAdmissionError {
-  constructor(code: ExecutorAdmissionErrorCode, message: string) {
-    super(code, message);
-    this.name = "ExecutorExecutionError";
-  }
-}
-
-export interface AdmissionLease {
-  /** Time spent waiting behind active work. Zero for immediate admission. */
-  readonly waitMs: number;
-  release(): void;
-}
-
-interface Waiter {
-  queuedAt: number;
-  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[] = [];
-  private admittedTotal = 0;
-  private queuedTotal = 0;
-  private rejectedTotal = 0;
-  private cancelledTotal = 0;
-  private closedTotal = 0;
-  private queueWaitCount = 0;
-  private queueWaitTotalMs = 0;
-  private queueWaitMaxMs = 0;
-
-  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;
-  }
-
-  snapshot(): AdmissionSnapshot {
-    return {
-      concurrency: this.concurrency,
-      maxQueueSize: this.maxQueueSize,
-      queueTimeoutMs: this.queueTimeoutMs,
-      retryAfterMs: this.retryAfterMs,
-      active: this.active,
-      queued: this.waiters.length,
-      closed: this.closed,
-      totals: {
-        admitted: this.admittedTotal,
-        queued: this.queuedTotal,
-        rejected: this.rejectedTotal,
-        cancelled: this.cancelledTotal,
-        closed: this.closedTotal,
-      },
-      queueWaitMs: {
-        count: this.queueWaitCount,
-        total: this.queueWaitTotalMs,
-        max: this.queueWaitMaxMs,
-      },
-    };
-  }
-
-  acquire(options: { signal?: AbortSignal } = {}): Promise<AdmissionLease> {
-    if (this.closed) {
-      this.closedTotal++;
-      return Promise.reject(
-        new ExecutorAdmissionError(
-          "executor_closed",
-          "Executor is shutting down.",
-        ),
-      );
-    }
-    if (options.signal?.aborted) {
-      this.cancelledTotal++;
-      return Promise.reject(
-        new ExecutorAdmissionError(
-          "executor_cancelled",
-          "Execution was cancelled before admission.",
-        ),
-      );
-    }
-    if (this.active < this.concurrency) {
-      this.active++;
-      this.admittedTotal++;
-      return Promise.resolve(this.makeLease(0));
-    }
-    if (this.waiters.length >= this.maxQueueSize) {
-      this.rejectedTotal++;
-      return Promise.reject(this.overloaded("Executor queue is full."));
-    }
-
-    return new Promise<AdmissionLease>((resolve, reject) => {
-      const waiter: Waiter = {
-        queuedAt: Date.now(),
-        resolve,
-        reject,
-        ...(options.signal ? { signal: options.signal } : {}),
-      };
-      waiter.onAbort = () => {
-        if (!this.remove(waiter)) return;
-        this.cleanup(waiter);
-        this.cancelledTotal++;
-        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);
-        this.rejectedTotal++;
-        reject(
-          this.overloaded(
-            `Executor admission timed out after ${this.queueTimeoutMs}ms.`,
-          ),
-        );
-      }, this.queueTimeoutMs);
-      this.waiters.push(waiter);
-      this.queuedTotal++;
-    });
-  }
-
-  close(): void {
-    if (this.closed) return;
-    this.closed = true;
-    for (const waiter of this.waiters.splice(0)) {
-      this.cleanup(waiter);
-      this.closedTotal++;
-      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(waitMs: number): AdmissionLease {
-    let released = false;
-    return {
-      waitMs,
-      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);
-    const waitMs = Math.max(0, Date.now() - waiter.queuedAt);
-    this.admittedTotal++;
-    this.queueWaitCount++;
-    this.queueWaitTotalMs += waitMs;
-    this.queueWaitMaxMs = Math.max(this.queueWaitMaxMs, waitMs);
-    this.active++;
-    waiter.resolve(this.makeLease(waitMs));
-  }
-
-  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"
-  );
-}
-
-/**
- * Give a structurally-compatible but otherwise unbounded executor the same
- * admission contract as the built-in Node executor. The wrapper owns only the
- * queue; closing the underlying runtime remains the Connecta lifecycle's job.
- */
-export function withExecutorAdmission(
-  executor: Executor,
-  admission: AdmissionController,
-): AdmittingExecutor {
-  return {
-    async acquire(options = {}): Promise<ExecutorLease> {
-      const token = await admission.acquire(options);
-      let released = false;
-      return {
-        waitMs: token.waitMs,
-        execute: (code, providers) => executor.execute(code, providers),
-        release: () => {
-          if (released) return;
-          released = true;
-          token.release();
-        },
-      };
-    },
-    async execute(code, providers) {
-      const lease = await this.acquire();
-      try {
-        return await lease.execute(code, providers);
-      } finally {
-        lease.release();
-      }
-    },
-    admissionSnapshot: () => admission.snapshot(),
-  };
-}

package/src/executor-result.ts

@@ -1,107 +0,0 @@
-import type { ExecuteResult } from "./types.js";
-
-/** ~6k tokens. Sandbox code should filter data down before returning. */
-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);
-}
-
-function serializeExecuteValue(value: unknown): string {
-  const serialized = JSON.stringify(value);
-  return serialized === undefined ? String(value) : serialized;
-}
-
-const TRUNCATION_HINT =
-  "filter/map/slice data inside execute_code and return only what you need";
-
-/**
- * Shape the over-cap notice so the **serialized envelope** fits the same cap
- * the raw value missed. Escaping matters: a preview sliced to the cap is JSON
- * text whose quotes and newlines re-escape to well over it, so a fixed slice
- * would leave the envelope over-cap and a second pass through this guard would
- * truncate the truncation — reporting the envelope's length as `totalChars` and
- * burying the real size. Shrinking proportionally until it fits keeps the guard
- * idempotent by construction: `totalChars` is always the true serialized size
- * of what the program returned, and truncation happens exactly once no matter
- * how many hops the value takes.
- */
-function truncationEnvelope(text: string): {
-  truncated: true;
-  preview: string;
-  totalChars: number;
-  hint: string;
-} {
-  const base = {
-    truncated: true as const,
-    preview: "",
-    totalChars: text.length,
-    hint: TRUNCATION_HINT,
-  };
-  let budget = Math.max(
-    0,
-    MAX_EXECUTE_RESULT_CHARS - JSON.stringify(base).length,
-  );
-  for (let attempt = 0; attempt < 8 && budget > 0; attempt += 1) {
-    const candidate = { ...base, preview: text.slice(0, budget) };
-    const size = JSON.stringify(candidate).length;
-    if (size <= MAX_EXECUTE_RESULT_CHARS) return candidate;
-    // Every character costs at least one serialized character, so scaling by
-    // the overshoot ratio (minus a step) strictly shrinks the budget.
-    budget = Math.max(
-      0,
-      Math.floor(budget * (MAX_EXECUTE_RESULT_CHARS / size)) - 8,
-    );
-  }
-  // The loop shrinks monotonically, so this is unreachable in practice — but an
-  // unchecked slice is exactly how a "bounded" envelope stops being bounded.
-  const clamped = { ...base, preview: text.slice(0, Math.max(0, budget)) };
-  return JSON.stringify(clamped).length <= MAX_EXECUTE_RESULT_CHARS
-    ? clamped
-    : { ...base, preview: "" };
-}
-
-export function guardExecuteResultValue(value: unknown): unknown {
-  const text = serializeExecuteValue(value);
-  if (text.length <= MAX_EXECUTE_RESULT_CHARS) return value;
-  return truncationEnvelope(text);
-}
-
-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

@@ -1,172 +0,0 @@
-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,
-  prelude?: string,
-): 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, ...(prelude ? { prelude } : {}) };
-}
-
-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.providers.map(({ name, prelude }) =>
-      provider(name, payload.id, prelude),
-    );
-    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

@@ -1,99 +0,0 @@
-import type { ExecuteResult } from "../types.js";
-import type { QuickJsRuntimeOptions } from "./quickjs-runtime.js";
-
-// An execution result is serialized once into payloadJson and again as that
-// string is embedded in ChildToParentMessage. Captured logs therefore get a
-// separate 512 KiB budget measured after both JSON encodings. The final result
-// is shaped to 24k characters; even if every character takes its worst-case
-// seven transport bytes, that leaves ample structural overhead below this hard
-// process.send ceiling.
-export const MAX_QUICKJS_IPC_BYTES = 1024 * 1024;
-export const MAX_QUICKJS_LOG_TRANSPORT_BYTES = 512 * 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;
-  providers: Array<{ name: string; prelude?: 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;
-}
-
-/**
- * How a host call should be named in an error a program will read. The lazy
- * connector namespaces all dispatch through one internal function, so the raw
- * provider/function pair would report every shortcut call as
- * `connecta.__callNamespace` — an internal name that appears nowhere in the
- * documented surface. Report the address the program actually called.
- */
-export function hostCallLabel(payload: {
-  namespace: string;
-  functionName: string;
-  args: unknown[];
-}): string {
-  if (payload.functionName === "__callNamespace") {
-    const [connectorId, toolAlias] = payload.args;
-    return `${String(connectorId)}.${String(toolAlias)}`;
-  }
-  return `${payload.namespace}.${payload.functionName}`;
-}
-
-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;
-}