pi-workflow-engine 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
   "keywords": ["pi-package"],
@@ -16,6 +16,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test:ui": "bun scripts/test-workflow-ui.ts",
     "prepublishOnly": "tsc --noEmit"
   },
   "peerDependencies": {

package/src/agent-runner.ts

@@ -49,11 +49,13 @@ function lastAssistantText(state: AgentState): string {
 export async function runAgent(rc: RunContext, prompt: string, opts: AgentOptions = {}): Promise<unknown> {
   const label = opts.label ?? "agent";
 
-  // Acquire a global concurrency slot before spawning the session.
+  // Track queued agents before acquiring a global concurrency slot.
+  const rowId = rc.progress.agentQueued(opts.phase, label);
   return rc.semaphore.run(async () => {
-    rc.progress.agentStart(opts.phase, label);
+    rc.progress.agentStart(opts.phase, label, rowId);
 
     let captured: unknown = null;
+    let failed = false;
     const customTools: ToolDefinition[] = opts.schema
       ? [
           defineTool({
@@ -92,7 +94,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
 
     const unsubscribe = session.subscribe((event) => {
       if (event.type === "tool_execution_start" && event.toolName !== FINAL_TOOL) {
-        rc.progress.agentTool(label, event.toolName);
+        rc.progress.agentTool(label, event.toolName, rowId);
       }
     });
 
@@ -107,12 +109,14 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
       }
       return lastAssistantText(session.state);
     } catch (error) {
+      failed = true;
+      rc.progress.agentFailed(label, error, rowId);
       rc.progress.log(`${label} failed: ${error instanceof Error ? error.message : String(error)}`);
       throw error;
     } finally {
       unsubscribe();
       session.dispose();
-      rc.progress.agentDone(label);
+      if (!failed) rc.progress.agentDone(label, rowId);
     }
   });
 }

package/src/engine.ts

@@ -3,7 +3,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { parallel, pipeline, Semaphore } from "./concurrency.ts";
 import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
-import type { AgentOptions, WorkflowApi, WorkflowModule } from "./types.ts";
+import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowRunOptions } from "./types.ts";
+import { WorkflowInspector } from "./ui/workflow-inspector.ts";
 
 /** Default global cap on concurrent agents per run. */
 const DEFAULT_CONCURRENCY = Math.min(8, Math.max(2, cpus().length));
@@ -12,8 +13,22 @@ const DEFAULT_CONCURRENCY = Math.min(8, Math.max(2, cpus().length));
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
  * to a shared semaphore + progress tracker), invoke the workflow, return its result.
  */
-export async function runWorkflow(ctx: ExtensionContext, mod: WorkflowModule, args: string): Promise<unknown> {
+export async function runWorkflow(
+  ctx: ExtensionContext,
+  mod: WorkflowModule,
+  args: string,
+  options: WorkflowRunOptions = {},
+): Promise<unknown> {
   const progress = new ProgressTracker(ctx, mod.meta.name);
+  if (options.inspect && ctx.hasUI) {
+    void ctx.ui
+      .custom<void>(
+        (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
+        { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
+      )
+      .catch((error: unknown) => progress.log(`inspector failed: ${error instanceof Error ? error.message : String(error)}`));
+  }
+
   const rc: RunContext = {
     cwd: ctx.cwd,
     hostModel: ctx.model,
@@ -31,7 +46,9 @@ export async function runWorkflow(ctx: ExtensionContext, mod: WorkflowModule, ar
     pipeline,
     phase: (title) => progress.phase(title),
     log: (message) => progress.log(message),
+    progress: (event) => progress.event(event),
     args,
+    cwd: ctx.cwd,
     signal: ctx.signal,
   };
 

package/src/index.ts

@@ -1,8 +1,11 @@
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { discoverWorkflows } from "./discovery.ts";
 import { runWorkflow } from "./engine.ts";
+import type { WorkflowModule, WorkflowRunOptions } from "./types.ts";
+import { isWorkflowResult, renderWorkflowResult, type WorkflowResultEnvelope } from "./ui/workflow-result-renderer.ts";
 
 /** Repo root (this file lives in <repo>/src/index.ts). */
 const REPO_DIR = fileURLToPath(new URL("..", import.meta.url));
@@ -18,34 +21,84 @@ function formatReport(name: string, result: unknown): string {
   return [`## Workflow: ${name}`, "", "```json", JSON.stringify(result, null, 2), "```"].join("\n");
 }
 
+function workflowEnvelope(name: string, result: unknown): WorkflowResultEnvelope {
+  return { name, result, completedAt: Date.now() };
+}
+
+interface WorkflowInvocation {
+  name: string;
+  args: string;
+  options: WorkflowRunOptions;
+}
+
+function parseWorkflowInvocation(input: string): WorkflowInvocation {
+  const trimmed = input.trim();
+  const space = trimmed.indexOf(" ");
+  const name = space === -1 ? trimmed : trimmed.slice(0, space);
+  const rest = space === -1 ? "" : trimmed.slice(space + 1).trim();
+  const inspect = /(?:^|\s)--inspect(?:\s|$)/.test(rest);
+  const cleanedArgs = rest.replace(/(?:^|\s)--inspect(?=\s|$)/g, " ").trim();
+  return { name, args: cleanedArgs, options: inspect ? { inspect: true } : {} };
+}
+
+async function pickWorkflow(
+  workflows: ReadonlyMap<string, WorkflowModule>,
+  ctx: ExtensionCommandContext,
+): Promise<WorkflowInvocation | undefined> {
+  const choices = [...workflows.values()].map((mod) => `${mod.meta.name} — ${mod.meta.description}`);
+  const choice = await ctx.ui.select("Run workflow", choices);
+  if (!choice) return undefined;
+
+  const separator = choice.indexOf(" — ");
+  const name = separator === -1 ? choice : choice.slice(0, separator);
+  const args = name === "code-review" ? (await ctx.ui.input("Code-review target/instructions", "Blank = auto-detect diff"))?.trim() ?? "" : "";
+  const inspect = await ctx.ui.confirm("Open inspector?", "Open a live workflow inspector while this workflow runs?");
+  return { name, args, options: { inspect } };
+}
+
+async function sendWorkflowResult(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  name: string,
+  mod: WorkflowModule,
+  args: string,
+  options: WorkflowRunOptions,
+): Promise<void> {
+  const result = await runWorkflow(ctx, mod, args, options);
+  pi.sendMessage(
+    { customType: "workflow-result", content: formatReport(name, result), display: true, details: workflowEnvelope(name, result) },
+    { triggerTurn: false },
+  );
+}
+
 export default function workflowEngine(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) => {
+    const details = message.details;
+    if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
+    return renderWorkflowResult("workflow", details ?? message.content, expanded, theme);
+  });
+
   // /workflow <name> [args] — user-invoked.
   pi.registerCommand("workflow", {
     description: "Run a multi-agent workflow: /workflow <name> [args]",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
-      const trimmed = args.trim();
-      const space = trimmed.indexOf(" ");
-      const name = space === -1 ? trimmed : trimmed.slice(0, space);
-      const rest = space === -1 ? "" : trimmed.slice(space + 1).trim();
-
       const workflows = await discoverWorkflows(REPO_DIR);
       const available = [...workflows.keys()].join(", ") || "(none)";
+      const direct = parseWorkflowInvocation(args);
+      const invocation = direct.name ? direct : ctx.hasUI ? await pickWorkflow(workflows, ctx) : undefined;
 
-      if (!name) {
+      if (!invocation) {
         ctx.ui.notify(`Usage: /workflow <name> [args]. Available: ${available}`, "warning");
         return;
       }
-      const mod = workflows.get(name);
+
+      const mod = workflows.get(invocation.name);
       if (!mod) {
-        ctx.ui.notify(`Unknown workflow "${name}". Available: ${available}`, "error");
+        ctx.ui.notify(`Unknown workflow "${invocation.name}". Available: ${available}`, "error");
         return;
       }
 
-      const result = await runWorkflow(ctx, mod, rest);
-      pi.sendMessage(
-        { customType: "workflow-result", content: formatReport(name, result), display: true, details: result },
-        { triggerTurn: false },
-      );
+      await sendWorkflowResult(pi, ctx, invocation.name, mod, invocation.args, invocation.options);
     },
   });
 
@@ -59,6 +112,18 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       name: Type.String({ description: "Workflow name, e.g. code-review" }),
       args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
     }),
+    renderCall(args, theme) {
+      const suffix = args.args ? ` ${theme.fg("dim", args.args)}` : "";
+      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name)}${suffix}`, 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("accent", "Running workflow…"), 0, 0);
+      const details = result.details;
+      if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
+      const first = result.content[0];
+      const text = first?.type === "text" ? first.text : "Workflow finished.";
+      return new Text(theme.fg("muted", text), 0, 0);
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const workflows = await discoverWorkflows(REPO_DIR);
       const mod = workflows.get(params.name);
@@ -70,7 +135,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         };
       }
       const result = await runWorkflow(ctx, mod, params.args ?? "");
-      return { content: [{ type: "text", text: summarize(result) }], details: result };
+      return { content: [{ type: "text", text: summarize(result) }], details: workflowEnvelope(params.name, result) };
     },
   });
 }

package/src/progress.ts

@@ -1,9 +1,63 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import type { WorkflowLaneItemStatus, WorkflowProgressEvent } from "./types.ts";
+import { statusText } from "./ui/workflow-format.ts";
+import { createWorkflowWidget, type WorkflowWidget } from "./ui/workflow-widget.ts";
+
+export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+
+export interface AgentRowSnapshot {
+  readonly id: number;
+  readonly label: string;
+  readonly status: AgentRowStatus;
+  readonly startedAt?: number;
+  readonly doneAt?: number;
+  readonly toolUses: number;
+  readonly lastTool?: string;
+  readonly error?: string;
+}
+
+export interface PhaseSnapshot {
+  readonly title: string;
+  readonly agents: readonly AgentRowSnapshot[];
+}
+
+export interface WorkflowCounterSnapshot {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+}
+
+export interface WorkflowLaneItemSnapshot {
+  readonly lane: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly status: WorkflowLaneItemStatus;
+  readonly details?: string;
+  readonly createdAt: number;
+}
+
+export interface WorkflowProgressSnapshot {
+  readonly title: string;
+  readonly startedAt: number;
+  readonly doneAt?: number;
+  readonly currentPhase: string;
+  readonly phases: readonly PhaseSnapshot[];
+  readonly counters: readonly WorkflowCounterSnapshot[];
+  readonly summary: readonly [string, string | number][];
+  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
+  readonly logs: readonly string[];
+}
 
 interface AgentRow {
+  id: number;
   label: string;
-  status: "running" | "done";
+  status: AgentRowStatus;
+  startedAt?: number;
+  doneAt?: number;
+  toolUses: number;
   lastTool?: string;
+  error?: string;
 }
 
 interface Phase {
@@ -11,21 +65,48 @@ interface Phase {
   agents: AgentRow[];
 }
 
+interface WorkflowCounter {
+  key: string;
+  label: string;
+  value: number;
+}
+
+interface WorkflowLaneItem {
+  lane: string;
+  title: string;
+  subtitle?: string;
+  status: WorkflowLaneItemStatus;
+  details?: string;
+  createdAt: number;
+}
+
+const LOG_LIMIT = 24;
+
 /**
- * Renders a live phase/agent tree into the pi TUI via `ctx.ui.setWidget`.
- * In non-interactive modes (print/JSON/RPC) it falls back to terse stderr breadcrumbs
- * so it never corrupts stdout.
+ * Tracks live workflow state for widgets, footer/status text, result renderers,
+ * and headless stderr breadcrumbs.
  */
 export class ProgressTracker {
   private readonly phases: Phase[] = [];
   private readonly logs: string[] = [];
-  private current = "Workflow";
+  private readonly counters = new Map<string, WorkflowCounter>();
+  private readonly summary = new Map<string, string | number>();
+  private readonly lanes = new Map<string, WorkflowLaneItem[]>();
+  private readonly startedAt = Date.now();
+  private doneAt: number | undefined;
+  private currentPhase = "Workflow";
+  private nextAgentId = 1;
+  private widget: WorkflowWidget | undefined;
+  private widgetRegistered = false;
+  private tui: Pick<TUI, "requestRender"> | undefined;
+  private widgetInterval: ReturnType<typeof setInterval> | undefined;
+  private lastStatusText: string | undefined;
 
   constructor(
     private readonly ctx: ExtensionContext,
     private readonly title: string,
   ) {
-    this.ensurePhase(this.current);
+    this.ensurePhase(this.currentPhase);
   }
 
   private ensurePhase(title: string): Phase {
@@ -38,7 +119,7 @@ export class ProgressTracker {
   }
 
   phase(title: string): void {
-    this.current = title;
+    this.currentPhase = title;
     this.ensurePhase(title);
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${title}\n`);
     this.render();
@@ -46,31 +127,121 @@ export class ProgressTracker {
 
   log(message: string): void {
     this.logs.push(message);
-    if (this.logs.length > 6) this.logs.shift();
+    while (this.logs.length > LOG_LIMIT) this.logs.shift();
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${message}\n`);
     this.render();
   }
 
-  agentStart(phase: string | undefined, label: string): void {
-    this.ensurePhase(phase ?? this.current).agents.push({ label, status: "running" });
+  event(event: WorkflowProgressEvent): void {
+    switch (event.type) {
+      case "counter":
+        this.counters.set(event.key, { key: event.key, label: event.label, value: event.value });
+        break;
+      case "counter_delta": {
+        const current = this.counters.get(event.key);
+        this.counters.set(event.key, {
+          key: event.key,
+          label: event.label,
+          value: (current?.value ?? 0) + event.delta,
+        });
+        break;
+      }
+      case "lane_item": {
+        const lane = this.lanes.get(event.lane) ?? [];
+        lane.push({
+          lane: event.lane,
+          title: event.title,
+          subtitle: event.subtitle,
+          status: event.status,
+          details: event.details,
+          createdAt: Date.now(),
+        });
+        this.lanes.set(event.lane, lane);
+        break;
+      }
+      case "summary":
+        this.summary.set(event.key, event.value);
+        break;
+    }
+    this.render();
+  }
+
+  agentQueued(phase: string | undefined, label: string): number {
+    const id = this.nextAgentId++;
+    this.ensurePhase(phase ?? this.currentPhase).agents.push({ label, id, status: "queued", toolUses: 0 });
+    this.render();
+    return id;
+  }
+
+  agentStart(phase: string | undefined, label: string, id?: number): void {
+    const row = id === undefined ? undefined : this.findRowById(id);
+    if (row) {
+      row.status = "running";
+      row.startedAt = Date.now();
+      row.error = undefined;
+    } else {
+      this.ensurePhase(phase ?? this.currentPhase).agents.push({
+        label,
+        id: this.nextAgentId++,
+        status: "running",
+        startedAt: Date.now(),
+        toolUses: 0,
+      });
+    }
     this.render();
   }
 
-  agentTool(label: string, tool: string): void {
-    const row = this.findRow(label);
-    if (row) row.lastTool = tool;
+  agentTool(label: string, tool: string, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row) {
+      row.lastTool = tool;
+      row.toolUses += 1;
+    }
     this.render();
   }
 
-  agentDone(label: string): void {
-    const row = this.findRow(label);
-    if (row && row.status === "running") row.status = "done";
+  agentDone(label: string, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row && row.status !== "failed") {
+      row.status = "done";
+      row.doneAt = Date.now();
+    }
     this.render();
   }
 
-  private findRow(label: string): AgentRow | undefined {
+  agentFailed(label: string, error: unknown, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row) {
+      row.status = "failed";
+      row.doneAt = Date.now();
+      row.error = errorMessage(error);
+    }
+    this.render();
+  }
+
+  snapshot(): WorkflowProgressSnapshot {
+    return {
+      title: this.title,
+      startedAt: this.startedAt,
+      doneAt: this.doneAt,
+      currentPhase: this.currentPhase,
+      phases: this.phases.map((phase) => ({
+        title: phase.title,
+        agents: phase.agents.map((agent) => ({ ...agent })),
+      })),
+      counters: [...this.counters.values()].map((counter) => ({ ...counter })),
+      summary: [...this.summary.entries()],
+      lanes: [...this.lanes.entries()].map(([lane, items]) => [lane, items.map((item) => ({ ...item }))]),
+      logs: [...this.logs],
+    };
+  }
+
+  private findRow(label: string, id?: number): AgentRow | undefined {
+    if (id !== undefined) return this.findRowById(id);
     for (let i = this.phases.length - 1; i >= 0; i--) {
-      const running = this.phases[i].agents.find((agent) => agent.label === label && agent.status === "running");
+      const running = this.phases[i].agents.find(
+        (agent) => agent.label === label && (agent.status === "running" || agent.status === "queued"),
+      );
       if (running) return running;
     }
     for (let i = this.phases.length - 1; i >= 0; i--) {
@@ -80,29 +251,93 @@ export class ProgressTracker {
     return undefined;
   }
 
+  private findRowById(id: number): AgentRow | undefined {
+    for (const phase of this.phases) {
+      const row = phase.agents.find((agent) => agent.id === id);
+      if (row) return row;
+    }
+    return undefined;
+  }
+
   private lines(): string[] {
     const out: string[] = [`⚙ ${this.title}`];
     for (const phase of this.phases) {
       if (phase.agents.length === 0 && phase.title === "Workflow") continue;
       out.push(`  ${phase.title}`);
       for (const agent of phase.agents) {
-        const icon = agent.status === "done" ? "✓" : "⏳";
+        const icon = agent.status === "done" ? "✓" : agent.status === "failed" ? "✗" : agent.status === "queued" ? "○" : "⏳";
         const tool = agent.status === "running" && agent.lastTool ? ` · ${agent.lastTool}` : "";
-        out.push(`    ${icon} ${agent.label}${tool}`);
+        const error = agent.status === "failed" && agent.error ? ` · ${agent.error}` : "";
+        out.push(`    ${icon} ${agent.label}${tool}${error}`);
       }
     }
-    for (const line of this.logs) out.push(`  · ${line}`);
+    const counterLine = [...this.counters.values()].map((counter) => `${counter.label}: ${counter.value}`).join(" · ");
+    if (counterLine) out.push(`  ${counterLine}`);
+    for (const line of this.logs.slice(-6)) out.push(`  · ${line}`);
     return out;
   }
 
   private render(): void {
-    if (this.ctx.hasUI) this.ctx.ui.setWidget("workflow", this.lines());
+    if (!this.ctx.hasUI) return;
+    this.ensureWidget();
+    this.widget?.invalidate();
+    this.tui?.requestRender();
+    this.publishStatus();
+  }
+
+  private publishStatus(): void {
+    const next = statusText(this.snapshot(), this.ctx.ui.theme);
+    if (next === this.lastStatusText) return;
+    this.ctx.ui.setStatus("workflow", next);
+    this.lastStatusText = next;
+  }
+
+  private ensureWidget(): void {
+    if (this.widgetRegistered) return;
+    this.widget = createWorkflowWidget(() => this.snapshot());
+    this.ctx.ui.setWidget(
+      "workflow",
+      (tui, theme) => {
+        this.tui = tui;
+        return {
+          render: (width?: number) => this.widget?.render(width ?? tui.terminal.columns, theme) ?? [],
+          invalidate: () => this.widget?.invalidate(),
+        };
+      },
+      { placement: "aboveEditor" },
+    );
+    this.widgetRegistered = true;
+    this.startWidgetTimer();
   }
 
-  /** Clear the widget; optionally leave a one-line status in the footer. */
+  private startWidgetTimer(): void {
+    if (this.widgetInterval !== undefined) return;
+    this.widgetInterval = setInterval(() => {
+      this.widget?.nextFrame();
+      this.tui?.requestRender();
+    }, 100);
+  }
+
+  private stopWidgetTimer(): void {
+    if (this.widgetInterval === undefined) return;
+    clearInterval(this.widgetInterval);
+    this.widgetInterval = undefined;
+  }
+
+  /** Clear live workflow surfaces; optionally leave a one-line final status. */
   done(status?: string): void {
+    this.doneAt = Date.now();
+    this.stopWidgetTimer();
     if (!this.ctx.hasUI) return;
     this.ctx.ui.setWidget("workflow", undefined);
     this.ctx.ui.setStatus("workflow", status);
+    this.lastStatusText = status;
+    this.widgetRegistered = false;
+    this.widget = undefined;
+    this.tui = undefined;
   }
 }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/types.ts

@@ -8,7 +8,34 @@ export interface WorkflowMeta {
   phases?: Array<{ title: string }>;
 }
 
+export interface WorkflowRunStats {
+  files: number;
+  candidates: number;
+  verified: number;
+  kept: number;
+  [key: string]: string | number;
+}
+
+export interface WorkflowRunOptions {
+  inspect?: boolean;
+}
+
 /** Options for a single `agent()` call. */
+export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
+
+export type WorkflowProgressEvent =
+  | { type: "counter"; key: string; label: string; value: number }
+  | { type: "counter_delta"; key: string; label: string; delta: number }
+  | {
+      type: "lane_item";
+      lane: string;
+      title: string;
+      subtitle?: string;
+      status: WorkflowLaneItemStatus;
+      details?: string;
+    }
+  | { type: "summary"; key: string; value: string | number };
+
 export interface AgentOptions<S extends TSchema = TSchema> {
   /** Label shown in the progress tree (e.g. "find:logic-bugs"). */
   label?: string;
@@ -44,8 +71,12 @@ export interface WorkflowApi {
   phase(title: string): void;
   /** Emit a progress line. */
   log(message: string): void;
+  /** Emit a structured progress event for native workflow UI surfaces. */
+  progress(event: WorkflowProgressEvent): void;
   /** Raw argument string passed after the workflow name. */
   args: string;
+  /** Working directory of the host session (typically the repo root). */
+  cwd: string;
   /** Abort signal for the run, propagated from the host. */
   signal: AbortSignal | undefined;
 }