@g3un/pi-orchestra 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,11 @@ pi -e npm:@g3un/pi-orchestra
 ```
 
 Pi-Orchestra registers four tools: `bus`, `subagent`, `workgroup`, and `workflow`.
+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
 
@@ -26,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:
 
@@ -35,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.0",
+  "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/adapters/in-memory-store.ts

@@ -3,16 +3,21 @@ import type { Bus, BusMessage } from "../core/bus.ts";
 import type { AgentStore } from "../core/store.ts";
 import type { WorkflowRun } from "../core/workflow.ts";
 
+interface StoreSubscription<T> {
+  listener(value: T): void;
+  filter?: (value: T) => boolean;
+}
+
 export class InMemoryAgentStore implements AgentStore {
   private readonly runs = new Map<string, AgentRun>();
   private readonly buses = new Map<string, Bus>();
   private readonly workflows = new Map<string, WorkflowRun>();
-  private readonly runListeners = new Map<string, Set<(run: AgentRun) => void>>();
-  private readonly workflowListeners = new Map<string, Set<(workflow: WorkflowRun) => void>>();
+  private readonly runSubscriptions = new Set<StoreSubscription<AgentRun>>();
+  private readonly workflowSubscriptions = new Set<StoreSubscription<WorkflowRun>>();
 
   saveRun(run: AgentRun): void {
     this.runs.set(run.id, run);
-    for (const listener of this.runListeners.get(run.id) ?? []) listener(run);
+    notifySubscribers(this.runSubscriptions, run);
   }
 
   getRun(id: string): AgentRun | undefined {
@@ -23,15 +28,10 @@ export class InMemoryAgentStore implements AgentStore {
     return [...this.runs.values()];
   }
 
-  subscribeRun(id: string, listener: (run: AgentRun) => void): () => void {
-    const listeners = this.runListeners.get(id) ?? new Set<(run: AgentRun) => void>();
-    listeners.add(listener);
-    this.runListeners.set(id, listeners);
-
-    return () => {
-      listeners.delete(listener);
-      if (listeners.size === 0) this.runListeners.delete(id);
-    };
+  subscribeRuns(listener: (run: AgentRun) => void, filter?: (run: AgentRun) => boolean): () => void {
+    const subscription = { listener, filter };
+    this.runSubscriptions.add(subscription);
+    return () => this.runSubscriptions.delete(subscription);
   }
 
   saveBus(bus: Bus): void {
@@ -61,7 +61,7 @@ export class InMemoryAgentStore implements AgentStore {
 
   saveWorkflow(workflow: WorkflowRun): void {
     this.workflows.set(workflow.id, workflow);
-    for (const listener of this.workflowListeners.get(workflow.id) ?? []) listener(workflow);
+    notifySubscribers(this.workflowSubscriptions, workflow);
   }
 
   getWorkflow(id: string): WorkflowRun | undefined {
@@ -72,14 +72,18 @@ export class InMemoryAgentStore implements AgentStore {
     return [...this.workflows.values()];
   }
 
-  subscribeWorkflow(id: string, listener: (workflow: WorkflowRun) => void): () => void {
-    const listeners = this.workflowListeners.get(id) ?? new Set<(workflow: WorkflowRun) => void>();
-    listeners.add(listener);
-    this.workflowListeners.set(id, listeners);
+  subscribeWorkflows(
+    listener: (workflow: WorkflowRun) => void,
+    filter?: (workflow: WorkflowRun) => boolean,
+  ): () => void {
+    const subscription = { listener, filter };
+    this.workflowSubscriptions.add(subscription);
+    return () => this.workflowSubscriptions.delete(subscription);
+  }
+}
 
-    return () => {
-      listeners.delete(listener);
-      if (listeners.size === 0) this.workflowListeners.delete(id);
-    };
+function notifySubscribers<T>(subscriptions: Set<StoreSubscription<T>>, value: T): void {
+  for (const subscription of subscriptions) {
+    if (!subscription.filter || subscription.filter(value)) subscription.listener(value);
   }
 }

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,115 +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.subscribeRun(run.id, (updatedRun) => {
-            if (settled) return;
-            latestRuns.set(updatedRun.id, updatedRun);
-            resolveIfDone();
-          }),
-        );
-      }
-
-      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.subscribeRun(run.id, (updatedRun) => {
-            if (settled) return;
-            latestRuns.set(updatedRun.id, updatedRun);
-            if (!excludedRunIds.has(updatedRun.id) && isTerminalAgentState(updatedRun.state))
-              resolveWithRun(updatedRun);
-          }),
-        );
-      }
-    });
-  }
-
   private requireBus(id: string): Bus {
     const bus = this.findBus(id);
     if (!bus) throw new Error(`Bus ${id} not found.`);
@@ -273,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");
   }
@@ -290,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/store.ts

@@ -6,7 +6,7 @@ export interface AgentStore {
   saveRun(run: AgentRun): void;
   getRun(id: string): AgentRun | undefined;
   listRuns(): AgentRun[];
-  subscribeRun(id: string, listener: (run: AgentRun) => void): () => void;
+  subscribeRuns(listener: (run: AgentRun) => void, filter?: (run: AgentRun) => boolean): () => void;
 
   saveBus(bus: Bus): void;
   getBus(id: string): Bus | undefined;
@@ -17,5 +17,8 @@ export interface AgentStore {
   saveWorkflow(workflow: WorkflowRun): void;
   getWorkflow(id: string): WorkflowRun | undefined;
   listWorkflows(): WorkflowRun[];
-  subscribeWorkflow(id: string, listener: (workflow: WorkflowRun) => void): () => void;
+  subscribeWorkflows(
+    listener: (workflow: WorkflowRun) => void,
+    filter?: (workflow: WorkflowRun) => boolean,
+  ): () => void;
 }

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,25 +6,47 @@ 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 {
   busTool: BusTool;
   subagentTool: SubagentTool;
   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));
   pi.registerTool(defineWorkgroupPiTool((ctx) => getToolBundle(ctx).workgroupTool));
-  pi.registerTool(defineWorkflowPiTool((ctx) => getToolBundle(ctx).workflowTool));
+  pi.registerTool(
+    defineWorkflowPiTool((ctx) => getToolBundle(ctx).workflowTool, {
+      onWorkflowInput: (ctx) => getToolBundle(ctx).workflowMonitor.show(ctx),
+      onWorkflowOutput: (ctx) => getToolBundle(ctx).workflowMonitor.show(ctx),
+    }),
+  );
+
+  pi.registerCommand("orchestra-workflows", {
+    description: "Show the active pi-orchestra workflow progress widget.",
+    handler: async (_args, ctx) => {
+      const monitor = getToolBundle(ctx).workflowMonitor;
+      if (monitor.show(ctx)) return;
+      ctx.ui.notify("No active pi-orchestra workflows.", "info");
+    },
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    bundles.get(ctx.cwd)?.workflowMonitor.dispose();
+  });
 }
 
-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;
 
@@ -35,16 +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) {