@lostgradient/weft 0.2.0

package/dist/server/serve-internals.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Internal helpers extracted from `serve()` to reduce its cyclomatic complexity.
+ * These are implementation details — do not import from outside `src/server/`.
+ *
+ * @internal
+ */
+import { MetricsCollector } from '../observability/metrics.ts';
+import { buildTLSOptions } from './authentication.ts';
+import type { ServeOptions } from './index.ts';
+import type { WebSocketData } from './json-rpc-websocket-runtime.ts';
+import { createServerWebSocketHandlers } from './runtime/authentication-bridge.ts';
+import type { ServerContext } from './runtime/context.ts';
+import { type EventBroadcastingHandle } from './runtime/event-broadcasting.ts';
+/**
+ * Clamp a user-supplied `workerReconnectGracePeriodMs` into `[0, 5_000]`.
+ * Returns the default when undefined or non-finite.
+ */
+export declare function clampWorkerReconnectGracePeriod(value: number | undefined): number;
+export declare function assertAuthenticationPosture(options: ServeOptions, environmentRequirement?: string | undefined): void;
+/**
+ * A mutable holder for the Bun server instance. The `fetch` handler needs to
+ * call back into the server (for WebSocket upgrades) but the server isn't
+ * created until `Bun.serve()` is called. The holder is populated immediately
+ * after `Bun.serve()` returns, before any requests can be handled.
+ */
+export type ServerHolder = {
+    current: ReturnType<typeof Bun.serve> | null;
+};
+/** `ServeOptions` with `prometheusExporter` guaranteed present. */
+export type ResolvedServeOptions = ServeOptions & {
+    prometheusExporter: NonNullable<ServeOptions['prometheusExporter']>;
+};
+/**
+ * Resolved network parameters plus the TLS config derived from auth options.
+ * Extracted so `serve()` does not need ternaries for defaults or TLS.
+ */
+export type ResolvedNetworkConfig = {
+    port: number;
+    hostname: string;
+    development: boolean;
+    tlsOptions: ReturnType<typeof buildTLSOptions>;
+    serverOptions: ResolvedServeOptions;
+    serverMetricsCollector: MetricsCollector;
+};
+/**
+ * Resolves all network configuration defaults and validates the auth config
+ * synchronously so misconfigurations fail fast before `Bun.serve()` binds.
+ */
+export declare function resolveNetworkConfig(options: ServeOptions): ResolvedNetworkConfig;
+/**
+ * Builds the initial `ServerContext` from resolved options. All mutable state
+ * maps and the metrics collector are allocated here so `serve()` stays linear.
+ */
+export declare function buildServerContext(options: ResolvedServeOptions, serverMetricsCollector: MetricsCollector): ServerContext;
+/**
+ * Returns the `fetch` handler for `Bun.serve()`. The handler reads the server
+ * instance from `serverHolder.current`, which is populated right after
+ * `Bun.serve()` returns. This avoids a circular dependency between the server
+ * reference and its own fetch callback.
+ */
+export declare function buildFetchHandler(serverHolder: ServerHolder, context: ServerContext, options: ResolvedServeOptions): (request: Request) => Promise<Response | undefined>;
+/**
+ * Removes an operationId from the workflow→operations reverse index.
+ * Module-scope so it does not contribute to `serve()`'s cyclomatic complexity.
+ */
+export declare function cleanupWorkflowIndex(context: ServerContext, operationId: string): void;
+/**
+ * Assembles the `Bun.serve()` options object. Separating this avoids a
+ * conditional spread (`...(tlsOptions ? { tls } : {})`) inside `serve()`.
+ */
+export declare function buildBunServeConfig(port: number, hostname: string, development: boolean, routes: Bun.Serve.Routes<WebSocketData, string>, tlsOptions: ReturnType<typeof buildTLSOptions>, fetchHandler: (request: Request) => Promise<Response | undefined>, websocketCallbacks: ReturnType<typeof createServerWebSocketHandlers>): Parameters<typeof Bun.serve<WebSocketData>>[0];
+/**
+ * Registers all `AsyncDisposableStack` entries and periodic intervals for a
+ * running server. The stack disposes entries in reverse registration order so
+ * the most-recently-registered item is torn down first.
+ */
+export declare function registerStackDisposers(stack: AsyncDisposableStack, context: ServerContext, options: ServeOptions, broadcastingHandle: EventBroadcastingHandle, onOperationCleanup: (operationId: string) => void): void;
+/**
+ * Restores persisted in-flight task records from storage into the in-memory
+ * context. Records whose deadline has already elapsed are removed from storage;
+ * the engine will retry them on the next dispatch cycle.
+ */
+export declare function restoreInflightTasks(context: ServerContext, options: ServeOptions): void;

package/dist/server/serve-internals.js

@@ -0,0 +1,203 @@
+import { decode } from "../core/codec.js";
+import { createMcpSessionManager } from "../mcp/session.js";
+import { createMetricsCollectorExporter, MetricsCollector } from "../observability/metrics.js";
+import { WorkerRegistry } from "../worker/registry.js";
+import {
+  buildTLSOptions,
+  createAuthenticator,
+  createRateLimiter,
+  validateAuthConfig,
+  validateRateLimitConfig
+} from "./authentication.js";
+import { DeadlineTracker } from "./deadline-tracker.js";
+import { createEngineEventFeedBackend } from "./engine-event-feed-backend.js";
+import { closeJsonRpcSessionsForShutdown } from "./json-rpc-websocket-runtime.js";
+import { createLiveOperationRegistry, createLiveRestBindings } from "./rest-bindings.js";
+import {
+  createServerWebSocketHandlers,
+  deriveSupportedOpenApiSecuritySchemes,
+  handleServerFetchRequest
+} from "./runtime/authentication-bridge.js";
+import { resolveCorsPolicy, validateCorsOptions } from "./runtime/cors.js";
+import {
+  registerWorkflowEventLifecycle
+} from "./runtime/event-broadcasting.js";
+import { reconcileOrphanedRecords, scanExpiredTasks } from "./runtime/task-reconciliation.js";
+import { isInflightRecord, withRetry } from "./runtime/websocket-worker.js";
+import { TaskQueue } from "./task-queue.js";
+import { createWorkflowEventFeed } from "./workflow-event-feed.js";
+const RECONCILIATION_MULTIPLIER = 12, DEFAULT_WORKER_RECONNECT_GRACE_PERIOD_MS = 100, MAX_WORKER_RECONNECT_GRACE_PERIOD_MS = 5000, AUTHENTICATION_REQUIRED_ENVIRONMENT_VARIABLE = "WEFT_SERVER_AUTHENTICATION_REQUIRED", NO_AUTHENTICATION_WARNING = '[weft] WARNING: server started with NO authentication; all non-public operations are publicly accessible. Configure serve({ auth }) to lock down, or set unauthenticatedAccess: "reject" in production to fail closed.', NO_AUTHENTICATION_REJECT_ERROR = '[weft] Refusing to start server with no authentication. Configure serve({ auth }) or set unauthenticatedAccess: "allow" only for trusted local development.', NO_AUTHENTICATION_ENVIRONMENT_ERROR = "[weft] Refusing to start server with no authentication because WEFT_SERVER_AUTHENTICATION_REQUIRED requires authentication. Configure serve({ auth }) or unset WEFT_SERVER_AUTHENTICATION_REQUIRED only for trusted local development.", TRUTHY_AUTHENTICATION_REQUIREMENT_VALUES = new Set(["1", "true", "yes", "on"]), FALSY_AUTHENTICATION_REQUIREMENT_VALUES = new Set(["0", "false", "no", "off"]);
+export function clampWorkerReconnectGracePeriod(value) {
+  if (value === void 0 || !Number.isFinite(value))
+    return DEFAULT_WORKER_RECONNECT_GRACE_PERIOD_MS;
+  if (value < 0)
+    return 0;
+  if (value > MAX_WORKER_RECONNECT_GRACE_PERIOD_MS)
+    return MAX_WORKER_RECONNECT_GRACE_PERIOD_MS;
+  return Math.floor(value);
+}
+function authenticationRequiredByEnvironment(rawValue) {
+  if (rawValue === void 0)
+    return !1;
+  const normalizedValue = rawValue.trim().toLowerCase();
+  if (normalizedValue === "")
+    return !1;
+  if (TRUTHY_AUTHENTICATION_REQUIREMENT_VALUES.has(normalizedValue))
+    return !0;
+  if (FALSY_AUTHENTICATION_REQUIREMENT_VALUES.has(normalizedValue))
+    return !1;
+  throw Error(`[weft] Invalid ${AUTHENTICATION_REQUIRED_ENVIRONMENT_VARIABLE} value "${rawValue}". Use one of: 1, true, yes, on, 0, false, no, off.`);
+}
+export function assertAuthenticationPosture(options, environmentRequirement = Bun.env[AUTHENTICATION_REQUIRED_ENVIRONMENT_VARIABLE]) {
+  if (options.auth)
+    return;
+  if (authenticationRequiredByEnvironment(environmentRequirement))
+    throw Error(NO_AUTHENTICATION_ENVIRONMENT_ERROR);
+  if (options.unauthenticatedAccess === "reject")
+    throw Error(NO_AUTHENTICATION_REJECT_ERROR);
+  if (options.unauthenticatedAccess === "allow")
+    return;
+  console.warn(NO_AUTHENTICATION_WARNING);
+}
+export function resolveNetworkConfig(options) {
+  if (options.auth)
+    validateAuthConfig(options.auth);
+  if (options.rateLimit)
+    validateRateLimitConfig(options.rateLimit);
+  if (options.cors)
+    validateCorsOptions(options.cors, options.auth !== void 0);
+  assertAuthenticationPosture(options);
+  const port = options.port ?? 7233, hostname = options.hostname ?? "0.0.0.0", development = options.development ?? !1, serverMetricsCollector = new MetricsCollector, prometheusExporter = options.prometheusExporter ?? createMetricsCollectorExporter(serverMetricsCollector), serverOptions = { ...options, prometheusExporter }, tlsOptions = buildTLSOptions(options.auth);
+  return { port, hostname, development, tlsOptions, serverOptions, serverMetricsCollector };
+}
+export function buildServerContext(options, serverMetricsCollector) {
+  const workerRegistry = new WorkerRegistry(options.routingPolicy !== void 0 ? { policy: options.routingPolicy } : void 0), taskQueue = new TaskQueue(options.schedulingPolicy !== void 0 ? { schedulingPolicy: options.schedulingPolicy } : void 0), eventFeedBackend = createEngineEventFeedBackend(options.engine);
+  return {
+    registry: workerRegistry,
+    taskQueue,
+    workerSockets: new Map,
+    streamSockets: new Map,
+    workerAffinity: new Map,
+    workflowOperations: new Map,
+    operationToWorkflow: new Map,
+    pendingTimers: new Set,
+    deadlineTracker: new DeadlineTracker,
+    liveOperationRegistry: createLiveOperationRegistry({
+      workerRegistry,
+      taskQueue,
+      metricsCollector: serverMetricsCollector
+    }),
+    liveRestBindings: createLiveRestBindings(),
+    supportedAuthenticationSchemes: deriveSupportedOpenApiSecuritySchemes(options.auth),
+    corsPolicy: options.cors ? resolveCorsPolicy(options.cors, options.auth !== void 0) : null,
+    metricsCollector: serverMetricsCollector,
+    eventFeedBackend,
+    workflowEventFeed: createWorkflowEventFeed(eventFeedBackend),
+    activeJsonRpcSessions: new Set,
+    mcpSessionManager: createMcpSessionManager(options.engine),
+    authenticatorPromise: options.auth ? createAuthenticator(options.auth) : null,
+    rateLimiter: options.rateLimit ? createRateLimiter(options.rateLimit) : null,
+    visibilityPollMs: options.visibilityPollIntervalMs ?? 5000,
+    workerReconnectGracePeriodMs: clampWorkerReconnectGracePeriod(options.workerReconnectGracePeriodMs),
+    pendingWorkerRequeues: new Map,
+    scanRunning: !1,
+    processingOperations: new Set,
+    reconciliationRunning: !1
+  };
+}
+export function buildFetchHandler(serverHolder, context, options) {
+  return (request) => {
+    const server = serverHolder.current;
+    if (server === null)
+      return Promise.resolve(new Response("Server not ready", { status: 503 }));
+    return handleServerFetchRequest(server, context, options, request);
+  };
+}
+export function cleanupWorkflowIndex(context, operationId) {
+  const workflowId = context.operationToWorkflow.get(operationId);
+  if (!workflowId)
+    return;
+  const opIds = context.workflowOperations.get(workflowId);
+  if (opIds) {
+    opIds.delete(operationId);
+    if (opIds.size === 0)
+      context.workflowOperations.delete(workflowId);
+  }
+  context.operationToWorkflow.delete(operationId);
+}
+export function buildBunServeConfig(port, hostname, development, routes, tlsOptions, fetchHandler, websocketCallbacks) {
+  const config = {
+    port,
+    hostname,
+    development,
+    routes,
+    fetch: fetchHandler,
+    websocket: websocketCallbacks
+  };
+  if (tlsOptions)
+    config.tls = tlsOptions;
+  return config;
+}
+export function registerStackDisposers(stack, context, options, broadcastingHandle, onOperationCleanup) {
+  stack.defer(broadcastingHandle.dispose);
+  stack.defer(() => context.workflowEventFeed.dispose());
+  stack.defer(async () => {
+    await closeJsonRpcSessionsForShutdown(context.activeJsonRpcSessions);
+  });
+  stack.defer(() => context.mcpSessionManager[Symbol.asyncDispose]());
+  stack.defer(registerWorkflowEventLifecycle(options.engine, context, broadcastingHandle));
+  const visibilityPollHandle = setInterval(() => {
+    scanExpiredTasks(context, options, onOperationCleanup);
+  }, context.visibilityPollMs), reconciliationIntervalMs = context.visibilityPollMs * RECONCILIATION_MULTIPLIER, reconciliationHandle = setInterval(() => {
+    reconcileOrphanedRecords(context, options, onOperationCleanup);
+  }, reconciliationIntervalMs);
+  stack.defer(() => {
+    clearInterval(visibilityPollHandle);
+    clearInterval(reconciliationHandle);
+    context.deadlineTracker.clear();
+    for (const timer of context.pendingTimers)
+      clearTimeout(timer);
+    context.pendingTimers.clear();
+    for (const timer of context.pendingWorkerRequeues.values())
+      clearTimeout(timer);
+    context.pendingWorkerRequeues.clear();
+    context.taskQueue[Symbol.dispose]();
+    context.rateLimiter?.dispose();
+  });
+}
+export function restoreInflightTasks(context, options) {
+  withRetry(async () => {
+    for await (const [key, value] of options.engine.storage.scan("op:inflight:")) {
+      const decoded = decode(value);
+      if (!isInflightRecord(decoded)) {
+        console.error(`[weft] Corrupt inflight record at "${key}" during restore \u2014 skipping`);
+        continue;
+      }
+      const record = decoded, now = Date.now();
+      if (record.deadline <= now) {
+        options.engine.storage.delete(key);
+        continue;
+      }
+      const remaining = record.deadline - now;
+      context.registry.assignTask(record.workerId, record.operationId, remaining);
+      context.deadlineTracker.add({ operationId: record.operationId, deadline: record.deadline });
+      const tracked = context.registry.getWorkerTasks(record.workerId).find((t) => t.operationId === record.operationId);
+      if (tracked)
+        tracked.visibilityTimeout = record.visibilityTimeout;
+      rebuildWorkflowIndex(context, record.operationId, record.workflowId);
+    }
+  }, "restore in-flight tasks from storage").catch((error) => {
+    console.error("[weft] Failed to restore in-flight tasks from storage:", error);
+  });
+}
+function rebuildWorkflowIndex(context, operationId, workflowId) {
+  if (!workflowId)
+    return;
+  let opIds = context.workflowOperations.get(workflowId);
+  if (!opIds) {
+    opIds = new Set;
+    context.workflowOperations.set(workflowId, opIds);
+  }
+  opIds.add(operationId);
+  context.operationToWorkflow.set(operationId, workflowId);
+}

package/dist/server/stdio-session.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Runtime JSON-RPC stdio session.
+ *
+ * `runStdioSession({ input, output, admission, registry, engine, feed, ... })`
+ * drives the `weft rpc-stdio` CLI subcommand (Track 8 design decision
+ * 19). It reads newline-delimited JSON frames from `input`, runs each
+ * through the same `createJsonRpcWebSocketSession` session the WS
+ * adapter uses, and writes responses to `output`.
+ *
+ * Admission is mandatory:
+ *   - `{ kind: 'startup-token', token }` — the first frame must be a
+ *     `weft.authenticate` call whose `params.token` matches. On match,
+ *     the session principal is `stdio-local` with admin scopes. On
+ *     mismatch, the session returns `exit 2` without starting.
+ *   - `{ kind: 'allow-unauthenticated-local-admin' }` — session starts
+ *     immediately with a `stdio-local` principal. The CLI flag that
+ *     enables this reads "grants full engine access to any local
+ *     process that can spawn this binary" in both the help text and
+ *     the startup log.
+ *   - `{ kind: 'require-one' }` — neither flag supplied → exit 2.
+ *
+ * The session is a thin wrapper over the WS session: the only real
+ * difference is the transport (newline-delimited stdin/stdout instead
+ * of a socket) and the admission gate. Subscribe / unsubscribe and all
+ * the JSON-RPC semantics come from the shared session.
+ */
+import type { OperationRegistry } from './operation-catalog.ts';
+import type { WorkflowEventFeed } from './workflow-event-feed.ts';
+export type StdioAdmission = {
+    readonly kind: 'require-one';
+} | {
+    readonly kind: 'startup-token';
+    readonly token: string;
+} | {
+    readonly kind: 'allow-unauthenticated-local-admin';
+};
+export type StdioSessionOptions = {
+    readonly input: ReadableStream<Uint8Array>;
+    readonly output: WritableStream<Uint8Array>;
+    readonly admission: StdioAdmission;
+    readonly registry: OperationRegistry;
+    readonly engine: unknown;
+    readonly feed: WorkflowEventFeed;
+    readonly maxFrameBytes?: number;
+    readonly maxSubscriptions?: number;
+};
+export type StdioSessionResult = {
+    readonly exitCode: number;
+    readonly reason?: string;
+};
+export declare function runStdioSession(options: StdioSessionOptions): Promise<StdioSessionResult>;

package/dist/server/stdio-session.js

@@ -0,0 +1,245 @@
+import { splitNewlineDelimitedBuffer } from "./json-rpc-framing.js";
+import { JSON_RPC_ERROR_CODES, JSON_RPC_VERSION } from "./json-rpc-protocol.js";
+import {
+  createJsonRpcWebSocketSession
+} from "./json-rpc-websocket.js";
+import { isPlainObject } from "./json-schema-utilities.js";
+import { principalFromStdioLocal } from "./principal.js";
+const AUTHENTICATE_METHOD = "weft.authenticate", DEFAULT_MAX_FRAME_BYTES = 1048576;
+export async function runStdioSession(options) {
+  if (options.admission.kind === "require-one")
+    return {
+      exitCode: 2,
+      reason: "stdio session admission required: pass --startup-token <hex> or --allow-unauthenticated-local-admin"
+    };
+  const maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, io = createSessionIO(options.output), reader = options.input.getReader(), decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  if (options.admission.kind === "startup-token") {
+    const outcome = await runStartupTokenAdmission(reader, decoder, buffer, maxFrameBytes, options.admission.token, io);
+    if (outcome.kind === "fail") {
+      await io.drainWrites();
+      await closeWriterSilent(io.writer);
+      return outcome.result;
+    }
+    buffer = outcome.remainder;
+  }
+  const principal = principalFromStdioLocal(), session = createJsonRpcWebSocketSession({
+    registry: options.registry,
+    engine: options.engine,
+    principal,
+    emitter: io.emitter,
+    feed: options.feed,
+    transport: "jsonRpcStdio",
+    ...options.maxFrameBytes !== void 0 ? { maxFrameBytes: options.maxFrameBytes } : {},
+    ...options.maxSubscriptions !== void 0 ? { maxSubscriptions: options.maxSubscriptions } : {}
+  });
+  try {
+    buffer = await drainCompleteFramesFromBuffer(buffer, session);
+    buffer = await runMainReadLoop(reader, decoder, buffer, maxFrameBytes, session, io);
+  } finally {
+    await session.close();
+    await io.drainWrites();
+    await closeWriterSilent(io.writer);
+  }
+  return { exitCode: 0 };
+}
+function createSessionIO(output) {
+  const writer = output.getWriter(), encoder = new TextEncoder;
+  let writeChain = Promise.resolve();
+  function enqueueWrite(text) {
+    const next = writeChain.then(() => writer.write(encoder.encode(text)));
+    writeChain = next.catch(() => {});
+    return next;
+  }
+  return {
+    writer,
+    writeFrame: (message) => enqueueWrite(JSON.stringify(message) + `
+`),
+    emitter: {
+      send(message) {
+        enqueueWrite(message + `
+`);
+      }
+    },
+    drainWrites: async () => {
+      try {
+        await writeChain;
+      } catch {}
+    }
+  };
+}
+async function runStartupTokenAdmission(reader, decoder, initialBuffer, maxFrameBytes, expectedToken, io) {
+  const first = await readOneFrame(reader, decoder, initialBuffer, maxFrameBytes);
+  if (first.kind === "closed")
+    return {
+      kind: "fail",
+      result: { exitCode: 2, reason: "stdio session closed before authenticate frame" }
+    };
+  if (first.kind === "overflow") {
+    await io.writeFrame({
+      jsonrpc: JSON_RPC_VERSION,
+      error: {
+        code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+        message: "authenticate frame exceeds maxFrameBytes",
+        data: { weftCode: "InvalidParams", httpStatus: 400 }
+      },
+      id: null
+    });
+    return {
+      kind: "fail",
+      result: { exitCode: 2, reason: "authenticate frame exceeds maxFrameBytes" }
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(first.line);
+  } catch {
+    await io.writeFrame({
+      jsonrpc: JSON_RPC_VERSION,
+      error: { code: JSON_RPC_ERROR_CODES.PARSE_ERROR, message: "Parse error" },
+      id: null
+    });
+    return {
+      kind: "fail",
+      result: { exitCode: 2, reason: "first frame was not valid JSON" }
+    };
+  }
+  const shapeFault = classifyAuthenticateShape(parsed);
+  if (shapeFault) {
+    await io.writeFrame(shapeFault.frame);
+    return { kind: "fail", result: shapeFault.result };
+  }
+  const asObject = parsed, params = asObject.params, providedToken = isPlainObject(params) ? params.token : void 0;
+  if (typeof providedToken !== "string" || !constantTimeStringEqual(providedToken, expectedToken)) {
+    const id = asId(asObject.id);
+    await io.writeFrame({
+      jsonrpc: JSON_RPC_VERSION,
+      error: {
+        code: JSON_RPC_ERROR_CODES.UNAUTHORIZED,
+        message: "startup token mismatch",
+        data: { weftCode: "Unauthorized", httpStatus: 401 }
+      },
+      id
+    });
+    return { kind: "fail", result: { exitCode: 2, reason: "startup token mismatch" } };
+  }
+  const id = asId(asObject.id);
+  await io.writeFrame({ jsonrpc: JSON_RPC_VERSION, result: {}, id });
+  return { kind: "ok", remainder: first.remainder };
+}
+function classifyAuthenticateShape(parsed) {
+  if (isPlainObject(parsed) && parsed.jsonrpc === JSON_RPC_VERSION && parsed.method === AUTHENTICATE_METHOD)
+    return null;
+  const id = isPlainObject(parsed) ? asId(parsed.id) : null;
+  return {
+    frame: {
+      jsonrpc: JSON_RPC_VERSION,
+      error: {
+        code: JSON_RPC_ERROR_CODES.UNAUTHORIZED,
+        message: "first frame must be weft.authenticate",
+        data: { weftCode: "Unauthorized", httpStatus: 401 }
+      },
+      id
+    },
+    result: { exitCode: 2, reason: "first frame was not weft.authenticate" }
+  };
+}
+async function runMainReadLoop(reader, decoder, initialBuffer, maxFrameBytes, session, io) {
+  let buffer = initialBuffer, discardingOversize = !1;
+  while (!0) {
+    const result = await reader.read();
+    if (result.done) {
+      if (buffer.trim().length > 0)
+        await io.writeFrame({
+          jsonrpc: JSON_RPC_VERSION,
+          error: {
+            code: JSON_RPC_ERROR_CODES.PARSE_ERROR,
+            message: "unterminated frame at stream close"
+          },
+          id: null
+        });
+      return "";
+    }
+    buffer += decoder.decode(result.value, { stream: !0 });
+    if (discardingOversize) {
+      const resumeIndex = buffer.indexOf(`
+`);
+      if (resumeIndex === -1) {
+        buffer = "";
+        continue;
+      }
+      buffer = buffer.slice(resumeIndex + 1);
+      discardingOversize = !1;
+    }
+    if (buffer.length > maxFrameBytes && buffer.indexOf(`
+`) === -1) {
+      await io.writeFrame({
+        jsonrpc: JSON_RPC_VERSION,
+        error: {
+          code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+          message: "frame exceeds maxFrameBytes",
+          data: { weftCode: "InvalidParams", httpStatus: 400 }
+        },
+        id: null
+      });
+      buffer = "";
+      discardingOversize = !0;
+      continue;
+    }
+    const framed = splitNewlineDelimitedBuffer(buffer, "");
+    buffer = framed.buffer;
+    for (const line of framed.lines)
+      await session.handleMessage(line);
+  }
+}
+async function readOneFrame(reader, decoder, initialBuffer, maxFrameBytes) {
+  let buffer = initialBuffer;
+  while (!0) {
+    const newlineIndex = buffer.indexOf(`
+`);
+    if (newlineIndex !== -1) {
+      if (newlineIndex > maxFrameBytes)
+        return { kind: "overflow" };
+      const line = buffer.slice(0, newlineIndex).trim(), remainder = buffer.slice(newlineIndex + 1);
+      if (line.length === 0) {
+        buffer = remainder;
+        continue;
+      }
+      return { kind: "ok", line, remainder };
+    }
+    if (buffer.length > maxFrameBytes)
+      return { kind: "overflow" };
+    const result = await reader.read();
+    if (result.done)
+      return { kind: "closed" };
+    buffer += decoder.decode(result.value, { stream: !0 });
+  }
+}
+async function drainCompleteFramesFromBuffer(buffer, session) {
+  const framed = splitNewlineDelimitedBuffer(buffer, "");
+  for (const line of framed.lines)
+    await session.handleMessage(line);
+  return framed.buffer;
+}
+async function closeWriterSilent(writer) {
+  try {
+    await writer.close();
+  } catch {}
+}
+function asId(value) {
+  if (value === null)
+    return null;
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  return null;
+}
+function constantTimeStringEqual(a, b) {
+  if (a.length !== b.length)
+    return !1;
+  let mismatch = 0;
+  for (let i = 0;i < a.length; i += 1)
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return mismatch === 0;
+}

package/dist/server/task-queue-summary.d.ts

@@ -0,0 +1,27 @@
+import type { SchedulingPolicy, TaskQueueSummary } from './task-queue-types.ts';
+/**
+ * Read-only snapshot of the fields {@link buildQueueSummaries} needs. Captured
+ * synchronously by {@link TaskQueue.captureSnapshot} so all reads happen within
+ * a single turn of the event loop — no locks required.
+ *
+ * This type is internal to the server package and must not be re-exported from
+ * the public barrel.
+ */
+export type TaskQueueSnapshot = {
+    /** Shallow copy of queue → pending task metadata (only `enqueuedAt` is read). */
+    pending: ReadonlyMap<string, ReadonlyArray<{
+        enqueuedAt?: number | undefined;
+    }>>;
+    /** Shallow copy of queue → waiter array (only `length` is read). */
+    waiters: ReadonlyMap<string, ReadonlyArray<unknown>>;
+    /** Scheduling policy the queue was configured with. */
+    schedulingPolicy: SchedulingPolicy;
+};
+/**
+ * Build the sorted per-queue summary list from a synchronously captured
+ * snapshot. Pure function: no live registry references, no side effects.
+ *
+ * Returns one entry per queue name appearing in either `pending` or `waiters`,
+ * sorted ascending by queue name so responses are stable.
+ */
+export declare function buildQueueSummaries(snapshot: TaskQueueSnapshot): TaskQueueSummary[];

package/dist/server/task-queue-summary.js

@@ -0,0 +1,34 @@
+export function buildQueueSummaries(snapshot) {
+  const summaries = new Map;
+  for (const [queue, tasks] of snapshot.pending) {
+    let oldestEnqueuedAt = null;
+    for (const task of tasks) {
+      const enqueuedAt = task.enqueuedAt;
+      if (enqueuedAt === void 0)
+        continue;
+      if (oldestEnqueuedAt === null || enqueuedAt < oldestEnqueuedAt)
+        oldestEnqueuedAt = enqueuedAt;
+    }
+    summaries.set(queue, {
+      queue,
+      backlog: tasks.length,
+      oldestEnqueuedAt,
+      waitingPollers: 0,
+      schedulingPolicy: snapshot.schedulingPolicy
+    });
+  }
+  for (const [queue, waiters] of snapshot.waiters) {
+    const existing = summaries.get(queue);
+    if (existing === void 0)
+      summaries.set(queue, {
+        queue,
+        backlog: 0,
+        oldestEnqueuedAt: null,
+        waitingPollers: waiters.length,
+        schedulingPolicy: snapshot.schedulingPolicy
+      });
+    else
+      existing.waitingPollers = waiters.length;
+  }
+  return [...summaries.values()].toSorted((a, b) => a.queue < b.queue ? -1 : a.queue > b.queue ? 1 : 0);
+}