@bastani/atomic 0.7.17 → 0.8.0

package/dist/builtin/workflows/src/shared/persistence-restore.ts

@@ -0,0 +1,257 @@
+/**
+ * Restore: scan session entries for in-flight runs on session_start.
+ * Detects run.start entries without matching run.end and marks crashed or
+ * attempts resume per the `resumeInFlight` config option.
+ *
+ * cross-ref: spec §5.6, §5.13
+ */
+
+import type { Store } from "./store.js";
+import type { RunSnapshot, StageSnapshot } from "./store-types.js";
+
+// ---------------------------------------------------------------------------
+// Config option
+// ---------------------------------------------------------------------------
+
+/** Controls what the extension does with in-flight runs on session_start. */
+export type ResumeInFlight = "ask" | "auto" | "never";
+
+// ---------------------------------------------------------------------------
+// Session entry types
+// ---------------------------------------------------------------------------
+
+/** Minimal shape of a pi session entry as returned by sessionManager.getEntries(). */
+export interface SessionEntry {
+  readonly id: string;
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+}
+
+/** Structural type for pi's sessionManager (optional — degrades gracefully). */
+export interface SessionManager {
+  getEntries?: () => SessionEntry[] | readonly SessionEntry[];
+}
+
+// ---------------------------------------------------------------------------
+// In-flight run descriptor (result of scan)
+// ---------------------------------------------------------------------------
+
+export interface InFlightRun {
+  readonly runId: string;
+  readonly name: string;
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly startTs: number;
+  /** Stage IDs that were started (in order) but may or may not have ended. */
+  readonly stageIds: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Scan logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Scans a list of session entries and returns runs that have a
+ * `workflow.run.start` entry but no matching `workflow.run.end`.
+ *
+ * Pure function — does not mutate anything.
+ */
+export function scanInFlightRuns(entries: readonly SessionEntry[]): InFlightRun[] {
+  const started = new Map<string, { name: string; inputs: Record<string, unknown>; startTs: number; stageIds: string[] }>();
+  const ended = new Set<string>();
+
+  for (const entry of entries) {
+    if (entry.type === "workflow.run.start") {
+      const runId = entry.payload["runId"];
+      const name = entry.payload["name"];
+      const inputs = entry.payload["inputs"];
+      const ts = entry.payload["ts"];
+      if (
+        typeof runId === "string" &&
+        typeof name === "string" &&
+        typeof ts === "number"
+      ) {
+        started.set(runId, {
+          name,
+          inputs: (inputs !== null && typeof inputs === "object" && !Array.isArray(inputs))
+            ? (inputs as Record<string, unknown>)
+            : {},
+          startTs: ts,
+          stageIds: [],
+        });
+      }
+    }
+
+    if (entry.type === "workflow.stage.start") {
+      const runId = entry.payload["runId"];
+      const stageId = entry.payload["stageId"];
+      if (typeof runId === "string" && typeof stageId === "string") {
+        const run = started.get(runId);
+        if (run && !run.stageIds.includes(stageId)) {
+          run.stageIds.push(stageId);
+        }
+      }
+    }
+
+    if (entry.type === "workflow.run.end") {
+      const runId = entry.payload["runId"];
+      if (typeof runId === "string") {
+        ended.add(runId);
+      }
+    }
+  }
+
+  const result: InFlightRun[] = [];
+  for (const [runId, info] of started) {
+    if (!ended.has(runId)) {
+      result.push({
+        runId,
+        name: info.name,
+        inputs: Object.freeze({ ...info.inputs }),
+        startTs: info.startTs,
+        stageIds: Object.freeze([...info.stageIds]),
+      });
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Restore callbacks
+// ---------------------------------------------------------------------------
+
+export interface RestoreCallbacks {
+  /**
+   * Called when a run is detected as crashed (no end entry, session restarted).
+   * Implementations typically mark the run "failed" in the store and optionally
+   * notify the user.
+   */
+  onCrashed?: (run: InFlightRun) => void;
+  /**
+   * Called when a run is being resumed (resumeInFlight === "auto").
+   * Implementations typically re-register the run in the store with status "running".
+   */
+  onResume?: (run: InFlightRun) => void;
+}
+
+// ---------------------------------------------------------------------------
+// restoreOnSessionStart
+// ---------------------------------------------------------------------------
+
+/**
+ * Entry point called on `session_start`.
+ *
+ * Behavior by `config.resumeInFlight`:
+ *   "never" — mark all in-flight runs as crashed (failed) in the store.
+ *   "auto"  — restore in-flight runs to "running" in the store and call onResume.
+ *   "ask"   — same as "never" for store side-effects; onCrashed is called so
+ *             the caller can prompt the user and invoke resume logic separately.
+ *
+ * When `config.persistRuns` is false the function returns early — no session
+ * entries were written, so there is nothing to restore.
+ */
+export function restoreOnSessionStart(
+  sessionManager: SessionManager,
+  config: { resumeInFlight: ResumeInFlight; persistRuns: boolean },
+  store: Store,
+  callbacks: RestoreCallbacks = {},
+): void {
+  if (!config.persistRuns) return;
+
+  const getEntries = sessionManager.getEntries;
+  if (typeof getEntries !== "function") return;
+
+  const entries = getEntries.call(sessionManager);
+  const inFlight = scanInFlightRuns(entries as readonly SessionEntry[]);
+  if (inFlight.length === 0) return;
+
+  for (const run of inFlight) {
+    if (config.resumeInFlight === "auto") {
+      // Re-hydrate the run into the store as "running"
+      const runSnapshot: RunSnapshot = {
+        id: run.runId,
+        name: run.name,
+        inputs: run.inputs,
+        status: "running",
+        stages: _buildStageSnapshots(entries as readonly SessionEntry[], run.runId),
+        startedAt: run.startTs,
+      };
+      store.recordRunStart(runSnapshot);
+      callbacks.onResume?.(run);
+    } else {
+      // "ask" or "never": mark as crashed in store, surface to caller
+      const runSnapshot: RunSnapshot = {
+        id: run.runId,
+        name: run.name,
+        inputs: run.inputs,
+        status: "failed",
+        stages: _buildStageSnapshots(entries as readonly SessionEntry[], run.runId),
+        startedAt: run.startTs,
+        endedAt: Date.now(),
+        error: "Run did not complete — process was interrupted.",
+      };
+      store.recordRunStart(runSnapshot);
+      store.recordRunEnd(run.runId, "failed");
+      callbacks.onCrashed?.(run);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Rebuild partial StageSnapshot array from session entries for a given run. */
+function _buildStageSnapshots(
+  entries: readonly SessionEntry[],
+  runId: string,
+): StageSnapshot[] {
+  const stageMap = new Map<string, StageSnapshot>();
+  const endedStages = new Set<string>();
+
+  for (const entry of entries) {
+    if (entry.payload["runId"] !== runId) continue;
+
+    if (entry.type === "workflow.stage.start") {
+      const stageId = entry.payload["stageId"];
+      const name = entry.payload["name"];
+      const parentIds = entry.payload["parentIds"];
+      const ts = entry.payload["ts"];
+      if (typeof stageId !== "string" || typeof name !== "string") continue;
+      if (!stageMap.has(stageId)) {
+        stageMap.set(stageId, {
+          id: stageId,
+          name,
+          status: "running",
+          parentIds: Array.isArray(parentIds) ? (parentIds as string[]) : [],
+          startedAt: typeof ts === "number" ? ts : undefined,
+          toolEvents: [],
+        });
+      }
+    }
+
+    if (entry.type === "workflow.stage.end") {
+      const stageId = entry.payload["stageId"];
+      const status = entry.payload["status"];
+      const durationMs = entry.payload["durationMs"];
+      const summary = entry.payload["summary"];
+      if (typeof stageId !== "string") continue;
+      endedStages.add(stageId);
+      const snap = stageMap.get(stageId);
+      if (snap) {
+        snap.status = (status === "completed" || status === "failed") ? status : "failed";
+        if (typeof durationMs === "number") snap.durationMs = durationMs;
+        if (typeof summary === "string") snap.result = summary;
+      }
+    }
+  }
+
+  // Mark any stage that didn't get an end entry as "failed" (crashed)
+  for (const [stageId, snap] of stageMap) {
+    if (!endedStages.has(stageId)) {
+      snap.status = "failed";
+      snap.error = "Stage did not complete — process was interrupted.";
+    }
+  }
+
+  return [...stageMap.values()];
+}

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -0,0 +1,145 @@
+/**
+ * Helpers to append workflow lifecycle entries via pi.appendEntry.
+ * cross-ref: spec §5.6 Persistence via session entries
+ *
+ * All functions are pure helpers — they accept a PersistenceAPI and call
+ * through gracefully when the runtime doesn't support the method.
+ */
+
+// ---------------------------------------------------------------------------
+// Structural API type (subset of ExtensionAPI needed here)
+// ---------------------------------------------------------------------------
+
+/** Subset of the pi runtime API required for persistence operations. */
+export interface PersistenceAPI {
+  /** Appends a typed entry to the session transcript. Returns the entry ID. */
+  appendEntry?: (type: string, payload: Record<string, unknown>) => string | undefined;
+  /** Labels an entry for /tree bookmark filtering. */
+  setLabel?: (entryId: string, label: string) => void;
+  /** Appends a synthetic system/assistant message entry. */
+  appendCustomMessageEntry?: (
+    content: string,
+    meta?: Record<string, unknown>,
+  ) => string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Entry payload types (spec §5.6)
+// ---------------------------------------------------------------------------
+
+export interface RunStartPayload {
+  readonly runId: string;
+  readonly name: string;
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly ts: number;
+}
+
+export interface StageStartPayload {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly name: string;
+  readonly parentIds: readonly string[];
+  readonly model?: string;
+  readonly ts: number;
+}
+
+export interface StageProgressPayload {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly kind: string;
+  readonly payload: unknown;
+}
+
+export interface StageEndPayload {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly status: string;
+  readonly durationMs?: number;
+  readonly summary?: string;
+}
+
+export interface RunEndPayload {
+  readonly runId: string;
+  readonly status: string;
+  readonly result?: unknown;
+  readonly ts: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Appends a `workflow.run.start` entry and labels it for /tree filtering.
+ * Label format: `wf:<name>:<short-id>` (first 8 chars of runId).
+ */
+export function appendRunStart(api: PersistenceAPI, payload: RunStartPayload): void {
+  if (typeof api.appendEntry !== "function") return;
+  const entryId = api.appendEntry("workflow.run.start", {
+    runId: payload.runId,
+    name: payload.name,
+    inputs: payload.inputs,
+    ts: payload.ts,
+  });
+  if (entryId && typeof api.setLabel === "function") {
+    const shortId = payload.runId.slice(0, 8);
+    api.setLabel(entryId, `wf:${payload.name}:${shortId}`);
+  }
+}
+
+/** Appends a `workflow.stage.start` entry. */
+export function appendStageStart(api: PersistenceAPI, payload: StageStartPayload): void {
+  if (typeof api.appendEntry !== "function") return;
+  api.appendEntry("workflow.stage.start", {
+    runId: payload.runId,
+    stageId: payload.stageId,
+    name: payload.name,
+    parentIds: [...payload.parentIds],
+    ...(payload.model !== undefined ? { model: payload.model } : {}),
+    ts: payload.ts,
+  });
+}
+
+/** Appends a `workflow.stage.progress` entry (tool calls, message deltas, etc.). */
+export function appendStageProgress(api: PersistenceAPI, payload: StageProgressPayload): void {
+  if (typeof api.appendEntry !== "function") return;
+  api.appendEntry("workflow.stage.progress", {
+    runId: payload.runId,
+    stageId: payload.stageId,
+    kind: payload.kind,
+    payload: payload.payload as Record<string, unknown>,
+  });
+}
+
+/** Appends a `workflow.stage.end` entry. Optionally emits a custom message entry. */
+export function appendStageEnd(
+  api: PersistenceAPI,
+  payload: StageEndPayload,
+  opts?: { emitMessage?: boolean },
+): void {
+  if (typeof api.appendEntry !== "function") return;
+  api.appendEntry("workflow.stage.end", {
+    runId: payload.runId,
+    stageId: payload.stageId,
+    status: payload.status,
+    ...(payload.durationMs !== undefined ? { durationMs: payload.durationMs } : {}),
+    ...(payload.summary !== undefined ? { summary: payload.summary } : {}),
+  });
+  if (opts?.emitMessage === true && payload.summary && typeof api.appendCustomMessageEntry === "function") {
+    api.appendCustomMessageEntry(
+      `Workflow stage ${payload.stageId} completed (${payload.status}): ${payload.summary}`,
+      { runId: payload.runId, stageId: payload.stageId },
+    );
+  }
+}
+
+/** Appends a `workflow.run.end` entry. */
+export function appendRunEnd(api: PersistenceAPI, payload: RunEndPayload): void {
+  if (typeof api.appendEntry !== "function") return;
+  api.appendEntry("workflow.run.end", {
+    runId: payload.runId,
+    status: payload.status,
+    ...(payload.result !== undefined ? { result: payload.result as Record<string, unknown> } : {}),
+    ts: payload.ts,
+  });
+}

package/dist/builtin/workflows/src/shared/render-inputs-schema.ts

@@ -0,0 +1,196 @@
+/**
+ * renderInputsSchema — canonical formatter for a workflow's declared input
+ * schema. Single source of truth for every surface that needs to show input
+ * metadata:
+ *
+ *   - renderResult({ action: "inputs", ... })  (LLM tool path; see render-result.ts)
+ *   - /workflow inputs <name>                  (slash command; extension/index.ts)
+ *   - /workflow <name> --help                  (slash help branch)
+ *   - programmatic workflow validation failures (workflow-runner.ts)
+ *
+ * The renderer has two output modes:
+ *
+ *   - **pretty** (default when a GraphTheme is supplied) — emits ANSI-coloured
+ *     blocks that match the `▎ INPUTS` aesthetic established in
+ *     `src/tui/session-list.ts`. Drawn for any interactive surface where the
+ *     terminal supports colour.
+ *   - **plain**  (used when no theme is supplied)         — emits the
+ *     historical flat indented form. Required for tests that diff exact text
+ *     and for non-TTY consumers (LLM tool results, logfiles, --help in
+ *     redirected output).
+ *
+ * The layout in pretty mode mirrors flora131/atomic's `renderInputsText` so a
+ * dev moving between the atomic CLI and the pi extension feels at home:
+ *
+ *   ▎ INPUTS FOR ralph
+ *
+ *     prompt          text · required
+ *       The high-level task to plan and execute.
+ *
+ *     iterations      number · optional
+ *       Loop budget before bailing out.
+ *       default: 5
+ *
+ *     focus           select · required
+ *       How aggressively to scope the work.
+ *       values: minimal, standard, exhaustive
+ *       default: standard
+ *
+ *   3 inputs · 1 required · pass via key=value or run with no args for picker
+ */
+
+import type { GraphTheme } from "../tui/graph-theme.js";
+import { paint } from "../tui/color-utils.js";
+import type { WorkflowInputEntry } from "../extension/render-result.js";
+
+export interface RenderInputsSchemaOptions {
+  /** When provided, output uses ANSI colours and the `▎ INPUTS` chrome. */
+  theme?: GraphTheme;
+}
+
+/**
+ * Render the schema as a printable block. With `opts.theme` the result is
+ * ANSI-coloured and structured for TUI surfaces; without it the output is
+ * the historical plain-text form, byte-for-byte stable for snapshot tests.
+ */
+export function renderInputsSchema(
+  name: string,
+  inputs: WorkflowInputEntry[],
+  opts: RenderInputsSchemaOptions = {},
+): string {
+  if (inputs.length === 0) return `Workflow "${name}" has no declared inputs.`;
+  if (opts.theme === undefined) return renderPlain(name, inputs);
+  return renderPretty(name, inputs, opts.theme);
+}
+
+// ---------------------------------------------------------------------------
+// Plain renderer — historical shape preserved for the LLM tool path and
+// non-TTY consumers. Stable byte-for-byte so existing snapshots keep passing.
+// ---------------------------------------------------------------------------
+
+function renderPlain(name: string, inputs: WorkflowInputEntry[]): string {
+  const lines = inputs.map((inp) => {
+    const req = inp.required ? " (required)" : "";
+    const def =
+      inp.default !== undefined ? ` [default: ${JSON.stringify(inp.default)}]` : "";
+    const choices =
+      inp.choices && inp.choices.length > 0
+        ? ` {choices: ${inp.choices.join(", ")}}`
+        : "";
+    const desc = inp.description ? ` — ${inp.description}` : "";
+    return `  ${inp.name}: ${inp.type}${req}${def}${choices}${desc}`;
+  });
+  return `Inputs for "${name}":\n${lines.join("\n")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Pretty renderer — ANSI-coloured, themed, matches the session-list aesthetic.
+//
+// Section labels lead with `▎ ` in mauve (the same glyph used across the
+// extension's TUI surfaces) and the field name is rendered bold-bright so
+// the eye scans the form top-to-bottom. The `required` tag is yellow
+// (theme.warning) — yellow draws attention to "you must fill this in"
+// without being alarming the way red would.
+// ---------------------------------------------------------------------------
+
+function renderPretty(
+  name: string,
+  inputs: WorkflowInputEntry[],
+  theme: GraphTheme,
+): string {
+  const out: string[] = [];
+
+  // Section header — mauve indicator bar + bold caps label, matching
+  // session-list.ts. Includes the workflow name so the block is
+  // self-titling when printed inline in a chat surface.
+  out.push("");
+  out.push(
+    `${paint("▎", theme.mauve)} ${paint(
+      `INPUTS FOR ${name.toUpperCase()}`,
+      theme.textMuted,
+      { bold: true },
+    )}`,
+  );
+  out.push("");
+
+  // Compute a stable left column for the name so types/required tags
+  // line up vertically — the form should *look* like a form, not a
+  // ragged paragraph. Cap at 24 chars so a stray long input name
+  // doesn't push everything off the right edge.
+  const nameWidth = Math.min(
+    24,
+    Math.max(...inputs.map((i) => i.name.length)),
+  );
+  const dimDot = paint("  ·  ", theme.dim);
+
+  for (const field of inputs) {
+    const namePad = field.name.padEnd(nameWidth);
+    const tagColour = field.required ? theme.warning : theme.dim;
+    const tagLabel = field.required ? "required" : "optional";
+
+    // Row 1: name · type · required|optional
+    out.push(
+      "  " +
+        paint(namePad, theme.text, { bold: true }) +
+        "  " +
+        paint(field.type, theme.dim) +
+        dimDot +
+        paint(tagLabel, tagColour),
+    );
+
+    // Row 2: description (when present)
+    if (field.description) {
+      out.push("    " + paint(field.description, theme.textMuted));
+    }
+
+    // Row 3: choices for selects — dot-separator style so the values
+    // read as a clear closed set.
+    if (field.choices && field.choices.length > 0) {
+      const joined = field.choices
+        .map((v) => paint(v, theme.text))
+        .join(dimDot);
+      out.push("    " + paint("values: ", theme.dim) + joined);
+    }
+
+    // Row 4: default (when present)
+    if (field.default !== undefined) {
+      out.push(
+        "    " +
+          paint("default: ", theme.dim) +
+          paint(String(field.default), theme.text),
+      );
+    }
+
+    // Row 5: placeholder hint (optional, mostly used by the picker)
+    if (field.placeholder) {
+      out.push(
+        "    " +
+          paint("placeholder: ", theme.dim) +
+          paint(field.placeholder, theme.textMuted),
+      );
+    }
+
+    out.push(""); // spacer between fields
+  }
+
+  // Summary footer — total/required count + the two-path hint that
+  // teaches the slash key=value form and the picker fallback in one line.
+  const required = inputs.filter((i) => i.required).length;
+  const total = inputs.length;
+  const totalLabel = `${total} input${total === 1 ? "" : "s"}`;
+  const reqLabel = `${required} required`;
+  out.push(
+    "  " +
+      paint(totalLabel, theme.dim) +
+      dimDot +
+      paint(reqLabel, theme.dim) +
+      dimDot +
+      paint(
+        `pass via key=value or run \`/workflow ${name}\` with no args for picker`,
+        theme.dim,
+      ),
+  );
+  out.push("");
+
+  return out.join("\n");
+}