Add supervised workflow scripts for coordinating pi-web sessions

[ashwin-pc]

Summary

Add an experimental workflow feature to pi-web: supervised local scripts that can coordinate normal pi-web sessions through a small SDK/API.

The goal is not to build a full workflow engine, DAG runner, or extension framework yet. The goal is to validate a minimal primitive:

Workflows are ordinary local TypeScript/JavaScript scripts that can spawn, message, wait on, and summarize pi-web sessions, while pi-web supervises the run lifecycle.

Motivation

pi-web is already session-oriented and minimal. For larger tasks, it would be useful to let a script coordinate multiple independent sessions, for example:

• start a security review session
• start a test-gap review session
• wait for both to finish
• start a synthesis session with their findings

This should preserve pi-web's ethos: small, local-first, inspectable, and user-controlled.

Product direction

For the first version, ignore extensions/server-extension architecture.

Build workflows as a small built-in experimental feature, but keep the internal boundary clean enough that it could be extracted into an extension later if pi-web grows a proper server-extension host.

Do not build:

• a generic workflow engine
• DAGs/phases/retry semantics
• a visual workflow builder
• a new extension host
• parent/child session hierarchy as a core abstraction

Do build:

• supervised script runs
• session spawn/send/wait primitives
• durable run state
• append-only audit events
• stdout/stderr logs
• human and agent cancellation
• a small UI to inspect running/completed workflows

Core invariant: always cancellable

Every workflow must be cancellable by both:

1. the human, from the pi-web UI
2. an agent/session, through an explicit workflow API

Cancellation should not rely only on workflow script cooperation. pi-web should supervise the process and enforce cancellation.

Suggested cancellation sequence:

1. mark run as cancellation_requested
2. append an audit event with actor/reason
3. broadcast a runtime/state update
4. signal the workflow process gracefully
5. after a grace period, hard-kill if still running
6. mark run as cancelled
7. preserve logs, events, and any sessions created by the run

Cancelling a workflow should abort active prompts in sessions created by that workflow, but should not delete those sessions. They should remain available for audit/review.

Core invariant: always auditable and viewable

All workflow runs should have durable state and append-only audit logs.

Suggested storage layout:

.pi/web/workflows/runs/<run-id>/run.json
.pi/web/workflows/runs/<run-id>/events.jsonl
.pi/web/workflows/runs/<run-id>/stdout.log
.pi/web/workflows/runs/<run-id>/stderr.log

Example WorkflowRun shape:

type WorkflowRun = {
  id: string;
  name: string;
  scriptPath: string;
  cwd: string;
  status:
    | "starting"
    | "running"
    | "cancellation_requested"
    | "cancelled"
    | "succeeded"
    | "failed";
  startedAt: string;
  updatedAt: string;
  endedAt?: string;
  pid?: number;
  exitCode?: number;
  signal?: string;
  createdBy: {
    actor: "human" | "agent";
    sessionId?: string;
  };
  cancelledBy?: {
    actor: "human" | "agent";
    sessionId?: string;
    reason?: string;
    timestamp: string;
  };
  sessionIds: string[];
  currentStep?: string;
  progress?: {
    completed?: number;
    total?: number;
    label?: string;
  };
  logPath: string;
  eventLogPath: string;
};

Example audit events:

{"type":"workflow_started","runId":"...","actor":"human","timestamp":"..."}
{"type":"step_started","step":"spawn security reviewer","timestamp":"..."}
{"type":"session_spawned","sessionId":"...","name":"security review","timestamp":"..."}
{"type":"session_prompt_sent","sessionId":"...","promptPreview":"Review auth/session risks...","timestamp":"..."}
{"type":"cancellation_requested","actor":"agent","reason":"Branch is stale","timestamp":"..."}
{"type":"process_killed","signal":"SIGTERM","timestamp":"..."}
{"type":"workflow_cancelled","timestamp":"..."}

Minimal server API

Initial endpoints could be:

GET  /api/workflows
GET  /api/workflows/:runId
GET  /api/workflows/:runId/events
GET  /api/workflows/:runId/logs
POST /api/workflows/run
POST /api/workflows/:runId/cancel

Minimal workflow SDK

A workflow script should be able to coordinate normal sessions:

const security = await pi.sessions.spawn({
  name: "security review",
  message: "Review the current branch for security issues only.",
});

const tests = await pi.sessions.spawn({
  name: "test review",
  message: "Review the current branch for missing or weak tests.",
});

await Promise.all([
  pi.sessions.waitForIdle(security.id, { signal: pi.workflow.signal }),
  pi.sessions.waitForIdle(tests.id, { signal: pi.workflow.signal }),
]);

pi.workflow.throwIfCancelled();

await pi.sessions.spawn({
  name: "final synthesis",
  message: "Combine the security and test findings into a concise review.",
});

Suggested SDK surface:

pi.sessions.list();
pi.sessions.spawn({ name, cwd, message });
pi.sessions.send({ sessionId, message, mode });
pi.sessions.waitForIdle(sessionId, { signal });
pi.sessions.abort(sessionId);

pi.workflow.currentRun();
pi.workflow.setStep(label);
pi.workflow.setProgress(progress);
pi.workflow.throwIfCancelled();
pi.workflow.signal;

pi.workflows.list();
pi.workflows.get(runId);
pi.workflows.cancel(runId, { reason });

Minimal UI

Add a small workflow runs panel/drawer:

• list running and recent workflow runs
• show status: starting/running/cancellation requested/cancelled/succeeded/failed
• show current step/progress if provided
• show sessions created by the run
• open stdout/stderr logs
• open event audit log
• cancel button always visible for active runs

UX principle

Running a generated workflow script should require explicit approval. A workflow script is code and can spend tokens, spawn sessions, and potentially drive tools.

Suggested approval copy:

Pi created workflow script:
.pi/web/workflows/<name>.ts

It will:
- start N sessions
- use cwd <path>
- wait for completion
- create a synthesis session

[Run once] [Open script] [Cancel]

Future considerations

• This could become a bundled pi-web extension later, but only after pi-web has multiple features that need a server-extension host.
• Do not introduce server-extension architecture as part of the MVP.
• Keep the workflow service behind a small internal interface so extraction remains possible later.

Example internal boundary:

type WorkflowService = {
  run(input: WorkflowRunInput): Promise<WorkflowRun>;
  cancel(runId: string, reason?: string): Promise<void>;
  get(runId: string): Promise<WorkflowRun>;
  list(): Promise<WorkflowRun[]>;
  events(runId: string): Promise<WorkflowEvent[]>;
};

Acceptance criteria

• A user can run a local workflow script from pi-web.
• A workflow can spawn and message normal pi-web sessions.
• A workflow can wait for sessions to become idle.
• Active workflow runs are visible in the UI at all times.
• Human can cancel any active workflow from the UI.
• Agent/session can request cancellation through an explicit API.
• Cancellation is enforced by the server even if the script ignores it.
• Workflow run state is persisted to disk.
• Workflow audit events are append-only and inspectable.
• stdout/stderr logs are preserved and viewable.
• Cancelling a workflow does not delete sessions it created.
• The implementation does not introduce a generic workflow engine, DAG runner, or server-extension host.

[ashwin-pc]

Update — MVP validated, and the UI design has converged

Spent a session validating the core hypothesis and working through the UX. Summary: the usefulness is proven with zero server changes, and the remaining work is "supervision," not "orchestration." The UI also moved away from a dedicated workflows panel toward an inline, session-born model. Details + examples below.

---

1. MVP result: usefulness is proven, no server changes needed

I wrote a ~120-line throwaway script that coordinates sessions purely through endpoints pi-web already exposes — no SDK, no new code:

SDK verb (this issue)	Existing endpoint it maps to
pi.sessions.spawn	POST /api/sessions/new → POST /api/prompt
pi.sessions.waitForIdle	poll GET /api/sessions → runtime.isRunning
read a result	GET /api/messages?sessionId=… (last assistant text)
pi.sessions.abort	POST /api/abort

Running the headline example (security review + test review in parallel → synthesis) against a live branch produced a genuinely useful, prioritized review — and the test reviewer caught a real bug (a spec referencing a mock harness that doesn't exist). Three real sessions, fan-out/fan-in, all over the existing HTTP API.

Lesson: the only rough edge was waitForIdle semantics (idle "flapping" when reading a session between turns). Everything else just worked, because pi-web is already multi-session. Idle-detection is the part worth getting right — not process supervision or storage.

---

2. Reframe: orchestration (done) vs supervision (to build)

Acceptance criterion	Status	Note
Spawn & message sessions	✅ done	proven by the probe
Wait for sessions to become idle	✅ done	runtime.isRunning poll
Cancelling doesn't delete sessions	✅ done	uses abort, never deletes
No engine / DAG / extension host	✅ done	stays a plain script
Run a workflow from pi-web	🟡 partial	runs from a terminal today
Active runs visible in the UI	❌ left	pi-web can't see the run
Human cancel from the UI	❌ left	only Ctrl-C today
Agent cancel via API	❌ left	no endpoint
Enforced cancel (script ignores it)	❌ left	probe cancel is cooperative
Run state persisted	❌ left	no run.json
Append-only audit	❌ left	no events.jsonl
stdout/stderr preserved & viewable	❌ left	logs go to terminal

The gap in one line: pi-web owns neither the process nor the sessions a run creates. Everything left flows from fixing that.

---

3. What's left to build (server) — unchanged from the original plan

1. WorkflowService spawns the child — spawn("node", ["--import","tsx", script]), exactly like supervisor.ts already spawns the server child. This single move gives pi-web the PID, which unlocks captured logs and enforced kill.
2. Enforced cancellation — SIGTERM → grace → SIGKILL (literally supervisor.ts's stopChild()), plus abort each id in run.sessionIds. The only invariant the probe fundamentally can't satisfy.
3. Run ↔ session association — every spawn goes through pi-web's API, so the server appends the new id to run.sessionIds and stamps the session with workflowRunId. Authoritative, not guessed.
4. Durable state + audit + logs — run.json, events.jsonl, stdout/stderr.log under .pi/web/workflows/runs/<id>/.
5. 6 endpoints — /api/workflows list/get/events/logs/run/cancel, wired into the existing route chain.

Minimal path to "real": items 1–5 are the server core; the UI is additive polish on top.

---

4. UI design — departs from the original "workflows drawer/panel"

After working through it, the original "small workflow runs panel/drawer + always-visible cancel button" felt wrong for pi-web. Workflows are adhoc, disposable, and created during a session for that session's need. So:

• ❌ No new drawer. ❌ No header icon (the header is per-session chrome and already crowded; a workflow isn't scoped to one session). ❌ No status-bar pill (it would collide with the existing connectionStatus/activityStatus).
• ✅ Two surfaces only, both reusing what exists:

(a) Inline run card in the chat — author / approve / run / progress / cancel, in context

The agent authors a workflow inline; it renders as a runnable card (a sibling of the existing tool cards), replacing the modal approval. Running streams in place like a tool card.

┌ branch-review  .pi/web/workflows/branch-review.ts          [ready] ┐
│  // fan-out → wait → synthesize                                    │
│  const sec  = await pi.sessions.spawn("security review", …)        │
│  const test = await pi.sessions.spawn("test review", …)            │
│  await Promise.all([waitForIdle(sec), waitForIdle(test)])          │
│  Starts 3 sessions · cwd ~/oss/pi-web · waits, then synthesizes    │
│  [ ▶ Run once ]  [ Open script ]                                   │
│  ⚠ Runs local code that spends tokens; pi-web supervises it.       │
└────────────────────────────────────────────────────────────────────┘

…after Run:

┌ ⟳ branch-review                                          [running] ┐
│  step: reviewing in parallel        (self-reported)               │
│  ▷ 2 sessions spawned · 1 running · 00:38   (observed)            │
│  [● security review · idle]  [⟳ test review · running]           │
│  sessions appear as the script creates them — no fixed plan       │
│  [ ✕ Cancel run ]  [ logs ]                                       │
└────────────────────────────────────────────────────────────────────┘

(b) Workflows accordion in the existing session drawer — run control only

A single accordion pinned above the cwd session groups. It lists runs (status, step, cancel). It does not re-list sessions. The sessions a run spawns appear once, in their normal cwd group, with a faint ↳ run tag; selecting a run highlights/filters them (reusing the existing color/filter mechanism, without consuming a color slot).

[▾ Workflows]                       1 running
   ⟳ branch-review   reviewing · 2 sessions    ✕   ← selected
   ▸ 3-way audit     succeeded · 3
[▾ pi-web   ~/oss/pi-web]
   • Feature feasibility research                     (originating; agent idle)
   • security review   ↳ branch-review   ✓            ← highlighted (run selected)
   • test review       ↳ branch-review   ⟳
   • Refactor auth guard

This avoids the "same session mentioned twice in one drawer" problem: each session has exactly one home (its cwd group); the accordion is purely run control; the run is the link between them.

---

5. Running-state model: a live log, not a checklist

A workflow is arbitrary, Turing-complete code (loops, conditionals). There is no DAG and no "total," so the server cannot know what's "yet to run." The card must therefore show two clearly separated sources of truth:

• Observed (authoritative, free): the exact set of sessions the run has spawned so far (run.sessionIds) + each one's live runtime. Always accurate, zero cooperation.
• Declared (advisory, optional): the script may call pi.workflow.setStep(label) / setProgress({completed, total}). A real progress bar appears only if the script declares a total.

Loops: no total → spinner + step label + a live counter ("4 spawned, 2 running") + the append-only event log that grows as the loop creates sessions. No fake "N of M," no "remaining." This is also what keeps us out of building a workflow engine.

---

6. Three independent "running" signals — never conflate them

flowchart TD
  H["Human in chat"] -->|Run once| R
  OS["Originating session<br/>agent: IDLE (handed off)"]:::sess -. card renders here .-> R
  R["Workflow run<br/>= supervised process<br/>process: RUNNING"]:::proc
  R -->|spawns + prompts| S1["security review<br/>agent: RUNNING · owned by run"]:::sess
  R -->|spawns + prompts| S2["test review<br/>agent: IDLE · owned by run"]:::sess
  R -.->|loop may spawn more,<br/>appear when created| S3["…unknown until run"]:::future
  classDef proc fill:#1f6feb,stroke:#58a6ff,color:#fff;
  classDef sess fill:#238636,stroke:#3fb950,color:#fff;
  classDef future fill:#8957e5,stroke:#bc8cff,color:#fff;

Loading

Signal	Question	Source	Shown by
Process liveness	Is the workflow child alive?	run.status	the run card / accordion run row
Agent activity	Is a session's agent mid-prompt?	session.runtime.isRunning	the existing per-session spinner
Workflow membership	Which run created this session?	session.workflowRunId ↔ run.sessionIds	a faint ↳ run tag on the session row

Key consequence: launching a workflow does NOT light up the originating session's agent spinner — the agent handed off; the workflow is a separate process. A busy spawned session reads as "agent busy (spinner) because run X created it (tag)."

Interplay rule (avoid two writers): a workflow drives sessions it spawns; it must not prompt the human's active/originating session. MVP: spawn-new only.

---

7. Data-model delta (tiny)

One back-reference is all the UI needs; run.sessionIds was already in the plan.

// pi-web's session view gains:
type SessionView = {
  /* …existing… */
  workflowRunId?: string;   // set when a run spawns this session
};
// WorkflowRun already carries the inverse:
//   run.sessionIds: string[]   // appended as the script spawns each session

That single field powers the ↳ run tag, the select-run highlight/filter, and "abort this run's sessions on cancel."

---

8. Examples

Workflow script (the validated probe shape — SDK is a thin HTTP client)

// .pi/web/workflows/branch-review.ts
const sec = await pi.sessions.spawn({
  name: "security review",
  message: "Review the current branch for SECURITY issues only. Be concise.",
});
const test = await pi.sessions.spawn({
  name: "test review",
  message: "Review the current branch for MISSING or WEAK tests only. Be concise.",
});

pi.workflow.setStep("reviewing in parallel");
await Promise.all([
  pi.sessions.waitForIdle(sec.id, { signal: pi.workflow.signal }),
  pi.sessions.waitForIdle(test.id, { signal: pi.workflow.signal }),
]);

pi.workflow.throwIfCancelled();

await pi.sessions.spawn({
  name: "final synthesis",
  message: `Combine these reviews into one prioritized list:\n\n` +
           `## Security\n${await pi.sessions.lastText(sec.id)}\n\n` +
           `## Tests\n${await pi.sessions.lastText(test.id)}`,
});

run.json (durable state)

{
  "id": "01J…",
  "name": "branch-review",
  "scriptPath": ".pi/web/workflows/branch-review.ts",
  "cwd": "/Users/me/oss/pi-web",
  "status": "running",
  "startedAt": "2026-06-19T03:44:58Z",
  "updatedAt": "2026-06-19T03:45:36Z",
  "pid": 48213,
  "createdBy": { "actor": "agent", "sessionId": "019e…orig" },
  "sessionIds": ["019e…sec", "019e…test"],
  "currentStep": "reviewing in parallel",
  "logPath": ".pi/web/workflows/runs/01J…/stdout.log",
  "eventLogPath": ".pi/web/workflows/runs/01J…/events.jsonl"
}

events.jsonl (append-only audit)

{"type":"workflow_started","actor":"agent","sessionId":"019e…orig","timestamp":"…:44:58Z"}
{"type":"step_started","step":"reviewing in parallel","timestamp":"…:44:58Z"}
{"type":"session_spawned","sessionId":"019e…sec","name":"security review","timestamp":"…:44:58Z"}
{"type":"session_spawned","sessionId":"019e…test","name":"test review","timestamp":"…:44:58Z"}
{"type":"session_idle","sessionId":"019e…sec","timestamp":"…:47:01Z"}
{"type":"cancellation_requested","actor":"human","reason":"wrong branch","timestamp":"…:47:05Z"}
{"type":"process_killed","signal":"SIGTERM","timestamp":"…:47:05Z"}
{"type":"workflow_cancelled","timestamp":"…:47:06Z"}

Server API

GET  /api/workflows                 # list runs
GET  /api/workflows/:runId          # run.json
GET  /api/workflows/:runId/events   # events.jsonl
GET  /api/workflows/:runId/logs     # stdout + stderr
POST /api/workflows/run             # { scriptPath, name?, cwd?, approved:true } -> spawn
POST /api/workflows/:runId/cancel   # { actor:"human"|"agent", reason? }  (enforced)

---

9. Phasing (each independently shippable)

Phase	What	Outcome
1 · Service core	WorkflowService + storage + the 6 routes + SIGTERM/SIGKILL + orphan reconcile on boot	runnable & force-cancellable via curl, no UI
2 · SDK	thin HTTP-client SDK (pi.sessions.*, pi.workflow.*) as a subpath export (mirrors @ashwin-pc/pi-web/extensions)	the example above runs end-to-end
3 · UI	inline run card in chat + Workflows accordion (run-control) + ↳ run tag + workflow_* WS events	visible & cancellable in context
4 · Agent cancel + approval	agent-facing cancel call + inline "Run once" approval	both invariants fully met

---

Open questions to settle before building

1. How does the agent emit the run card? Lean toward a fenced ```pi-workflow block pi-web renders with a Run button (markdown-native, like Mermaid), vs. a workflow tool the agent calls.
2. Where does the script physically live? Default to .pi/web/workflows/<name>.ts (so "Open script" + re-run work), with easy delete — vs. a GC'd temp file for true disposability.
3. Finished runs in the accordion: keep the run (and its ↳ run-tagged sessions) until dismissed, vs. auto-graduate sessions to plain cwd entries on completion.

[ashwin-pc]

Visual mockup of the converged UI

A self-contained HTML mockup (styled with pi-web's real design tokens) of the inline, session-born direction described above — the inline run card, the running/observed states, the Workflows accordion in the existing drawer, and the "two kinds of running" anatomy.

• Gist: https://gist.github.com/ashwin-pc/128cbf67c4c046e2066e64304a2f8cf8
• Live render: https://gistpreview.github.io/?128cbf67c4c046e2066e64304a2f8cf8

It's a single static file (Mermaid loads from CDN as progressive enhancement), so it renders fully in the browser. Frames: (A) author & run in chat, (B) running + done inline, (C) Workflows accordion = run control with sessions listed once in their cwd group, plus a panel answering "how does it know what's done/running?" and "is the session or the workflow running?".