@osolmaz/pi-workflows 0.1.0

package/dist/workflows/types.d.ts

@@ -0,0 +1,280 @@
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Context passed to node callbacks (prompt builders, compute/action runners,
+ * validators). `outputs` maps node ids to their accepted outputs; `results`
+ * maps node ids to the full result record of their latest attempt.
+ */
+export type WorkflowNodeContext<TInput = unknown> = {
+    input: TInput;
+    outputs: Record<string, unknown>;
+    results: Record<string, WorkflowNodeResult>;
+    state: WorkflowRunState;
+    /**
+     * Aborted when the node times out or the run is cancelled. Long-running
+     * callbacks should observe it (pass it to fetch/spawn or check
+     * `signal.aborted`) so side effects stop when the engine gives up on the
+     * node.
+     */
+    signal: AbortSignal;
+};
+export type WorkflowNodeCommon = {
+    /** Per-node timeout. Falls back to the engine default (15 minutes). */
+    timeoutMs?: number;
+    /** Short human-readable label shown in the viewer while the node runs. */
+    statusDetail?: string;
+};
+/**
+ * Edges route between nodes. A node has at most one outgoing edge: either a
+ * plain `to` edge or a `switch` edge that routes on a JSON path into the
+ * node's output (`$.field`, `$output.field`) or result (`$result.outcome`).
+ */
+export type WorkflowEdge = {
+    from: string;
+    to: string;
+} | {
+    from: string;
+    switch: {
+        on: string;
+        cases: Record<string, string>;
+    };
+};
+/**
+ * A model-shaped step. The engine sends the prompt into the pi conversation
+ * and the model completes the step by calling the `workflow` tool with a JSON
+ * output. `expectedOutput` is appended to the step contract so the model
+ * knows what shape to submit. `validate` may reject (throw) or normalize the
+ * submitted output; rejections are surfaced to the model so it can retry
+ * within the same step.
+ */
+export type AgentNodeDefinition = WorkflowNodeCommon & {
+    nodeType: "agent";
+    prompt: (context: WorkflowNodeContext) => MaybePromise<string>;
+    expectedOutput?: string;
+    validate?: (output: unknown, context: WorkflowNodeContext) => MaybePromise<unknown>;
+};
+/** A pure local function: shape inputs, route, format, derive values. */
+export type ComputeNodeDefinition = WorkflowNodeCommon & {
+    nodeType: "compute";
+    run: (context: WorkflowNodeContext) => MaybePromise<unknown>;
+};
+/** A deterministic runtime-owned step implemented as a local function. */
+export type FunctionActionNodeDefinition = WorkflowNodeCommon & {
+    nodeType: "action";
+    run: (context: WorkflowNodeContext) => MaybePromise<unknown>;
+};
+export type ShellActionExecution = {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    shell?: boolean | string;
+    allowNonZeroExit?: boolean;
+    timeoutMs?: number;
+    /** Cap on captured stdout/stderr each, default 1,000,000 characters. */
+    maxOutputChars?: number;
+};
+export type ShellActionResult = {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    durationMs: number;
+};
+/** A deterministic runtime-owned step implemented as a shell command. */
+export type ShellActionNodeDefinition = WorkflowNodeCommon & {
+    nodeType: "action";
+    exec: (context: WorkflowNodeContext) => MaybePromise<ShellActionExecution>;
+    parse?: (result: ShellActionResult, context: WorkflowNodeContext) => MaybePromise<unknown>;
+};
+export type ActionNodeDefinition = FunctionActionNodeDefinition | ShellActionNodeDefinition;
+/**
+ * A pause point. The run terminates with status `waiting` so a human (or an
+ * external trigger) can decide how to continue. The optional `run` callback
+ * produces the checkpoint's output before the run pauses.
+ */
+export type CheckpointNodeDefinition = WorkflowNodeCommon & {
+    nodeType: "checkpoint";
+    summary?: string;
+    run?: (context: WorkflowNodeContext) => MaybePromise<unknown>;
+};
+export type WorkflowNodeDefinition = AgentNodeDefinition | ComputeNodeDefinition | ActionNodeDefinition | CheckpointNodeDefinition;
+export type WorkflowPresentationContext = {
+    /** Final persisted state of the workflow run. */
+    state: WorkflowRunState;
+    /** Convenience alias for `state.finalOutput`. */
+    finalOutput: unknown;
+    /** Aborted if a new run starts, the session closes, or prompt generation times out. */
+    signal: AbortSignal;
+};
+export type WorkflowDefinition = {
+    name: string;
+    /** Optional human-readable run title (static or derived from input). */
+    title?: string | ((context: {
+        input: unknown;
+        workflowName: string;
+    }) => MaybePromise<string | undefined>);
+    /**
+     * Optional instructions for a normal assistant response after the run ends.
+     * The Pi extension resolves this only after the final state is persisted;
+     * the engine and run bundle remain presentation-agnostic.
+     */
+    presentationPrompt?: string | ((context: WorkflowPresentationContext) => MaybePromise<string | undefined>);
+    startAt: string;
+    nodes: Record<string, WorkflowNodeDefinition>;
+    edges: WorkflowEdge[];
+    /** Guard against unbounded loops. Defaults to the engine's maxSteps. */
+    maxSteps?: number;
+};
+export type WorkflowNodeOutcome = "ok" | "timed_out" | "failed" | "cancelled";
+export type WorkflowNodeResult = {
+    attemptId: string;
+    nodeId: string;
+    nodeType: WorkflowNodeDefinition["nodeType"];
+    outcome: WorkflowNodeOutcome;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    output?: unknown;
+    error?: string;
+};
+export type WorkflowActionReceipt = {
+    actionType: "shell" | "function";
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    durationMs?: number;
+};
+export type WorkflowStepRecord = {
+    attemptId: string;
+    nodeId: string;
+    nodeType: WorkflowNodeDefinition["nodeType"];
+    outcome: WorkflowNodeOutcome;
+    startedAt: string;
+    finishedAt: string;
+    promptText: string | null;
+    output: unknown;
+    error?: string;
+    action?: WorkflowActionReceipt;
+};
+export type WorkflowRunStatus = "running" | "waiting" | "completed" | "failed" | "timed_out" | "cancelled";
+export type WorkflowRunState = {
+    runId: string;
+    workflowName: string;
+    runTitle?: string;
+    workflowPath?: string;
+    startedAt: string;
+    finishedAt?: string;
+    updatedAt: string;
+    status: WorkflowRunStatus;
+    input: unknown;
+    outputs: Record<string, unknown>;
+    results: Record<string, WorkflowNodeResult>;
+    steps: WorkflowStepRecord[];
+    currentNode?: string;
+    currentAttemptId?: string;
+    currentNodeType?: WorkflowNodeDefinition["nodeType"];
+    currentNodeStartedAt?: string;
+    statusDetail?: string;
+    /** True while the run is held at a step boundary by a pause request. */
+    paused?: boolean;
+    waitingOn?: string;
+    finalOutput?: unknown;
+    error?: string;
+};
+export type WorkflowNodeSnapshot = {
+    nodeType: WorkflowNodeDefinition["nodeType"];
+    timeoutMs?: number;
+    statusDetail?: string;
+    summary?: string;
+    expectedOutput?: string;
+    actionExecution?: "function" | "shell";
+};
+export type WorkflowDefinitionSnapshot = {
+    schema: "pi-workflows.definition-snapshot.v1";
+    name: string;
+    startAt: string;
+    nodes: Record<string, WorkflowNodeSnapshot>;
+    edges: WorkflowEdge[];
+};
+export type WorkflowTraceEvent = {
+    seq: number;
+    at: string;
+    scope: "run" | "node" | "agent" | "action";
+    type: string;
+    runId: string;
+    nodeId?: string;
+    attemptId?: string;
+    payload: Record<string, unknown>;
+};
+export type WorkflowTraceEventDraft = Omit<WorkflowTraceEvent, "seq" | "at" | "runId">;
+export type WorkflowRunManifest = {
+    schema: "pi-workflows.run-bundle.v1";
+    runId: string;
+    workflowName: string;
+    runTitle?: string;
+    workflowPath?: string;
+    startedAt: string;
+    finishedAt?: string;
+    status: WorkflowRunStatus;
+    traceSchema: "pi-workflows.trace-event.v1";
+    paths: {
+        workflow: string;
+        state: string;
+        trace: string;
+    };
+};
+export type WorkflowRunResult = {
+    runDir: string;
+    state: WorkflowRunState;
+};
+/** The step contract handed to the executor alongside the prompt. */
+export type AgentStepContract = {
+    runId: string;
+    workflowName: string;
+    nodeId: string;
+    attemptId: string;
+    expectedOutput?: string;
+};
+export type AgentStepRequest = {
+    contract: AgentStepContract;
+    prompt: string;
+    /**
+     * Validate a submission from the model. Returns the normalized output or an
+     * error message the executor should surface to the model for retry.
+     */
+    accept: (output: unknown) => Promise<{
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+};
+export type AgentStepSubmission = {
+    output: unknown;
+};
+/**
+ * Runs one agent step to completion. Implementations deliver the prompt to
+ * the model and resolve once a submission has been accepted via `accept`.
+ * Must reject with an `AbortError`-like error when `signal` aborts.
+ */
+export interface AgentStepExecutor {
+    runAgentStep(request: AgentStepRequest, signal: AbortSignal): Promise<AgentStepSubmission>;
+}
+export type WorkflowEngineOptions = {
+    executor: AgentStepExecutor;
+    /** Root directory for run bundles. Defaults to `~/.pi/agent/workflows/runs`. */
+    outputRoot?: string;
+    /** Default per-node timeout. Defaults to 15 minutes. */
+    defaultNodeTimeoutMs?: number;
+    /** Guard against unbounded graph loops. Defaults to 100 executed steps. */
+    maxSteps?: number;
+    /** Observer invoked after every persisted trace event. */
+    onEvent?: (event: WorkflowTraceEvent, state: WorkflowRunState) => void;
+};

package/dist/workflows/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/workflows/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflows/types.ts"],"names":[],"mappings":""}

package/docs/development.md

@@ -0,0 +1,130 @@
+# Development guide
+
+This document covers the standards for working on pi-workflows itself. For
+authoring workflows, see [workflows.md](workflows.md).
+
+## Layout and boundaries
+
+```
+src/workflows/   engine core: definitions, graph, engine, store, loader
+src/extension/   pi integration: /workflow command, workflow tool, widget
+src/viewer/      standalone TUI viewer over run bundles
+```
+
+The dependency direction is enforced by `slophammer.yml`. `src/workflows`
+imports nothing outside itself and never imports pi. `src/extension` and
+`src/viewer` may import `src/workflows` and never each other. The viewer
+observes runs purely through the bundle files, so it works from any process.
+
+Within `src/render`, `graph.ts` computes a pure layered layout (ported from
+the acpx replay viewer: labelled switch expansion, DFS back-edge detection,
+longest-path layering, barycenter ordering, virtual pass-through cells for
+long edges), `canvas.ts` is a character grid that merges box-drawing
+characters by connectivity, and `graph-render.ts` turns a run bundle plus a
+replay position into the drawn graph in one of two node styles: `box`
+(bordered nodes, used by the viewer and the in-pi widget) or `line`
+(single-line nodes). The widget windows the boxed graph around the active
+node to stay inside pi's 10-line widget cap; `shift+↑`/`shift+↓` shortcuts
+(registered through pi's `registerShortcut`) scroll that window manually, and
+the scroll resets to follow mode when the run records a new step. `render.ts`
+in `src/viewer`
+composes the full detail view (header, graph, step timeline, step inspector)
+and stays pure so tests can assert on rendered lines.
+
+The renderer is built so that overlaps cannot corrupt the drawing: every
+back edge owns exclusive lane rows and an exclusive gutter column, multiple
+edges leaving one node fan out over separate exit columns, and labels are
+drawn last through `textOverRun`/`textIfEmpty`, which refuse to overwrite
+anything but a plain horizontal run or empty cells. `test/helpers/graph-verify.ts`
+enforces this structurally: it re-parses the rendered characters, checks
+every node box is unbroken, and traces every declared edge through the
+actual box-drawing characters from source box to target arrow.
+`test/graph-verify.test.ts` runs that verifier over 60 seeded random
+workflow shapes at every replay position; if a rendering change breaks a
+line, misplaces an arrow, or lets a label damage an edge, those tests fail
+with the offending drawing in the assertion message.
+
+Inside the engine, the pi-facing seam is the `AgentStepExecutor` interface.
+The extension implements it on top of the live conversation
+(`src/extension/executor.ts`), and tests implement it with a scripted fake
+(`test/helpers.ts`). Anything that would couple the engine to pi belongs on
+the extension side of that seam.
+
+## Toolchain
+
+Node 22+, ESM, TypeScript strict (including `exactOptionalPropertyTypes`).
+Formatting is oxfmt, linting is oxlint with warnings denied, tests are vitest
+with istanbul coverage. The single gate is:
+
+```bash
+npm run check   # format:check + lint + typecheck + build + test:coverage
+```
+
+Coverage thresholds are 85% lines/functions/branches/statements, configured
+in `vitest.config.ts`. The istanbul provider is deliberate. Workflow files are
+loaded through jiti at runtime, and the v8 provider mismapped those modules;
+istanbul instruments through the vitest transform pipeline only.
+
+Slophammer runs in CI (coverage, complexity max 8, DRY max 0 findings,
+dependency boundaries). Run it locally with:
+
+```bash
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+## End-to-end tests
+
+```bash
+npm run test:e2e
+```
+
+The E2E suite (`test/e2e/`) is non-destructive and fully local. It starts a
+mock OpenAI-compatible server (`test/e2e/mock-openai.ts`) whose scripted
+"model" answers each step contract with a `workflow` tool call, then spawns
+the real pi CLI from `devDependencies` in RPC mode with:
+
+- `PI_CODING_AGENT_DIR` pointed at a temp agent dir containing a `models.json`
+  for the mock provider,
+- `PI_WORKFLOWS_RUNS_DIR` pointed at a temp runs dir,
+- the extension loaded from source with `-e src/extension/index.ts`.
+
+It drives `/workflow` over the RPC protocol and asserts on the resulting run
+bundle, then renders the finished run through the viewer CLI. Nothing outside
+the temp directories is touched, and no real model is called.
+
+## Publishing
+
+The npm package is `@osolmaz/pi-workflows`. The first version must be published
+locally because npm cannot configure a trusted publisher until the package
+exists:
+
+```bash
+npm publish --access public
+```
+
+After that first publish, configure npm trusted publishing for the
+`osolmaz/pi-workflows` repository, `.github/workflows/publish.yml`, and the
+`npm` GitHub environment. The workflow does not use a stored npm token.
+
+For later versions:
+
+1. Update `version` in `package.json` and `package-lock.json`, then merge that
+   change into the default branch.
+2. Publish a GitHub Release whose tag is `v<version>`, such as `v0.2.0`.
+3. Wait for the **Publish npm package** workflow to finish and verify the new
+   version on npm.
+
+The workflow rejects mismatched tags, commits outside the default branch, and
+versions already present on npm. It runs the full checks and end-to-end tests
+before `npm publish --provenance`.
+
+## Conventions
+
+- Conventional Commits for commit messages and PR titles.
+- Persisted JSON uses camelCase keys and versioned `schema` identifiers; see
+  [run-bundles.md](run-bundles.md). Breaking a persisted shape means bumping
+  the schema version string.
+- Every exported API of the engine (`src/workflows/index.ts`) is covered by
+  unit tests; new node types or edge semantics need tests in `test/` and a
+  section in [workflows.md](workflows.md).

package/docs/run-bundles.md

@@ -0,0 +1,114 @@
+# Run bundle format
+
+Every workflow run persists to its own directory, called a run bundle. The
+bundle is the contract between the engine and anything that observes runs,
+including the bundled terminal viewer. This document specifies the format so
+other tools can consume it.
+
+## Location and layout
+
+Bundles live under `~/.pi/agent/workflows/runs/` by default. The
+`PI_WORKFLOWS_RUNS_DIR` environment variable overrides the location for both
+the engine and the viewer, which is how the test suite keeps runs inside
+temporary directories.
+
+```
+~/.pi/agent/workflows/runs/
+  20260719T023912Z-autoimplement-3f2a9c1b/
+    manifest.json     # pi-workflows.run-bundle.v1
+    workflow.json     # pi-workflows.definition-snapshot.v1
+    state.json        # full run projection
+    trace.ndjson      # pi-workflows.trace-event.v1, append-only
+```
+
+Run ids are `<UTC timestamp>-<workflow slug>-<8 hex chars>`, so lexical order
+is chronological order.
+
+## Write discipline
+
+Every JSON file in the bundle is written atomically (write to a temp file in
+the same directory, then rename), so a reader never sees a partial document. `trace.ndjson` is append-only, one JSON object
+per line, with writes serialized per file. After a run reaches a terminal
+status (`completed`, `failed`, `timed_out`, `cancelled`, or `waiting`), the
+bundle no longer changes.
+
+A live viewer needs only two behaviors. Treat `state.json` as the current
+projection and re-read it on any file change, and treat `trace.ndjson` as the
+event timeline when history matters.
+
+## manifest.json
+
+Identity and pointers, kept in sync with the state on every snapshot:
+
+```json
+{
+  "schema": "pi-workflows.run-bundle.v1",
+  "runId": "20260719T023912Z-autoimplement-3f2a9c1b",
+  "workflowName": "autoimplement",
+  "runTitle": "autoimplement: fix the flaky test",
+  "workflowPath": "/repo/.pi/workflows/autoimplement.workflow.ts",
+  "startedAt": "2026-07-19T02:39:12.412Z",
+  "finishedAt": "2026-07-19T02:41:03.977Z",
+  "status": "completed",
+  "traceSchema": "pi-workflows.trace-event.v1",
+  "paths": { "workflow": "workflow.json", "state": "state.json", "trace": "trace.ndjson" }
+}
+```
+
+## workflow.json
+
+A serializable snapshot of the graph taken at run start. Functions such as
+prompts and validators are not serialized. Each node keeps only its metadata
+(`nodeType`, `timeoutMs`, `statusDetail`, `expectedOutput`, `summary`,
+`actionExecution`), and edges are copied verbatim. The snapshot is what lets
+the viewer draw all nodes, including ones that have not run yet.
+
+## state.json
+
+The full run projection (`WorkflowRunState` in
+[`src/workflows/types.ts`](../src/workflows/types.ts)). The `status` field is
+one of `running`, `waiting`, `completed`, `failed`, `timed_out`, or
+`cancelled`. While a node is executing, `currentNode`, `currentNodeType`,
+`currentNodeStartedAt`, and `statusDetail` describe it, and they disappear
+when the node finishes. While a pause request holds the run at a step
+boundary, `paused` is `true` (with matching `run_paused`/`run_resumed` trace
+events); it disappears when the run resumes or ends.
+
+Per-node data lives in `outputs` (the accepted output of each finished node,
+where the latest attempt wins on loops) and in `results` (the full result
+record including the outcome and timing). The ordered history is `steps`,
+with one record per node execution that includes the prompt text for agent
+steps and an action receipt with the command, exit code, and duration for
+action steps. When a run pauses at a checkpoint, `waitingOn` names the
+checkpoint node. Terminal runs carry `finalOutput` on success and `error` on
+failure.
+
+## trace.ndjson
+
+One event per line, monotonically sequenced per run:
+
+```json
+{
+  "seq": 3,
+  "at": "2026-07-19T02:39:14.101Z",
+  "scope": "agent",
+  "type": "agent_prompt_sent",
+  "runId": "...",
+  "nodeId": "implement",
+  "attemptId": "...",
+  "payload": { "prompt": "..." }
+}
+```
+
+Event types: `run_started`, `node_started`, `agent_prompt_sent`,
+`node_finished`, `node_failed`, and a terminal `run_<status>`. The `scope`
+field (`run`, `node`, `agent`, `action`) groups them. Consumers should ignore
+unknown event types so new ones can be added within the same schema version.
+
+## Versioning
+
+Each file carries a versioned schema identifier such as
+`pi-workflows.run-bundle.v1`, and the identifier changes only on breaking
+shape changes. Readers should check `manifest.json`'s `schema` field and skip
+bundles they do not understand, which is exactly what the bundled viewer does
+with unreadable directories.