@g3un/pi-orchestra 0.2.1 → 0.9.2

package/src/extension/orchestra-events.ts

@@ -1,8 +1,9 @@
+import { isBusMessageDelivered, markBusMessagesDelivered, type BusMessage } from "../core/bus.ts";
 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";
+import { formatNamedEntityLabel, isAgentRunActive, isTerminalAgentState, toAgentRunResult } from "../utils.ts";
 
 export const ORCHESTRA_EVENT_CUSTOM_TYPE = "pi-orchestra.event";
 
@@ -22,6 +23,11 @@ export type OrchestraMainEvent =
   | {
       type: "workflow.finished";
       workflow: WorkflowRun;
+    }
+  | {
+      type: "bus.message";
+      busId: string;
+      message: BusMessage;
     };
 
 export interface WorkgroupRegistration {
@@ -33,8 +39,8 @@ export interface WorkgroupRegistration {
 export interface OrchestraEventControllerOptions {
   store: AgentStore;
   sendEvents: (events: OrchestraMainEvent[], content: string) => void;
-  /** Defaults to 50 ms. Use 0 in tests for immediate delivery. */
-  flushDelayMs?: number;
+  /** Defaults to 50 ms when undefined. Use 0 in tests for immediate delivery. */
+  flushDelayMs: number | undefined;
 }
 
 interface RegisteredWorkgroup {
@@ -47,16 +53,27 @@ interface LaunchingWorkgroup {
   finishedRunIds: Set<string>;
 }
 
+interface BusMessageDelivery {
+  subscriptionId: string;
+  message: BusMessage;
+}
+
+interface FormatOrchestraEventsOptions {
+  formatBusMessageFrom: ((from: string) => string) | undefined;
+}
+
 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 runFinished = new Map<string, boolean>();
   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 queuedBusMessageDeliveries: BusMessageDelivery[] = [];
   private readonly unsubscribeRuns: () => void;
+  private readonly unsubscribeBusMessages: () => void;
   private readonly unsubscribeWorkflows: () => void;
   private flushTimer: ReturnType<typeof setTimeout> | undefined;
 
@@ -65,11 +82,18 @@ export class OrchestraEventController {
     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 run of this.store.listRuns()) this.runFinished.set(run.id, isAgentFinishRun(run));
     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));
+    this.unsubscribeRuns = this.store.subscribeRuns((run) => this.handleRunSaved(run), undefined);
+    this.unsubscribeBusMessages = this.store.subscribeBusMessages(
+      (event) => this.handleBusMessageSaved(event),
+      undefined,
+    );
+    this.unsubscribeWorkflows = this.store.subscribeWorkflows(
+      (workflow) => this.handleWorkflowSaved(workflow),
+      undefined,
+    );
   }
 
   beginWorkgroup(busId: string, strategy: WorkgroupStrategy): void {
@@ -98,7 +122,9 @@ export class OrchestraEventController {
     if (this.flushTimer) clearTimeout(this.flushTimer);
     this.flushTimer = undefined;
     this.queuedEvents.length = 0;
+    this.queuedBusMessageDeliveries.length = 0;
     this.unsubscribeRuns();
+    this.unsubscribeBusMessages();
     this.unsubscribeWorkflows();
   }
 
@@ -107,15 +133,23 @@ export class OrchestraEventController {
     this.flushTimer = undefined;
     if (this.queuedEvents.length === 0) return;
 
-    const events = this.queuedEvents.splice(0);
-    this.sendEvents(events, formatOrchestraEvents(events));
+    const events = [...this.queuedEvents];
+    const busMessageDeliveries = [...this.queuedBusMessageDeliveries];
+    this.sendEvents(
+      events,
+      formatOrchestraEvents(events, { formatBusMessageFrom: (from) => this.formatBusMessageFrom(from) }),
+    );
+    this.queuedEvents.splice(0, events.length);
+    this.queuedBusMessageDeliveries.splice(0, busMessageDeliveries.length);
+    for (const delivery of busMessageDeliveries) this.markBusMessageDelivered(delivery);
   }
 
   private handleRunSaved(run: AgentRun): void {
-    const previousState = this.runStates.get(run.id);
-    this.runStates.set(run.id, run.state);
+    const wasFinished = this.runFinished.get(run.id) ?? false;
+    const isFinished = isAgentFinishRun(run);
+    this.runFinished.set(run.id, isFinished);
 
-    if (!isAgentFinishState(run.state) || isAgentFinishState(previousState)) return;
+    if (!isFinished || wasFinished) return;
     if (this.isWorkflowBus(run.busId)) return;
 
     const registeredWorkgroup = this.mainWorkgroupsByBusId.get(run.busId);
@@ -146,11 +180,29 @@ export class OrchestraEventController {
     this.queueEvent({ type: "subagent.finished", busId: run.busId, run: toAgentRunResult(run) });
   }
 
+  private handleBusMessageSaved(event: { busId: string; message: BusMessage }): void {
+    if (event.message.from === "main") return;
+
+    const subscriptions = this.store.listBusSubscriptions({
+      busId: event.busId,
+      subscriberId: "main",
+      subscriberKind: "main",
+    });
+    for (const subscription of subscriptions) {
+      if (isBusMessageDelivered(subscription, event.message.id)) continue;
+      if (this.hasQueuedBusMessageDelivery(subscription.id, event.message.id)) continue;
+
+      this.queuedBusMessageDeliveries.push({ subscriptionId: subscription.id, message: event.message });
+      this.queueEvent({ type: "bus.message", busId: event.busId, message: event.message });
+    }
+  }
+
   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;
+    if (!isTerminalAgentState(workflow.state) || (previousState !== undefined && isTerminalAgentState(previousState)))
+      return;
     this.queueEvent({ type: "workflow.finished", workflow });
   }
 
@@ -161,17 +213,35 @@ export class OrchestraEventController {
   private getPendingWorkgroupRunIds(busId: string, runIds: Set<string>): string[] {
     return this.store
       .listRuns()
-      .filter((run) => run.busId === busId && runIds.has(run.id) && run.state === "idle")
+      .filter((run) => run.busId === busId && runIds.has(run.id) && isAgentRunActive(run))
       .map((run) => run.id);
   }
 
   private getPendingBusRunIds(busId: string): string[] {
     return this.store
       .listRuns()
-      .filter((run) => run.busId === busId && run.state === "idle")
+      .filter((run) => run.busId === busId && isAgentRunActive(run))
       .map((run) => run.id);
   }
 
+  private hasQueuedBusMessageDelivery(subscriptionId: string, messageId: string): boolean {
+    return this.queuedBusMessageDeliveries.some(
+      (delivery) => delivery.subscriptionId === subscriptionId && delivery.message.id === messageId,
+    );
+  }
+
+  private formatBusMessageFrom(from: string): string {
+    if (from === "main") return from;
+    return this.store.getRun(from)?.name ?? from;
+  }
+
+  private markBusMessageDelivered(delivery: BusMessageDelivery): void {
+    const subscription = this.store.getBusSubscription(delivery.subscriptionId);
+    if (!subscription) return;
+
+    this.store.saveBusSubscription(markBusMessagesDelivered(subscription, delivery.message));
+  }
+
   private queueEvent(event: OrchestraMainEvent): void {
     this.queuedEvents.push(event);
     if (this.flushDelayMs === 0) {
@@ -183,28 +253,37 @@ export class OrchestraEventController {
   }
 }
 
-export function formatOrchestraEvents(events: OrchestraMainEvent[]): string {
+export function formatOrchestraEvents(events: OrchestraMainEvent[], options?: FormatOrchestraEventsOptions): string {
   const headline = events.length === 1 ? "Pi-orchestra event:" : `Pi-orchestra events (${events.length}):`;
-  return [headline, ...events.flatMap((event) => ["", formatOrchestraEvent(event)])].join("\n");
+  return [headline, ...events.flatMap((event) => ["", formatOrchestraEvent(event, options)])].join("\n");
 }
 
-function formatOrchestraEvent(event: OrchestraMainEvent): string {
+function formatOrchestraEvent(event: OrchestraMainEvent, options: FormatOrchestraEventsOptions | undefined): string {
   if (event.type === "workflow.finished") return formatWorkflowFinishedEvent(event.workflow);
+  if (event.type === "bus.message") return formatBusMessageEvent(event, options);
 
   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}.`,
+          `- Workgroup member finished on bus ${event.busId}: ${runLabel} ${formatRunFinishedState(event.run)}.`,
           `  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}.`];
+      : [`- Subagent finished on bus ${event.busId}: ${runLabel} ${formatRunFinishedState(event.run)}.`];
 
   lines.push(...formatRunResultLines(event.run));
   return lines.join("\n");
 }
 
+function formatBusMessageEvent(
+  event: Extract<OrchestraMainEvent, { type: "bus.message" }>,
+  options: FormatOrchestraEventsOptions | undefined,
+): string {
+  const from = options?.formatBusMessageFrom?.(event.message.from) ?? event.message.from;
+  return [`- Bus message on ${event.busId} from ${from}:`, event.message.message].join("\n");
+}
+
 function formatWorkflowFinishedEvent(workflow: WorkflowRun): string {
   const lines = [`- Workflow finished: ${formatNamedEntityLabel(workflow)} is ${workflow.state}.`];
   if (workflow.result) {
@@ -222,10 +301,14 @@ function formatRunResultLines(run: AgentRunResult): string[] {
   return lines;
 }
 
-function isAgentFinishState(state: AgentState | undefined): boolean {
-  return state === "success" || state === "blocked" || state === "failed";
+function formatRunFinishedState(run: AgentRunResult): string {
+  return run.result ? `finished with ${run.result.status}; state=${run.state}` : `is ${run.state}`;
 }
 
-function isTerminalWorkflowState(state: AgentState | undefined): boolean {
-  return state !== undefined && isTerminalAgentState(state);
+function isAgentFinishRun(run: AgentRun | AgentRunResult): boolean {
+  return run.result !== undefined || isAgentResultState(run.state);
+}
+
+function isAgentResultState(state: AgentState | undefined): boolean {
+  return state === "success" || state === "blocked" || state === "failed";
 }

package/src/extension/workflow-monitor.ts

@@ -2,7 +2,7 @@ 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 { isTerminalAgentState } from "../utils.ts";
+import { isAgentRunFinished, isTerminalAgentState } from "../utils.ts";
 
 const WIDGET_KEY = "pi-orchestra.workflow-monitor";
 const MAX_MONITORED_WORKFLOWS = 2;
@@ -10,9 +10,9 @@ const MAX_WIDGET_LINES = 10;
 const DEFAULT_TICK_MS = 1_000;
 
 export interface WorkflowMonitorControllerOptions {
-  now?: () => number;
-  /** Defaults to 1000 ms. Use 0 to disable uptime ticks in tests. */
-  tickMs?: number;
+  now: (() => number) | undefined;
+  /** Defaults to 1000 ms when undefined. Use 0 to disable uptime ticks in tests. */
+  tickMs: number | undefined;
 }
 
 export class WorkflowMonitorController {
@@ -24,7 +24,7 @@ export class WorkflowMonitorController {
 
   constructor(
     private readonly store: AgentStore,
-    options: WorkflowMonitorControllerOptions = {},
+    options: WorkflowMonitorControllerOptions = { now: undefined, tickMs: undefined },
   ) {
     this.now = options.now ?? Date.now;
     this.tickMs = options.tickMs ?? DEFAULT_TICK_MS;
@@ -39,8 +39,8 @@ export class WorkflowMonitorController {
 
     this.ctx = ctx;
     if (!this.unsubscribe) {
-      const unsubscribeRuns = this.store.subscribeRuns(() => this.render());
-      const unsubscribeWorkflows = this.store.subscribeWorkflows(() => this.render());
+      const unsubscribeRuns = this.store.subscribeRuns(() => this.render(), undefined);
+      const unsubscribeWorkflows = this.store.subscribeWorkflows(() => this.render(), undefined);
       this.unsubscribe = () => {
         unsubscribeRuns();
         unsubscribeWorkflows();
@@ -112,10 +112,11 @@ function appendWorkflowLines(lines: string[], store: AgentStore, workflow: Workf
   if (lines.length >= MAX_WIDGET_LINES) return;
 
   const stage = getCurrentStage(workflow);
+  const workflowLabel = `${workflow.name} [${formatUptimeSince(workflow.startedAtMs, nowMs)}]`;
   const stageLabel = stage
-    ? formatStageLabel(store, workflow, stage)
+    ? formatStageLabel(store, workflow, stage, nowMs)
     : `none (0/${workflow.stages.length}) | agents (0/0)`;
-  lines.push(`${workflow.name} | ${stageLabel} | ${formatWorkflowUptime(workflow, nowMs)}`);
+  lines.push(`${workflowLabel} | ${stageLabel}`);
 }
 
 function listActiveWorkflows(store: AgentStore): WorkflowRun[] {
@@ -128,10 +129,11 @@ function getCurrentStage(workflow: WorkflowRun): WorkflowStageRun | undefined {
   );
 }
 
-function formatStageLabel(store: AgentStore, workflow: WorkflowRun, stage: WorkflowStageRun): string {
+function formatStageLabel(store: AgentStore, workflow: WorkflowRun, stage: WorkflowStageRun, nowMs: number): string {
   const stageIndex = workflow.stages.indexOf(stage);
   const stagePosition = stageIndex >= 0 ? `${stageIndex + 1}/${workflow.stages.length}` : `?/${workflow.stages.length}`;
-  return `${stage.name} (${stagePosition}) | agents (${formatStageProgress(store, stage)})`;
+  const stageUptime = formatUptimeSince(stage.startedAtMs, nowMs);
+  return `${stage.name} [${stageUptime}] (${stagePosition}) | agents (${formatStageProgress(store, stage)})`;
 }
 
 function formatStageProgress(store: AgentStore, stage: WorkflowStageRun): string {
@@ -139,8 +141,8 @@ function formatStageProgress(store: AgentStore, stage: WorkflowStageRun): string
   return `${progress.completed}/${progress.total}`;
 }
 
-function formatWorkflowUptime(workflow: WorkflowRun, nowMs: number): string {
-  const elapsedSeconds = Math.max(0, Math.floor((nowMs - workflow.startedAtMs) / 1_000));
+function formatUptimeSince(startedAtMs: number, nowMs: number): string {
+  const elapsedSeconds = Math.max(0, Math.floor((nowMs - startedAtMs) / 1_000));
   const seconds = elapsedSeconds % 60;
   const totalMinutes = Math.floor(elapsedSeconds / 60);
   const minutes = totalMinutes % 60;
@@ -157,7 +159,7 @@ function pad2(value: number): string {
 
 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 completed = runs.filter(isAgentRunFinished).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;

package/src/profiles/code-reviewer.ts

@@ -0,0 +1,20 @@
+import type { AgentProfile } from "../core/subagent.ts";
+import { defineAgentProfile, type ToolProfileOptions } from "./profile.ts";
+
+export interface CodeReviewerProfileOptions extends ToolProfileOptions {}
+
+export function createCodeReviewerProfile(options: CodeReviewerProfileOptions): AgentProfile {
+  return defineAgentProfile({
+    defaultName: "code-reviewer",
+    systemPrompt: [
+      "You are a code reviewer: identify bugs, behavioral regressions, security risks, and missing tests in the assigned local code or change.",
+      "Prioritize findings over summary. For each finding, include severity, affected file/symbol or line reference, impact, and a concrete remediation direction.",
+      "Use local repository evidence and supplied task context; treat bus context as supplemental and note conflicts.",
+      "Do not modify files or perform unrelated implementation work, even if editing tools are present.",
+      "If no material issues are found, say so clearly and note residual test gaps or review limits.",
+      "Use status=success when review findings or a no-issues conclusion are supported, blocked when the target/diff/context/tools are insufficient, and failed when review execution fails.",
+    ],
+    tools: options.tools,
+    options,
+  });
+}

package/src/profiles/evidence-synthesizer.ts

@@ -0,0 +1,20 @@
+import type { AgentProfile } from "../core/subagent.ts";
+import { defineAgentProfile, type ToolProfileOptions } from "./profile.ts";
+
+export interface EvidenceSynthesizerProfileOptions extends ToolProfileOptions {}
+
+export function createEvidenceSynthesizerProfile(options: EvidenceSynthesizerProfileOptions): AgentProfile {
+  return defineAgentProfile({
+    defaultName: "evidence-synthesizer",
+    systemPrompt: [
+      "You are an evidence synthesizer: produce concise canonical output from supplied worker results and shared context.",
+      "Treat supplied context (workflow/stage goals, previous outputs, worker results, bus context) as primary evidence.",
+      "Use allowed tools only to verify evidence or resolve concrete gaps needed for synthesis; do not broaden scope or perform unrelated work.",
+      "Do not modify files or external state; if necessary tools/context are unavailable, report blocked instead of guessing.",
+      "Deduplicate and reconcile evidence; note conflicts/gaps; prefer finish results over bus context.",
+      "Prefer status=success if useful output exists; use blocked if context is insufficient, failed if synthesis fails.",
+    ],
+    tools: options.tools,
+    options,
+  });
+}

package/src/profiles/external-researcher.ts

@@ -0,0 +1,20 @@
+import type { AgentProfile } from "../core/subagent.ts";
+import { defineAgentProfile, type ToolProfileOptions } from "./profile.ts";
+
+export interface ExternalResearcherProfileOptions extends ToolProfileOptions {}
+
+export function createExternalResearcherProfile(options: ExternalResearcherProfileOptions): AgentProfile {
+  return defineAgentProfile({
+    defaultName: "external-researcher",
+    systemPrompt: [
+      "You are an external research agent: gather, verify, and synthesize information from outside the target repository.",
+      "Use the supplied task and bus context to define scope; prefer official and primary sources, then clearly label secondary sources.",
+      "Record source names, links, publication or version dates when available, and distinguish current facts from inference.",
+      "Compare similar projects only when the assignment asks; otherwise stay focused on the named target.",
+      "Do not modify local files. If required search/fetch/browse tools or credible sources are unavailable, finish with status=blocked instead of guessing.",
+      "Finish with concise findings, cited source list, conflicts/gaps, confidence, and useful structured data when comparison or source tables help.",
+    ],
+    tools: options.tools,
+    options,
+  });
+}

package/src/profiles/index.ts

@@ -1 +1,5 @@
-export * from "./stage-leader.ts";
+export * from "./code-reviewer.ts";
+export * from "./evidence-synthesizer.ts";
+export * from "./external-researcher.ts";
+export * from "./profile.ts";
+export * from "./source-code-qa.ts";

package/src/profiles/profile.ts

@@ -0,0 +1,31 @@
+import type { AgentProfile } from "../core/subagent.ts";
+
+export interface BaseProfileOptions {
+  name: string | undefined;
+  model: string | undefined;
+}
+
+export interface ToolProfileOptions extends BaseProfileOptions {
+  tools: string[];
+}
+
+interface DefineAgentProfileOptions {
+  defaultName: string;
+  systemPrompt: readonly string[];
+  tools: readonly string[];
+  options: BaseProfileOptions;
+}
+
+export function defineAgentProfile({
+  defaultName,
+  systemPrompt,
+  tools,
+  options,
+}: DefineAgentProfileOptions): AgentProfile {
+  return {
+    name: options.name ?? defaultName,
+    systemPrompt: systemPrompt.join("\n"),
+    tools: [...tools],
+    model: options.model,
+  };
+}

package/src/profiles/source-code-qa.ts

@@ -0,0 +1,19 @@
+import type { AgentProfile } from "../core/subagent.ts";
+import { defineAgentProfile, type ToolProfileOptions } from "./profile.ts";
+
+export interface SourceCodeQaProfileOptions extends ToolProfileOptions {}
+
+export function createSourceCodeQaProfile(options: SourceCodeQaProfileOptions): AgentProfile {
+  return defineAgentProfile({
+    defaultName: "source-code-qa",
+    systemPrompt: [
+      "You are a source-code QA agent: answer questions using the target repository's source code, tests, and local docs.",
+      "Treat repository files and explicit task context as authoritative; treat bus context as supplemental unless the task says otherwise.",
+      "Inspect only the local project and supplied context; do not perform external research or modify files.",
+      "Finish with a concise answer, evidence paths/symbols or line references when useful, assumptions, and unresolved gaps.",
+      "Use status=success when the answer is supported, blocked when required code/context/tools are unavailable, and failed when inspection fails.",
+    ],
+    tools: options.tools,
+    options,
+  });
+}