@g3un/pi-orchestra 0.1.1 → 0.2.0

package/README.md

@@ -15,9 +15,11 @@ pi -e npm:@g3un/pi-orchestra
 ```
 
 Pi-Orchestra registers four tools: `bus`, `subagent`, `workgroup`, and `workflow`.
-Active workflows are also shown in a TUI progress widget with the current stage
-and agent completion counts. Use `/orchestra-workflows` to reopen the widget if
-needed.
+Subagent, workgroup-member, and workflow completions are delivered back to the
+main agent as pi-orchestra events, so the main conversation stays responsive
+while delegated work runs. Active workflows are also shown in a TUI progress
+widget with the current stage and agent completion counts. Use
+`/orchestra-workflows` to reopen the widget if needed.
 
 ## Core concepts
 
@@ -29,7 +31,7 @@ Use subagents when you want to delegate a focused task, such as review, research
 
 ### Workgroup
 
-A workgroup starts multiple subagents on the same bus for one shared goal. Each member can have a different profile or assignment.
+A workgroup starts multiple subagents on the same bus for one shared goal. Each member can have a different profile or assignment. Member completions are delivered as `workgroup.member_finished` events with the strategy and pending run ids.
 
 Workgroups support two strategies:
 
@@ -38,12 +40,12 @@ Workgroups support two strategies:
 
 ### Workflow
 
-A workflow runs ordered workgroup stages. Each stage gets a fresh bus, starts its workers, collects results, and uses a stage leader to produce a canonical stage output.
+A workflow runs ordered workgroup stages. Each stage gets a fresh bus, starts its workers, collects results through internal finish-event subscriptions, and uses a stage leader to produce a canonical stage output. The main agent receives a single `workflow.finished` event for the whole workflow.
 
 Use workflows for multi-step plans where later stages should depend on the summarized output of earlier stages instead of raw worker transcripts.
 
 ## Notes
 
 - Create a `bus` before spawning related subagents or workgroups.
-- Subagents report completion with `success`, `blocked`, or `failed`.
+- Subagents report completion with `success`, `blocked`, or `failed`; completions are surfaced as pi-orchestra events.
 - Use `workflow` for linear staged work, not branching/DAG execution.

package/docs/orchestration-model.md

@@ -46,10 +46,12 @@ Strategies:
 - `compete`: one successful member can be enough.
 - `synthesize`: collect complementary findings and combine them.
 
-Leaders collect results with bus wait actions:
+Main receives finish events instead of blocking on completion calls:
 
-- `wait_next`: handle terminal runs as they finish.
-- `wait_settled`: wait until every attached run is terminal.
+- Standalone subagent completions arrive as `subagent.finished` events.
+- Workgroup member completions arrive as `workgroup.member_finished` events with the strategy and pending run ids.
+- For `compete`, a successful member may be enough; close pending losers when appropriate.
+- For `synthesize`, use each member event to decide whether to steer active members, spawn follow-up work, publish more context, or continue collecting results.
 
 ## Workflow
 
@@ -60,10 +62,12 @@ For each stage:
 
 1. Create a fresh bus.
 2. Spawn the worker workgroup.
-3. Collect worker results.
+3. Collect worker results through store finish-event subscriptions in the background.
 4. Spawn a restricted stage leader.
 5. Store the leader's canonical output as the stage output.
 
+Workflow-internal worker and leader completions are consumed by the workflow runner. Main receives a single `workflow.finished` event when the whole workflow reaches `success`, `blocked`, `failed`, or `closed`.
+
 The next stage receives the previous stage output, not raw worker transcripts.
 If no leader is provided, `createStageLeaderProfile` supplies a restricted
 leader with no tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3un/pi-orchestra",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Subagent orchestration tools for Pi.",
   "keywords": [
     "orchestration",
@@ -9,8 +9,16 @@
     "pi-package",
     "subagent"
   ],
+  "homepage": "https://codeberg.org/g3un/pi-orchestra",
+  "bugs": {
+    "url": "https://codeberg.org/g3un/pi-orchestra/issues"
+  },
   "license": "MIT",
   "author": "Changeun Park <g3un@protonmail.ch>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/g3un/pi-orchestra.git"
+  },
   "files": [
     "src/**/*.ts",
     "!src/**/*.test.ts",
@@ -19,6 +27,9 @@
     "LICENSE"
   ],
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "dev": "pi -e .",
     "fmt": "oxfmt",

package/src/core/orchestra.ts

@@ -1,7 +1,7 @@
 import type { AgentProfile, AgentRun } from "./subagent.ts";
 import type { Bus, BusMessage } from "./bus.ts";
 import type { AgentRuntime } from "./runtime.ts";
-import { createEntityIdentity, isTerminalAgentState, resolveWaitTimeoutMs, toWaitRunResult } from "../utils.ts";
+import { createEntityIdentity } from "../utils.ts";
 import type { AgentStore } from "./store.ts";
 
 export interface OrchestraApi {
@@ -14,8 +14,6 @@ export interface OrchestraApi {
   listRuns(options?: ListRunsOptions): AgentRun[];
   messageAgent(id: string, message: string, options?: RunLookupOptions): Promise<AgentRun>;
   closeAgent(id: string, options?: RunLookupOptions): Promise<AgentRun | undefined>;
-  waitBusSettled(busId: string, options?: WaitBusSettledOptions): Promise<WaitBusSettledResult>;
-  waitNextRun(busId: string, options?: WaitNextRunOptions): Promise<WaitNextRunResult>;
 }
 
 export interface CreateBusOptions {
@@ -31,44 +29,6 @@ export interface PublishedBusMessage {
   busMessage: BusMessage;
 }
 
-export interface WaitBusSettledResult {
-  bus: Bus;
-  runs: AgentRun[];
-  runResults: WaitRunResult[];
-  timedOut: boolean;
-  pendingRunIds: string[];
-}
-
-export interface WaitNextRunResult {
-  bus: Bus;
-  run?: AgentRun;
-  runResult?: WaitRunResult;
-  runs: AgentRun[];
-  runResults: WaitRunResult[];
-  timedOut: boolean;
-  pendingRunIds: string[];
-}
-
-export interface WaitRunResult {
-  runId: string;
-  name: string;
-  profile: string;
-  state: AgentRun["state"];
-  result?: AgentRun["result"];
-}
-
-export interface WaitBusSettledOptions {
-  /** Defaults to 10 minutes. Use null to wait indefinitely. */
-  timeoutMs?: number | null;
-}
-
-export interface WaitNextRunOptions {
-  /** Defaults to 10 minutes. Use null to wait indefinitely. */
-  timeoutMs?: number | null;
-  /** Run ids or names that have already been handled by the leader. */
-  excludeRunIds?: string[];
-}
-
 export interface ListRunsOptions {
   busId?: string;
 }
@@ -140,121 +100,6 @@ export class Orchestra implements OrchestraApi {
     return await this.runtime.close(run?.id ?? id);
   }
 
-  waitBusSettled(busId: string, options: WaitBusSettledOptions = {}): Promise<WaitBusSettledResult> {
-    const timeoutMs = resolveWaitTimeoutMs("waitBusSettled", options.timeoutMs);
-    const bus = this.requireBus(busId);
-    const initialRuns = this.listRuns({ busId: bus.id });
-    if (initialRuns.every((run) => isTerminalAgentState(run.state))) {
-      return Promise.resolve(buildWaitBusSettledResult(bus, initialRuns, false));
-    }
-
-    return new Promise((resolve) => {
-      const latestRuns = new Map(initialRuns.map((run) => [run.id, run]));
-      const unsubscribeAll: Array<() => void> = [];
-      let settled = false;
-      let timeout: ReturnType<typeof setTimeout> | undefined;
-
-      const cleanup = () => {
-        if (timeout) clearTimeout(timeout);
-        for (const unsubscribe of unsubscribeAll.splice(0)) unsubscribe();
-      };
-
-      const getLatestRuns = () => initialRuns.map((run) => latestRuns.get(run.id) ?? run);
-
-      const resolveIfDone = () => {
-        const runs = getLatestRuns();
-        if (runs.some((run) => !isTerminalAgentState(run.state))) return;
-
-        settled = true;
-        cleanup();
-        resolve(buildWaitBusSettledResult(bus, runs, false));
-      };
-
-      if (timeoutMs !== null) {
-        timeout = setTimeout(() => {
-          if (settled) return;
-
-          settled = true;
-          cleanup();
-          resolve(buildWaitBusSettledResult(bus, getLatestRuns(), true));
-        }, timeoutMs);
-      }
-
-      for (const run of initialRuns) {
-        if (isTerminalAgentState(run.state)) continue;
-        unsubscribeAll.push(
-          this.store.subscribeRuns(
-            (updatedRun) => {
-              if (settled) return;
-              latestRuns.set(updatedRun.id, updatedRun);
-              resolveIfDone();
-            },
-            (updatedRun) => updatedRun.id === run.id,
-          ),
-        );
-      }
-
-      resolveIfDone();
-    });
-  }
-
-  waitNextRun(busId: string, options: WaitNextRunOptions = {}): Promise<WaitNextRunResult> {
-    const timeoutMs = resolveWaitTimeoutMs("waitNextRun", options.timeoutMs);
-    const bus = this.requireBus(busId);
-    const initialRuns = this.listRuns({ busId: bus.id });
-    const excludedRunIds = this.resolveExcludedRunIds(initialRuns, options.excludeRunIds ?? []);
-    const candidateRuns = initialRuns.filter((run) => !excludedRunIds.has(run.id));
-    const alreadyDone = candidateRuns.find((run) => isTerminalAgentState(run.state));
-    if (alreadyDone || candidateRuns.length === 0) {
-      return Promise.resolve(buildWaitNextRunResult(bus, initialRuns, alreadyDone, false, excludedRunIds));
-    }
-
-    return new Promise((resolve) => {
-      const latestRuns = new Map(initialRuns.map((run) => [run.id, run]));
-      const unsubscribeAll: Array<() => void> = [];
-      let settled = false;
-      let timeout: ReturnType<typeof setTimeout> | undefined;
-
-      const cleanup = () => {
-        if (timeout) clearTimeout(timeout);
-        for (const unsubscribe of unsubscribeAll.splice(0)) unsubscribe();
-      };
-
-      const getLatestRuns = () => initialRuns.map((run) => latestRuns.get(run.id) ?? run);
-
-      const resolveWithRun = (run: AgentRun) => {
-        settled = true;
-        cleanup();
-        resolve(buildWaitNextRunResult(bus, getLatestRuns(), run, false, excludedRunIds));
-      };
-
-      if (timeoutMs !== null) {
-        timeout = setTimeout(() => {
-          if (settled) return;
-
-          settled = true;
-          cleanup();
-          resolve(buildWaitNextRunResult(bus, getLatestRuns(), undefined, true, excludedRunIds));
-        }, timeoutMs);
-      }
-
-      for (const run of initialRuns) {
-        if (isTerminalAgentState(run.state)) continue;
-        unsubscribeAll.push(
-          this.store.subscribeRuns(
-            (updatedRun) => {
-              if (settled) return;
-              latestRuns.set(updatedRun.id, updatedRun);
-              if (!excludedRunIds.has(updatedRun.id) && isTerminalAgentState(updatedRun.state))
-                resolveWithRun(updatedRun);
-            },
-            (updatedRun) => updatedRun.id === run.id,
-          ),
-        );
-      }
-    });
-  }
-
   private requireBus(id: string): Bus {
     const bus = this.findBus(id);
     if (!bus) throw new Error(`Bus ${id} not found.`);
@@ -279,15 +124,6 @@ export class Orchestra implements OrchestraApi {
     return this.store.listRuns().find((run) => run.name === id && (!bus || run.busId === bus.id));
   }
 
-  private resolveExcludedRunIds(busRuns: AgentRun[], excludedRunIds: string[]): Set<string> {
-    const resolvedIds = new Set<string>();
-    for (const id of excludedRunIds) {
-      const run = busRuns.find((current) => current.id === id || current.name === id);
-      resolvedIds.add(run?.id ?? id);
-    }
-    return resolvedIds;
-  }
-
   private createBusIdentity(name: string | undefined) {
     return createEntityIdentity(name, "bus", this.store.listBuses(), "Bus");
   }
@@ -296,33 +132,3 @@ export class Orchestra implements OrchestraApi {
     return createEntityIdentity(name, profile.name, this.store.listRuns(), "Agent");
   }
 }
-
-function buildWaitBusSettledResult(bus: Bus, runs: AgentRun[], timedOut: boolean): WaitBusSettledResult {
-  return {
-    bus,
-    runs,
-    runResults: runs.map(toWaitRunResult),
-    timedOut,
-    pendingRunIds: runs.filter((run) => !isTerminalAgentState(run.state)).map((run) => run.id),
-  };
-}
-
-function buildWaitNextRunResult(
-  bus: Bus,
-  runs: AgentRun[],
-  run: AgentRun | undefined,
-  timedOut: boolean,
-  excludedRunIds: Set<string>,
-): WaitNextRunResult {
-  return {
-    bus,
-    run,
-    runResult: run ? toWaitRunResult(run) : undefined,
-    runs,
-    runResults: runs.map(toWaitRunResult),
-    timedOut,
-    pendingRunIds: runs
-      .filter((current) => !excludedRunIds.has(current.id) && !isTerminalAgentState(current.state))
-      .map((current) => current.id),
-  };
-}

package/src/core/subagent.ts

@@ -25,3 +25,11 @@ export interface AgentRun {
   state: AgentState;
   result?: AgentResult;
 }
+
+export interface AgentRunResult {
+  runId: string;
+  name: string;
+  profile: string;
+  state: AgentRun["state"];
+  result?: AgentRun["result"];
+}

package/src/extension/index.ts

@@ -6,6 +6,7 @@ import { createBusTool, defineBusPiTool, type BusTool } from "../tools/bus.ts";
 import { createSubagentTool, defineSubagentPiTool, type SubagentTool } from "../tools/subagent.ts";
 import { createWorkflowTool, defineWorkflowPiTool, type WorkflowTool } from "../tools/workflow.ts";
 import { createWorkgroupTool, defineWorkgroupPiTool, type WorkgroupTool } from "../tools/workgroup.ts";
+import { ORCHESTRA_EVENT_CUSTOM_TYPE, OrchestraEventController, type OrchestraMainEvent } from "./orchestra-events.ts";
 import { WorkflowMonitorController } from "./workflow-monitor.ts";
 
 interface ToolBundle {
@@ -14,11 +15,12 @@ interface ToolBundle {
   workgroupTool: WorkgroupTool;
   workflowTool: WorkflowTool;
   workflowMonitor: WorkflowMonitorController;
+  orchestraEvents: OrchestraEventController;
 }
 
 export default function piOrchestraExtension(pi: ExtensionAPI): void {
   const bundles = new Map<string, ToolBundle>();
-  const getToolBundle = (ctx: ExtensionContext) => getBundle(bundles, ctx);
+  const getToolBundle = (ctx: ExtensionContext) => getBundle(pi, bundles, ctx);
 
   pi.registerTool(defineBusPiTool((ctx) => getToolBundle(ctx).busTool));
   pi.registerTool(defineSubagentPiTool((ctx) => getToolBundle(ctx).subagentTool));
@@ -44,7 +46,7 @@ export default function piOrchestraExtension(pi: ExtensionAPI): void {
   });
 }
 
-function getBundle(bundles: Map<string, ToolBundle>, ctx: ExtensionContext): ToolBundle {
+function getBundle(pi: ExtensionAPI, bundles: Map<string, ToolBundle>, ctx: ExtensionContext): ToolBundle {
   const existing = bundles.get(ctx.cwd);
   if (existing) return existing;
 
@@ -55,17 +57,45 @@ function getBundle(bundles: Map<string, ToolBundle>, ctx: ExtensionContext): Too
     resolveModel: (model) => resolveModel(ctx, model),
   });
   const orchestra = new Orchestra({ runtime, store });
+  const orchestraEvents = new OrchestraEventController({
+    store,
+    sendEvents: (events, content) => sendOrchestraEvents(pi, events, content),
+  });
+  const workgroupTool = createWorkgroupTool({
+    orchestra,
+    onWorkgroupLaunching: ({ input, bus }) => orchestraEvents.beginWorkgroup(bus.id, input.strategy),
+    onWorkgroupLaunched: ({ input, output }) =>
+      orchestraEvents.registerWorkgroup({
+        busId: output.bus.id,
+        strategy: input.strategy,
+        runIds: output.runs.map((run) => run.id),
+      }),
+    onWorkgroupLaunchFailed: ({ bus }) => orchestraEvents.cancelWorkgroupLaunch(bus.id),
+  });
   const bundle = {
     busTool: createBusTool({ orchestra }),
     subagentTool: createSubagentTool({ orchestra }),
-    workgroupTool: createWorkgroupTool({ orchestra }),
+    workgroupTool,
     workflowTool: createWorkflowTool({ orchestra, store }),
     workflowMonitor: new WorkflowMonitorController(store),
+    orchestraEvents,
   };
   bundles.set(ctx.cwd, bundle);
   return bundle;
 }
 
+function sendOrchestraEvents(pi: ExtensionAPI, events: OrchestraMainEvent[], content: string): void {
+  pi.sendMessage(
+    {
+      customType: ORCHESTRA_EVENT_CUSTOM_TYPE,
+      content,
+      display: true,
+      details: { events },
+    },
+    { deliverAs: "steer", triggerTurn: true },
+  );
+}
+
 function resolveModel(ctx: ExtensionContext, model: string): ReturnType<ExtensionContext["modelRegistry"]["find"]> {
   const slashIndex = model.indexOf("/");
   if (slashIndex < 0) {

package/src/extension/orchestra-events.ts

@@ -0,0 +1,231 @@
+import type { AgentRun, AgentRunResult, AgentState } from "../core/subagent.ts";
+import type { AgentStore } from "../core/store.ts";
+import type { WorkflowRun } from "../core/workflow.ts";
+import type { WorkgroupStrategy } from "../core/workgroup.ts";
+import { formatNamedEntityLabel, isTerminalAgentState, toAgentRunResult } from "../utils.ts";
+
+export const ORCHESTRA_EVENT_CUSTOM_TYPE = "pi-orchestra.event";
+
+export type OrchestraMainEvent =
+  | {
+      type: "subagent.finished";
+      busId: string;
+      run: AgentRunResult;
+    }
+  | {
+      type: "workgroup.member_finished";
+      busId: string;
+      strategy: WorkgroupStrategy;
+      run: AgentRunResult;
+      pendingRunIds: string[];
+    }
+  | {
+      type: "workflow.finished";
+      workflow: WorkflowRun;
+    };
+
+export interface WorkgroupRegistration {
+  busId: string;
+  strategy: WorkgroupStrategy;
+  runIds: string[];
+}
+
+export interface OrchestraEventControllerOptions {
+  store: AgentStore;
+  sendEvents: (events: OrchestraMainEvent[], content: string) => void;
+  /** Defaults to 50 ms. Use 0 in tests for immediate delivery. */
+  flushDelayMs?: number;
+}
+
+interface RegisteredWorkgroup {
+  strategy: WorkgroupStrategy;
+  runIds: Set<string>;
+}
+
+interface LaunchingWorkgroup {
+  strategy: WorkgroupStrategy;
+  finishedRunIds: Set<string>;
+}
+
+export class OrchestraEventController {
+  private readonly store: AgentStore;
+  private readonly sendEvents: OrchestraEventControllerOptions["sendEvents"];
+  private readonly flushDelayMs: number;
+  private readonly runStates = new Map<string, AgentState>();
+  private readonly workflowStates = new Map<string, AgentState>();
+  private readonly mainWorkgroupsByBusId = new Map<string, RegisteredWorkgroup>();
+  private readonly launchingWorkgroupsByBusId = new Map<string, LaunchingWorkgroup>();
+  private readonly queuedEvents: OrchestraMainEvent[] = [];
+  private readonly unsubscribeRuns: () => void;
+  private readonly unsubscribeWorkflows: () => void;
+  private flushTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(options: OrchestraEventControllerOptions) {
+    this.store = options.store;
+    this.sendEvents = options.sendEvents;
+    this.flushDelayMs = options.flushDelayMs ?? 50;
+
+    for (const run of this.store.listRuns()) this.runStates.set(run.id, run.state);
+    for (const workflow of this.store.listWorkflows()) this.workflowStates.set(workflow.id, workflow.state);
+
+    this.unsubscribeRuns = this.store.subscribeRuns((run) => this.handleRunSaved(run));
+    this.unsubscribeWorkflows = this.store.subscribeWorkflows((workflow) => this.handleWorkflowSaved(workflow));
+  }
+
+  beginWorkgroup(busId: string, strategy: WorkgroupStrategy): void {
+    this.launchingWorkgroupsByBusId.set(busId, { strategy, finishedRunIds: new Set() });
+  }
+
+  registerWorkgroup(registration: WorkgroupRegistration): void {
+    const launching = this.launchingWorkgroupsByBusId.get(registration.busId);
+    const existing = this.mainWorkgroupsByBusId.get(registration.busId);
+    const runIds = new Set<string>(existing?.runIds);
+    for (const runId of launching?.finishedRunIds ?? []) runIds.add(runId);
+    for (const runId of registration.runIds) runIds.add(runId);
+
+    this.mainWorkgroupsByBusId.set(registration.busId, {
+      strategy: registration.strategy,
+      runIds,
+    });
+    this.launchingWorkgroupsByBusId.delete(registration.busId);
+  }
+
+  cancelWorkgroupLaunch(busId: string): void {
+    this.launchingWorkgroupsByBusId.delete(busId);
+  }
+
+  dispose(): void {
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = undefined;
+    this.queuedEvents.length = 0;
+    this.unsubscribeRuns();
+    this.unsubscribeWorkflows();
+  }
+
+  flush(): void {
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = undefined;
+    if (this.queuedEvents.length === 0) return;
+
+    const events = this.queuedEvents.splice(0);
+    this.sendEvents(events, formatOrchestraEvents(events));
+  }
+
+  private handleRunSaved(run: AgentRun): void {
+    const previousState = this.runStates.get(run.id);
+    this.runStates.set(run.id, run.state);
+
+    if (!isAgentFinishState(run.state) || isAgentFinishState(previousState)) return;
+    if (this.isWorkflowBus(run.busId)) return;
+
+    const registeredWorkgroup = this.mainWorkgroupsByBusId.get(run.busId);
+    if (registeredWorkgroup?.runIds.has(run.id)) {
+      this.queueEvent({
+        type: "workgroup.member_finished",
+        busId: run.busId,
+        strategy: registeredWorkgroup.strategy,
+        run: toAgentRunResult(run),
+        pendingRunIds: this.getPendingWorkgroupRunIds(run.busId, registeredWorkgroup.runIds),
+      });
+      return;
+    }
+
+    const launchingWorkgroup = this.launchingWorkgroupsByBusId.get(run.busId);
+    if (launchingWorkgroup) {
+      launchingWorkgroup.finishedRunIds.add(run.id);
+      this.queueEvent({
+        type: "workgroup.member_finished",
+        busId: run.busId,
+        strategy: launchingWorkgroup.strategy,
+        run: toAgentRunResult(run),
+        pendingRunIds: this.getPendingBusRunIds(run.busId),
+      });
+      return;
+    }
+
+    this.queueEvent({ type: "subagent.finished", busId: run.busId, run: toAgentRunResult(run) });
+  }
+
+  private handleWorkflowSaved(workflow: WorkflowRun): void {
+    const previousState = this.workflowStates.get(workflow.id);
+    this.workflowStates.set(workflow.id, workflow.state);
+
+    if (!isTerminalAgentState(workflow.state) || isTerminalWorkflowState(previousState)) return;
+    this.queueEvent({ type: "workflow.finished", workflow });
+  }
+
+  private isWorkflowBus(busId: string): boolean {
+    return this.store.listWorkflows().some((workflow) => workflow.stages.some((stage) => stage.busId === busId));
+  }
+
+  private getPendingWorkgroupRunIds(busId: string, runIds: Set<string>): string[] {
+    return this.store
+      .listRuns()
+      .filter((run) => run.busId === busId && runIds.has(run.id) && run.state === "idle")
+      .map((run) => run.id);
+  }
+
+  private getPendingBusRunIds(busId: string): string[] {
+    return this.store
+      .listRuns()
+      .filter((run) => run.busId === busId && run.state === "idle")
+      .map((run) => run.id);
+  }
+
+  private queueEvent(event: OrchestraMainEvent): void {
+    this.queuedEvents.push(event);
+    if (this.flushDelayMs === 0) {
+      this.flush();
+      return;
+    }
+
+    this.flushTimer ??= setTimeout(() => this.flush(), this.flushDelayMs);
+  }
+}
+
+export function formatOrchestraEvents(events: OrchestraMainEvent[]): string {
+  const headline = events.length === 1 ? "Pi-orchestra event:" : `Pi-orchestra events (${events.length}):`;
+  return [headline, ...events.flatMap((event) => ["", formatOrchestraEvent(event)])].join("\n");
+}
+
+function formatOrchestraEvent(event: OrchestraMainEvent): string {
+  if (event.type === "workflow.finished") return formatWorkflowFinishedEvent(event.workflow);
+
+  const runLabel = event.run.name === event.run.runId ? event.run.runId : `${event.run.name} (${event.run.runId})`;
+  const lines =
+    event.type === "workgroup.member_finished"
+      ? [
+          `- Workgroup member finished on bus ${event.busId}: ${runLabel} is ${event.run.state}.`,
+          `  Strategy: ${event.strategy}`,
+          `  Pending workgroup run ids: ${event.pendingRunIds.length > 0 ? event.pendingRunIds.join(", ") : "none"}`,
+        ]
+      : [`- Subagent finished on bus ${event.busId}: ${runLabel} is ${event.run.state}.`];
+
+  lines.push(...formatRunResultLines(event.run));
+  return lines.join("\n");
+}
+
+function formatWorkflowFinishedEvent(workflow: WorkflowRun): string {
+  const lines = [`- Workflow finished: ${formatNamedEntityLabel(workflow)} is ${workflow.state}.`];
+  if (workflow.result) {
+    lines.push(`  Result: ${workflow.result.status}`, `  Summary: ${workflow.result.summary}`);
+  }
+  if (workflow.error) lines.push(`  Error: ${workflow.error}`);
+  return lines.join("\n");
+}
+
+function formatRunResultLines(run: AgentRunResult): string[] {
+  if (!run.result) return ["  No result payload recorded."];
+
+  const lines = [`  Result: ${run.result.status}`, `  Summary: ${run.result.summary}`];
+  if (run.result.data !== undefined) lines.push(`  Data: ${JSON.stringify(run.result.data)}`);
+  return lines;
+}
+
+function isAgentFinishState(state: AgentState | undefined): boolean {
+  return state === "success" || state === "blocked" || state === "failed";
+}
+
+function isTerminalWorkflowState(state: AgentState | undefined): boolean {
+  return state !== undefined && isTerminalAgentState(state);
+}