stageflow 0.1.0 → 0.3.0

package/README.md

@@ -1,43 +1,216 @@
-# Stageflow
+# <img src="ui/public/stageflow-icon.svg" alt="" width="44" height="44" valign="middle"> Stageflow
 
-CLI pipeline runtime for configurable SDLC stages on [Pi](https://github.com/badlogic/pi-mono), plus a local operator console.
+CLI pipeline runtime for **configurable stages** on [Pi](https://github.com/badlogic/pi-mono), with a local operator console.
 
-Author YAML pipelines, stages, and tasks in a project directory. Stageflow runs each stage in a fresh Pi agent session, writes a structured handoff envelope, and keeps run state under `.stageflow/`. Bins: **`sf`** and **`stageflow`**.
+[![npm version](https://img.shields.io/npm/v/stageflow)](https://www.npmjs.com/package/stageflow)
+[![npm downloads](https://img.shields.io/npm/dm/stageflow)](https://www.npmjs.com/package/stageflow)
+![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/tejasghutukade/stageflow)](https://github.com/tejasghutukade/stageflow/issues)
+[![CI](https://img.shields.io/github/actions/workflow/status/tejasghutukade/stageflow/ci.yml?branch=main)](https://github.com/tejasghutukade/stageflow/actions/workflows/ci.yml)
+
+Author pipeline-owned YAML in your project. Stageflow runs each stage in a fresh Pi agent session, writes a structured handoff envelope, and keeps run state under `.stageflow/`. Bins: **`sf`** and **`stageflow`**.
+
+## Why Stageflow?
+
+Multi-step agent work breaks down when every handoff is ad hoc — a shell script here, a chat transcript there, no shared contract between steps. You end up re-explaining context, losing artifacts, and unable to run the same flow locally and in CI.
+
+Stageflow treats **stages as the unit of composition**. You author pipeline-owned YAML — `*.pipeline.yaml`, `*.task.yaml`, optional `stageflow.yaml` manifest — and define whatever workflow fits your domain: release automation, research pipelines, content review, SDLC, ops runbooks, or something entirely custom. Each stage runs in a **fresh Pi session**, emits a typed **envelope** for the next stage, and can pause on **human-in-the-loop (HITL)** gates when you need an operator in the loop.
+
+The same pipeline runs three ways without rewriting anything:
+
+- **Locally** — `sf ui` for triage, provider setup, and gate replies
+- **Headless / CI** — `sf validate` and `sf run --json` with predictable exit codes
+- **Via MCP** — Streamable HTTP tools when the console is running
+
+**Stageflow is not an SDLC tool.** Software delivery is a popular pattern in fixtures and dogfood flows, but stages are user-authored and domain-agnostic. If you can express a multi-step workflow in YAML, Stageflow can run it on Pi.
+
+## Features
+
+- **Pipeline-owned YAML** — `*.pipeline.yaml` with inline stages or `uses:` refs; separate `*.task.yaml` files; optional repo-root `stageflow.yaml` manifest
+- **Path-based CLI** — `--pipeline` and `--task` take filesystem paths (no bare-id lookup)
+- **Pi-native** — runs on `@earendil-works/pi-coding-agent`; reuse an existing Pi login (`pi_home`) or store credentials in `~/.stageflow/agent/auth.json` (`sf_owned`)
+- **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
+- **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
+- **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
+- **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` is running
+- **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
+- **Parallel stages** — pipeline DAG with fan-out and join (see [YAML catalog](docs/yaml-catalog.md))
+- **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
+
+## Installation
 
 Requires **Node.js ≥ 20**.
 
-## Install
+**Quick install (macOS / Linux):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tejasghutukade/stageflow/main/install.sh | bash
+```
+
+**npm:**
 
 ```bash
 npm i -g stageflow
 # or
 npx stageflow
+# or, from a packed tarball
+npm i -g ./stageflow-*.tgz
 ```
 
 `better-sqlite3` ships prebuilds for common platforms. `--ignore-scripts` is fine when a prebuild exists. Benign `node-gyp` warnings during install can be ignored if `require("better-sqlite3")` works.
 
 ## Quick start
 
-In a project directory, author:
+In a project directory (preferably a git repo):
+
+```bash
+sf init
+```
+
+This scaffolds `stageflow.yaml`, `pipelines/hello.pipeline.yaml` (inline stage), and `tasks/hello.task.yaml`.
 
-- `pipelines/` — ordered stage lists
-- `stages/` — stage definitions (instructions, model, optional human gates)
-- `tasks/` — work items (goal, pipeline, optional checkout)
+Run (after connecting a provider — see below):
 
 ```bash
 sf ui                          # operator console at http://127.0.0.1:3847
-sf run --task tasks/foo.yaml --pipeline <pipeline-id>
+sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
+```
+
+Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
+
+## Connect a model provider
+
+Each stage sets a **`model`** id in YAML (e.g. `anthropic/claude-sonnet-4-5`). The matching provider must be authenticated before runs succeed — `sf validate` does not check auth.
+
+**Operator console** (easiest for local setup):
+
+```bash
+sf ui
+```
+
+Open **Settings → Providers** (or **Connect** from the rail when nothing is configured) and sign in with API key or OAuth.
+
+**CLI** (works headless and in CI):
+
+```bash
+sf providers list
+sf providers login anthropic --type api_key
+sf providers login anthropic --type api_key --api-key-env ANTHROPIC_API_KEY
+```
+
+Use `sf providers list` to see provider ids and supported auth types (`api_key`, `oauth`).
+
+**Credential storage:** reuse Pi's shared auth file (`pi_home`) or keep credentials in Stageflow's global store (`sf_owned`):
+
+```bash
+sf providers detect
+sf providers source set pi_home    # or sf_owned
 ```
 
-Connect model providers in the console (Settings → Providers) or via `sf providers …`. Stageflow is a thin Pi shell: reuse an existing Pi login (`pi_home`) or store credentials in an SF-owned file (`sf_owned`). You do not need Pi CLI `/login` as a hard prerequisite.
+Stageflow is a thin Pi shell — you do not need Pi CLI `/login` as a hard prerequisite if you configure providers via the console or `sf providers`.
+
+Full reference: [docs/providers.md](docs/providers.md)
+
+## Operator console
+
+Start the console with `sf ui` (default `http://127.0.0.1:3847`).
+
+- **Runs** — active and recent pipeline runs, capacity, and status at a glance
+- **Run detail** — stage timeline, transcripts, envelope payloads, and artifact paths
+- **HITL reply** — answer operator gates (`ask_operator`) without leaving the browser
+- **Pipelines** — browse manifest-declared pipeline definitions
+- **Settings → Providers** — connect model providers (`pi_home` or `sf_owned` credential storage)
+
+*Screenshot coming soon — capture after console polish lands (see `docs/img/`).*
+
+## Headless / CI
+
+The guest actor is the CLI (`sf` / `stageflow`). `sf ui` and MCP are not required in the job.
+
+```bash
+sf validate --strict --json
+```
+
+Validate exits `0` or `1` only (no waiting / `2`). It checks pipeline and stage YAML only; it does not prove provider auth, Task, or checkout.
+
+```bash
+sf providers login <providerId> --api-key-env <VAR>
+```
+
+If the provider also supports OAuth, pass `--type api_key`.
+
+```bash
+sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml --json
+```
+
+The process exits `0` when the Run succeeded, `1` when it failed (including a busy start), and `2` when waiting. `sf run --json` prints one stdout document. `ok` is true only for `succeeded`. Busy has no `runId`.
+
+| outcome | ok | runId | exit |
+|---|---|---|---|
+| `succeeded` | true | present | `0` |
+| `failed` | false | present after start; omit when start never created a run | `1` |
+| `waiting` | false | present | `2` |
+| `busy` | false | omit | `1` |
+
+On a mixed Pipeline, default wait parks the Run (exit `2`). `--skip-gates` fails the Stage (exit `1`). A Pipeline with no HITL does not need the flag.
 
 ## State
 
-Runtime state lives in **`.stageflow/`** (SQLite + per-run workspaces under `.stageflow/runs/`). If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
+Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository (SQLite + per-run workspaces under `.stageflow/runs/`). Global config and `sf_owned` auth live under **`~/.stageflow/`**. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
 
 ## MCP
 
-`sf ui` also serves a Streamable HTTP MCP endpoint at `http://127.0.0.1:3847/mcp` (URL printed on boot). Point a Cursor (or other) MCP client at that URL for tools like `list_pipelines`, `start_run`, and `get_run`.
+`sf ui` also serves a Streamable HTTP MCP endpoint at `http://127.0.0.1:3847/mcp` (URL printed on boot). Point a Cursor (or other) MCP client at that URL.
+
+Available tools: `list_pipelines`, `list_tasks`, `list_runs`, `get_health`, `start_run`, `get_run`, `read_artifact`.
+
+Full reference: [docs/mcp.md](docs/mcp.md)
+
+## Stageflow vs Conductor
+
+Both projects address multi-step agent workflows. They differ in orchestration model and runtime.
+
+| | **Stageflow** | **Conductor** |
+|---|---------------|---------------|
+| **Model** | Configurable **stages** on Pi; pipeline-owned YAML (any domain) | Multi-**agent** workflow graph |
+| **Orchestration** | Pipeline DAG + stage worker | Jinja routing, no LLM in router |
+| **Unit of work** | Task → Pipeline → Stage attempts | Workflow → Agents |
+| **Handoff** | Typed **envelope** + artifacts | Agent output → context |
+| **Human gates** | Operator console + MCP | Dashboard + TUI fleet |
+| **Runtime** | Node.js, Pi coding agent | Python, Copilot/Claude SDKs |
+| **Best for** | Personal/team **multi-stage Pi workflows** you define (releases, research, SDLC, …) | Enterprise multi-agent workflows |
+
+If you want deterministic YAML routing across many agents, look at [Conductor](https://github.com/microsoft/conductor). If you want stage-bound Pi runs with reviewable envelopes and an operator console for **workflows you author**, use Stageflow.
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [hello-world](examples/hello-world/) | Single stage, domain-neutral |
+| [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
+| [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
+| [ci-validate](examples/ci-validate/) | Strict validate in CI |
+
+Index: [examples/README.md](examples/README.md)
+
+## Documentation
+
+Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.io/stageflow/)** (GitHub Pages — live after merge to `main` and Pages enabled). Source in [`docs/`](docs/).
+
+| Doc | Description |
+|-----|-------------|
+| [docs/README.md](docs/README.md) | Documentation index |
+| [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
+| [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
+| [docs/cli-reference.md](docs/cli-reference.md) | `sf run`, `sf validate`, `sf ui`, `sf providers` |
+| [docs/envelopes.md](docs/envelopes.md) | Handoff envelope contract |
+| [docs/hitl.md](docs/hitl.md) | Gate kinds, `--skip-gates`, exit code `2` |
+| [docs/ci.md](docs/ci.md) | `--json`, env vars, GitHub Actions |
+| [docs/mcp.md](docs/mcp.md) | MCP tool reference |
+| [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
+| [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
+| [docs/compare-conductor.md](docs/compare-conductor.md) | Positioning deep dive |
 
 ## Develop from source
 
@@ -49,8 +222,12 @@ npm run build && npm run ui:build   # ui:build builds the UI and copies assets i
 sf ui
 ```
 
+Run tests: `npm test` and `npm run ui:test`. Typecheck: `npm run typecheck`.
+
 ## License
 
 MIT © Tejas G
 
-Issues: https://github.com/tejasghutukade/stageflow/issues
+**Support:** [GitHub Issues](https://github.com/tejasghutukade/stageflow/issues) · [SUPPORT.md](SUPPORT.md)
+
+**Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)

package/dist/agent/activity.d.ts

@@ -11,7 +11,11 @@
  * those Q&A bodies.
  */
 import type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
-export declare const ACTIVITY_TEXT_LIMIT = 500;
+export declare const ACTIVITY_TEXT_LIMIT = 2000;
+export declare const ACTIVITY_TEXT_LIMIT_ENV = "STAGEFLOW_ACTIVITY_TEXT_LIMIT";
+export declare const ACTIVITY_VERBOSE_ENV = "STAGEFLOW_ACTIVITY_VERBOSE";
+export declare function readActivityTextLimit(env?: Record<string, string | undefined>, override?: number): number;
+export declare function readActivityVerbose(env?: Record<string, string | undefined>, override?: boolean): boolean;
 export type StageActivityEvent = {
     event: "agent_start";
 } | {
@@ -29,6 +33,11 @@ export type StageActivityEvent = {
     toolCallId?: string;
     isError?: boolean;
     resultPreview?: string;
+} | {
+    event: "tool_progress";
+    toolName: string;
+    toolCallId?: string;
+    textPreview?: string;
 } | {
     event: "message";
     role: string;

package/dist/agent/activity.js

@@ -10,8 +10,43 @@
  * ACTIVITY_TEXT_LIMIT applies only to tool/message *previews* — never to
  * those Q&A bodies.
  */
-export const ACTIVITY_TEXT_LIMIT = 500;
-export function truncateActivityText(value, limit = ACTIVITY_TEXT_LIMIT) {
+export const ACTIVITY_TEXT_LIMIT = 2000;
+export const ACTIVITY_TEXT_LIMIT_ENV = "STAGEFLOW_ACTIVITY_TEXT_LIMIT";
+export const ACTIVITY_VERBOSE_ENV = "STAGEFLOW_ACTIVITY_VERBOSE";
+export function readActivityTextLimit(env = process.env, override) {
+    if (override !== undefined) {
+        if (Number.isFinite(override) && override >= 1)
+            return Math.floor(override);
+        return ACTIVITY_TEXT_LIMIT;
+    }
+    const raw = env[ACTIVITY_TEXT_LIMIT_ENV];
+    if (raw === undefined || raw.trim() === "") {
+        return ACTIVITY_TEXT_LIMIT;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1) {
+        return ACTIVITY_TEXT_LIMIT;
+    }
+    return n;
+}
+export function readActivityVerbose(env = process.env, override) {
+    if (override !== undefined) {
+        return override;
+    }
+    const raw = env[ACTIVITY_VERBOSE_ENV];
+    if (raw === undefined || raw.trim() === "") {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "0" ||
+        normalized === "false" ||
+        normalized === "off" ||
+        normalized === "no") {
+        return false;
+    }
+    return true;
+}
+export function truncateActivityText(value, limit = readActivityTextLimit()) {
     if (value === undefined || value === null)
         return undefined;
     let text;

package/dist/agent/activityObserver.d.ts

@@ -1,6 +1,9 @@
-import type { StageActivityEvent } from "./activity.js";
+import { type StageActivityEvent } from "./activity.js";
+export declare const TOOL_PROGRESS_THROTTLE_MS = 300;
 export type StageActivityObserver = {
     onAssistantTextDelta(delta: string): void;
+    onThinkingDelta(delta: string): void;
+    onToolPartialResult(accumulatedText: string): void;
     onStreamBoundary(): void;
     onActivity(activity: StageActivityEvent): void;
     dispose(): void;
@@ -8,6 +11,7 @@ export type StageActivityObserver = {
 export type CreateStageActivityObserverOptions = {
     onActivity?: (event: StageActivityEvent) => void;
     writeStderr?: boolean;
+    toolProgressThrottleMs?: number;
 };
 /**
  * Observe StageActivityEvent milestones and optional assistant text deltas.

package/dist/agent/activityObserver.js

@@ -1,4 +1,11 @@
-function writeActivityStderr(activity) {
+import { truncateActivityText, } from "./activity.js";
+export const TOOL_PROGRESS_THROTTLE_MS = 300;
+function writeIndentedPreview(preview) {
+    for (const line of preview.split("\n")) {
+        process.stderr.write(`    ${line}\n`);
+    }
+}
+function writeActivityStderr(activity, skipAssistantMessage) {
     switch (activity.event) {
         case "agent_start":
             process.stderr.write("  … agent started\n");
@@ -11,13 +18,33 @@ function writeActivityStderr(activity) {
             return;
         case "tool_start":
             process.stderr.write(`  → ${activity.toolName}\n`);
+            if (activity.argsPreview) {
+                writeIndentedPreview(activity.argsPreview);
+            }
             return;
         case "tool_end":
             if (activity.isError) {
                 process.stderr.write(`  ✕ ${activity.toolName}\n`);
             }
+            else if (activity.resultPreview) {
+                process.stderr.write(`  ← ${activity.toolName}\n`);
+            }
+            if (activity.resultPreview) {
+                writeIndentedPreview(activity.resultPreview);
+            }
+            return;
+        case "tool_progress":
             return;
         case "message":
+            if (activity.role === "assistant" && skipAssistantMessage) {
+                return;
+            }
+            if (activity.role === "thinking") {
+                return;
+            }
+            if (activity.text) {
+                writeIndentedPreview(activity.text);
+            }
             return;
     }
 }
@@ -28,39 +55,175 @@ function writeActivityStderr(activity) {
  */
 export function createStageActivityObserver(options = {}) {
     const writeStderr = options.writeStderr !== false;
-    let inAssistantText = false;
-    const endTextLine = () => {
-        if (!inAssistantText) {
+    const toolProgressThrottleMs = options.toolProgressThrottleMs ?? TOOL_PROGRESS_THROTTLE_MS;
+    let openStream = "none";
+    let assistantStreamedForMessage = false;
+    let lastToolPartial = "";
+    let thinkingBuffer = "";
+    let openTool = null;
+    let toolProgressAccum = "";
+    let toolProgressPending = false;
+    let toolProgressTimer = null;
+    const endOpenStream = () => {
+        if (openStream === "none") {
             return;
         }
         if (writeStderr) {
             process.stderr.write("\n");
         }
-        inAssistantText = false;
+        openStream = "none";
+    };
+    const flushThinking = () => {
+        const raw = thinkingBuffer;
+        thinkingBuffer = "";
+        if (!raw.trim()) {
+            return;
+        }
+        options.onActivity?.({
+            event: "message",
+            role: "thinking",
+            text: truncateActivityText(raw),
+        });
+    };
+    const emitToolProgress = () => {
+        if (!toolProgressPending || !openTool) {
+            toolProgressPending = false;
+            return;
+        }
+        const textPreview = truncateActivityText(toolProgressAccum);
+        toolProgressPending = false;
+        if (!textPreview?.trim()) {
+            return;
+        }
+        options.onActivity?.({
+            event: "tool_progress",
+            toolName: openTool.toolName,
+            toolCallId: openTool.toolCallId,
+            textPreview,
+        });
+    };
+    const cancelToolProgressTimer = () => {
+        if (toolProgressTimer !== null) {
+            clearTimeout(toolProgressTimer);
+            toolProgressTimer = null;
+        }
+    };
+    const flushToolProgress = () => {
+        cancelToolProgressTimer();
+        emitToolProgress();
+    };
+    const scheduleToolProgress = () => {
+        if (!openTool || !toolProgressAccum.trim()) {
+            return;
+        }
+        toolProgressPending = true;
+        if (toolProgressTimer !== null) {
+            return;
+        }
+        toolProgressTimer = setTimeout(() => {
+            toolProgressTimer = null;
+            emitToolProgress();
+        }, toolProgressThrottleMs);
     };
     return {
         onAssistantTextDelta(delta) {
             if (!writeStderr || !delta) {
                 return;
             }
-            if (!inAssistantText) {
+            assistantStreamedForMessage = true;
+            if (openStream !== "assistant") {
+                endOpenStream();
                 process.stderr.write("  ");
-                inAssistantText = true;
+                openStream = "assistant";
+            }
+            process.stderr.write(delta);
+        },
+        onThinkingDelta(delta) {
+            if (!delta) {
+                return;
+            }
+            thinkingBuffer += delta;
+            if (!writeStderr) {
+                return;
+            }
+            if (openStream !== "thinking") {
+                endOpenStream();
+                process.stderr.write("  ∴ ");
+                openStream = "thinking";
+            }
+            process.stderr.write(delta);
+        },
+        onToolPartialResult(accumulatedText) {
+            if (!accumulatedText) {
+                return;
+            }
+            toolProgressAccum = accumulatedText;
+            scheduleToolProgress();
+            if (!writeStderr) {
+                return;
+            }
+            const delta = accumulatedText.startsWith(lastToolPartial)
+                ? accumulatedText.slice(lastToolPartial.length)
+                : accumulatedText;
+            lastToolPartial = accumulatedText;
+            if (!delta) {
+                return;
+            }
+            if (openStream !== "tool") {
+                endOpenStream();
+                process.stderr.write("  │ ");
+                openStream = "tool";
             }
             process.stderr.write(delta);
         },
         onStreamBoundary() {
-            endTextLine();
+            endOpenStream();
+            flushThinking();
+            flushToolProgress();
+            lastToolPartial = "";
         },
         onActivity(activity) {
-            endTextLine();
+            flushThinking();
+            if (activity.event === "tool_end") {
+                flushToolProgress();
+            }
+            endOpenStream();
+            lastToolPartial = "";
+            if (activity.event === "turn_start") {
+                assistantStreamedForMessage = false;
+            }
+            if (activity.event === "tool_start") {
+                openTool = {
+                    toolName: activity.toolName,
+                    toolCallId: activity.toolCallId,
+                };
+                toolProgressAccum = "";
+                toolProgressPending = false;
+                cancelToolProgressTimer();
+            }
+            else if (activity.event === "tool_end") {
+                openTool = null;
+                toolProgressAccum = "";
+                toolProgressPending = false;
+                cancelToolProgressTimer();
+            }
+            const skipAssistantMessage = activity.event === "message" &&
+                activity.role === "assistant" &&
+                assistantStreamedForMessage;
+            if (activity.event === "message" &&
+                activity.role === "assistant") {
+                assistantStreamedForMessage = false;
+            }
             options.onActivity?.(activity);
             if (writeStderr) {
-                writeActivityStderr(activity);
+                writeActivityStderr(activity, skipAssistantMessage);
             }
         },
         dispose() {
-            endTextLine();
+            endOpenStream();
+            flushThinking();
+            flushToolProgress();
+            cancelToolProgressTimer();
         },
     };
 }

package/dist/agent/fakeAgent.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
+import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
 import { runStageViaOpen } from "./port.js";
@@ -135,6 +136,9 @@ export class FakeAgent {
                 : undefined;
             try {
                 const envelope = assertRequiredEnvelope(envelopeValue);
+                if (input.forkEmitContext !== undefined) {
+                    assertForkEnvelope(envelope, input.forkEmitContext);
+                }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);
                 if (!isAdvancingEnvelope(envelope)) {
                     input.onActivity?.({ event: "agent_end" });

package/dist/agent/piAdapter.d.ts

@@ -2,6 +2,7 @@ import { type AgentSession, DefaultResourceLoader, SessionManager, SettingsManag
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
+import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
@@ -45,6 +46,21 @@ export type ConnectedAskWaitStageHandleOptions = {
  * runtime never imports the channel.
  */
 export declare function createConnectedAskWaitStageHandle(options: ConnectedAskWaitStageHandleOptions): StageHandle;
+/**
+ * Extract display text from a Pi tool_execution_update partialResult.
+ * Prefers content[].text blocks; otherwise JSON-stringifies.
+ */
+export declare function extractPartialResultText(partialResult: unknown): string;
+export type RouteSessionEventToProgressOptions = {
+    observer: StageActivityObserver;
+    verbose: boolean;
+};
+/**
+ * Adapter-edge routing: stream deltas to the observer, map milestones to
+ * StageActivityEvent. Verbose thinking / live tool partials go to observer
+ * hooks (stderr streams + coalesced/throttled persist via onActivity).
+ */
+export declare function routeSessionEventToProgress(event: Record<string, unknown>, options: RouteSessionEventToProgressOptions): void;
 export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
 /**
  * DefaultResourceLoader with host/global discovery turned off.