pi-workflow-engine 0.6.1 → 0.8.0

package/.pi/extensions/pi-workflow-engine/src/dynamax.ts

@@ -1,12 +1,27 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+import { resolveDynamaxShortcuts, type DynamaxShortcuts } from "./dynamax-shortcuts.ts";
 
 export interface DynamaxState {
   sticky: boolean;
   oneShotPending: boolean;
+  turnActive: boolean;
+}
+
+export interface DynamaxRuntime {
+  state: DynamaxState;
+  runningWorkflow?: string;
+}
+
+export type DynamaxRuntimeStore = Map<string, DynamaxRuntime>;
+export interface DynamaxRegistrationOptions {
+  openInspector?: (ctx: ExtensionContext) => Promise<void> | void;
 }
 
 export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/i;
+export const DYNAMAX_STATUS_KEY = "dynamax";
+export const DYNAMAX_WIDGET_KEY = "workflow-dynamax";
 
 export const DYNAMAX_REMINDER = `
 ## dynamax workflow opt-in
@@ -23,7 +38,24 @@ Inline workflow rules:
 const DYNAMAX_CONTEXT_CUSTOM_TYPE = "workflow-dynamax-reminder";
 
 export function createDynamaxState(): DynamaxState {
-  return { sticky: false, oneShotPending: false };
+  return { sticky: false, oneShotPending: false, turnActive: false };
+}
+
+export function createDynamaxRuntime(): DynamaxRuntime {
+  return { state: createDynamaxState() };
+}
+
+export function dynamaxSessionKey(ctx: Pick<ExtensionContext, "sessionManager">): string {
+  return ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
+}
+
+export function getDynamaxRuntime(store: DynamaxRuntimeStore, ctx: Pick<ExtensionContext, "sessionManager">): DynamaxRuntime {
+  const key = dynamaxSessionKey(ctx);
+  const existing = store.get(key);
+  if (existing) return existing;
+  const runtime = createDynamaxRuntime();
+  store.set(key, runtime);
+  return runtime;
 }
 
 export function hasDynamaxToken(text: string): boolean {
@@ -36,12 +68,16 @@ export function markDynamaxOneShot(state: DynamaxState): void {
 
 export function setDynamaxSticky(state: DynamaxState, sticky: boolean): void {
   state.sticky = sticky;
-  if (!sticky) state.oneShotPending = false;
+  if (!sticky) {
+    state.oneShotPending = false;
+    state.turnActive = false;
+  }
 }
 
 export function clearDynamax(state: DynamaxState): void {
   state.sticky = false;
   state.oneShotPending = false;
+  state.turnActive = false;
 }
 
 export function consumeDynamaxOneShot(state: DynamaxState): boolean {
@@ -51,12 +87,32 @@ export function consumeDynamaxOneShot(state: DynamaxState): boolean {
 }
 
 export function isDynamaxActive(state: DynamaxState): boolean {
-  return state.sticky || state.oneShotPending;
+  return state.sticky || state.oneShotPending || state.turnActive;
+}
+
+export function describeDynamaxState(state: DynamaxState): string {
+  const sticky = state.sticky ? "on" : "off";
+  const oneShot = state.oneShotPending ? "pending" : "clear";
+  const turn = state.turnActive ? "; active for current turn" : "";
+  return `sticky ${sticky}; one-shot ${oneShot}${turn}`;
+}
+
+export function dynamaxWidgetLine(state: DynamaxState, shortcut: KeyId | null, runningWorkflow?: string): string {
+  const modes = [
+    runningWorkflow ? `running ${runningWorkflow}` : undefined,
+    state.sticky ? "sticky on" : undefined,
+    !state.sticky && state.turnActive ? "active this turn" : undefined,
+    state.oneShotPending ? "one-shot pending" : undefined,
+  ].filter((value): value is string => value !== undefined);
+  const mode = modes.join(" + ") || "off";
+  const inspectorHint = shortcut ? `${shortcut} inspector` : "/workflow:inspector";
+  return `dynamax: ${mode} | /workflow:dynamax on|off | ${inspectorHint}`;
 }
 
 export function appendDynamaxSystemReminder(systemPrompt: string, state: DynamaxState): string {
-  if (!isDynamaxActive(state)) return systemPrompt;
+  if (!state.sticky && !state.oneShotPending) return systemPrompt;
   state.oneShotPending = false;
+  state.turnActive = true;
   return `${systemPrompt}\n\n${DYNAMAX_REMINDER.trim()}`;
 }
 
@@ -65,52 +121,174 @@ export function appendDynamaxContextReminder(messages: AgentMessage[], state: Dy
   return [...messages, createDynamaxContextMessage()];
 }
 
-export function registerDynamax(pi: ExtensionAPI): void {
-  const state = createDynamaxState();
+export function registerDynamax(
+  pi: ExtensionAPI,
+  shortcuts: DynamaxShortcuts = resolveDynamaxShortcuts(),
+  options: DynamaxRegistrationOptions = {},
+): void {
+  const runtimes: DynamaxRuntimeStore = new Map();
+  const openInspector =
+    options.openInspector ??
+    ((ctx: ExtensionContext): void => {
+      ctx.ui.notify("No workflow inspector is available yet", "warning");
+    });
+  const refreshIfVisible = (ctx: ExtensionContext): void => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    if (isDynamaxActive(runtime.state) || runtime.runningWorkflow) {
+      updateDynamaxSurfaces(ctx, runtime, shortcuts);
+    }
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    updateDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx), shortcuts);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    clearDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx));
+  });
 
-  pi.on("input", (event) => {
+  pi.on("input", (event, ctx) => {
     if (event.source === "extension") return { action: "continue" };
-    if (hasDynamaxToken(event.text)) markDynamaxOneShot(state);
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    if (hasDynamaxToken(event.text)) {
+      markDynamaxOneShot(runtime.state);
+      updateDynamaxSurfaces(ctx, runtime, shortcuts);
+    }
     return { action: "continue" };
   });
 
-  pi.on("before_agent_start", (event) => {
-    const systemPrompt = appendDynamaxSystemReminder(event.systemPrompt, state);
+  pi.on("before_agent_start", (event, ctx) => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    const systemPrompt = appendDynamaxSystemReminder(event.systemPrompt, runtime.state);
     if (systemPrompt === event.systemPrompt) return undefined;
+    updateDynamaxSurfaces(ctx, runtime, shortcuts);
     return { systemPrompt };
   });
 
-  pi.on("context", (event) => {
-    const messages = appendDynamaxContextReminder(event.messages, state);
+  pi.on("agent_start", (_event, ctx) => {
+    refreshIfVisible(ctx);
+  });
+
+  pi.on("message_start", (_event, ctx) => {
+    refreshIfVisible(ctx);
+  });
+
+  pi.on("message_update", (_event, ctx) => {
+    refreshIfVisible(ctx);
+  });
+
+  pi.on("message_end", (_event, ctx) => {
+    refreshIfVisible(ctx);
+  });
+
+  pi.on("turn_end", (_event, ctx) => {
+    refreshIfVisible(ctx);
+  });
+
+  pi.on("agent_end", (_event, ctx) => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    runtime.runningWorkflow = undefined;
+    if (!runtime.state.sticky) runtime.state.turnActive = false;
+    updateDynamaxSurfaces(ctx, runtime, shortcuts);
+  });
+
+  pi.on("tool_execution_start", (event, ctx) => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    if (event.toolName === "workflow") {
+      runtime.runningWorkflow = workflowLabel(event.args);
+    }
+    updateDynamaxSurfaces(ctx, runtime, shortcuts);
+    return undefined;
+  });
+
+  pi.on("tool_execution_update", (_event, ctx) => {
+    refreshIfVisible(ctx);
+  });
+
+  pi.on("tool_execution_end", (event, ctx) => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    if (event.toolName === "workflow") {
+      runtime.runningWorkflow = undefined;
+    }
+    updateDynamaxSurfaces(ctx, runtime, shortcuts);
+    return undefined;
+  });
+
+  pi.on("context", (event, ctx) => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    const messages = appendDynamaxContextReminder(event.messages, runtime.state);
     if (messages === event.messages) return undefined;
     return { messages };
   });
 
+  if (shortcuts.inspector) {
+    pi.registerShortcut(shortcuts.inspector, {
+      description: "Open workflow inspector",
+      handler: async (ctx) => {
+        await openInspector(ctx);
+      },
+    });
+  }
+
   pi.registerCommand("workflow:dynamax", {
-    description: "Toggle dynamax workflow orchestration opt-in: /workflow:dynamax on|off|status",
+    description: "Toggle Dynamax workflow orchestration: /workflow:dynamax [on|off|status]",
     handler: async (args, ctx) => {
+      const runtime = getDynamaxRuntime(runtimes, ctx);
       const action = args.trim().toLowerCase();
+      if (action === "") {
+        ctx.ui.notify(`Dynamax ${describeDynamaxState(runtime.state)}. Usage: /workflow:dynamax [on|off|status]`, "info");
+        return;
+      }
       if (action === "on") {
-        setDynamaxSticky(state, true);
-        ctx.ui.notify("dynamax workflow orchestration is on for this session", "info");
+        setDynamaxSticky(runtime.state, true);
+        updateDynamaxSurfaces(ctx, runtime, shortcuts);
+        ctx.ui.notify("Dynamax workflow orchestration is on for this session", "info");
         return;
       }
       if (action === "off") {
-        clearDynamax(state);
-        ctx.ui.notify("dynamax workflow orchestration is off", "info");
+        clearDynamax(runtime.state);
+        updateDynamaxSurfaces(ctx, runtime, shortcuts);
+        ctx.ui.notify("Dynamax workflow orchestration is off", "info");
         return;
       }
       if (action === "status") {
-        const sticky = state.sticky ? "on" : "off";
-        const oneShot = state.oneShotPending ? "; one-shot opt-in pending" : "";
-        ctx.ui.notify(`dynamax sticky mode is ${sticky}${oneShot}`, "info");
+        ctx.ui.notify(`Dynamax ${describeDynamaxState(runtime.state)}`, "info");
         return;
       }
-      ctx.ui.notify("Usage: /workflow:dynamax on|off|status", "warning");
+      ctx.ui.notify("Usage: /workflow:dynamax [on|off|status]", "warning");
     },
   });
 }
 
+export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime, shortcuts: DynamaxShortcuts): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.setWidget(DYNAMAX_WIDGET_KEY, undefined);
+  ctx.ui.setStatus(DYNAMAX_WIDGET_KEY, undefined);
+  if (!isDynamaxActive(runtime.state) && !runtime.runningWorkflow) {
+    clearDynamaxSurfaces(ctx, runtime);
+    return;
+  }
+
+  const status = dynamaxWidgetLine(runtime.state, shortcuts.inspector, runtime.runningWorkflow);
+  ctx.ui.setStatus(DYNAMAX_STATUS_KEY, status);
+}
+
+export function clearDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.setWidget(DYNAMAX_WIDGET_KEY, undefined);
+  ctx.ui.setStatus(DYNAMAX_STATUS_KEY, undefined);
+  ctx.ui.setStatus(DYNAMAX_WIDGET_KEY, undefined);
+}
+
+function workflowLabel(args: unknown): string {
+  if (!isRecord(args)) return "workflow";
+  const name = args.name;
+  if (typeof name === "string" && name.trim()) return name.trim();
+  const script = args.script;
+  if (typeof script === "string" && script.trim()) return "inline workflow";
+  return "workflow";
+}
+
 function createDynamaxContextMessage(): AgentMessage {
   return {
     role: "custom",
@@ -121,3 +299,7 @@ function createDynamaxContextMessage(): AgentMessage {
     timestamp: Date.now(),
   };
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/.pi/extensions/pi-workflow-engine/src/engine.ts

@@ -4,13 +4,37 @@ import { linkAbortSignal } from "./cancellation.ts";
 import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, type PerfSnapshot } from "./perf.ts";
+import { createWorkflowUsageRecorder } from "./usage.ts";
 import { defaultConcurrency, resolveWorkflowRunOptions } from "./options.ts";
-import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowRunOptions } from "./types.ts";
+import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
 
 /** Default global cap on concurrent agents per run. */
 const DEFAULT_CONCURRENCY = defaultConcurrency();
 
+/** The workflow-facing slice of the progress tracker (satisfied by `ProgressTracker`). */
+export interface WorkflowProgress {
+  phase(title: string): void;
+  log(message: string): void;
+  event(event: WorkflowProgressEvent): void;
+}
+
+/** Per-context knobs threaded through `runWorkflowWithContext` (and re-derived for each sub-workflow). */
+export interface WorkflowContextOptions {
+  /** Controller whose `.signal` equals `rc.signal`; aborts in-flight `parallel` siblings on failure. */
+  abortController: AbortController;
+  /** Eager-submission cap for `parallel`. */
+  submissionLimit: number;
+  /** Resolve a sub-workflow reference for `api.workflow()`. Omit to disable composition. */
+  resolveWorkflow?: (ref: WorkflowRef) => Promise<WorkflowModule>;
+  /** Nesting depth. Sub-workflows run at depth >= 1, where `api.workflow()` rejects. */
+  depth?: number;
+  /** Prefix applied to phase titles so sub-workflow phases nest as "<name> ▸ <title>". */
+  progressPrefix?: string;
+  /** Namespace applied to child structured progress keys/lanes/logs. */
+  progressNamespace?: string;
+}
+
 /**
  * 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.
@@ -23,6 +47,8 @@ export async function runWorkflow(
 ): Promise<unknown> {
   const resolvedOptions = resolveWorkflowRunOptions(options);
   const progress = new ProgressTracker(ctx, mod.meta.name);
+  const progressSource = { snapshot: () => progress.snapshot() };
+  resolvedOptions.onProgressSource?.(progressSource);
   if (resolvedOptions.inspect && ctx.hasUI) {
     void ctx.ui
       .custom<void>(
@@ -33,6 +59,7 @@ export async function runWorkflow(
   }
 
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
+  const usage = createWorkflowUsageRecorder();
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
   const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
@@ -44,31 +71,23 @@ export async function runWorkflow(
     progress,
     signal: runAbortController.signal,
     perf,
+    usage,
   };
 
-  const agent = ((prompt: string, opts?: AgentOptions) => runAgent(rc, prompt, opts)) as WorkflowApi["agent"];
-
-  const api: WorkflowApi = {
-    agent,
-    parallel: (thunks) =>
-      parallel(thunks, {
-        signal: runAbortController.signal,
+  try {
+    // perf.total_ms wraps the whole tree: sub-workflows run inside this span via api.workflow().
+    return await perf.time("workflow.total_ms", () =>
+      runWorkflowWithContext(rc, progress, mod, args, {
         abortController: runAbortController,
-        limit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
+        submissionLimit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
+        resolveWorkflow: resolvedOptions.resolveWorkflow,
+        depth: 0,
+        progressPrefix: "",
       }),
-    pipeline,
-    phase: (title) => progress.phase(title),
-    log: (message) => progress.log(message),
-    progress: (event) => progress.event(event),
-    args,
-    cwd: ctx.cwd,
-    signal: runAbortController.signal,
-  };
-
-  try {
-    return await perf.time("workflow.total_ms", () => mod.default(api));
+    );
   } finally {
     try {
+      resolvedOptions.onUsageSnapshot?.(usage.snapshot());
       const snapshot = perf.snapshot();
       if (resolvedOptions.perf) {
         resolvedOptions.onPerfSnapshot?.(snapshot);
@@ -77,12 +96,123 @@ export async function runWorkflow(
       progress.done();
       resolvedOptions.onProgressSnapshot?.(progress.snapshot());
     } finally {
+      resolvedOptions.onProgressSource?.(undefined);
       unlinkContextAbortSignal();
       unlinkOptionAbortSignal();
     }
   }
 }
 
+/**
+ * Build the `WorkflowApi` from an existing run context and invoke the module. Reused for both
+ * the top-level run and every `api.workflow()` sub-step, so children share the parent's semaphore,
+ * abort signal, and perf sink. No setup/teardown of its own — that belongs to `runWorkflow`.
+ */
+export async function runWorkflowWithContext(
+  rc: RunContext,
+  progress: WorkflowProgress,
+  mod: WorkflowModule,
+  args: string,
+  opts: WorkflowContextOptions,
+): Promise<unknown> {
+  const depth = opts.depth ?? 0;
+  const scope = createWorkflowScope(progress, opts.progressPrefix ?? "", opts.progressNamespace);
+
+  const agent = ((prompt: string, agentOpts?: AgentOptions) => runAgent(rc, prompt, scope.agentOptions(agentOpts))) as WorkflowApi["agent"];
+
+  const workflow: WorkflowApi["workflow"] =
+    depth >= 1
+      ? async () => {
+          throw new Error("workflow() can only nest one level deep");
+        }
+      : async (ref, childArgs) => {
+          if (!opts.resolveWorkflow) throw new Error("sub-workflows are not enabled in this context");
+          const childMod = await opts.resolveWorkflow(ref);
+          // A child controller isolates the child's failures from the parent (so the parent can
+          // try/catch a failed sub-workflow), while still cancelling the child when the run aborts.
+          const childController = new AbortController();
+          const unlink = linkAbortSignal(rc.signal, childController);
+          try {
+            return await runWorkflowWithContext({ ...rc, signal: childController.signal }, progress, childMod, childArgs ?? "", {
+              abortController: childController,
+              submissionLimit: opts.submissionLimit,
+              resolveWorkflow: opts.resolveWorkflow,
+              depth: depth + 1,
+              progressPrefix: `${childMod.meta.name} ▸ `,
+              progressNamespace: childMod.meta.name,
+            });
+          } finally {
+            unlink();
+            scope.restorePhase();
+          }
+        };
+
+  const api: WorkflowApi = {
+    agent,
+    workflow,
+    parallel: (thunks) =>
+      parallel(thunks, {
+        signal: rc.signal,
+        abortController: opts.abortController,
+        limit: opts.submissionLimit,
+      }),
+    pipeline,
+    phase: scope.phase,
+    log: scope.log,
+    progress: scope.event,
+    args,
+    cwd: rc.cwd,
+    signal: rc.signal,
+  };
+
+  return await mod.default(api);
+}
+
+interface WorkflowScope {
+  agentOptions(opts: AgentOptions | undefined): AgentOptions;
+  phase(title: string): void;
+  log(message: string): void;
+  event(event: WorkflowProgressEvent): void;
+  restorePhase(): void;
+}
+
+function createWorkflowScope(progress: WorkflowProgress, prefix: string, namespace: string | undefined): WorkflowScope {
+  let currentPhase = `${prefix}Workflow`;
+  const display = (title: string) => `${prefix}${title}`;
+  return {
+    agentOptions(opts) {
+      const phase = opts?.phase ? display(opts.phase) : currentPhase;
+      return opts ? { ...opts, phase } : { phase };
+    },
+    phase(title) {
+      currentPhase = display(title);
+      progress.phase(currentPhase);
+    },
+    log(message) {
+      progress.log(namespace ? `${namespace}: ${message}` : message);
+    },
+    event(event) {
+      progress.event(namespace ? namespaceProgressEvent(namespace, event) : event);
+    },
+    restorePhase() {
+      progress.phase(currentPhase);
+    },
+  };
+}
+
+function namespaceProgressEvent(namespace: string, event: WorkflowProgressEvent): WorkflowProgressEvent {
+  switch (event.type) {
+    case "counter":
+      return { ...event, key: `${namespace}.${event.key}` };
+    case "counter_delta":
+      return { ...event, key: `${namespace}.${event.key}` };
+    case "lane_item":
+      return { ...event, lane: `${namespace} ▸ ${event.lane}` };
+    case "summary":
+      return { ...event, key: `${namespace}.${event.key}` };
+  }
+}
+
 function formatPerfSummary(snapshot: PerfSnapshot): string {
   const parts = snapshot.aggregates
     .filter((aggregate) => aggregate.count > 0)

package/.pi/extensions/pi-workflow-engine/src/review/github-pr-comments.ts

@@ -28,7 +28,7 @@ export type InlineCommentStatus =
   | { readonly issueId: string; readonly status: "skipped"; readonly reason: string }
   | { readonly issueId: string; readonly status: "failed"; readonly reason: string };
 
-const PR_VIEW_JSON_FIELDS = "number,headRefOid,url,headRepositoryOwner,headRepository";
+const PR_VIEW_JSON_FIELDS = "number,headRefOid,url";
 
 export async function resolveGitHubPrContext(
   exec: ExecLike,
@@ -47,10 +47,10 @@ export async function resolveGitHubPrContext(
   if (number === undefined) return { ok: false, reason: "No GitHub PR number found." };
   if (!headSha) return { ok: false, reason: "GitHub PR head SHA is missing." };
 
-  const ownerFromPr = nestedStringField(prView.value, "headRepositoryOwner", "login");
-  const repoFromPr = nestedStringField(prView.value, "headRepository", "name");
-  let owner = ownerFromPr;
-  let repo = repoFromPr;
+  const url = stringField(prView.value, "url");
+  const baseFromUrl = parsePullRequestUrl(url);
+  let owner = baseFromUrl?.owner;
+  let repo = baseFromUrl?.repo;
   if (!owner || !repo) {
     const repoView = await runJson(exec, cwd, ["repo", "view", "--json", "nameWithOwner"]);
     if (!repoView.ok) return { ok: false, reason: repoView.reason };
@@ -61,7 +61,6 @@ export async function resolveGitHubPrContext(
   }
   if (!owner || !repo) return { ok: false, reason: "GitHub repository owner/name is missing." };
 
-  const url = stringField(prView.value, "url");
   return { ok: true, context: { owner, repo, number, headSha, url } };
 }
 
@@ -159,12 +158,6 @@ function stringField(value: unknown, key: string): string | undefined {
   return typeof field === "string" && field.trim().length > 0 ? field : undefined;
 }
 
-function nestedStringField(value: unknown, objectKey: string, key: string): string | undefined {
-  if (!isRecord(value)) return undefined;
-  const nested = value[objectKey];
-  return stringField(nested, key);
-}
-
 function parseNameWithOwner(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
   if (!value) return undefined;
   const [owner, repo, extra] = value.split("/");
@@ -172,6 +165,18 @@ function parseNameWithOwner(value: string | undefined): { readonly owner: string
   return { owner, repo };
 }
 
+function parsePullRequestUrl(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
+  if (!value) return undefined;
+  try {
+    const parsed = new URL(value);
+    const [owner, repo, type, number, extra] = parsed.pathname.split("/").filter(Boolean);
+    if (!owner || !repo || type !== "pull" || !number || extra !== undefined) return undefined;
+    return { owner, repo };
+  } catch {
+    return undefined;
+  }
+}
+
 function parsePostedCommentUrl(stdout: string): string | undefined {
   try {
     return stringField(JSON.parse(stdout), "html_url");

package/.pi/extensions/pi-workflow-engine/src/types.ts

@@ -3,6 +3,10 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Pipeline } from "./concurrency.ts";
 import type { PerfSink, PerfSnapshot } from "./perf.ts";
 import type { WorkflowProgressSnapshot } from "./progress.ts";
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+
+/** A reference to a registered workflow by name. */
+export type WorkflowRef = string;
 
 /** Metadata every workflow module must export. */
 export interface WorkflowMeta {
@@ -29,12 +33,22 @@ export interface WorkflowRunOptions {
   signal?: AbortSignal;
   /** Internal recorder override for command/tool invocation timing. */
   perfRecorder?: PerfSink;
+  /** Resolve a sub-workflow reference to a module, enabling `api.workflow()`. When omitted, `api.workflow()` throws. */
+  resolveWorkflow?: (ref: WorkflowRef) => Promise<WorkflowModule>;
   /** Called with the final performance snapshot when perf is enabled. */
   onPerfSnapshot?: (snapshot: PerfSnapshot) => void;
+  /** Called with the final workflow subagent usage snapshot. */
+  onUsageSnapshot?: (snapshot: WorkflowUsageSnapshot) => void;
+  /** Called with the live progress source while a workflow is running, then undefined when it ends. */
+  onProgressSource?: (source: WorkflowProgressSource | undefined) => void;
   /** Called with the final completed progress snapshot after live workflow UI teardown. */
   onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void;
 }
 
+export interface WorkflowProgressSource {
+  snapshot(): WorkflowProgressSnapshot;
+}
+
 /** Options for a single `agent()` call. */
 export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
 
@@ -56,7 +70,10 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   label?: string;
   /** Phase to group this agent under in the progress tree. */
   phase?: string;
-  /** Model id (e.g. "claude-opus-4-5"); omit to inherit the host's current model. */
+  /**
+   * Optional model id. Omit to inherit the host model. Explicit refs are strict:
+   * bare ids resolve as Anthropic shorthand; use "provider/id" for other providers.
+   */
   model?: string;
   /** Reasoning effort for this agent. */
   thinkingLevel?: ThinkingLevel;
@@ -75,6 +92,13 @@ export interface WorkflowApi {
   agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S> | null>;
   /** Run a subagent and return its final assistant text. */
   agent(prompt: string, opts?: AgentOptions): Promise<string>;
+  /**
+   * Run another registered workflow inline as a sub-step and return its result. The child shares
+   * this run's concurrency cap, abort signal, and perf sink. Nests one level only: calling
+   * `workflow()` from within a sub-workflow rejects. Rejects on unknown name — catch it to handle
+   * a missing sub-workflow gracefully.
+   */
+  workflow(ref: WorkflowRef, args?: string): Promise<unknown>;
   /** Run every thunk concurrently and wait for all (a barrier). */
   parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]>;
   /** Run each item through all stages independently — no barrier between stages. */