@dungle-scrubs/harness-cli-normalizer 0.1.1

package/src/execution/deps.ts

@@ -0,0 +1,59 @@
+/**
+ * Injected runtime primitives (D-005): the execution layer never imports
+ * child_process, never calls process.kill, and never reads a wall clock -
+ * spawn, clock, and signalling arrive as data so Node/Bun is a real
+ * portability boundary and tests run against fakes deterministically.
+ */
+
+export interface SpawnedProcess {
+  readonly stdout: AsyncIterable<string | Uint8Array>;
+  readonly stderr: AsyncIterable<string | Uint8Array>;
+  /** Idempotently terminate stdout and stderr reads without signalling the
+   * child. An adapter MUST preserve chunks already buffered when disposal is
+   * requested, then settle the first read beyond that finite snapshot.
+   * Terminal cleanup owns process signalling separately. */
+  disposeOutput(): void;
+  /** Resolves with the exit code, or null when the process died to a
+   * signal without one. */
+  readonly exited: Promise<number | null>;
+  /** Present when the spawner opened a writable stdin (session mode needs
+   * it; one-shot turns close or inherit stdin instead). */
+  readonly stdin?: {
+    write(data: string): void;
+    end(): void;
+  };
+}
+
+export interface SpawnOptions {
+  readonly cwd?: string;
+  /** `pipe` opens a writable stdin (sessions require it); `inherit` hands
+   * the child the parent's fd 0; `close` gives it nothing (pi's rule). */
+  readonly stdin: "inherit" | "close" | "pipe";
+}
+
+export type TimerHandle = number;
+
+export interface Clock {
+  now(): number;
+  setTimeout(fn: () => void, ms: number): TimerHandle;
+  clearTimeout(handle: TimerHandle): void;
+}
+
+export type SignalName = "SIGTERM" | "SIGKILL";
+
+/** One structured line per boundary transition - spawn, exit, stall,
+ * redacted argv. Always-on baseline evidence; the host decides where it
+ * goes. */
+export type BoundaryLog = (event: Record<string, unknown>) => void;
+
+export interface RunnerDeps {
+  readonly spawn: (argv: readonly string[], opts: SpawnOptions) => SpawnedProcess;
+  readonly clock: Clock;
+  readonly signal: (proc: SpawnedProcess, sig: SignalName) => void;
+  /** Stall watchdog budget; armed ONLY for none-granularity invocations. */
+  readonly stallMs?: number;
+  readonly log?: BoundaryLog;
+  /** Host-minted correlation id; without it the runner falls back to a
+   * per-process monotonic counter (collides across processes). */
+  readonly turnId?: string;
+}

package/src/execution/events.ts

@@ -0,0 +1,37 @@
+/**
+ * HarnessEvent: the runner's output vocabulary (PLAN.md Part 0). The
+ * normalizer owns these events and the parsing that produces them; it does
+ * NOT own the chat protocol - lucid maps events into frames downstream.
+ * Only `done` is terminal. A turn may emit MULTIPLE `error` events before
+ * it (a decoded mid-stream error, then a crash-exit stderr tail, etc.), so
+ * a consumer treats `error` as informational and waits for `done`.
+ *
+ * Event classes are load-bearing for backpressure: token/progress/context
+ * are droppable (coalescible, latest-wins); the rest are lossless. The
+ * split is DECLARED here because the normalizer emits the events; the
+ * coalescing policy that consumes it lives in the chat layer (lucid-v2).
+ * Under token granularity a turn's text arrives twice by design: as token
+ * deltas AND as the whole trailing message event - render one, never
+ * concatenate both.
+ */
+import type { CapabilityResult } from "../interpretation/capabilities.js";
+
+export type ExitCause = "clean" | "limit" | "crash" | "stall" | "killed";
+
+export type HarnessEvent =
+  | {
+      readonly kind: "identity";
+      readonly sessionId: string;
+      readonly authority: "caller-assigned" | "harness-minted";
+      readonly capabilities: CapabilityResult;
+    }
+  | { readonly kind: "token"; readonly text: string }
+  | { readonly kind: "message"; readonly role: string; readonly text: string }
+  | { readonly kind: "progress"; readonly label: string }
+  | { readonly kind: "tool"; readonly name: string; readonly input?: unknown }
+  | { readonly kind: "context"; readonly usedPct: number }
+  | { readonly kind: "limit"; readonly code: string; readonly message: string }
+  | { readonly kind: "error"; readonly message: string }
+  | { readonly kind: "done"; readonly exitCode: number | null; readonly cause: ExitCause };
+
+export const DROPPABLE_KINDS = new Set(["token", "progress", "context"]);

package/src/execution/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Execution layer: owns the process lifecycle for a harness session.
+ *
+ * It exposes openSession() and streamTurn(), which drive a CLI process via
+ * injected {spawn, clock, signal} primitives and emit HarnessEvent values.
+ * This module knows nothing about any chat protocol. Because it must run
+ * identically on Node and Bun, it never imports child_process and never calls
+ * process.kill directly outside the node-deps adapter - all process I/O and
+ * signalling flows through the injected primitives.
+ */
+export { AsyncChannel } from "./channel.js";
+export * from "./decode.js";
+export * from "./deps.js";
+export * from "./events.js";
+export { LINE_MAX, LineBuffer } from "./lines.js";
+export { nodeRunnerDeps } from "./node-deps.js";
+export * from "./open-session.js";
+export * from "./stream-turn.js";

package/src/execution/lines.ts

@@ -0,0 +1,71 @@
+/**
+ * Line assembly for process streams: chunks arrive torn at arbitrary BYTE
+ * boundaries, so the byte->string step must stream (a multibyte character
+ * split across chunks decodes whole, never as replacement bytes), and
+ * complete lines are only ever cut at '\n'. The pending partial is scanned
+ * incrementally (never re-split from the start) and bounded: a payload
+ * must not become parseable - or resident - by luck of where the pipe
+ * split it, so an over-long line flips to discard until its newline.
+ */
+
+export const LINE_MAX = 65_536;
+
+export class LineBuffer {
+  // Per-instance and stateful ({stream:true}): a shared decoder would carry
+  // partial-sequence state across two streams and corrupt both.
+  private readonly decoder = new TextDecoder();
+  private pending = "";
+  private scanFrom = 0;
+  private discarding = false;
+
+  push(chunk: string | Uint8Array): string[] {
+    const text = typeof chunk === "string" ? chunk : this.decoder.decode(chunk, { stream: true });
+    return this.ingest(text);
+  }
+
+  private ingest(text: string): string[] {
+    this.pending += text;
+    const lines: string[] = [];
+    while (true) {
+      const at = this.pending.indexOf("\n", this.scanFrom);
+      if (at === -1) break;
+      const line = this.pending.slice(0, at);
+      this.pending = this.pending.slice(at + 1);
+      this.scanFrom = 0;
+      if (this.discarding) {
+        // The truncated head of an over-long line ends here; drop it whole.
+        this.discarding = false;
+        continue;
+      }
+      // The bound applies to COMPLETE lines too - an oversized line whose
+      // newline arrived in the same chunk must not bypass it.
+      if (line.length <= LINE_MAX && !isBlank(line)) lines.push(line);
+    }
+    this.scanFrom = this.pending.length;
+    if (this.pending.length > LINE_MAX) {
+      this.pending = "";
+      this.scanFrom = 0;
+      this.discarding = true;
+    }
+    return lines;
+  }
+
+  /** The final partial line at stream close, if any. */
+  flush(): string | null {
+    const tail = this.decoder.decode();
+    if (tail !== "") this.pending += tail;
+    const rest = this.discarding || isBlank(this.pending) ? null : this.pending;
+    this.pending = "";
+    this.scanFrom = 0;
+    this.discarding = false;
+    return rest;
+  }
+}
+
+const isBlank = (line: string): boolean => {
+  for (let i = 0; i < line.length; i++) {
+    const c = line.charCodeAt(i);
+    if (c !== 32 && c !== 9 && c !== 13) return false;
+  }
+  return true;
+};

package/src/execution/node-deps.ts

@@ -0,0 +1,179 @@
+/**
+ * The real runtime adapter for RunnerDeps: node:child_process spawn (Bun
+ * implements the same module, so this is the Node AND Bun adapter), wall
+ * clock, and process signalling. This is the ONE module where the injected
+ * primitives touch the operating system - everything above it stays pure
+ * and fake-driven. Kills go to the exact child handle this adapter
+ * spawned, never to a pid pattern.
+ */
+import { type ChildProcess, spawn as nodeSpawn } from "node:child_process";
+import type { Readable } from "node:stream";
+import type { Clock, RunnerDeps, SpawnedProcess, SpawnOptions } from "./deps.js";
+
+const children = new WeakMap<SpawnedProcess, ChildProcess>();
+
+const emptyStream = async function* (): AsyncIterable<Uint8Array> {};
+
+type SpawnOutcome = "spawned" | "failed";
+
+/** Normalize only errors created by this adapter's own terminal operations.
+ * Identity comparison keeps an unrelated read failure visible even when it
+ * settles after output disposal has started. */
+const normalizeOutputStream = async function* (
+  source: AsyncIterable<Uint8Array>,
+  disposalCause: Error,
+  spawnOutcome: Promise<SpawnOutcome>,
+): AsyncIterable<Uint8Array> {
+  try {
+    yield* source;
+  } catch (cause) {
+    if (cause === disposalCause) return;
+    if (
+      (cause as NodeJS.ErrnoException)?.code === "ERR_STREAM_PREMATURE_CLOSE" &&
+      (await spawnOutcome) === "failed"
+    ) {
+      return;
+    }
+    throw cause;
+  }
+};
+
+/** Request terminal disposal without discarding chunks already buffered by
+ * the runtime. Once the consumer reaches the first pending read, destruction
+ * settles that read with this adapter's unique disposal cause. */
+export const disposableOutputStream = (
+  source: Readable,
+  disposalCause: Error,
+  spawnOutcome: Promise<SpawnOutcome>,
+): { readonly stream: AsyncIterable<Uint8Array>; dispose(): void } => {
+  let disposalRequested = false;
+  let disposalDrainBudget = 0;
+  let readPending = false;
+
+  const destroyPendingRead = (): void => {
+    if (disposalRequested && readPending && disposalDrainBudget === 0 && !source.destroyed) {
+      source.destroy(disposalCause);
+    }
+  };
+  const drainBeforeDisposal = async function* (): AsyncIterable<Uint8Array> {
+    const iterator = source[Symbol.asyncIterator]();
+    while (true) {
+      readPending = true;
+      if (disposalRequested && disposalDrainBudget === 0 && !source.destroyed) {
+        source.destroy(disposalCause);
+      }
+      let next: IteratorResult<unknown>;
+      try {
+        next = await iterator.next();
+      } finally {
+        readPending = false;
+      }
+      if (next.done) return;
+      if (disposalRequested) {
+        const bytes = next.value as { readonly byteLength?: number };
+        disposalDrainBudget = Math.max(0, disposalDrainBudget - (bytes.byteLength ?? 0));
+      }
+      yield next.value as Uint8Array;
+    }
+  };
+
+  return {
+    stream: normalizeOutputStream(drainBeforeDisposal(), disposalCause, spawnOutcome),
+    dispose: (): void => {
+      if (disposalRequested) return;
+      disposalRequested = true;
+      disposalDrainBudget = source.readableLength;
+      destroyPendingRead();
+    },
+  };
+};
+
+const realSpawn = (argv: readonly string[], opts: SpawnOptions): SpawnedProcess => {
+  const [bin, ...args] = argv;
+  if (bin === undefined) throw new Error("empty argv");
+  const child = nodeSpawn(bin, args, {
+    ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+    stdio: [
+      opts.stdin === "pipe" ? "pipe" : opts.stdin === "close" ? "ignore" : "inherit",
+      "pipe",
+      "pipe",
+    ],
+  });
+  let outputDisposed = false;
+  const stdoutDisposalCause = new Error("stdout disposed by runner");
+  const stderrDisposalCause = new Error("stderr disposed by runner");
+  let spawnError: Error | null = null;
+  const spawnOutcome = new Promise<SpawnOutcome>((resolve) => {
+    child.once("spawn", () => resolve("spawned"));
+    child.once("error", () => resolve("failed"));
+  });
+  const stdoutOutput =
+    child.stdout === null
+      ? null
+      : disposableOutputStream(child.stdout, stdoutDisposalCause, spawnOutcome);
+  const stderrOutput =
+    child.stderr === null
+      ? null
+      : disposableOutputStream(child.stderr, stderrDisposalCause, spawnOutcome);
+  // exited resolves via 'exit' (process died - fires even while a grandchild
+  // holds the pipes open, unlike 'close') or 'error' (ENOENT etc., which
+  // node reports async, not as a sync throw -> map to 127 crash). The error
+  // handler sets spawnError before it resolves exited.
+  const exited = new Promise<number | null>((resolve) => {
+    child.on("error", (err) => {
+      spawnError = err;
+      resolve(127);
+    });
+    child.on("exit", (code) => resolve(code));
+  });
+  // The spawn error rides the stderr stream so the runner's tail (and the
+  // crash exit log) carry the explanation, matching the sync-throw path.
+  // normalizeOutputStream waits only for the spawn/error outcome when it sees a
+  // premature close, so a genuine read failure on a live child propagates
+  // immediately while an async ENOENT remains the single spawn-error signal.
+  const stderrWithError = async function* (): AsyncIterable<string | Uint8Array> {
+    if (stderrOutput !== null) yield* stderrOutput.stream;
+    await exited;
+    if (spawnError !== null) yield `spawn failed: ${(spawnError as Error).message}\n`;
+  };
+  const proc: SpawnedProcess = {
+    stdout: stdoutOutput === null ? emptyStream() : stdoutOutput.stream,
+    stderr: stderrWithError(),
+    exited,
+    disposeOutput: (): void => {
+      if (outputDisposed) return;
+      outputDisposed = true;
+      stdoutOutput?.dispose();
+      stderrOutput?.dispose();
+    },
+    ...(opts.stdin === "pipe" && child.stdin !== null
+      ? {
+          stdin: {
+            write: (data: string): void => {
+              child.stdin?.write(data);
+            },
+            end: (): void => {
+              child.stdin?.end();
+            },
+          },
+        }
+      : {}),
+  };
+  children.set(proc, child);
+  return proc;
+};
+
+const realClock: Clock = {
+  now: () => Date.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms) as unknown as number,
+  clearTimeout: (handle) => clearTimeout(handle as unknown as ReturnType<typeof setTimeout>),
+};
+
+export const nodeRunnerDeps = (extra?: Partial<RunnerDeps>): RunnerDeps => ({
+  spawn: realSpawn,
+  clock: realClock,
+  signal: (proc, sig) => {
+    children.get(proc)?.kill(sig);
+  },
+  ...extra,
+});