@g3un/pi-orchestra 0.1.0 → 0.2.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);
+}

package/src/extension/workflow-monitor.ts

@@ -0,0 +1,143 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentRun } from "../core/subagent.ts";
+import type { AgentStore } from "../core/store.ts";
+import type { WorkflowRun, WorkflowStageRun } from "../core/workflow.ts";
+import { formatNamedEntityLabel, isTerminalAgentState } from "../utils.ts";
+
+const WIDGET_KEY = "pi-orchestra.workflow-monitor";
+const MAX_MONITORED_WORKFLOWS = 2;
+const MAX_WIDGET_LINES = 10;
+
+export class WorkflowMonitorController {
+  private unsubscribe?: () => void;
+  private ctx?: ExtensionContext;
+
+  constructor(private readonly store: AgentStore) {}
+
+  hasActiveWorkflows(): boolean {
+    return listActiveWorkflows(this.store).length > 0;
+  }
+
+  show(ctx: ExtensionContext): boolean {
+    if (!ctx.hasUI) return false;
+
+    this.ctx = ctx;
+    if (!this.unsubscribe) {
+      const unsubscribeRuns = this.store.subscribeRuns(() => this.render());
+      const unsubscribeWorkflows = this.store.subscribeWorkflows(() => this.render());
+      this.unsubscribe = () => {
+        unsubscribeRuns();
+        unsubscribeWorkflows();
+      };
+    }
+
+    return this.render();
+  }
+
+  dispose(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+
+    if (this.ctx?.hasUI) {
+      this.ctx.ui.setWidget(WIDGET_KEY, undefined);
+    }
+    this.ctx = undefined;
+  }
+
+  private render(): boolean {
+    const ctx = this.ctx;
+    if (!ctx?.hasUI) return false;
+
+    const lines = buildWorkflowMonitorLines(this.store);
+    if (lines.length === 0) {
+      this.dispose();
+      return false;
+    }
+
+    ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "belowEditor" });
+    return true;
+  }
+}
+
+export function buildWorkflowMonitorLines(store: AgentStore): string[] {
+  const workflows = listActiveWorkflows(store);
+  if (workflows.length === 0) return [];
+
+  const lines: string[] = [];
+  for (const workflow of workflows.slice(0, MAX_MONITORED_WORKFLOWS)) {
+    appendWorkflowLines(lines, store, workflow);
+    if (lines.length >= MAX_WIDGET_LINES) break;
+  }
+
+  const hiddenWorkflowCount = workflows.length - MAX_MONITORED_WORKFLOWS;
+  if (hiddenWorkflowCount > 0 && lines.length < MAX_WIDGET_LINES) {
+    lines.push(`... +${hiddenWorkflowCount} more active ${pluralize("workflow", hiddenWorkflowCount)}`);
+  }
+
+  return lines.slice(0, MAX_WIDGET_LINES);
+}
+
+function appendWorkflowLines(lines: string[], store: AgentStore, workflow: WorkflowRun): void {
+  if (lines.length >= MAX_WIDGET_LINES) return;
+
+  const stage = getCurrentStage(workflow);
+  const stageLabel = stage ? formatStageLabel(store, workflow, stage) : "none · agents 0/0";
+  lines.push(`${formatNamedEntityLabel(workflow)} | ${stageLabel}`);
+}
+
+function listActiveWorkflows(store: AgentStore): WorkflowRun[] {
+  return store.listWorkflows().filter((workflow) => !isTerminalAgentState(workflow.state));
+}
+
+function getCurrentStage(workflow: WorkflowRun): WorkflowStageRun | undefined {
+  return (
+    workflow.stages[workflow.currentStageIndex] ?? workflow.stages.find((stage) => !isTerminalAgentState(stage.state))
+  );
+}
+
+function formatStageLabel(store: AgentStore, workflow: WorkflowRun, stage: WorkflowStageRun): string {
+  const stageIndex = workflow.stages.indexOf(stage);
+  const stagePosition = stageIndex >= 0 ? `${stageIndex + 1}/${workflow.stages.length}` : `?/${workflow.stages.length}`;
+  return `${stage.name} · step ${stagePosition} · agents ${formatStageProgress(store, stage)}`;
+}
+
+function formatStageProgress(store: AgentStore, stage: WorkflowStageRun): string {
+  const progress = calculateStageProgress(store, stage);
+  return `${progress.completed}/${progress.total}`;
+}
+
+function calculateStageProgress(store: AgentStore, stage: WorkflowStageRun): { completed: number; total: number } {
+  const runs = collectStageRuns(store, stage);
+  const completed = runs.filter((run) => isTerminalAgentState(run.state)).length;
+  const workerRunCount = runs.filter((run) => run.id !== stage.leaderRunId).length;
+  const workerTotal = Math.max(stage.members.length, stage.workerRunIds.length, workerRunCount);
+  const leaderTotal = stage.phase === "leader" || stage.leaderRunId !== undefined ? 1 : 0;
+  const total = Math.max(workerTotal + leaderTotal, runs.length);
+  return { completed: Math.min(completed, total), total };
+}
+
+function collectStageRuns(store: AgentStore, stage: WorkflowStageRun): AgentRun[] {
+  const runsById = new Map<string, AgentRun>();
+
+  for (const runId of stage.workerRunIds) {
+    const run = store.getRun(runId);
+    if (run) runsById.set(run.id, run);
+  }
+
+  if (stage.leaderRunId) {
+    const leaderRun = store.getRun(stage.leaderRunId);
+    if (leaderRun) runsById.set(leaderRun.id, leaderRun);
+  }
+
+  if (stage.busId) {
+    for (const run of store.listRuns().filter((current) => current.busId === stage.busId)) {
+      runsById.set(run.id, run);
+    }
+  }
+
+  return [...runsById.values()];
+}
+
+function pluralize(noun: string, count: number): string {
+  return count === 1 ? noun : `${noun}s`;
+}

package/src/tools/bus.ts

@@ -1,8 +1,7 @@
 import { defineTool, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { AgentRun } from "../core/subagent.ts";
 import type { Bus, BusMessage } from "../core/bus.ts";
-import type { OrchestraApi, WaitBusSettledResult, WaitNextRunResult, WaitRunResult } from "../core/orchestra.ts";
+import type { OrchestraApi } from "../core/orchestra.ts";
 import { formatNamedEntityLabel } from "../utils.ts";
 
 export type BusInput =
@@ -19,31 +18,11 @@ export type BusInput =
       id: string;
       message: string;
       from?: string;
-    }
-  | {
-      action: "wait_settled";
-      id: string;
-      /** Defaults to 10 minutes. Use null to wait indefinitely. */
-      timeoutMs?: number | null;
-    }
-  | {
-      action: "wait_next";
-      id: string;
-      /** Run ids or names to ignore. */
-      excludeRunIds?: string[];
-      /** Defaults to 10 minutes. Use null to wait indefinitely. */
-      timeoutMs?: number | null;
     };
 
 export interface BusOutput {
   bus?: Bus;
   busMessage?: BusMessage;
-  run?: AgentRun;
-  runResult?: WaitRunResult;
-  runs?: AgentRun[];
-  runResults?: WaitRunResult[];
-  timedOut?: boolean;
-  pendingRunIds?: string[];
   message: string;
 }
 
@@ -57,8 +36,8 @@ export interface BusToolDeps {
 }
 
 const BusActionParams = Type.String({
-  enum: ["create", "status", "publish", "wait_settled", "wait_next"],
-  description: "create/status/publish; wait_settled waits all attached runs; wait_next waits the next terminal run.",
+  enum: ["create", "status", "publish"],
+  description: "create/status/publish shared context buses; completion is delivered through pi-orchestra events.",
 });
 
 const BusToolParams = Type.Object(
@@ -79,24 +58,6 @@ const BusToolParams = Type.Object(
         description: "Required for action=publish. Shared context for attached agents.",
       }),
     ),
-    excludeRunIds: Type.Optional(
-      Type.Array(Type.String(), {
-        description: "Optional for action=wait_next. Already handled run ids/names.",
-      }),
-    ),
-    timeoutMs: Type.Optional(
-      Type.Union(
-        [
-          Type.Number({
-            exclusiveMinimum: 0,
-          }),
-          Type.Null(),
-        ],
-        {
-          description: "Optional for wait actions. Positive ms; default 10 min; null waits indefinitely.",
-        },
-      ),
-    ),
   },
   { additionalProperties: false },
 );
@@ -118,35 +79,6 @@ export function createBusTool({ orchestra }: BusToolDeps): BusTool {
         return { bus, message: formatBusStatus(bus) };
       }
 
-      if (input.action === "wait_settled") {
-        const output = await orchestra.waitBusSettled(bus.id, { timeoutMs: input.timeoutMs });
-        return {
-          bus: output.bus,
-          runs: output.runs,
-          runResults: output.runResults,
-          timedOut: output.timedOut,
-          pendingRunIds: output.pendingRunIds,
-          message: formatWaitBusSettledMessage(output),
-        };
-      }
-
-      if (input.action === "wait_next") {
-        const output = await orchestra.waitNextRun(bus.id, {
-          excludeRunIds: input.excludeRunIds,
-          timeoutMs: input.timeoutMs,
-        });
-        return {
-          bus: output.bus,
-          run: output.run,
-          runResult: output.runResult,
-          runs: output.runs,
-          runResults: output.runResults,
-          timedOut: output.timedOut,
-          pendingRunIds: output.pendingRunIds,
-          message: formatWaitNextRunMessage(output),
-        };
-      }
-
       const published = await orchestra.publishBus(input.id, input.message, input.from ?? "main");
       return {
         bus: published.bus,
@@ -161,13 +93,12 @@ export function defineBusPiTool(resolveTool: (ctx: ExtensionContext) => BusTool)
   return defineTool({
     name: "bus",
     label: "Bus",
-    description: "Create, inspect, publish to, and wait on work buses.",
-    promptSnippet:
-      "Use one bus per delegated work item; spawn related subagents on it and collect results with wait actions.",
+    description: "Create, inspect, and publish to work buses.",
+    promptSnippet: "Use one bus per delegated work item; spawn related subagents or workgroups on it.",
     promptGuidelines: [
-      "Create a bus before spawning related subagents; reuse it for that work item.",
-      "publish sends shared context to attached agents; status shows published messages.",
-      "wait_next handles results as they arrive; wait_settled waits for full fan-in.",
+      "Use bus create before spawning related subagents or workgroups; reuse it for that work item.",
+      "Use bus publish to send shared context to attached agents; bus status shows published messages.",
+      "Do not wait on buses; pi-orchestra delivers subagent and workgroup finish events automatically.",
     ],
     parameters: BusToolParams,
     executionMode: "sequential",
@@ -190,21 +121,6 @@ function toBusInput(params: RawBusParams): BusInput {
     return { action: "status", id: params.id };
   }
 
-  if (params.action === "wait_settled") {
-    if (!params.id) throw new Error("bus action=wait_settled requires id.");
-    return { action: "wait_settled", id: params.id, timeoutMs: params.timeoutMs };
-  }
-
-  if (params.action === "wait_next") {
-    if (!params.id) throw new Error("bus action=wait_next requires id.");
-    return {
-      action: "wait_next",
-      id: params.id,
-      excludeRunIds: params.excludeRunIds,
-      timeoutMs: params.timeoutMs,
-    };
-  }
-
   if (!params.id) throw new Error("bus action=publish requires id.");
   if (!params.message) throw new Error("bus action=publish requires message.");
   return { action: "publish", id: params.id, message: params.message };
@@ -227,49 +143,9 @@ function formatBusMessage(message: BusMessage): string {
   return [`- ${message.id} from ${message.from}:`, message.message].join("\n");
 }
 
-function formatWaitBusSettledMessage(result: WaitBusSettledResult): string {
-  const busLabel = formatNamedEntityLabel(result.bus);
-  const headline = result.timedOut
-    ? `Timed out waiting for bus ${busLabel} to settle; ${result.pendingRunIds.length} run(s) still pending.`
-    : `All ${result.runs.length} run(s) attached to bus ${busLabel} reached terminal state.`;
-  if (result.runs.length === 0) return headline;
-
-  return [headline, "", "Runs:", ...result.runs.map(formatRunSummary)].join("\n");
-}
-
-function formatRunSummary(run: AgentRun): string {
-  const runLabel = formatNamedEntityLabel(run);
-  if (!run.result) return `- ${runLabel}: ${run.state}`;
-  return `- ${runLabel}: ${run.state} result=${run.result.status} summary=${run.result.summary}`;
-}
-
-function formatWaitNextRunMessage(result: WaitNextRunResult): string {
-  const busLabel = formatNamedEntityLabel(result.bus);
-  if (result.run) {
-    return [
-      `Next terminal run on bus ${busLabel}: ${formatNamedEntityLabel(result.run)} is ${result.run.state}.`,
-      "",
-      formatRunResult(result.run),
-    ].join("\n");
-  }
-
-  if (result.timedOut) {
-    return `Timed out waiting for the next run on bus ${busLabel}; ${result.pendingRunIds.length} run(s) still pending.`;
-  }
-
-  return `No unhandled current runs remain on bus ${busLabel}.`;
-}
-
-function formatRunResult(run: AgentRun): string {
-  if (!run.result) return "No result payload recorded.";
-  return [`Result: ${run.result.status}`, run.result.summary].join("\n");
-}
-
 type RawBusParams = {
-  action: "create" | "status" | "publish" | "wait_settled" | "wait_next";
+  action: "create" | "status" | "publish";
   name?: string;
   id?: string;
   message?: string;
-  excludeRunIds?: string[];
-  timeoutMs?: number | null;
 };