@dungle-scrubs/harness-cli-normalizer 0.5.3 → 0.5.4

package/src/cli/session-json.ts

@@ -0,0 +1,230 @@
+/**
+ * The machine session surface: `hcn session <h> --json`. Two pumps over one
+ * persistent session - stdin NDJSON commands in, stdout NDJSON events out -
+ * with the control events (`session`, `turn`, `disposition`, `closed`) that
+ * a program needs to drive a session it does not own the timing of. RFC-01.
+ *
+ * This owns the wire framing only. The turn lifecycle, the queue, and the id
+ * correlation live in `openSession`; this reads the id off the yielded turn
+ * rather than shadowing the runner's delivery order.
+ */
+import { createInterface } from "node:readline/promises";
+import type { HarnessEvent } from "../execution/events.js";
+import type { FailureSummary } from "../execution/failure.js";
+import {
+  SessionClosedError,
+  type SessionHandle,
+  type SessionSendResult,
+} from "../execution/open-session.js";
+
+/** What the CLI reads back after a close, captured from the runner's
+ * `session_close` boundary log. */
+export interface CloseInfo {
+  exitCode: number | null;
+  cause: string;
+}
+
+export interface JsonSessionArgs {
+  readonly handle: SessionHandle;
+  readonly sessionId: string;
+  readonly harness: string;
+  readonly hcnVersion: string;
+  readonly escalateQuestions: boolean;
+  /** Read after close - the runner's final exitCode and cause. */
+  readonly getCloseInfo: () => CloseInfo;
+  /** Read after close - ids the runner accepted as queued and never
+   * delivered. Each owes the consumer a rejection (RFC S003). */
+  readonly getDroppedIds?: () => readonly string[];
+  /** Injected for tests; defaults to process.stdin / process.stdout. */
+  readonly input?: NodeJS.ReadableStream;
+  readonly write?: (line: string) => boolean;
+  readonly onDrain?: (fn: () => void) => void;
+}
+
+type ParsedCommand =
+  | { readonly op: "send" | "answer"; readonly id: string; readonly text: string }
+  | { readonly op: "close" }
+  | { readonly malformed: string };
+
+const parseCommand = (line: string): ParsedCommand => {
+  let obj: unknown;
+  try {
+    obj = JSON.parse(line);
+  } catch {
+    return { malformed: "not JSON" };
+  }
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return { malformed: "not an object" };
+  }
+  const rec = obj as Record<string, unknown>;
+  if (rec.op === "close") return { op: "close" };
+  if (rec.op === "send" || rec.op === "answer") {
+    if (typeof rec.id !== "string" || rec.id === "") return { malformed: "missing or empty id" };
+    if (typeof rec.text !== "string") return { malformed: "text must be a string" };
+    return { op: rec.op, id: rec.id, text: rec.text };
+  }
+  return { malformed: `unknown op ${JSON.stringify(rec.op)}` };
+};
+
+/** The answer wrapper hcn composes so a consumer never re-derives it
+ * (RFC-01: the preamble is normalizer knowledge). */
+const composeAnswer = (question: string, answer: string): string =>
+  `The user answered the question: "${question}" with: ${answer}. Continue accordingly.`;
+
+export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
+  const rawWrite = a.write ?? ((line: string) => process.stdout.write(line));
+  const onDrain = a.onDrain ?? ((fn: () => void) => process.stdout.once("drain", fn));
+
+  // The consumer's read end can close mid-session (it died, or it stopped
+  // reading). The process-wide EPIPE guard in index.ts exits 0 immediately,
+  // which would strand the harness child with nobody to end it. For a
+  // machine session the right answer is to close the session - grace, then
+  // signal - and exit 1. Replacing the listener is deliberate: the global
+  // one runs first otherwise and the process is gone before we act.
+  let consumerGone = false;
+  if (a.write === undefined) {
+    process.stdout.removeAllListeners("error");
+    process.stdout.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code !== "EPIPE") return;
+      consumerGone = true;
+      void a.handle.close();
+    });
+  }
+
+  // One serialized, drain-aware writer for both pumps: stdout never
+  // interleaves two events and never buffers past the OS pipe.
+  let chain: Promise<void> = Promise.resolve();
+  const emit = (event: unknown): Promise<void> => {
+    chain = chain.then(
+      () =>
+        new Promise<void>((resolve) => {
+          // A broken stdout never drains. Writing into it would park this
+          // chain forever and the session would hang instead of closing.
+          if (consumerGone) {
+            resolve();
+            return;
+          }
+          try {
+            if (rawWrite(`${JSON.stringify(event)}\n`)) resolve();
+            else onDrain(resolve);
+          } catch {
+            consumerGone = true;
+            resolve();
+          }
+        }),
+    );
+    return chain;
+  };
+
+  await emit({
+    kind: "session",
+    sessionId: a.sessionId,
+    harness: a.harness,
+    hcn: a.hcnVersion,
+    escalateQuestions: a.escalateQuestions,
+  });
+
+  // Shared between the pumps: the last question asked, whether the last turn
+  // ended awaiting an answer, and the last failure seen (for closed.failure).
+  let lastQuestion = "";
+  let awaitingAnswer = false;
+  let lastFailure: FailureSummary | undefined;
+
+  const stdoutPump = (async () => {
+    for await (const turn of a.handle.turns) {
+      awaitingAnswer = false;
+      await emit({
+        kind: "turn",
+        turnId: turn.turnId,
+        ...(turn.inputId !== undefined ? { id: turn.inputId } : {}),
+      });
+      for await (const ev of turn as AsyncIterable<HarnessEvent>) {
+        // Update the answer state BEFORE the event reaches the consumer. A
+        // consumer answers the moment it reads `done`, so setting this after
+        // the emit leaves a window where a valid answer is refused.
+        if (ev.kind === "question") lastQuestion = ev.question;
+        if (ev.kind === "done") {
+          awaitingAnswer = ev.cause === "awaiting-input";
+          if (ev.failure !== undefined) lastFailure = ev.failure;
+        }
+        if (ev.kind === "failure") lastFailure = ev;
+        await emit(ev);
+      }
+    }
+  })();
+
+  const rl = createInterface({ input: a.input ?? process.stdin });
+  const stdinPump = (async () => {
+    for await (const line of rl) {
+      if (line.trim() === "") continue;
+      const cmd = parseCommand(line);
+      if ("malformed" in cmd) {
+        await emit({ kind: "error", message: `malformed command: ${cmd.malformed}` });
+        continue;
+      }
+      if (cmd.op === "close") return;
+      let text = cmd.text;
+      if (cmd.op === "answer") {
+        if (!awaitingAnswer) {
+          await emit({
+            kind: "disposition",
+            id: cmd.id,
+            disposition: "rejected",
+            reason: "no-open-question",
+          });
+          continue;
+        }
+        text = composeAnswer(lastQuestion, cmd.text);
+      }
+      let sent: SessionSendResult;
+      try {
+        sent = a.handle.send({ id: cmd.id, text });
+      } catch (err) {
+        // A session the caller already closed, or one already dead: a
+        // different remedy from a broken pipe, so a different reason.
+        if (err instanceof SessionClosedError) {
+          await emit({
+            kind: "disposition",
+            id: cmd.id,
+            disposition: "rejected",
+            reason: "closed",
+          });
+          continue;
+        }
+        throw err;
+      }
+      await emit({
+        kind: "disposition",
+        id: cmd.id,
+        disposition: sent.disposition,
+        ...(sent.reason !== undefined ? { reason: sent.reason } : {}),
+      });
+    }
+  })();
+
+  // Whichever ends first drives the close: a close/EOF from stdin, or the
+  // session dying (the turns iterable ends). close() is idempotent; closing
+  // the readline unblocks the stdin pump if the session died first.
+  await Promise.race([stdinPump, stdoutPump]);
+  await a.handle.close();
+  rl.close();
+  await Promise.allSettled([stdinPump, stdoutPump]);
+
+  // Every input the runner accepted as queued and then lost gets its own
+  // rejection, before the terminal line (RFC S003).
+  for (const id of a.getDroppedIds?.() ?? []) {
+    await emit({ kind: "disposition", id, disposition: "rejected", reason: "closed" });
+  }
+
+  const info = a.getCloseInfo();
+  await emit({
+    kind: "closed",
+    exitCode: info.exitCode,
+    cause: info.cause,
+    ...(info.cause !== "clean" && lastFailure !== undefined ? { failure: lastFailure } : {}),
+  });
+  // A consumer that stopped reading gets exit 1 even on a clean harness exit:
+  // the session did not end the way the consumer asked for.
+  if (consumerGone) return 1;
+  return info.cause === "clean" ? 0 : 1;
+};

package/src/cli/session.ts

@@ -9,6 +9,9 @@ import { createRenderState, renderEvent } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 
 export const session = async (harnessName: string, rawArgs: string[]): Promise<void> => {
+  // Decided before any refusal can fire: a refused --json session still owes
+  // the stream a failure and a terminal `closed` (RFC-01 rule 3).
+  const jsonMode = rawArgs.includes("--json");
   // issue #44: the gate is the descriptor's sessionMode (claude stream-json,
   // pi --mode rpc), not a hardcoded name list - a harness that grows a
   // session mode is available the moment its descriptor declares one.
@@ -23,9 +26,8 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       supported,
       detail: `session mode is available on ${supported.join(", ")}; ${harnessName} declares no persistent headless session`,
     });
-    process.stderr.write(`${err.message}\n`);
-    process.stderr.write(`supported: ${supported.join(", ")}\n`);
-    process.exitCode = 2;
+    const { refusalOf, refuse } = await import("./refuse.js");
+    refuse(refusalOf(err), jsonMode, "closed");
     return;
   }
 
@@ -42,6 +44,14 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`unknown flag: ${message}\n`);
+    if (jsonMode) {
+      const { writeFailurePair } = await import("./refuse.js");
+      const { failureFromRejected } = await import("../execution/failure.js");
+      writeFailurePair(
+        failureFromRejected({ issue: "invalid-option-value", detail: `unknown flag: ${message}` }),
+        "closed",
+      );
+    }
     process.exitCode = 2;
     return;
   }
@@ -53,6 +63,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
     randomUUID();
   const model = values.model as string | undefined;
   const cwd = values.cwd as string | undefined;
+  const provider = values.provider as string | undefined;
 
   // issue #44: same precedence as hcn run - arg > project > user >
   // default-true. A behavior instruction, so it rides every send's
@@ -87,6 +98,17 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
             : "default";
   } catch (configErr) {
     process.stderr.write(`config error: ${(configErr as Error).message}\n`);
+    if (jsonMode) {
+      const { writeFailurePair } = await import("./refuse.js");
+      const { failureFromRejected } = await import("../execution/failure.js");
+      writeFailurePair(
+        failureFromRejected({
+          issue: "invalid-option-value",
+          detail: `config error: ${(configErr as Error).message}`,
+        }),
+        "closed",
+      );
+    }
     process.exitCode = 2;
     return;
   }
@@ -95,25 +117,92 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   // Validate sessionId shape? let openSession handle via assertUsableSessionId
   delete (process.env as Record<string, string | undefined>).HERDR_ENV;
 
-  const deps = nodeRunnerDeps();
+  const wantJson = values.json === true;
+  // Opt-in per-turn inactivity budget. 0 disables; no default. A session turn
+  // can hang with the process alive, which no exit code reports.
+  const rawStall = values.stall as string | undefined;
+  let stallMs: number | undefined;
+  if (rawStall !== undefined) {
+    const seconds = Number(rawStall);
+    if (!Number.isFinite(seconds) || seconds < 0) {
+      process.stderr.write(`invalid --stall ${JSON.stringify(rawStall)}; expected seconds >= 0\n`);
+      if (jsonMode) {
+        const { writeFailurePair } = await import("./refuse.js");
+        const { failureFromRejected } = await import("../execution/failure.js");
+        writeFailurePair(
+          failureFromRejected({
+            issue: "invalid-option-value",
+            detail: `invalid --stall ${JSON.stringify(rawStall)}`,
+          }),
+          "closed",
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
+    if (seconds > 0) stallMs = seconds * 1000;
+  }
+  const baseDeps = stallMs === undefined ? nodeRunnerDeps() : nodeRunnerDeps({ stallMs });
+  // Capture the runner's final exitCode/cause for the --json `closed` event.
+  const closeInfo = { exitCode: null as number | null, cause: "clean" };
+  const droppedIds: string[] = [];
+  const deps = wantJson
+    ? {
+        ...baseDeps,
+        log: (e: Record<string, unknown>) => {
+          if (e.event === "session_close") {
+            closeInfo.exitCode = (e.exitCode as number | null) ?? null;
+            closeInfo.cause = (e.cause as string) ?? "clean";
+          }
+          if (e.event === "sends_dropped" && Array.isArray(e.ids)) {
+            for (const id of e.ids as unknown[]) if (typeof id === "string") droppedIds.push(id);
+          }
+          baseDeps.log?.(e);
+        },
+      }
+    : baseDeps;
 
   let handle: ReturnType<typeof openSession>;
   try {
-    handle = openSession(h, { sessionId, model, cwd, escalateQuestions }, deps);
+    handle = openSession(h, { sessionId, model, cwd, escalateQuestions, provider }, deps);
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
-      process.stderr.write(`${err.message}\n`);
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
+      const { refusalOf, refuse } = await import("./refuse.js");
+      refuse(refusalOf(err), jsonMode, "closed");
       return;
     }
+    // S002: the harness binary is missing or would not start. A transport
+    // failure, not a refusal - exit 1, and the stream is still owed its pair.
     process.stderr.write(
       `could not open session: ${err instanceof Error ? err.message : String(err)}\n`,
     );
+    if (jsonMode) {
+      const { writeFailurePair } = await import("./refuse.js");
+      const { failureFromTransport } = await import("../execution/failure.js");
+      writeFailurePair(
+        failureFromTransport(err instanceof Error ? err.message : String(err)),
+        "closed",
+      );
+    }
     process.exitCode = 1;
     return;
   }
 
+  if (wantJson) {
+    const { runJsonSession } = await import("./session-json.js");
+    const { getVersion } = await import("./version.js");
+    process.exitCode = await runJsonSession({
+      handle,
+      sessionId,
+      harness: h.name,
+      hcnVersion: getVersion(),
+      escalateQuestions,
+      getCloseInfo: () => closeInfo,
+      getDroppedIds: () => droppedIds,
+    });
+    return;
+  }
+
   process.stdout.write(
     `interactive ${h.name} session ${sessionId}\n(empty line or "exit" to quit)\n`,
   );
@@ -136,6 +225,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
 
   // Handle SIGINT to close session cleanly
   let closing = false;
+  let sendCount = 0;
   const doClose = async () => {
     if (closing) return;
     closing = true;
@@ -168,7 +258,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       const trimmed = line.trim();
       if (trimmed === "" || trimmed === "exit") break;
 
-      const result = handle.send(line);
+      const result = handle.send({ id: `you-${++sendCount}`, text: line });
       if (result.disposition === "queued") {
         process.stderr.write(`disposition: queued (turn in progress)\n`);
       }
@@ -209,9 +299,10 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
             answer = a;
           }
         }
-        handle.send(
-          `The user answered the question: "${q.question}" with: ${answer}. Continue accordingly.`,
-        );
+        handle.send({
+          id: `you-${++sendCount}`,
+          text: `The user answered the question: "${q.question}" with: ${answer}. Continue accordingly.`,
+        });
         // Drain the answer turn BEFORE prompting again - the pump's
         // backpressure stalls the harness until the turn iterable is
         // consumed (verified live: menu answered, you-prompt rendered, no