@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/lib/run-evidence-policy.ts

@@ -0,0 +1,242 @@
+/**
+ * Pure bounded Run-evidence policy.
+ * Zones: Trace retention, compaction accounting, Control capacity and admission
+ * Owns deterministic limits policy; journal I/O, locks, lifecycle authorization, and projection stay in adapters.
+ * Trace keeps the newest physical suffix because semantic priority would silently
+ * redefine causal history. Admitted Controls never expire: only a real terminal
+ * transition or generation replacement proves that durable work is finished.
+ */
+
+import * as Limits from "./limits.ts";
+
+export const TRACE_COMPACTION_KIND = "runtime.trace_compacted";
+export const TRACE_COMPACTION_VERSION = 1;
+export type TraceJournalUsage = { bytes: number; events: number };
+export type TraceRetentionCandidate<T> = { encodedBytes: number; value: T };
+export type TraceRetentionSelection<T> = {
+  droppedEvents: number; retained: TraceRetentionCandidate<T>[];
+  retainedBytes: number; retainedEvents: number;
+};
+export interface TraceCompactionData {
+  version: typeof TRACE_COMPACTION_VERSION;
+  compactions_total: number;
+  dropped_valid_events_total: number;
+  dropped_malformed_lines_total: number;
+  dropped_bytes_total: number;
+  dropped_event_count_exact: boolean;
+  retained_events: number;
+  retained_bytes: number;
+  history_complete: false;
+}
+export interface TraceCompactionDelta {
+  dropped_valid_events: number;
+  dropped_malformed_lines: number;
+  dropped_bytes: number;
+  dropped_event_count_exact: boolean;
+  retained_events: number;
+  retained_bytes: number;
+}
+export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
+export type RunControlCapacity = {
+  available: number; backpressured: boolean; limit: number;
+  oldest_pending_at?: string; pending: number;
+};
+export type RunControlAdmissionIntegrity =
+  | "valid" | "unreadable" | "malformed" | "noncanonical"
+  | "invalid_record" | "invalid_status_timestamp" | "generation_mismatch"
+  | "journal_bytes";
+export interface RunControlAdmissionErrorDetails {
+  reason: "control_backpressure" | "control_journal_integrity";
+  pending: number;
+  limit: number;
+  journal_bytes: number;
+  journal_limit: number;
+  oldest_pending_at?: string;
+  run_instance_id: string;
+  next_actions: string[];
+  integrity_reason?: string;
+}
+export type RunControlAdmissionDecision =
+  { admitted: true; capacity: RunControlCapacity } |
+  { admitted: false; capacity: RunControlCapacity; error: RunControlAdmissionErrorDetails };
+export type RunControlAdmissionInput = {
+  integrity: RunControlAdmissionIntegrity; journalBytes: number;
+  newRecordBytes: number; records: readonly unknown[];
+  retainedJournalBytes: number; runInstanceId: string;
+  capacity?: RunControlCapacity;
+};
+
+const PENDING_CONTROL_STATUSES = new Set<RunControlStatus>(["queued", "delivered", "claimed"]);
+const TERMINAL_CONTROL_STATUSES = new Set<RunControlStatus>(["handled", "failed"]);
+const CONTROL_ADMISSION_NEXT_ACTIONS = [
+  "inspect target=run:<id> view=control",
+  "inspect target=runtime view=triage",
+];
+
+function isCount(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+function assertCount(value: number, name: string): void {
+  if (!isCount(value)) throw new RangeError(`${name} must be a non-negative safe integer`);
+}
+function boundedAdd(left: number, right: number): number {
+  return Math.min(Number.MAX_SAFE_INTEGER, left + right);
+}
+export function traceAppendFits(usage: TraceJournalUsage, encodedEventBytes: number): boolean {
+  if (!isCount(usage.events) || !isCount(usage.bytes) || !isCount(encodedEventBytes)) return false;
+  return usage.events + 1 <= Limits.TRACE_JOURNAL_MAX_EVENTS &&
+    usage.bytes + encodedEventBytes <= Limits.TRACE_JOURNAL_MAX_BYTES;
+}
+
+export function selectNewestTraceSuffix<T>(
+  candidates: readonly TraceRetentionCandidate<T>[],
+  reserve: { bytes?: number; events?: number } = {},
+): TraceRetentionSelection<T> {
+  const reservedBytes = reserve.bytes ?? 0;
+  const reservedEvents = reserve.events ?? 0;
+  assertCount(reservedBytes, "reserved Trace bytes");
+  assertCount(reservedEvents, "reserved Trace events");
+  const byteBudget = Math.max(0, Limits.TRACE_JOURNAL_TARGET_BYTES - reservedBytes);
+  const eventBudget = Math.max(0, Limits.TRACE_JOURNAL_TARGET_EVENTS - reservedEvents);
+  let retainedBytes = 0;
+  let start = candidates.length;
+  while (start > 0 && candidates.length - start < eventBudget) {
+    const candidate = candidates[start - 1]!;
+    assertCount(candidate.encodedBytes, "encoded Trace bytes");
+    if (retainedBytes + candidate.encodedBytes > byteBudget) break;
+    retainedBytes += candidate.encodedBytes;
+    start -= 1;
+  }
+  const retained = candidates.slice(start);
+  return {
+    droppedEvents: candidates.length - retained.length,
+    retained,
+    retainedBytes,
+    retainedEvents: retained.length,
+  };
+}
+
+export function accumulateTraceCompactionStatistics(
+  previous: TraceCompactionData | undefined,
+  delta: TraceCompactionDelta,
+): TraceCompactionData {
+  for (const [name, value] of Object.entries(delta)) {
+    if (name !== "dropped_event_count_exact") assertCount(value as number, name);
+  }
+  const prior = previous ?? {
+    compactions_total: 0,
+    dropped_bytes_total: 0,
+    dropped_event_count_exact: true,
+    dropped_malformed_lines_total: 0,
+    dropped_valid_events_total: 0,
+  };
+  const eventCountOverflow = prior.dropped_valid_events_total +
+    delta.dropped_valid_events > Number.MAX_SAFE_INTEGER;
+  return {
+    version: TRACE_COMPACTION_VERSION,
+    compactions_total: boundedAdd(prior.compactions_total, 1),
+    dropped_valid_events_total: boundedAdd(prior.dropped_valid_events_total, delta.dropped_valid_events),
+    dropped_malformed_lines_total: boundedAdd(prior.dropped_malformed_lines_total, delta.dropped_malformed_lines),
+    dropped_bytes_total: boundedAdd(prior.dropped_bytes_total, delta.dropped_bytes),
+    dropped_event_count_exact: prior.dropped_event_count_exact &&
+      delta.dropped_event_count_exact && !eventCountOverflow,
+    retained_events: delta.retained_events,
+    retained_bytes: delta.retained_bytes,
+    history_complete: false,
+  };
+}
+
+export function traceCompactionMarkerInput(data: TraceCompactionData): {
+  data: TraceCompactionData; kind: typeof TRACE_COMPACTION_KIND; level: "warning";
+} {
+  return { data, kind: TRACE_COMPACTION_KIND, level: "warning" };
+}
+
+export function classifyRunControlRecord(value: unknown): "pending" | "terminal" | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const status = (value as { status?: unknown }).status as RunControlStatus;
+  if (PENDING_CONTROL_STATUSES.has(status)) return "pending";
+  if (TERMINAL_CONTROL_STATUSES.has(status)) return "terminal";
+  return undefined;
+}
+
+export function runControlStatusTimestamp(
+  record: Record<string, unknown>, status: RunControlStatus,
+): unknown {
+  if (status === "failed") return record.failed_at;
+  if (status === "handled") return record.handled_at;
+  if (status === "claimed") return record.claimed_at;
+  if (status === "delivered") return record.delivered_at;
+  return record.queued_at;
+}
+
+export function computeRunControlCapacity(records: readonly unknown[]): RunControlCapacity {
+  let oldest: { timestamp: string; timestampMs: number } | undefined;
+  let pending = 0;
+  for (const value of records) {
+    if (classifyRunControlRecord(value) !== "pending") continue;
+    pending += 1;
+    const record = value as Record<string, unknown>;
+    const timestamp = runControlStatusTimestamp(record, record.status as RunControlStatus);
+    const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+    if (typeof timestamp === "string" && Number.isFinite(timestampMs) &&
+        (!oldest || timestampMs < oldest.timestampMs)) {
+      oldest = { timestamp, timestampMs };
+    }
+  }
+  return {
+    available: Math.max(0, Limits.RUN_CONTROL_PENDING_LIMIT - pending),
+    backpressured: pending >= Limits.RUN_CONTROL_PENDING_LIMIT,
+    limit: Limits.RUN_CONTROL_PENDING_LIMIT,
+    ...(oldest ? { oldest_pending_at: oldest.timestamp } : {}),
+    pending,
+  };
+}
+
+export function decideRunControlAdmission(
+  input: RunControlAdmissionInput,
+): RunControlAdmissionDecision {
+  const capacity = input.capacity ?? computeRunControlCapacity(input.records);
+  const reject = (
+    reason: RunControlAdmissionErrorDetails["reason"],
+    integrityReason?: string,
+  ): RunControlAdmissionDecision => ({
+    admitted: false,
+    capacity,
+    error: {
+      reason,
+      pending: capacity.pending,
+      limit: capacity.limit,
+      journal_bytes: input.journalBytes,
+      journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+      ...(capacity.oldest_pending_at ? { oldest_pending_at: capacity.oldest_pending_at } : {}),
+      run_instance_id: input.runInstanceId,
+      next_actions: [...CONTROL_ADMISSION_NEXT_ACTIONS],
+      ...(integrityReason ? { integrity_reason: integrityReason } : {}),
+    },
+  });
+  if (input.integrity !== "valid") return reject("control_journal_integrity", input.integrity);
+  if (!isCount(input.journalBytes) || !isCount(input.retainedJournalBytes) ||
+      !isCount(input.newRecordBytes) ||
+      input.journalBytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+    return reject("control_journal_integrity", "journal_bytes");
+  }
+  for (const value of input.records) {
+    const classification = classifyRunControlRecord(value);
+    if (!classification) return reject("control_journal_integrity", "invalid_record");
+    if (classification !== "pending") continue;
+    const record = value as Record<string, unknown>;
+    const timestamp = runControlStatusTimestamp(record, record.status as RunControlStatus);
+    if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp))) {
+      return reject("control_journal_integrity", "invalid_status_timestamp");
+    }
+    if (record.run_instance_id !== input.runInstanceId) {
+      return reject("control_journal_integrity", "generation_mismatch");
+    }
+  }
+  if (capacity.backpressured ||
+      input.retainedJournalBytes + input.newRecordBytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+    return reject("control_backpressure");
+  }
+  return { admitted: true, capacity };
+}

package/node_modules/@llblab/pi-actors/lib/run-ui-runtime.ts

@@ -0,0 +1,155 @@
+/**
+ * Ambient run observability runtime.
+ * Zones: run watcher lifecycle, terminal reconciliation, status animation, shutdown teardown
+ * Owns event-driven run UI coordination without owning actor execution semantics.
+ */
+
+import * as AsyncRuns from "./async-runs.ts";
+import * as Observability from "./observability.ts";
+import * as Paths from "./paths.ts";
+import * as Pi from "./pi.ts";
+
+export interface RunUiRuntime {
+  close(): void;
+  shutdown(eventReason: string, ctx: Pi.ExtensionContext): void;
+  start(ctx: Pi.ExtensionContext): void;
+}
+
+export interface RunUiRuntimeDeps {
+  getActiveContext(): Pi.ExtensionContext | undefined;
+  getRunOwnerId(ctx: Pi.ExtensionContext): string;
+  onRunEvent(): void;
+  pi: Pi.ExtensionAPI;
+}
+
+export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
+  let animationInterval: NodeJS.Timeout | undefined;
+  let notifyTimeout: NodeJS.Timeout | undefined;
+  let lastWatcherDiagnosticId = 0;
+  const observation = Observability.createRunUiObservationState();
+  const retirementAttempts = new Set<string>();
+  const terminalNotificationsInFlight = new Set<string>();
+
+  const retireCandidateRuns = (
+    ctx: Pi.ExtensionContext,
+    summary: Observability.RunSummary,
+  ): void => {
+    void Observability.executeRunRetirements(summary, {
+      attempted: retirementAttempts,
+      cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+      notify: (message, level) => ctx.ui.notify(message, level),
+      sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+    });
+  };
+  const update = (
+    ctx: Pi.ExtensionContext,
+    notify = false,
+    terminalOnly = false,
+  ): void => {
+    const ownerId = deps.getRunOwnerId(ctx);
+    const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
+    ctx.ui.setStatus(
+      "zz-pi-actors-runs",
+      snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined,
+    );
+    if (!notify) return;
+    const sink = Pi.createNotificationSink(deps.pi, ctx);
+    retireCandidateRuns(ctx, snapshot.summary);
+    Observability.deliverRunTransitionNotifications(
+      snapshot.transitions,
+      sink,
+      terminalNotificationsInFlight,
+    );
+    Observability.pruneRunUiObservationState(observation, snapshot);
+    if (!terminalOnly) {
+      Observability.deliverRunAttentionNotifications(snapshot.attentionEvents, sink);
+    }
+  };
+  const reportDiagnostics = (ctx: Pi.ExtensionContext): void => {
+    for (const diagnostic of watcher.getDiagnostics()) {
+      if (diagnostic.id <= lastWatcherDiagnosticId) continue;
+      lastWatcherDiagnosticId = diagnostic.id;
+      ctx.ui.notify(
+        diagnostic.message,
+        diagnostic.code === "rearmed" ? "info" : "warning",
+      );
+    }
+  };
+  const scheduleUpdate = (): void => {
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notifyTimeout = setTimeout(() => {
+      const ctx = deps.getActiveContext();
+      if (!ctx) return;
+      watcher.refresh();
+      update(ctx, true);
+      deps.onRunEvent();
+      reportDiagnostics(ctx);
+    }, 50);
+    notifyTimeout.unref?.();
+  };
+  const watcher = Observability.createRunStateWatcher({
+    stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+    onChange: scheduleUpdate,
+  });
+  const reconciliation = Observability.createRunTerminalReconciliationLoop({
+    onError: (error) => {
+      const ctx = deps.getActiveContext();
+      if (!ctx) return;
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+    },
+    reconcile: () => {
+      const ctx = deps.getActiveContext();
+      if (!ctx) return;
+      Observability.reconcileRunTerminalNotifications({
+        inFlight: terminalNotificationsInFlight,
+        ownerId: deps.getRunOwnerId(ctx),
+        sink: Pi.createNotificationSink(deps.pi, ctx),
+        state: observation,
+        includeAttention: true,
+      });
+      reportDiagnostics(ctx);
+    },
+    refreshWatcher: () => watcher.refresh(),
+  });
+  const close = (): void => {
+    watcher.close();
+    reconciliation.close();
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notifyTimeout = undefined;
+    if (animationInterval) clearInterval(animationInterval);
+    animationInterval = undefined;
+  };
+
+  return {
+    close,
+    shutdown(eventReason, ctx) {
+      close();
+      const teardown = AsyncRuns.teardownRunsOwnedByParent(
+        deps.getRunOwnerId(ctx),
+        Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+        { trigger: `session_shutdown:${eventReason}` },
+      );
+      if (teardown.failed === 0) return;
+      try {
+        ctx.ui.notify(
+          `Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`,
+          "warning",
+        );
+      } catch {
+        /* stale shutdown context */
+      }
+    },
+    start(ctx) {
+      close();
+      Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
+      update(ctx, true, true);
+      watcher.refresh();
+      reconciliation.start();
+      animationInterval = setInterval(() => {
+        if (deps.getActiveContext() === ctx) update(ctx);
+      }, 1000);
+      animationInterval.unref?.();
+    },
+  };
+}

package/node_modules/@llblab/pi-actors/lib/runs-artifacts.ts

@@ -0,0 +1,96 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns: artifact path template expansion and filesystem-backed artifact metadata.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import { substituteCommandTemplateToken } from "./command-templates.ts";
+
+export type RunArtifactDeclaration =
+  | string
+  | { path: string; kind?: string; media_type?: string; required?: boolean };
+
+export interface RunArtifactManifestEntry {
+  exists: boolean;
+  kind?: string;
+  media_type?: string;
+  path: string;
+  required?: boolean;
+  sha256?: string;
+  size?: number;
+}
+
+export function resolveArtifactPaths(
+  artifacts: Record<string, RunArtifactDeclaration> | undefined,
+  values: Record<string, unknown>,
+): Record<string, RunArtifactDeclaration> | undefined {
+  if (!artifacts) return undefined;
+  const resolved: Record<string, RunArtifactDeclaration> = {};
+  for (const [key, value] of Object.entries(artifacts)) {
+    if (!key.trim()) continue;
+    if (typeof value === "string") {
+      resolved[key] = substituteCommandTemplateToken(
+        value,
+        values,
+        `recipe artifacts.${key}`,
+      );
+    } else if (
+      value &&
+      typeof value === "object" &&
+      typeof value.path === "string"
+    ) {
+      resolved[key] = {
+        ...value,
+        path: substituteCommandTemplateToken(
+          value.path,
+          values,
+          `recipe artifacts.${key}.path`,
+        ),
+      };
+    }
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+export function resolveArtifactManifest(
+  artifacts: Record<string, RunArtifactDeclaration> | undefined,
+): Record<string, RunArtifactManifestEntry> | undefined {
+  if (!artifacts) return undefined;
+  const manifest: Record<string, RunArtifactManifestEntry> = {};
+  for (const [name, artifact] of Object.entries(artifacts)) {
+    const declaration =
+      typeof artifact === "string" ? { path: artifact } : artifact;
+    if (!declaration?.path) continue;
+    try {
+      const content = readFileSync(declaration.path);
+      manifest[name] = {
+        exists: true,
+        ...(declaration.kind ? { kind: declaration.kind } : {}),
+        ...(declaration.media_type
+          ? { media_type: declaration.media_type }
+          : {}),
+        path: declaration.path,
+        ...(declaration.required !== undefined
+          ? { required: declaration.required }
+          : {}),
+        sha256: createHash("sha256").update(content).digest("hex"),
+        size: content.byteLength,
+      };
+    } catch {
+      manifest[name] = {
+        exists: false,
+        ...(declaration.kind ? { kind: declaration.kind } : {}),
+        ...(declaration.media_type
+          ? { media_type: declaration.media_type }
+          : {}),
+        path: declaration.path,
+        ...(declaration.required !== undefined
+          ? { required: declaration.required }
+          : {}),
+      };
+    }
+  }
+  return Object.keys(manifest).length > 0 ? manifest : undefined;
+}

package/node_modules/@llblab/pi-actors/lib/runs-control-delivery.ts

@@ -0,0 +1,209 @@
+/**
+ * Run Control delivery.
+ * Zones: generation-fenced endpoint resolution, FIFO/named-pipe writes, durable outcomes
+ * Owns delivery of persisted actor-local Controls to ready service endpoints.
+ */
+
+import {
+  closeSync,
+  constants,
+  existsSync,
+  openSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+
+import * as Control from "./control.ts";
+import * as Limits from "./limits.ts";
+import {
+  appendRunControlInStateDir,
+  updateRunControlStatusInStateDir,
+} from "./runs-controls.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export interface RunControlEndpoint {
+  path: string;
+  type: "fifo" | "named-pipe";
+}
+
+export interface DeliverRunControlOptions {
+  namedPipeSend?: (path: string, payload: string) => Promise<number>;
+  platform?: NodeJS.Platform;
+}
+
+export interface DeliverRunControlRequest {
+  action: string;
+  input?: unknown;
+  run_instance_id: string;
+}
+
+const PREFLIGHT_CONTROL_ID = "00000000-0000-4000-8000-000000000000";
+
+export function encodeRunControlWire(wire: {
+  action: string;
+  id: string;
+  input?: unknown;
+}): { bytes: number; payload: string } {
+  const payload = `${JSON.stringify({
+    id: wire.id,
+    action: wire.action,
+    ...(wire.input !== undefined ? { input: wire.input } : {}),
+  })}\n`;
+  const bytes = Buffer.byteLength(payload);
+  if (bytes > Limits.CONTROL_WIRE_MAX_BYTES) {
+    throw new Error(
+      `Run Control wire record exceeds the ${Limits.CONTROL_WIRE_MAX_BYTES}-byte portable bound`,
+    );
+  }
+  return { bytes, payload };
+}
+
+export function readRunControlEndpoint(
+  stateDir: string,
+  runInstanceId: string,
+): RunControlEndpoint | undefined {
+  const endpoint = readJsonFileResilient<Record<string, unknown>>(
+    join(stateDir, "control-endpoint.json"),
+    {},
+  ).value;
+  if (endpoint.run_instance_id !== runInstanceId) return undefined;
+  if (
+    (endpoint.type === "fifo" || endpoint.type === "named-pipe") &&
+    typeof endpoint.path === "string" &&
+    endpoint.path.trim()
+  ) {
+    return { path: endpoint.path, type: endpoint.type };
+  }
+  return undefined;
+}
+
+function sendToFifo(endpoint: RunControlEndpoint, payload: string): number {
+  if (!existsSync(endpoint.path))
+    throw new Error(`Run Control FIFO not found: ${endpoint.path}`);
+  const stat = statSync(endpoint.path);
+  if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+    throw new Error(`Run Control endpoint is not a FIFO: ${endpoint.path}`);
+  }
+  let fd: number | undefined;
+  try {
+    fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+    return writeSync(fd, payload);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function sendToNamedPipe(
+  endpoint: RunControlEndpoint,
+  payload: string,
+  send?: (path: string, payload: string) => Promise<number>,
+): Promise<number> {
+  if (send) return send(endpoint.path, payload);
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(endpoint.path);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(new Error("named pipe connection timed out"));
+    }, 5000);
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve(Buffer.byteLength(payload));
+    };
+    socket.on("error", finish);
+    socket.on("connect", () => socket.end(payload, () => finish()));
+  });
+}
+
+export async function deliverRunControl(
+  run: string,
+  stateDir: string,
+  request: DeliverRunControlRequest,
+  options: DeliverRunControlOptions = {},
+): Promise<Record<string, unknown>> {
+  const action = Control.normalizeControlAction(request.action);
+  const input = request.input === undefined
+    ? undefined
+    : Control.normalizeControlInput(request.input);
+  const normalizedRequest = {
+    action,
+    ...(input !== undefined ? { input } : {}),
+    run_instance_id: request.run_instance_id,
+  };
+  encodeRunControlWire({
+    id: PREFLIGHT_CONTROL_ID,
+    action,
+    ...(input !== undefined ? { input } : {}),
+  });
+  const control = appendRunControlInStateDir(stateDir, normalizedRequest);
+  const endpoint = readRunControlEndpoint(stateDir, request.run_instance_id);
+  if (!endpoint) {
+    updateRunControlStatusInStateDir(
+      stateDir,
+      control.id,
+      "failed",
+      { error: "control endpoint is not ready for this Run generation" },
+      ["queued", "delivered"],
+    );
+    throw Object.assign(new Error("Run Control endpoint is not ready."), {
+      action,
+      control_id: control.id,
+      reason: "endpoint_not_ready",
+      run,
+      run_instance_id: request.run_instance_id,
+    });
+  }
+  try {
+    const { bytes, payload } = encodeRunControlWire({
+      id: control.id,
+      action,
+      ...(input !== undefined ? { input } : {}),
+    });
+    let written: number;
+    if (endpoint.type === "fifo") {
+      if ((options.platform ?? process.platform) === "win32") {
+        throw new Error("FIFO Control delivery is unsupported on native Windows");
+      }
+      written = sendToFifo(endpoint, payload);
+    } else {
+      written = await sendToNamedPipe(endpoint, payload, options.namedPipeSend);
+    }
+    if (written !== bytes) {
+      throw new Error(`Run Control endpoint wrote ${written} of ${bytes} bytes`);
+    }
+    updateRunControlStatusInStateDir(stateDir, control.id, "delivered");
+    return {
+      action,
+      bytes,
+      control_id: control.id,
+      delivery: "delivered",
+      endpoint_type: endpoint.type,
+      run,
+      run_instance_id: request.run_instance_id,
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    updateRunControlStatusInStateDir(
+      stateDir,
+      control.id,
+      "failed",
+      { error: reason },
+      ["queued", "delivered"],
+    );
+    throw Object.assign(new Error(`Run Control delivery failed: ${reason}`), {
+      action,
+      control_id: control.id,
+      endpoint_type: endpoint.type,
+      reason: "delivery_failed",
+      run,
+      run_instance_id: request.run_instance_id,
+    });
+  }
+}