@yaag/cli 0.1.0

package/src/cli.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env bun
+import { writeSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  executeRun,
+  isOrchestrationProgram,
+  isYaagError,
+  loadCassette,
+  type OrchestrationProgram,
+  programDefinition,
+  type StampedEventSink,
+} from "@yaag/runtime";
+import { interactiveAvailable } from "./alt-screen.ts";
+import { parseArgv } from "./argv.ts";
+import { runInteractive } from "./interactive-run.ts";
+import { createPlainPresenter } from "./presenter.ts";
+import { executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
+import { registerRuntimeAlias } from "./runtime-alias.ts";
+import { setupWorkspace } from "./setup-workspace.ts";
+
+registerRuntimeAlias();
+
+/** Sets up a workspace, runs, or describes one Orchestration Program and returns an exit code. */
+export async function main(argv: readonly string[]): Promise<number> {
+  const parsed = parseArgv(argv);
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}\n`);
+    return 2;
+  }
+
+  try {
+    if (parsed.command === "setup-workspace") {
+      process.stdout.write(`${(await setupWorkspace(resolve(parsed.dir))).join("\n")}\n`);
+      return 0;
+    }
+    // A bad artifact must fail before importing an arbitrary program module.
+    if (parsed.command === "run" && (parsed.replay !== undefined || parsed.resume !== undefined)) {
+      await loadCassette(parsed.replay ?? parsed.resume ?? "");
+    }
+    const programFile = resolve(parsed.file);
+    const program = await loadProgram(programFile);
+    if (parsed.command === "describe") return describe(program);
+    return await run(program, {
+      programFile,
+      args: parsed.args,
+      eventsFd: parsed.eventsFd,
+      record: parsed.record,
+      replay: parsed.replay,
+      resume: parsed.resume,
+      quiet: parsed.quiet,
+    });
+  } catch (error) {
+    process.stderr.write(`[yaag] ${error instanceof Error ? error.message : String(error)}\n`);
+    return parsed.command === "run" && isYaagError(error) && error.code === "ARGS_INVALID" ? 2 : 1;
+  }
+}
+
+function describe(program: OrchestrationProgram): number {
+  const definition = programDefinition(program);
+  process.stdout.write(
+    `${JSON.stringify({
+      name: definition.name ?? null,
+      description: definition.description ?? null,
+      args: definition.args ?? null,
+    })}\n`,
+  );
+  return 0;
+}
+
+async function run(program: OrchestrationProgram, flags: RunFlags): Promise<number> {
+  if (
+    interactiveAvailable({
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr,
+      quiet: flags.quiet,
+    })
+  ) {
+    return await runInteractive({
+      program,
+      flags,
+      events: (present) => eventSink(flags.eventsFd, present),
+    });
+  }
+  return await runPlain(program, flags);
+}
+
+/**
+ * The plain path: sanitized stderr lines, and stdin EOF as a stop.
+ *
+ * The interactive path cannot share this wiring, because `ProcessTerminal`
+ * owns stdin in raw mode, where Ctrl-D arrives as a `\x04` byte and no `end`
+ * event ever fires.
+ */
+async function runPlain(program: OrchestrationProgram, flags: RunFlags): Promise<number> {
+  const presenter = createPlainPresenter(flags.quiet);
+  const stop = new AbortController();
+  const onSignal = (): void => stop.abort();
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  // Stdin EOF is how a parent stops a Run it started (ADR-0008): it takes the
+  // same path as a signal, so every Agent is still reaped and costed. On a TTY
+  // the event simply never fires.
+  process.stdin.on("end", onSignal);
+  process.stdin.resume();
+
+  try {
+    const result = await executeRun(
+      program,
+      executeOptions(flags, eventSink(flags.eventsFd, presenter.present), stop.signal),
+    );
+    const output = formatResult(result);
+    if (output !== null) process.stdout.write(`${output}\n`);
+    return 0;
+  } finally {
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+    process.stdin.off("end", onSignal);
+    process.stdin.pause();
+    presenter.dispose();
+  }
+}
+
+/**
+ * The descriptor, when asked for, gets each event verbatim in the v1 envelope
+ * (ADR-0016). writeSync keeps the framing whole — one write, one line — and
+ * survives the process exiting right after the final event.
+ */
+function eventSink(fd: number | undefined, present: StampedEventSink): StampedEventSink {
+  return (event) => {
+    if (fd !== undefined) writeSync(fd, `${JSON.stringify({ v: 1, ...event })}\n`);
+    present(event);
+  };
+}
+
+/** The program is the module's default export, and nothing else will do. */
+async function loadProgram(path: string): Promise<OrchestrationProgram> {
+  const module: unknown = await import(path);
+  const program =
+    typeof module === "object" && module !== null && "default" in module
+      ? module.default
+      : undefined;
+  if (!isOrchestrationProgram(program)) {
+    throw new Error(`${path}: export defineRun({ run }) as the default export`);
+  }
+  return program;
+}
+
+if (import.meta.main) {
+  const code = await main(process.argv.slice(2));
+  // Exit rather than wait for the loop to drain: a stopped Run may leave the
+  // program's own timers pending, and a stop that does not actually end the
+  // process is not a stop (ADR-0008). Every Agent is already reaped by here.
+  process.exit(code);
+}

package/src/fatal-signal.ts

@@ -0,0 +1,45 @@
+/**
+ * The first-write-wins fatal latch the interactive Run path races and reads.
+ *
+ * A render throw arrives from a callback, so the orchestration must observe it
+ * two ways: `wait` for the live races, and `taken()` for the continuation
+ * boundary a race cannot see — a fatal queued after the raced work resolved can
+ * never win that race, so it is read synchronously instead.
+ */
+import type { TreeAppExit } from "./tree-app.ts";
+
+/** The fatal variant of a `TreeAppExit`. */
+export type FatalExit = Extract<TreeAppExit, { kind: "fatal" }>;
+
+/** A fatal error, awaitable and synchronously readable. */
+export interface FatalSignal {
+  /** Accepts the first error only; later errors are ignored (no re-entry). */
+  raise(error: unknown): void;
+  /** Resolves when a fatal is raised, and never otherwise. For racing. */
+  readonly wait: Promise<FatalExit>;
+  /** The raised fatal, read synchronously. Undefined until one is raised. */
+  taken(): FatalExit | undefined;
+}
+
+/**
+ * Creates one fatal latch.
+ *
+ * `raise` stores the exit before it resolves `wait`, so `taken()` reports the
+ * fatal in the same tick as the call. It never throws and never rejects.
+ */
+export function createFatalSignal(): FatalSignal {
+  let taken: FatalExit | undefined;
+  let deliver: (exit: FatalExit) => void = () => {};
+  const wait = new Promise<FatalExit>((resolve) => {
+    deliver = resolve;
+  });
+  return {
+    raise(error: unknown): void {
+      if (taken !== undefined) return;
+      taken = { kind: "fatal", error };
+      deliver(taken);
+    },
+    wait,
+    taken: () => taken,
+  };
+}

package/src/final-frame.ts

@@ -0,0 +1,71 @@
+/**
+ * The final summary frame the CLI leaves on stderr after the alt-screen closes
+ * (architecture §9).
+ *
+ * Pure over the `TreeState`: it takes its clock and its width, so the same
+ * state always renders the same frame. It replaces the retained last frame the
+ * CLI used to leave on the terminal. It is now on stderr, where the Run result
+ * on stdout stays pipeable.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { TreeState } from "@yaag/tui";
+import { type RunViewResult, renderCompact, resultText, sanitizeTerminalLine } from "@yaag/tui";
+
+/** Everything the frame needs; nothing is read from the process. */
+export interface FinalFrameOptions {
+  readonly now: number;
+  readonly columns: number;
+  /** Header text before the Program name; defaults to `yaag`. */
+  readonly label?: string;
+  /** How the Run ended; absent while it did not end. */
+  readonly result?: RunViewResult;
+}
+
+const RESULT_HEADING = "Result:";
+
+/**
+ * Renders the header line, one line per Agent, and the `Result:` block.
+ *
+ * Every line is sanitized and cut to `columns` terminal display columns — the
+ * `Result:` heading included — so a hostile Program name, Run value, or stderr
+ * tail can emit no escape byte, forge no region, and overflow no narrow
+ * terminal, even when it is wide Unicode.
+ */
+export function finalFrame(state: TreeState, options: FinalFrameOptions): readonly string[] {
+  const width = Math.max(1, options.columns);
+  const compact = renderCompact(state, {
+    now: options.now,
+    width,
+    ...(options.label === undefined ? {} : { label: options.label }),
+  });
+  return [...compact.map((line) => cut(line, width)), ...resultLines(options.result, width)];
+}
+
+function resultLines(result: RunViewResult | undefined, width: number): readonly string[] {
+  if (result === undefined) return [];
+  const body = resultText(result)
+    .split("\n")
+    .map((line) => cut(line, width));
+  return [cut(RESULT_HEADING, width), ...body];
+}
+
+/**
+ * Sanitizes one line, then cuts it by terminal display width.
+ *
+ * A code-unit `slice` would let one CJK or emoji character spill a column past
+ * `width`, so the cut counts what the terminal shows.
+ */
+function cut(line: string, width: number): string {
+  const safe = sanitizeTerminalLine(line);
+  if (visibleWidth(safe) <= width) return safe;
+  let used = 0;
+  let kept = "";
+  for (const character of safe) {
+    const next = used + visibleWidth(character);
+    if (next > width) break;
+    kept += character;
+    used = next;
+  }
+  return kept;
+}

package/src/interactive-run.ts

@@ -0,0 +1,231 @@
+/**
+ * The `yaag run` path that opens the alt-screen Run tree (spec §4).
+ *
+ * `orchestrateInteractiveRun` is process-free: every collaborator arrives as a
+ * parameter, so each exit path — settle, detach, fatal render, signal — is
+ * driven in tests without a TTY. `runInteractive` is the thin production edge
+ * that binds it to the real terminal, the real signals, and the real streams.
+ *
+ * A fatal render error is observed by a latch read immediately before the final
+ * channel write, with no asynchronous yield in between, so a fatal delivered in
+ * a continuation queued after a race latched is still reported.
+ */
+import { executeRun, type OrchestrationProgram, type StampedEventSink } from "@yaag/runtime";
+import type { RunViewResult, TreeState } from "@yaag/tui";
+import { createAltScreen } from "./alt-screen.ts";
+import { createFatalSignal, type FatalExit, type FatalSignal } from "./fatal-signal.ts";
+import { finalFrame } from "./final-frame.ts";
+import { createPlainPresenter } from "./presenter.ts";
+import { errorText, executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
+import { type FinalOutput, startTreeApp, type TreeApp } from "./tree-app.ts";
+
+/** How one Run settled, as both paths report it. */
+type Settlement =
+  | { readonly kind: "fulfilled"; readonly result: string | null }
+  | { readonly kind: "failed"; readonly error: unknown };
+
+/** What the interactive path needs besides the Run's own flags. */
+export interface InteractiveRunOptions {
+  readonly program: OrchestrationProgram;
+  readonly flags: RunFlags;
+  /** Wraps the app's presenter with the fd n writer the CLI already installed. */
+  events(present: StampedEventSink): StampedEventSink;
+}
+
+/** The signal and render-throw handlers the host installs while the app is up. */
+export interface InteractiveHandlers {
+  /** SIGINT: opens the stop prompt, and a second one confirms. */
+  interrupt(): void;
+  /** SIGTERM: aborts the Run without waiting for a keystroke. */
+  terminate(): void;
+  /** A render throw that escaped every `try`: restore, then report. */
+  fatal(error: unknown): void;
+}
+
+/** Everything `orchestrateInteractiveRun` would otherwise read from the process. */
+export interface InteractiveRunDeps {
+  /** Starts the app; `stop` runs the reap ladder for this Run (ADR-0008). */
+  startApp(stop: () => void): TreeApp;
+  /** Starts the Run and resolves with its value. */
+  startRun(events: StampedEventSink, signal: AbortSignal): Promise<unknown>;
+  /** The presenter the plain lines use after the alt-screen closes. */
+  plainPresent: StampedEventSink;
+  /** Width of the final summary frame, in terminal columns. */
+  columns(): number;
+  now(): number;
+  /** Installs the handlers and returns the uninstaller. */
+  installHandlers(handlers: InteractiveHandlers): () => void;
+}
+
+/**
+ * Runs one Orchestration Program under the alt-screen tree and returns the
+ * exit code of the Run.
+ *
+ * The terminal is restored before this resolves or rejects, on every path: the
+ * settle-then-`q` path, a confirmed stop, a detach, and a render throw. A
+ * detach closes the alt-screen and keeps awaiting the Run on the plain lines,
+ * so the process never exits with a Run still running. A fatal render error is
+ * reported only after the terminal is restored and the Run is aborted and
+ * reaped, so no Run is abandoned pending. A fatal accepted at any point while
+ * the handlers are installed is rethrown, never converted into a normal return.
+ */
+export async function orchestrateInteractiveRun(deps: InteractiveRunDeps): Promise<number> {
+  const stop = new AbortController();
+  const app = deps.startApp(() => stop.abort());
+  let present: StampedEventSink = app.present;
+  // A render throw that escaped every `try` becomes one more exit signal the
+  // orchestration races, so it runs the same close → abort → await → emit
+  // ladder as every other path instead of throwing from a stray callback.
+  const signal = createFatalSignal();
+  const uninstall = deps.installHandlers({
+    interrupt: () => app.interrupt(),
+    terminate: () => stop.abort(),
+    fatal: (error) => signal.raise(error),
+  });
+  const running = settle(deps.startRun((event) => present(event), stop.signal));
+
+  try {
+    const early = await Promise.race([running.then(() => undefined), app.exit, signal.wait]);
+    if (early !== undefined) {
+      // The reader left before the Run settled. Close the alt-screen first,
+      // then keep awaiting the Run on the plain lines so it is still reaped and
+      // costed, and only then write the final channels.
+      await app.close();
+      present = deps.plainPresent;
+      // A fatal render must not abandon the Run: abort it and await settlement.
+      // The race carries the settlement back, so the last fatal read below is
+      // not followed by a yield that could drop a late fatal.
+      let fatal = early.kind === "fatal" ? early : undefined;
+      let settled: Settlement;
+      if (fatal !== undefined) {
+        stop.abort();
+        settled = await running;
+      } else {
+        const raced = await raceFatal(running, signal);
+        if (raced.kind === "work") {
+          settled = raced.value;
+        } else {
+          fatal = raced.exit;
+          stop.abort();
+          settled = await running;
+        }
+      }
+      fatal ??= signal.taken();
+      app.emit(finalOutput(deps, app.state, settled));
+      if (fatal !== undefined) throw fatal.error;
+      return code(settled);
+    }
+    const settled = await running;
+    app.settle(viewResult(settled));
+    // The settled view stays interactive until the reader presses `q` (spec §1).
+    const exit = await Promise.race([app.exit, signal.wait]);
+    let fatal = exit.kind === "fatal" ? exit : signal.taken();
+    const closing = app.close();
+    // A fatal raised while `app.close()` is pending must not be converted into a
+    // normal return: the close still completes, then the fatal error is thrown.
+    const raced = await raceFatal(closing, signal);
+    if (raced.kind === "fatal") {
+      fatal ??= raced.exit;
+      await closing;
+    }
+    fatal ??= signal.taken();
+    app.emit(finalOutput(deps, app.state, settled));
+    if (fatal !== undefined) throw fatal.error;
+    return code(settled);
+  } finally {
+    uninstall();
+  }
+}
+
+/** Binds the orchestration to the real terminal, signals, and streams. */
+export async function runInteractive(options: InteractiveRunOptions): Promise<number> {
+  const plain = createPlainPresenter(options.flags.quiet);
+  try {
+    return await orchestrateInteractiveRun({
+      startApp: (stop) =>
+        startTreeApp({
+          tui: createAltScreen(),
+          stop,
+          writeStdout: (text) => process.stdout.write(text),
+          writeStderr: (text) => process.stderr.write(text),
+        }),
+      startRun: (events, signal) =>
+        executeRun(options.program, executeOptions(options.flags, options.events(events), signal)),
+      plainPresent: plain.present,
+      columns: () => process.stderr.columns ?? 80,
+      now: () => Date.now(),
+      installHandlers: installSignals,
+    });
+  } finally {
+    plain.dispose();
+  }
+}
+
+/** Signals and the render-throw net, installed only while the app is up. */
+function installSignals(handlers: InteractiveHandlers): () => void {
+  const onInterrupt = (): void => handlers.interrupt();
+  // SIGTERM means "abort the Run now": it must not open a prompt that waits for
+  // a keystroke. The Run's own reap ladder then ends the process (ADR-0008).
+  const onTerminate = (): void => handlers.terminate();
+  // The TUI renders from process.nextTick, so a render throw escapes every
+  // try/finally; the terminal must still be restored before it is reported.
+  const onFatal = (error: unknown): void => handlers.fatal(error);
+  process.on("SIGINT", onInterrupt);
+  process.on("SIGTERM", onTerminate);
+  process.on("uncaughtException", onFatal);
+  process.on("unhandledRejection", onFatal);
+  return () => {
+    process.off("SIGINT", onInterrupt);
+    process.off("SIGTERM", onTerminate);
+    process.off("uncaughtException", onFatal);
+    process.off("unhandledRejection", onFatal);
+  };
+}
+
+/** Which of the two raced outcomes arrived first, with the work's value. */
+type Raced<T> =
+  | { readonly kind: "work"; readonly value: T }
+  | { readonly kind: "fatal"; readonly exit: FatalExit };
+
+/**
+ * Awaits `work` while the fatal latch stays observable.
+ *
+ * The work's value travels back with the outcome, so a caller that observed a
+ * fatal never awaits `work` a second time before it reports the error.
+ */
+async function raceFatal<T>(work: Promise<T>, signal: FatalSignal): Promise<Raced<T>> {
+  return await Promise.race([
+    work.then((value): Raced<T> => ({ kind: "work", value })),
+    signal.wait.then((exit): Raced<T> => ({ kind: "fatal", exit })),
+  ]);
+}
+
+async function settle(run: Promise<unknown>): Promise<Settlement> {
+  try {
+    return { kind: "fulfilled", result: formatResult(await run) };
+  } catch (error) {
+    return { kind: "failed", error };
+  }
+}
+
+function viewResult(settled: Settlement): RunViewResult {
+  return settled.kind === "fulfilled"
+    ? { kind: "fulfilled", result: settled.result ?? "" }
+    : { kind: "failed", error: errorText(settled.error) };
+}
+
+function code(settled: Settlement): number {
+  return settled.kind === "fulfilled" ? 0 : 1;
+}
+
+/** The pipeable Run result for stdout, and the settled final frame for stderr. */
+function finalOutput(deps: InteractiveRunDeps, state: TreeState, settled: Settlement): FinalOutput {
+  return {
+    result: settled.kind === "fulfilled" ? settled.result : null,
+    frame: finalFrame(state, {
+      now: deps.now(),
+      columns: deps.columns(),
+      result: viewResult(settled),
+    }),
+  };
+}

package/src/presenter.ts

@@ -0,0 +1,31 @@
+/**
+ * The plain stderr presentation of a Run's Lifecycle Events (architecture §9).
+ *
+ * It is the only presenter for a non-TTY stream and for `--quiet`; a full TTY
+ * gets the interactive alt-screen tree instead (`tree-app.ts`).
+ */
+import type { StampedEventSink } from "@yaag/runtime";
+import { type PlainRenderMode, renderEvent } from "./render.ts";
+
+/**
+ * One presentation of the Run in flight, plus the teardown its surface needs.
+ *
+ * Human-readable stderr lines are unversioned; the descriptor, when asked for,
+ * gets each event verbatim in the v1 envelope (ADR-0016).
+ */
+export interface EventPresenter {
+  readonly present: StampedEventSink;
+  readonly dispose: () => void;
+}
+
+/** Builds the sanitized line presenter; `quiet` keeps the minimal line set. */
+export function createPlainPresenter(quiet: boolean): EventPresenter {
+  const mode: PlainRenderMode = quiet ? "quiet" : "rich";
+  return {
+    present: (event) => {
+      const rendered = renderEvent(event, mode);
+      if (rendered !== null) process.stderr.write(`${rendered}\n`);
+    },
+    dispose: () => {},
+  };
+}

package/src/render.ts

@@ -0,0 +1,96 @@
+import type { AgentActivity, LifecycleEventBody, TokenBreakdown } from "@yaag/runtime";
+import { sanitizeTerminalLine } from "@yaag/tui";
+
+export type PlainRenderMode = "rich" | "quiet";
+
+/**
+ * Renders one Lifecycle Event as a human-readable stderr line.
+ *
+ * This format is deliberately not a wire protocol — the extension reads the
+ * event objects on a dedicated fd instead (ADR-0006). Accepts the body type:
+ * the line never shows `at`, so stamped and unstamped events render alike.
+ */
+export function renderEvent(
+  event: LifecycleEventBody,
+  mode: PlainRenderMode = "rich",
+): string | null {
+  const line = renderPlainEvent(event, mode);
+  return line === null ? null : sanitizeTerminalLine(line);
+}
+
+function renderPlainEvent(event: LifecycleEventBody, mode: PlainRenderMode): string | null {
+  if (mode === "quiet" && !minimalEvent(event.type)) return null;
+  switch (event.type) {
+    case "run_start":
+      return `[yaag] run ${event.program}`;
+    case "agent_spawn":
+      return `[${event.agent}] spawned ${event.model} in ${event.cwd}`;
+    case "ask_start":
+      return `[${event.agent}] ask #${event.index + 1}${event.replayed === true ? " (replayed)" : ""}${event.promptGist === "" ? "" : ` — ${event.promptGist}`}`;
+    case "ask_activity":
+      return `[${event.agent}] ${renderActivity(event.activity)}`;
+    case "ask_output":
+    case "agent_usage":
+      return null;
+    case "node_update":
+      return `[${event.agent}] node ${event.path} ${event.state}${event.activityGist === undefined || event.activityGist === "" ? "" : ` \u2014 ${event.activityGist}`}`;
+    case "ask_end": {
+      const gap =
+        event.maxFrameGapMs === undefined ? "" : ` max gap ${seconds(event.maxFrameGapMs)}`;
+      return `[${event.agent}] ask #${event.index + 1} ${event.ok ? "done" : "failed"} ${seconds(event.durationMs)}${gap}`;
+    }
+    case "agent_exit":
+      return `[${event.agent}] exit ${tokens(event.tokens)} ${cost(event.cost)}${event.incomplete ? " (killed mid-ask, cost incomplete)" : ""}`;
+    case "run_end": {
+      const gap = event.worstFrameGapMs > 0 ? ` worst gap ${seconds(event.worstFrameGapMs)}` : "";
+      return `[yaag] ${event.ok ? "done" : "failed"} ${seconds(event.durationMs)} ${cost(event.cost)}${event.incomplete ? "+ (incomplete)" : ""}${gap}`;
+    }
+    default: {
+      const never: never = event;
+      throw new Error(`unhandled lifecycle event: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+function minimalEvent(type: LifecycleEventBody["type"]): boolean {
+  return (
+    type === "run_start" ||
+    type === "agent_spawn" ||
+    type === "ask_start" ||
+    type === "ask_end" ||
+    type === "agent_exit" ||
+    type === "run_end"
+  );
+}
+
+function renderActivity(activity: AgentActivity): string {
+  switch (activity.type) {
+    case "thinking":
+      return "thinking…";
+    case "writing":
+      return "writing…";
+    case "tool":
+      return `${activity.name}${activity.argsGist === "" ? "" : `: ${activity.argsGist}`}`;
+    case "compacting":
+      return "compacting context…";
+    case "retrying":
+      return `retrying ${activity.attempt}/${activity.max}…`;
+    default: {
+      const never: never = activity;
+      throw new Error(`unhandled Agent Activity: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+function seconds(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** The line reports the total only; the breakdown travels on the event (ticket 01). */
+function tokens(value: TokenBreakdown | null): string {
+  return value === null ? "tokens unknown" : `${value.total} tokens`;
+}
+
+function cost(value: number | null): string {
+  return value === null ? "cost unknown" : `$${value.toFixed(4)}`;
+}

package/src/run-invocation.ts

@@ -0,0 +1,48 @@
+/**
+ * One `yaag run` invocation: the flags the command parsed, the `executeRun`
+ * options they build, and how the Run's value reaches stdout.
+ *
+ * Both presentation paths — the plain lines and the alt-screen tree — compose
+ * it, so they cannot drift on artifact flags or on the result format.
+ */
+import type { RunOptions, StampedEventSink } from "@yaag/runtime";
+
+/** Everything `yaag run` parsed for one Run. */
+export interface RunFlags {
+  readonly programFile: string;
+  readonly args: unknown;
+  readonly eventsFd: number | undefined;
+  readonly record: string | undefined;
+  readonly replay: string | undefined;
+  readonly resume: string | undefined;
+  readonly quiet: boolean;
+}
+
+/** Builds the `executeRun` options for these flags, one sink and one signal. */
+export function executeOptions(
+  flags: RunFlags,
+  events: StampedEventSink,
+  signal: AbortSignal,
+): RunOptions {
+  return {
+    events,
+    args: flags.args,
+    programFile: flags.programFile,
+    ...(flags.record === undefined ? {} : { record: flags.record }),
+    ...(flags.replay === undefined ? {} : { replay: flags.replay }),
+    ...(flags.resume === undefined ? {} : { resume: flags.resume }),
+    signal,
+  };
+}
+
+/** The Run's result goes to stdout, so `yaag run p.ts | jq` works (ADR-0006). */
+export function formatResult(result: unknown): string | null {
+  if (result === undefined) return null;
+  if (typeof result === "string") return result;
+  return JSON.stringify(result, null, 2);
+}
+
+/** The message a failed Run reports, on stderr and in the Result region. */
+export function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}