@osolmaz/pi-workflows 0.1.0

package/src/workflows/schema.ts

@@ -0,0 +1,218 @@
+import type {
+  AgentNodeDefinition,
+  ActionNodeDefinition,
+  CheckpointNodeDefinition,
+  ComputeNodeDefinition,
+  FunctionActionNodeDefinition,
+  ShellActionNodeDefinition,
+  WorkflowDefinition,
+  WorkflowEdge,
+  WorkflowNodeDefinition,
+} from "./types.js";
+
+const NODE_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+function fail(message: string): never {
+  throw new Error(`Invalid workflow definition: ${message}`);
+}
+
+function assertRecord(
+  value: unknown,
+  description: string,
+): asserts value is Record<string, unknown> {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    fail(`${description} must be an object`);
+  }
+}
+
+function assertOptionalFunction(value: unknown, description: string): void {
+  if (value !== undefined && typeof value !== "function") {
+    fail(`${description} must be a function when provided`);
+  }
+}
+
+function assertCommonNodeFields(node: WorkflowNodeDefinition, nodeId: string): void {
+  if (
+    node.timeoutMs !== undefined &&
+    (typeof node.timeoutMs !== "number" || !Number.isFinite(node.timeoutMs) || node.timeoutMs <= 0)
+  ) {
+    fail(`node ${nodeId} timeoutMs must be a finite positive number`);
+  }
+  if (node.statusDetail !== undefined && typeof node.statusDetail !== "string") {
+    fail(`node ${nodeId} statusDetail must be a string`);
+  }
+}
+
+export function assertValidAgentNode(node: AgentNodeDefinition, nodeId = "agent"): void {
+  if (typeof node.prompt !== "function") {
+    fail(`node ${nodeId} requires a prompt function`);
+  }
+  if (node.expectedOutput !== undefined && typeof node.expectedOutput !== "string") {
+    fail(`node ${nodeId} expectedOutput must be a string`);
+  }
+  assertOptionalFunction(node.validate, `node ${nodeId} validate`);
+  assertCommonNodeFields(node, nodeId);
+}
+
+export function assertValidComputeNode(node: ComputeNodeDefinition, nodeId = "compute"): void {
+  if (typeof node.run !== "function") {
+    fail(`node ${nodeId} requires a run function`);
+  }
+  assertCommonNodeFields(node, nodeId);
+}
+
+export function assertValidActionNode(node: ActionNodeDefinition, nodeId = "action"): void {
+  // Dispatch discriminates with `"exec" in node`, so validation must use the
+  // same property semantics: a present-but-invalid `exec` is an error even
+  // when a `run` function exists.
+  const hasExec = "exec" in node;
+  const hasRun = "run" in node;
+  if (hasExec === hasRun) {
+    fail(`node ${nodeId} requires exactly one of run or exec`);
+  }
+  if (hasExec) {
+    if (typeof node.exec !== "function") {
+      fail(`node ${nodeId} exec must be a function`);
+    }
+    assertOptionalFunction((node as ShellActionNodeDefinition).parse, `node ${nodeId} parse`);
+  } else if (typeof (node as FunctionActionNodeDefinition).run !== "function") {
+    fail(`node ${nodeId} run must be a function`);
+  }
+  assertCommonNodeFields(node, nodeId);
+}
+
+export function assertValidShellActionNode(
+  node: ShellActionNodeDefinition,
+  nodeId = "shell",
+): void {
+  if (typeof node.exec !== "function") {
+    fail(`node ${nodeId} requires an exec function`);
+  }
+  assertOptionalFunction(node.parse, `node ${nodeId} parse`);
+  assertCommonNodeFields(node, nodeId);
+}
+
+export function assertValidCheckpointNode(
+  node: CheckpointNodeDefinition,
+  nodeId = "checkpoint",
+): void {
+  if (node.summary !== undefined && typeof node.summary !== "string") {
+    fail(`node ${nodeId} summary must be a string`);
+  }
+  assertOptionalFunction(node.run, `node ${nodeId} run`);
+  assertCommonNodeFields(node, nodeId);
+}
+
+function assertValidNode(node: WorkflowNodeDefinition, nodeId: string): void {
+  switch (node.nodeType) {
+    case "agent":
+      assertValidAgentNode(node, nodeId);
+      return;
+    case "compute":
+      assertValidComputeNode(node, nodeId);
+      return;
+    case "action":
+      assertValidActionNode(node, nodeId);
+      return;
+    case "checkpoint":
+      assertValidCheckpointNode(node, nodeId);
+      return;
+    default:
+      fail(
+        `node ${nodeId} has unknown nodeType ${String((node as { nodeType?: unknown }).nodeType)}`,
+      );
+  }
+}
+
+function assertValidEdgeShape(edge: WorkflowEdge, index: number): void {
+  assertRecord(edge, `edge ${index}`);
+  if (typeof edge.from !== "string" || edge.from.length === 0) {
+    fail(`edge ${index} requires a from node id`);
+  }
+  if ("to" in edge) {
+    if (typeof edge.to !== "string" || edge.to.length === 0) {
+      fail(`edge ${index} requires a to node id`);
+    }
+    return;
+  }
+  assertRecord(edge.switch, `edge ${index} switch`);
+  if (typeof edge.switch.on !== "string" || edge.switch.on.length === 0) {
+    fail(`edge ${index} switch.on must be a JSON path string`);
+  }
+  // Routing only understands these prefixes; rejecting others here prevents
+  // the source node from executing its side effects before a routing error.
+  const on = edge.switch.on;
+  if (!on.startsWith("$.") && !on.startsWith("$output.") && !on.startsWith("$result.")) {
+    fail(`edge ${index} switch.on must start with "$.", "$output.", or "$result."`);
+  }
+  assertRecord(edge.switch.cases, `edge ${index} switch.cases`);
+  if (Object.keys(edge.switch.cases).length === 0) {
+    fail(`edge ${index} switch.cases must not be empty`);
+  }
+  for (const [caseKey, target] of Object.entries(edge.switch.cases)) {
+    if (typeof target !== "string" || target.length === 0) {
+      fail(`edge ${index} switch case ${JSON.stringify(caseKey)} must map to a node id`);
+    }
+  }
+}
+
+/**
+ * Names claimed by `/workflow` subcommands; a workflow with one of these
+ * names could never be started because the keyword wins the argument slot.
+ */
+const RESERVED_WORKFLOW_NAMES = new Set(["cancel", "list", "pause", "resume"]);
+
+export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinition): void {
+  assertRecord(definition, "workflow");
+  if (typeof definition.name !== "string" || definition.name.length === 0) {
+    fail("workflow requires a name");
+  }
+  if (RESERVED_WORKFLOW_NAMES.has(definition.name)) {
+    fail(`workflow name ${JSON.stringify(definition.name)} is reserved for /workflow subcommands`);
+  }
+  if (
+    definition.title !== undefined &&
+    typeof definition.title !== "string" &&
+    typeof definition.title !== "function"
+  ) {
+    fail("workflow title must be a string or function");
+  }
+  if (
+    definition.presentationPrompt !== undefined &&
+    typeof definition.presentationPrompt !== "string" &&
+    typeof definition.presentationPrompt !== "function"
+  ) {
+    fail("workflow presentationPrompt must be a string or function");
+  }
+  if (typeof definition.startAt !== "string" || definition.startAt.length === 0) {
+    fail("workflow requires startAt");
+  }
+  if (
+    definition.maxSteps !== undefined &&
+    (typeof definition.maxSteps !== "number" ||
+      !Number.isInteger(definition.maxSteps) ||
+      definition.maxSteps <= 0)
+  ) {
+    fail("workflow maxSteps must be a positive integer");
+  }
+  assertRecord(definition.nodes, "workflow nodes");
+  if (Object.keys(definition.nodes).length === 0) {
+    fail("workflow requires at least one node");
+  }
+  for (const [nodeId, node] of Object.entries(definition.nodes)) {
+    if (!NODE_ID_PATTERN.test(nodeId)) {
+      fail(`node id ${JSON.stringify(nodeId)} must match ${NODE_ID_PATTERN.source}`);
+    }
+    // Ids like __proto__ or toString would collide with Object prototype
+    // members in the plain-object maps used for outputs and results.
+    if (nodeId in Object.prototype) {
+      fail(`node id ${JSON.stringify(nodeId)} shadows an Object prototype member`);
+    }
+    assertRecord(node, `node ${nodeId}`);
+    assertValidNode(node, nodeId);
+  }
+  if (!Array.isArray(definition.edges)) {
+    fail("workflow edges must be an array");
+  }
+  definition.edges.forEach(assertValidEdgeShape);
+}

package/src/workflows/shell.ts

@@ -0,0 +1,199 @@
+import { spawn } from "node:child_process";
+import { CancelledError, TimeoutError } from "./errors.js";
+import type { ShellActionExecution, ShellActionResult } from "./types.js";
+
+/** Default cap on captured stdout/stderr, each. */
+const DEFAULT_MAX_OUTPUT_CHARS = 1_000_000;
+const TRUNCATION_MARKER = "\n…[output truncated]";
+
+const SHELL_RESULT = Symbol.for("pi-workflows.shell-result");
+
+/**
+ * Retrieve the shell result attached to an error thrown by
+ * {@link runShellAction}, so callers can persist the action receipt even when
+ * the command failed.
+ */
+export function shellResultFromError(error: unknown): ShellActionResult | null {
+  if (error instanceof Error) {
+    const attached = (error as Error & { [SHELL_RESULT]?: ShellActionResult })[SHELL_RESULT];
+    return attached ?? null;
+  }
+  return null;
+}
+
+export function renderShellCommand(command: string, args: string[]): string {
+  const renderedArgs = args.map((arg) => JSON.stringify(arg)).join(" ");
+  return renderedArgs.length > 0 ? `${command} ${renderedArgs}` : command;
+}
+
+function shellFailure(
+  spec: ShellActionExecution,
+  args: string[],
+  result: ShellActionResult,
+  killedBy: "timeout" | "abort" | null,
+): Error | undefined {
+  if (killedBy === "timeout") {
+    return new TimeoutError(spec.timeoutMs ?? 0);
+  }
+  if (killedBy === "abort") {
+    return new CancelledError();
+  }
+  if (((result.exitCode ?? 0) !== 0 || result.signal != null) && spec.allowNonZeroExit !== true) {
+    const status = result.signal ? `signal ${result.signal}` : `exit ${String(result.exitCode)}`;
+    const details = result.stderr.length > 0 ? `\n${result.stderr.trim()}` : "";
+    return new Error(
+      `Shell action failed (${renderShellCommand(spec.command, args)}): ${status}${details}`,
+    );
+  }
+  return undefined;
+}
+
+export async function runShellAction(
+  spec: ShellActionExecution,
+  signal?: AbortSignal,
+): Promise<ShellActionResult> {
+  // The node may have been cancelled while an async `exec` callback resolved;
+  // never start side effects for an already-abandoned attempt.
+  if (signal?.aborted) {
+    throw new CancelledError();
+  }
+  const cwd = spec.cwd ?? process.cwd();
+  const args = spec.args ?? [];
+  const startMs = Date.now();
+  // POSIX: run in its own process group so timeout/abort can kill the whole
+  // tree, including descendants that inherited the stdio pipes.
+  const useProcessGroup = process.platform !== "win32";
+  const child = spawn(spec.command, args, {
+    cwd,
+    env: { ...process.env, ...spec.env },
+    shell: spec.shell,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+    detached: useProcessGroup,
+  });
+
+  let stdout = "";
+  let stderr = "";
+  let killedBy: "timeout" | "abort" | null = null;
+  let timeout: NodeJS.Timeout | undefined;
+
+  // Cap retained output so a verbose or unending command cannot exhaust
+  // memory before its timeout fires.
+  const maxOutputChars = spec.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+  const appendCapped = (current: string, chunk: string): string => {
+    if (current.endsWith(TRUNCATION_MARKER)) {
+      return current;
+    }
+    const room = maxOutputChars - current.length;
+    if (chunk.length <= room) {
+      return current + chunk;
+    }
+    return current + chunk.slice(0, Math.max(0, room)) + TRUNCATION_MARKER;
+  };
+
+  const signalTree = (killSignal: NodeJS.Signals) => {
+    if (useProcessGroup && child.pid !== undefined) {
+      try {
+        process.kill(-child.pid, killSignal);
+        return;
+      } catch {
+        // Group already gone; fall back to the direct child.
+      }
+    }
+    child.kill(killSignal);
+  };
+
+  let killEscalation: NodeJS.Timeout | undefined;
+  const kill = (reason: "timeout" | "abort") => {
+    killedBy ??= reason;
+    signalTree("SIGTERM");
+    killEscalation ??= setTimeout(() => {
+      signalTree("SIGKILL");
+    }, 1_000);
+    killEscalation.unref();
+  };
+  const onAbort = () => kill("abort");
+
+  const finish = new Promise<ShellActionResult>((resolve, reject) => {
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout = appendCapped(stdout, chunk);
+    });
+    child.stderr.on("data", (chunk: string) => {
+      stderr = appendCapped(stderr, chunk);
+    });
+
+    child.once("error", (error) => {
+      // Spawn failures (missing executable, EACCES) still get a receipt so
+      // failed actions remain auditable.
+      const result: ShellActionResult = {
+        command: spec.command,
+        args,
+        cwd,
+        stdout,
+        stderr,
+        exitCode: null,
+        signal: null,
+        durationMs: Date.now() - startMs,
+      };
+      (error as Error & { [SHELL_RESULT]?: ShellActionResult })[SHELL_RESULT] = result;
+      reject(error);
+    });
+    // `close` (unlike `exit`) fires only after stdio has fully closed, so
+    // captured output is never truncated.
+    child.once("close", (exitCode, signalName) => {
+      const result: ShellActionResult = {
+        command: spec.command,
+        args,
+        cwd,
+        stdout,
+        stderr,
+        exitCode,
+        signal: signalName,
+        durationMs: Date.now() - startMs,
+      };
+      const error = shellFailure(spec, args, result, killedBy);
+      if (error) {
+        // Attach the result so callers can persist the action receipt.
+        (error as Error & { [SHELL_RESULT]?: ShellActionResult })[SHELL_RESULT] = result;
+        reject(error);
+        return;
+      }
+      resolve(result);
+    });
+  });
+
+  // A child that exits without consuming stdin emits EPIPE; without a
+  // listener that would crash the whole process instead of just this action.
+  child.stdin.on("error", () => {});
+  if (spec.stdin != null) {
+    child.stdin.write(spec.stdin);
+  }
+  child.stdin.end();
+
+  if (spec.timeoutMs != null && spec.timeoutMs > 0) {
+    timeout = setTimeout(() => kill("timeout"), spec.timeoutMs);
+  }
+  if (signal) {
+    if (signal.aborted) {
+      onAbort();
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+
+  try {
+    return await finish;
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    if (killEscalation) {
+      // The group pid may be reused after the child exits; never let the
+      // delayed SIGKILL fire once the command has fully closed.
+      clearTimeout(killEscalation);
+    }
+    signal?.removeEventListener("abort", onAbort);
+  }
+}

package/src/workflows/store.ts

@@ -0,0 +1,234 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type {
+  WorkflowDefinition,
+  WorkflowDefinitionSnapshot,
+  WorkflowNodeDefinition,
+  WorkflowNodeSnapshot,
+  WorkflowRunManifest,
+  WorkflowRunState,
+  WorkflowTraceEvent,
+  WorkflowTraceEventDraft,
+} from "./types.js";
+
+export const RUN_BUNDLE_SCHEMA = "pi-workflows.run-bundle.v1" as const;
+export const TRACE_EVENT_SCHEMA = "pi-workflows.trace-event.v1" as const;
+export const DEFINITION_SNAPSHOT_SCHEMA = "pi-workflows.definition-snapshot.v1" as const;
+
+const MANIFEST_PATH = "manifest.json";
+const WORKFLOW_SNAPSHOT_PATH = "workflow.json";
+const STATE_PATH = "state.json";
+const TRACE_PATH = "trace.ndjson";
+
+/** Runs directory: `$PI_WORKFLOWS_RUNS_DIR` or `~/.pi/agent/workflows/runs`. */
+export function workflowRunsBaseDir(homeDir: string = os.homedir()): string {
+  const override = process.env.PI_WORKFLOWS_RUNS_DIR;
+  if (override !== undefined && override.length > 0) {
+    return override;
+  }
+  return path.join(homeDir, ".pi", "agent", "workflows", "runs");
+}
+
+export function createRunId(workflowName: string, now: Date = new Date()): string {
+  const stamp = now
+    .toISOString()
+    .replaceAll(/[-:]/g, "")
+    .replace(/\.\d+Z$/, "Z");
+  const slug = workflowName
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/(^-|-$)/g, "")
+    .slice(0, 40);
+  return `${stamp}-${slug || "workflow"}-${randomUUID().slice(0, 8)}`;
+}
+
+/**
+ * Persists run bundles. A bundle directory contains `manifest.json`,
+ * `workflow.json` (definition snapshot), `state.json` (full run projection,
+ * atomically replaced), and `trace.ndjson` (append-only event log).
+ */
+export class WorkflowRunStore {
+  readonly outputRoot: string;
+  private readonly traceSeqByRun = new Map<string, number>();
+  private readonly appendChainByPath = new Map<string, Promise<void>>();
+
+  constructor(outputRoot: string = workflowRunsBaseDir()) {
+    this.outputRoot = outputRoot;
+  }
+
+  runDirFor(runId: string): string {
+    return path.join(this.outputRoot, runId);
+  }
+
+  async initializeRunBundle(
+    workflow: WorkflowDefinition,
+    state: WorkflowRunState,
+  ): Promise<string> {
+    const runDir = this.runDirFor(state.runId);
+    await fs.mkdir(runDir, { recursive: true });
+    this.traceSeqByRun.set(runDir, 0);
+
+    await writeJsonAtomic(
+      path.join(runDir, WORKFLOW_SNAPSHOT_PATH),
+      createDefinitionSnapshot(workflow),
+    );
+    await writeJsonAtomic(path.join(runDir, MANIFEST_PATH), createManifest(state));
+    await writeJsonAtomic(path.join(runDir, STATE_PATH), state);
+    await this.appendJsonLine(path.join(runDir, TRACE_PATH), null);
+
+    return runDir;
+  }
+
+  async writeSnapshot(
+    runDir: string,
+    state: WorkflowRunState,
+    event: WorkflowTraceEventDraft,
+  ): Promise<WorkflowTraceEvent> {
+    state.updatedAt = new Date().toISOString();
+    await writeJsonAtomic(path.join(runDir, STATE_PATH), state);
+    await writeJsonAtomic(path.join(runDir, MANIFEST_PATH), createManifest(state));
+    return await this.appendTrace(runDir, state, event);
+  }
+
+  async appendTrace(
+    runDir: string,
+    state: WorkflowRunState,
+    event: WorkflowTraceEventDraft,
+  ): Promise<WorkflowTraceEvent> {
+    const traceEvent: WorkflowTraceEvent = {
+      seq: this.nextTraceSeq(runDir),
+      at: new Date().toISOString(),
+      runId: state.runId,
+      ...event,
+    };
+    await this.appendJsonLine(path.join(runDir, TRACE_PATH), traceEvent);
+    return traceEvent;
+  }
+
+  private nextTraceSeq(runDir: string): number {
+    const next = (this.traceSeqByRun.get(runDir) ?? 0) + 1;
+    this.traceSeqByRun.set(runDir, next);
+    return next;
+  }
+
+  private async appendJsonLine(filePath: string, value: unknown): Promise<void> {
+    const prior = this.appendChainByPath.get(filePath) ?? Promise.resolve();
+    const nextWrite = prior.then(async () => {
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.appendFile(filePath, value === null ? "" : `${JSON.stringify(value)}\n`, "utf8");
+    });
+    const tracked = nextWrite.finally(() => {
+      if (this.appendChainByPath.get(filePath) === tracked) {
+        this.appendChainByPath.delete(filePath);
+      }
+    });
+    this.appendChainByPath.set(filePath, tracked);
+    await tracked;
+  }
+}
+
+export type LoadedRunBundle = {
+  runDir: string;
+  manifest: WorkflowRunManifest;
+  state: WorkflowRunState;
+  snapshot: WorkflowDefinitionSnapshot | null;
+};
+
+/** Read a run bundle from disk. Returns null when the bundle is unreadable. */
+export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | null> {
+  const manifest = await readJsonFile<WorkflowRunManifest>(path.join(runDir, MANIFEST_PATH));
+  const state = await readJsonFile<WorkflowRunState>(path.join(runDir, STATE_PATH));
+  if (!manifest || !state || manifest.schema !== RUN_BUNDLE_SCHEMA) {
+    return null;
+  }
+  const snapshot = await readJsonFile<WorkflowDefinitionSnapshot>(
+    path.join(runDir, WORKFLOW_SNAPSHOT_PATH),
+  );
+  return { runDir, manifest, state, snapshot };
+}
+
+/** List run bundles under `outputRoot`, most recently started first. */
+export async function listRunBundles(outputRoot: string): Promise<LoadedRunBundle[]> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(outputRoot);
+  } catch {
+    return [];
+  }
+  const bundles: LoadedRunBundle[] = [];
+  for (const entry of entries) {
+    const bundle = await readRunBundle(path.join(outputRoot, entry));
+    if (bundle) {
+      bundles.push(bundle);
+    }
+  }
+  bundles.sort((a, b) => b.state.startedAt.localeCompare(a.state.startedAt));
+  return bundles;
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+function createManifest(state: WorkflowRunState): WorkflowRunManifest {
+  return {
+    schema: RUN_BUNDLE_SCHEMA,
+    runId: state.runId,
+    workflowName: state.workflowName,
+    ...(state.runTitle !== undefined ? { runTitle: state.runTitle } : {}),
+    ...(state.workflowPath !== undefined ? { workflowPath: state.workflowPath } : {}),
+    startedAt: state.startedAt,
+    ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),
+    status: state.status,
+    traceSchema: TRACE_EVENT_SCHEMA,
+    paths: {
+      workflow: WORKFLOW_SNAPSHOT_PATH,
+      state: STATE_PATH,
+      trace: TRACE_PATH,
+    },
+  };
+}
+
+export function createDefinitionSnapshot(workflow: WorkflowDefinition): WorkflowDefinitionSnapshot {
+  return {
+    schema: DEFINITION_SNAPSHOT_SCHEMA,
+    name: workflow.name,
+    startAt: workflow.startAt,
+    nodes: Object.fromEntries(
+      Object.entries(workflow.nodes).map(([nodeId, node]) => [nodeId, snapshotNode(node)]),
+    ),
+    edges: structuredClone(workflow.edges),
+  };
+}
+
+function snapshotNode(node: WorkflowNodeDefinition): WorkflowNodeSnapshot {
+  const common: WorkflowNodeSnapshot = {
+    nodeType: node.nodeType,
+    ...(node.timeoutMs !== undefined ? { timeoutMs: node.timeoutMs } : {}),
+    ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
+  };
+  if (node.nodeType === "agent" && node.expectedOutput !== undefined) {
+    common.expectedOutput = node.expectedOutput;
+  }
+  if (node.nodeType === "checkpoint" && node.summary !== undefined) {
+    common.summary = node.summary;
+  }
+  if (node.nodeType === "action") {
+    common.actionExecution = "exec" in node ? "shell" : "function";
+  }
+  return common;
+}
+
+async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await fs.rename(tempPath, filePath);
+}

package/src/workflows/text.ts

@@ -0,0 +1,34 @@
+/** Remove ANSI escape sequences (CSI style) from a string. */
+export function stripAnsi(text: string): string {
+  let result = "";
+  let index = 0;
+  while (index < text.length) {
+    if (text[index] === "\u001b" && text[index + 1] === "[") {
+      index += 2;
+      while (index < text.length && !/[A-Za-z]/.test(text[index] as string)) {
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+    result += text[index];
+    index += 1;
+  }
+  return result;
+}
+
+/**
+ * Remove ANSI escapes and control characters from untrusted text (model
+ * outputs, errors, titles) so rendering it cannot alter terminal state. Line
+ * breaks and tabs collapse to single spaces because callers interpolate the
+ * result into single terminal lines, where a stray newline would break
+ * viewport math and allow fake rows.
+ */
+export function sanitizeText(text: string): string {
+  return (
+    stripAnsi(text)
+      .replaceAll(/[\t\n\r]+/g, " ")
+      // eslint-disable-next-line no-control-regex
+      .replaceAll(/[\u0000-\u001f\u007f]/g, "")
+  );
+}