@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/src/tui/workflow-attach-pane.ts

@@ -0,0 +1,285 @@
+/**
+ * WorkflowAttachPane — outer in-place attach shell.
+ *
+ * Wraps a single `pi.ui.custom` overlay popup whose interior swaps
+ * between the orchestrator `GraphView` and a stage-scoped
+ * `StageChatView`. Pressing Enter on a graph node attaches the popup
+ * to that node's chat; Ctrl+D in chat mode swaps back to graph mode
+ * with the same node still focused (see ui/attach-mockup.html).
+ *
+ * The shell never remounts the overlay — it only flips a `mode`
+ * field and re-renders, so the popup stays in pi-tui's overlay layer
+ * across attach/detach cycles. This matches the mockup contract
+ * (`only the popup interior swapped — outer chrome is unchanged`).
+ *
+ * cross-ref:
+ *  - src/tui/overlay-adapter.ts (host mount glue)
+ *  - src/tui/graph-view.ts (graph mode Component)
+ *  - src/tui/stage-chat-view.ts (chat mode Component)
+ *  - src/runs/foreground/stage-control-registry.ts (live handles)
+ */
+
+import type { Component, EditorComponent, EditorTheme, TUI } from "@earendil-works/pi-tui";
+import type { Store } from "../shared/store.js";
+import type { GraphTheme } from "./graph-theme.js";
+import { GraphView } from "./graph-view.js";
+import { StageChatView } from "./stage-chat-view.js";
+import type {
+  StageControlHandle,
+  StageControlRegistry,
+} from "../runs/foreground/stage-control-registry.js";
+
+/**
+ * Surface used to write Pi's footer/status tag while the attach pane is
+ * mounted. Passing `undefined` clears the slot — required on dispose so
+ * the `pi-workflows/<workflow>[/<stage>]` tag does NOT linger in every
+ * subsequent chat message after the overlay is closed.
+ * cross-ref: @earendil-works/pi-coding-agent docs/extensions.md
+ * §Widgets, Status, and Footer (`ctx.ui.setStatus`).
+ */
+export interface AttachUiStatusSurface {
+  setStatus?: (key: string, value: string | undefined) => void;
+}
+
+export interface WorkflowAttachPaneOpts {
+  store: Store;
+  graphTheme: GraphTheme;
+  runId: string | null;
+  /**
+   * Live stage-control registry. The pane resolves stage handles when
+   * the user attaches to a node. Defaults to the singleton registry.
+   */
+  stageControlRegistry?: StageControlRegistry;
+  /**
+   * Optional UI status surface. When present, attaching/detaching
+   * updates the `pi-workflows` status tag with `<workflow>/<stage>`.
+   */
+  uiStatus?: AttachUiStatusSurface;
+  /** Called when the user closes (Escape in graph mode). */
+  onClose: () => void;
+  /** Called when the user requests the host to hide the popup. */
+  onHide?: () => void;
+  /** Called when the user kills the active run (q in graph mode). */
+  onKill?: (runId: string) => void;
+  /** Called when the user resolves a HIL prompt via the graph view. */
+  onPromptResolve?: (runId: string, promptId: string, response: unknown) => void;
+  /** Live pi-tui host objects used by attached stage chat to reuse coding-agent editor UI. */
+  piTui?: TUI;
+  piKeybindings?: unknown;
+  /** Host custom editor factory installed by extensions via ctx.ui.setEditorComponent(). */
+  piEditorFactory?: (tui: TUI, theme: EditorTheme, keybindings: unknown) => EditorComponent;
+  /**
+   * Optional override: pre-select chat mode for a stage on construction.
+   * Used by `/workflow attach <runId> <stageId>` so the popup opens
+   * directly on the node's chat.
+   */
+  initialAttachStageId?: string;
+  /**
+   * Optional accessor returning the current terminal row count. Threaded
+   * into both `GraphView` and `StageChatView` so the overlay renders a
+   * frame that fills the full viewport instead of a fixed 32-row pane.
+   * Returns `undefined` when the host has not surfaced terminal
+   * dimensions; views fall back to their constant row budget.
+   */
+  getViewportRows?: () => number | undefined;
+  /**
+   * Render-tick callback supplied by the overlay host. Forwarded to the
+   * embedded `GraphView` so its 10 FPS animation tick (running-stage
+   * border pulse, duration counter) can request frames without a key
+   * press. The host gates the underlying `tui.requestRender` on overlay
+   * visibility so a hidden pane stays cheap.
+   */
+  requestRender?: () => void;
+}
+
+export type WorkflowAttachPaneMode = "graph" | "stage-chat";
+
+const STATUS_KEY = "pi-workflows";
+
+export class WorkflowAttachPane implements Component {
+  private store: Store;
+  private theme: GraphTheme;
+  private runId: string | null;
+  private registry: StageControlRegistry | undefined;
+  private uiStatus: AttachUiStatusSurface | undefined;
+  private onClose: () => void;
+  private onHide?: () => void;
+  private onKill?: (runId: string) => void;
+  private onPromptResolve?: (runId: string, promptId: string, response: unknown) => void;
+  private getViewportRows?: () => number | undefined;
+  private hostRequestRender?: () => void;
+  private piTui?: TUI;
+  private piKeybindings?: unknown;
+  private piEditorFactory?: (tui: TUI, theme: EditorTheme, keybindings: unknown) => EditorComponent;
+
+  private mode: WorkflowAttachPaneMode = "graph";
+  private graphView: GraphView;
+  private chatView: StageChatView | null = null;
+  /** Stage id the user most recently attached to (used to seed focus). */
+  private lastAttachedStageId: string | null = null;
+
+  constructor(opts: WorkflowAttachPaneOpts) {
+    this.store = opts.store;
+    this.theme = opts.graphTheme;
+    this.runId = opts.runId;
+    this.registry = opts.stageControlRegistry;
+    this.uiStatus = opts.uiStatus;
+    this.onClose = opts.onClose;
+    this.onHide = opts.onHide;
+    this.onKill = opts.onKill;
+    this.onPromptResolve = opts.onPromptResolve;
+    this.getViewportRows = opts.getViewportRows;
+    this.hostRequestRender = opts.requestRender;
+    this.piTui = opts.piTui;
+    this.piKeybindings = opts.piKeybindings;
+    this.piEditorFactory = opts.piEditorFactory;
+
+    this.graphView = this._buildGraphView();
+
+    if (opts.initialAttachStageId !== undefined && this.runId) {
+      this._attachToStage(this.runId, opts.initialAttachStageId);
+    } else {
+      this._setBaseStatus();
+    }
+  }
+
+  private _buildGraphView(initialFocusedStageId?: string): GraphView {
+    return new GraphView({
+      mode: "overlay",
+      runId: this.runId,
+      store: this.store,
+      graphTheme: this.theme,
+      onClose: this.onClose,
+      onHide: this.onHide,
+      onKill: this.onKill,
+      onPromptResolve: this.onPromptResolve,
+      onStageAttach: (runId, stageId) => this._attachToStage(runId, stageId),
+      onDetach: () => {
+        if (this.onHide) this.onHide();
+      },
+      initialFocusedStageId,
+      getViewportRows: this.getViewportRows,
+      // Gate the host render tick on `graph` mode. While the chat view
+      // is attached, the GraphView is hidden behind the chat — firing
+      // pi-tui renders for a frame the user can't see is wasted work.
+      requestRender: () => {
+        if (this.mode !== "graph") return;
+        this.hostRequestRender?.();
+      },
+    });
+  }
+
+  private _resolveRunId(): string | null {
+    if (this.runId) return this.runId;
+    const active = this.store.activeRunId();
+    if (active) {
+      this.runId = active;
+      return active;
+    }
+    return null;
+  }
+
+  private _workflowName(runId: string): string {
+    const snap = this.store.snapshot();
+    const run = snap.runs.find((r) => r.id === runId);
+    return run?.name ?? "workflow";
+  }
+
+  private _stageName(runId: string, stageId: string): string {
+    const snap = this.store.snapshot();
+    const run = snap.runs.find((r) => r.id === runId);
+    return run?.stages.find((s) => s.id === stageId)?.name ?? "stage";
+  }
+
+  private _attachToStage(runId: string, stageId: string): void {
+    this.runId = runId;
+    this.lastAttachedStageId = stageId;
+    const handle: StageControlHandle | undefined = this.registry?.get(runId, stageId);
+    this.chatView?.dispose();
+    this.chatView = new StageChatView({
+      store: this.store,
+      graphTheme: this.theme,
+      runId,
+      stageId,
+      workflowName: this._workflowName(runId),
+      handle,
+      onDetach: () => this._detachFromStage(),
+      onClose: this.onClose,
+      requestRender: this.hostRequestRender,
+      piTui: this.piTui,
+      piKeybindings: this.piKeybindings,
+      piEditorFactory: this.piEditorFactory,
+      getViewportRows: this.getViewportRows,
+    });
+    this.store.recordStageAttached(runId, stageId, true);
+    this.mode = "stage-chat";
+    this._setAttachedStatus(runId, stageId);
+  }
+
+  private _detachFromStage(): void {
+    if (this.chatView && this.runId && this.lastAttachedStageId) {
+      this.store.recordStageAttached(this.runId, this.lastAttachedStageId, false);
+    }
+    this.chatView?.dispose();
+    this.chatView = null;
+    // Rebuild graph view so the focused stage matches the node we
+    // were just attached to (mockup contract: cursor still on
+    // `review-a` after Ctrl+D detach).
+    this.graphView.dispose();
+    this.graphView = this._buildGraphView(this.lastAttachedStageId ?? undefined);
+    this.mode = "graph";
+    this._setBaseStatus();
+  }
+
+  private _setBaseStatus(): void {
+    const runId = this._resolveRunId();
+    const name = runId ? `pi-workflows/${this._workflowName(runId)}` : "pi-workflows";
+    this.uiStatus?.setStatus?.(STATUS_KEY, name);
+  }
+
+  private _setAttachedStatus(runId: string, stageId: string): void {
+    const value = `pi-workflows/${this._workflowName(runId)}/${this._stageName(runId, stageId)}`;
+    this.uiStatus?.setStatus?.(STATUS_KEY, value);
+  }
+
+  render(width: number): string[] {
+    if (this.mode === "stage-chat" && this.chatView) {
+      return this.chatView.render(width);
+    }
+    return this.graphView.render(width);
+  }
+
+  handleInput(data: string): boolean | void {
+    if (this.mode === "stage-chat" && this.chatView) {
+      return this.chatView.handleInput(data);
+    }
+    return this.graphView.handleInput(data);
+  }
+
+  invalidate(): void {
+    if (this.mode === "stage-chat" && this.chatView) this.chatView.invalidate();
+    else this.graphView.invalidate();
+  }
+
+  dispose(): void {
+    this.chatView?.dispose();
+    this.chatView = null;
+    this.graphView.dispose();
+    // Clear the pi-workflows status tag so it doesn't follow the user
+    // back into chat. Without this, every subsequent message header
+    // keeps rendering `pi-workflows/<workflow>` (or `…/<stage>`) until
+    // the next attach replaces the slot.
+    this.uiStatus?.setStatus?.(STATUS_KEY, undefined);
+  }
+
+  // ---- Test seams ----
+  get _mode(): WorkflowAttachPaneMode {
+    return this.mode;
+  }
+  get _lastAttachedStageId(): string | null {
+    return this.lastAttachedStageId;
+  }
+  get _hasChatView(): boolean {
+    return this.chatView !== null;
+  }
+}

package/dist/builtin/workflows/src/tui/workflow-list.ts

@@ -0,0 +1,224 @@
+/**
+ * `/workflow list` catalogue — chat-surface vocabulary from ui/mockups.html §3.
+ *
+ * Visual contract:
+ *  - One full-width `[ WORKFLOWS ]` mauve band (catalogue accent — distinct
+ *    from the blue live-run accent used by `[ BACKGROUND ]` / `[ DISPATCHED ]`).
+ *  - One card per workflow:
+ *      row 1: ▎ stripe · [tag workflow-name]
+ *      row 2: ▎ stripe · muted description
+ *      row 3: ▎ stripe · dim "inputs"  ·  signature
+ *  - Hint rows pointing at `/workflow <name> …` and `/workflow inputs <name>`.
+ *
+ * Truncation policy (ui/mockups.html §4):
+ *  - workflow name in tag end-truncates with `…`;
+ *  - description end-truncates to the row width;
+ *  - input signature renders the first 3 inputs inline, then `+N more`.
+ *  - optional inputs are marked with a trailing `?`.
+ *
+ * cross-ref:
+ *  - ui/mockups.html §3, §4 (long-description policy)
+ *  - src/tui/chat-surface.ts shared primitives
+ *  - src/extension/dispatcher.ts list result with `items` metadata
+ */
+
+import type { GraphTheme } from "./graph-theme.js";
+import {
+  renderFlatBand,
+  renderTaggedCard,
+  renderHintRows,
+  ELLIPSIS,
+  chatWidth,
+} from "./chat-surface.js";
+import { hexToAnsi, RESET } from "./color-utils.js";
+import { visibleWidth, truncateToWidth } from "./text-helpers.js";
+
+const INLINE_INPUT_LIMIT = 3;
+const TAG_NAME_BUDGET = 50;
+
+export interface WorkflowListEntry {
+  /** Normalised workflow name — appears in the surface0 tag. */
+  name: string;
+  /** One-line description. End-truncated to the card body width. */
+  description: string;
+  /** Declared inputs in registry order. */
+  inputs: ReadonlyArray<{ name: string; required?: boolean }>;
+}
+
+export interface RenderWorkflowListOpts {
+  /** Provide for themed Catppuccin chrome; omit for plain ASCII. */
+  theme?: GraphTheme;
+  /** Render width (cells). Defaults to `process.stdout.columns`. */
+  width?: number;
+  /**
+   * When true, append the standard hint pair beneath the catalogue.
+   * Defaults to true.
+   */
+  showHints?: boolean;
+}
+
+/**
+ * Render the workflow catalogue as a `[ WORKFLOWS ]` band followed by
+ * one card per registered workflow.
+ */
+export function renderWorkflowList(
+  entries: readonly WorkflowListEntry[],
+  opts: RenderWorkflowListOpts = {},
+): string {
+  const lines: string[] = [];
+  const subtitle = `${entries.length} registered`;
+  const accent = opts.theme?.mauve;
+
+  lines.push(renderFlatBand({
+    label: "WORKFLOWS",
+    subtitle,
+    accent,
+    theme: opts.theme,
+    width: opts.width,
+  }));
+  // Blank line after the band — mirrors the mockup's `.band { padding-bottom }`
+  // + first `.card { margin-top }` (ui/mockups.html §3). The band reads as
+  // a header, not as the first card's row 0.
+  lines.push("");
+
+  if (entries.length === 0) {
+    // The blank line emitted after the band already provides spacing
+    // before the empty-state line; no extra spacer needed.
+    lines.push(emptyState(opts.theme));
+    return lines.join("\n");
+  }
+
+  // Blank line between cards mirrors the mockup's `.card { margin: 0.25rem 1.1rem }`
+  // top/bottom margin — without it the three workflow rows collapse into one
+  // visual block (see ui/Screenshot 2026-05-12 "Notice how the spacing is off").
+  for (let i = 0; i < entries.length; i++) {
+    if (i > 0) lines.push("");
+    lines.push(renderWorkflowCard(entries[i]!, opts));
+  }
+
+  if (opts.showHints !== false) {
+    lines.push("");
+    lines.push(
+      renderHintRows(
+        [
+          { command: "/workflow <name> …", hint: "run a workflow" },
+          { command: "/workflow inputs <name>", hint: "inspect input schema" },
+        ],
+        opts.theme,
+      ),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function renderWorkflowCard(
+  entry: WorkflowListEntry,
+  opts: RenderWorkflowListOpts,
+): string {
+  const theme = opts.theme;
+  const cardWidth = effectiveWidth(opts.width);
+  const stripPrefix = 3; // "▎  "
+  const interior = Math.max(8, cardWidth - stripPrefix - 1);
+  const accent = theme?.mauve ?? "#000000";
+
+  const tag = truncateToWidth(entry.name, TAG_NAME_BUDGET, ELLIPSIS);
+
+  // Row 2: description (muted)
+  const descBudget = Math.max(8, interior - 2);
+  const description = truncateToWidth(entry.description, descBudget, ELLIPSIS);
+  const row2 = paintMuted(description, theme);
+
+  // Row 3: inputs signature
+  const row3 = inputsSignatureRow(entry.inputs, interior, theme);
+
+  return renderTaggedCard({
+    tag,
+    bodyRows: [row2, row3],
+    accent,
+    width: opts.width,
+    theme,
+  });
+}
+
+function inputsSignatureRow(
+  inputs: ReadonlyArray<{ name: string; required?: boolean }>,
+  interior: number,
+  theme?: GraphTheme,
+): string {
+  const dim = theme ? hexToAnsi(theme.dim) : "";
+  const text = theme ? hexToAnsi(theme.text) : "";
+  const muted = theme ? hexToAnsi(theme.textMuted) : "";
+  const reset = theme ? RESET : "";
+  const sep = theme ? `  ${muted}·${reset}  ` : "  ·  ";
+  const sepPlain = "  ·  ";
+
+  const label = theme ? `${dim}inputs${reset}` : "inputs";
+  const labelW = visibleWidth("inputs");
+
+  if (inputs.length === 0) {
+    const none = theme ? `${dim}(none)${reset}` : "(none)";
+    return `${label}    ${none}`;
+  }
+
+  const visible = inputs.slice(0, INLINE_INPUT_LIMIT);
+  const overflow = inputs.length - visible.length;
+
+  // Build inline segments with optional `?` marker for optional inputs.
+  const segs = visible.map((inp) => {
+    const optional = inp.required !== true;
+    const name = inp.name;
+    if (theme) {
+      return optional
+        ? `${text}${name}${reset}${dim}?${reset}`
+        : `${text}${name}${reset}`;
+    }
+    return optional ? `${name}?` : name;
+  });
+
+  let row = `${label}    ${segs.join(sep)}`;
+  if (overflow > 0) {
+    const moreText = `+${overflow} more`;
+    if (theme) {
+      row += `${sep}${dim}${moreText}${reset}`;
+    } else {
+      row += `${sepPlain}${moreText}`;
+    }
+  }
+
+  // If the row exceeds budget, fall back to inline name list w/o decoration.
+  const inlineLen =
+    labelW +
+    4 +
+    visible.reduce((a, b) => a + b.name.length + (b.required ? 0 : 1), 0) +
+    Math.max(0, visible.length - 1) * sepPlain.length +
+    (overflow > 0 ? sepPlain.length + `+${overflow} more`.length : 0);
+  if (inlineLen > interior) {
+    // Drop to a single ellipsis-truncated plain join.
+    const flat = inputs.map((i) => (i.required ? i.name : `${i.name}?`)).join(", ");
+    const cut = truncateToWidth(flat, Math.max(8, interior - labelW - 4), ELLIPSIS);
+    row = theme
+      ? `${label}    ${text}${cut}${reset}`
+      : `inputs    ${cut}`;
+  }
+  return row;
+}
+
+function paintMuted(text: string, theme?: GraphTheme): string {
+  if (!theme) return text;
+  return `${hexToAnsi(theme.textMuted)}${text}${RESET}`;
+}
+
+function emptyState(theme?: GraphTheme): string {
+  if (!theme) return "  no workflows registered";
+  return `  ${hexToAnsi(theme.dim)}no workflows registered${RESET}`;
+}
+
+/**
+ * Resolve the render width for the catalogue surface. Delegates to the
+ * shared `chatWidth()` helper which already accounts for the chat host's
+ * 2-cell horizontal padding when no explicit width is supplied.
+ */
+function effectiveWidth(width?: number): number {
+  return chatWidth(width);
+}

package/dist/builtin/workflows/src/workflows/define-workflow.ts

@@ -0,0 +1,150 @@
+/**
+ * Workflow definition builder.
+ * Authoring API: defineWorkflow(name).description(...).input(...).run(fn).compile()
+ *
+ * Immutable/chained semantics: every builder method returns a NEW builder
+ * instance; the previous instance is unchanged.
+ *
+ * cross-ref: v0.x packages/atomic-sdk/src/define-workflow.ts
+ */
+
+import type { WorkflowDefinition, WorkflowInputSchema, WorkflowRunFn } from "../shared/types.js";
+import { normalizeWorkflowName } from "./identity.js";
+
+// ---------------------------------------------------------------------------
+// Internal builder state (plain data, never mutated after creation)
+// ---------------------------------------------------------------------------
+
+interface BuilderState<TInputs extends Record<string, unknown>> {
+  readonly name: string;
+  readonly description: string;
+  readonly inputs: Readonly<Record<string, WorkflowInputSchema>>;
+  readonly runFn: WorkflowRunFn<TInputs> | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Public builder interfaces — split so .compile() only appears after .run()
+// ---------------------------------------------------------------------------
+
+/**
+ * Builder returned by defineWorkflow(name) before .run() is called.
+ * Allows chaining .description() and .input() in any order; .run() seals
+ * the run function and returns a CompletedWorkflowBuilder.
+ *
+ * TInputs defaults to Record<string, unknown> so that compile() produces a
+ * definition compatible with the type-erased registry without casts.
+ */
+export interface WorkflowBuilder<TInputs extends Record<string, unknown> = Record<string, unknown>> {
+  /** Set (or replace) the human-readable description. Returns a new builder. */
+  description(text: string): WorkflowBuilder<TInputs>;
+  /**
+   * Declare a typed input.  Returns a new builder whose TInputs grows with
+   * the new key (typed as the schema's default value type).
+   */
+  input<K extends string>(
+    key: K,
+    schema: WorkflowInputSchema,
+  ): WorkflowBuilder<TInputs & Record<K, unknown>>;
+  /** Seal the run function.  Returns a builder on which .compile() is available. */
+  run(fn: WorkflowRunFn<TInputs>): CompletedWorkflowBuilder<TInputs>;
+}
+
+/**
+ * Builder returned after .run() is called.
+ * Still allows chaining .description() and .input(); .compile() is now available.
+ */
+export interface CompletedWorkflowBuilder<TInputs extends Record<string, unknown>> {
+  description(text: string): CompletedWorkflowBuilder<TInputs>;
+  input<K extends string>(
+    key: K,
+    schema: WorkflowInputSchema,
+  ): CompletedWorkflowBuilder<TInputs & Record<K, unknown>>;
+  run(fn: WorkflowRunFn<TInputs>): CompletedWorkflowBuilder<TInputs>;
+  /** Freeze and return the completed WorkflowDefinition. */
+  compile(): WorkflowDefinition<TInputs>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal factory — constructs a builder from immutable state
+// ---------------------------------------------------------------------------
+
+function makeBuilder<TInputs extends Record<string, unknown>>(
+  state: BuilderState<TInputs>,
+): WorkflowBuilder<TInputs> & CompletedWorkflowBuilder<TInputs> {
+  return {
+    description(text: string) {
+      return makeBuilder<TInputs>({ ...state, description: text });
+    },
+
+    input<K extends string>(key: K, schema: WorkflowInputSchema) {
+      return makeBuilder<TInputs & Record<K, unknown>>({
+        ...state,
+        inputs: { ...state.inputs, [key]: schema },
+      } as BuilderState<TInputs & Record<K, unknown>>);
+    },
+
+    run(fn: WorkflowRunFn<TInputs>) {
+      return makeBuilder<TInputs>({ ...state, runFn: fn });
+    },
+
+    compile(): WorkflowDefinition<TInputs> {
+      if (!state.runFn) {
+        throw new Error(
+          `defineWorkflow("${state.name}"): .run(fn) must be called before .compile()`,
+        );
+      }
+
+      const normalizedName = normalizeWorkflowName(state.name);
+
+      // Deep-freeze inputs map first, then the top-level definition.
+      const frozenInputs = Object.freeze({ ...state.inputs });
+
+      const definition: WorkflowDefinition<TInputs> = {
+        __piWorkflow: true,
+        name: state.name,
+        normalizedName,
+        description: state.description,
+        inputs: frozenInputs,
+        run: state.runFn,
+      };
+
+      return Object.freeze(definition) as WorkflowDefinition<TInputs>;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Start building a workflow definition.
+ *
+ * @example
+ * import { defineWorkflow } from "@bastani/workflows";
+ *
+ * export default defineWorkflow("deep-research-codebase")
+ *   .description("Scout → specialists → aggregator")
+ *   .input("prompt", { type: "text", required: true, description: "research question" })
+ *   .input("max_partitions", { type: "number", default: 4 })
+ *   .run(async (ctx) => {
+ *     const scout = ctx.stage("scout");
+ *     const findings = await scout.prompt(`Scout: ${ctx.inputs.prompt}`);
+ *     return { findings };
+ *   })
+ *   .compile();
+ */
+export function defineWorkflow(name: string): WorkflowBuilder {
+  if (!name || typeof name !== "string") {
+    throw new TypeError("defineWorkflow: name must be a non-empty string");
+  }
+
+  const initialState: BuilderState<Record<string, unknown>> = {
+    name,
+    description: "",
+    inputs: {},
+    runFn: undefined,
+  };
+
+  return makeBuilder(initialState);
+}

package/dist/builtin/workflows/src/workflows/identity.ts

@@ -0,0 +1,39 @@
+/**
+ * Workflow name identity helpers.
+ * Provides a canonical normalized form used as the registry key.
+ *
+ * cross-ref: pi-subagents src/agents/identity.ts
+ */
+
+/**
+ * Normalize a workflow name to a canonical key:
+ * - Trim surrounding whitespace
+ * - Lowercase
+ * - Replace one or more whitespace / underscore characters with a single hyphen
+ * - Strip any characters that are not alphanumeric or hyphens
+ *
+ * @example
+ * normalizeWorkflowName("Deep Research Codebase") // "deep-research-codebase"
+ * normalizeWorkflowName("my_workflow")             // "my-workflow"
+ * normalizeWorkflowName("  My Workflow  ")         // "my-workflow"
+ */
+export function normalizeWorkflowName(name: string): string {
+  if (!name || typeof name !== "string") {
+    throw new TypeError("normalizeWorkflowName: name must be a non-empty string");
+  }
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Returns true when two workflow names refer to the same workflow
+ * (i.e. their normalized forms are identical).
+ */
+export function workflowNamesEqual(a: string, b: string): boolean {
+  return normalizeWorkflowName(a) === normalizeWorkflowName(b);
+}