@g3un/pi-orchestra 0.2.1 → 0.9.2

package/src/tools/bus.ts

@@ -1,28 +1,43 @@
 import { defineTool, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { Bus, BusMessage } from "../core/bus.ts";
+import {
+  createBusSubscription,
+  createBusSubscriptionId,
+  type Bus,
+  type BusMessage,
+  type BusSubscription,
+} from "../core/bus.ts";
 import type { OrchestraApi } from "../core/orchestra.ts";
-import { formatNamedEntityLabel } from "../utils.ts";
+import type { AgentStore } from "../core/store.ts";
 
 export type BusInput =
   | {
       action: "create";
-      name?: string;
+      name: string | undefined;
     }
   | {
       action: "status";
-      id: string;
+      name: string;
     }
   | {
       action: "publish";
-      id: string;
+      name: string;
       message: string;
-      from?: string;
+      from: string;
+    }
+  | {
+      action: "subscribe";
+      name: string;
+    }
+  | {
+      action: "unsubscribe";
+      name: string;
     };
 
 export interface BusOutput {
   bus?: Bus;
   busMessage?: BusMessage;
+  subscription?: BusSubscription;
   message: string;
 }
 
@@ -33,11 +48,13 @@ export interface BusTool {
 
 export interface BusToolDeps {
   orchestra: OrchestraApi;
+  store: AgentStore;
 }
 
 const BusActionParams = Type.String({
-  enum: ["create", "status", "publish"],
-  description: "create/status/publish shared context buses; completion is delivered through pi-orchestra events.",
+  enum: ["create", "status", "publish", "subscribe", "unsubscribe"],
+  description:
+    "create/status/publish/subscribe/unsubscribe shared context buses; completion is delivered through pi-orchestra events.",
 });
 
 const BusToolParams = Type.Object(
@@ -45,45 +62,52 @@ const BusToolParams = Type.Object(
     action: BusActionParams,
     name: Type.Optional(
       Type.String({
-        description: "Optional short bus name for action=create.",
-      }),
-    ),
-    id: Type.Optional(
-      Type.String({
-        description: "Required except create. Bus id/name returned by action=create.",
+        description:
+          "Optional for action=create; required for action=status/publish. Use the short bus name, not a bus id.",
       }),
     ),
     message: Type.Optional(
       Type.String({
-        description: "Required for action=publish. Shared context for attached agents.",
+        description: "Required for action=publish. Shared context for subscribed agents.",
       }),
     ),
   },
   { additionalProperties: false },
 );
 
-export function createBusTool({ orchestra }: BusToolDeps): BusTool {
+export function createBusTool({ orchestra, store }: BusToolDeps): BusTool {
   return {
     name: "bus",
 
     async execute(input) {
       if (input.action === "create") {
         const bus = orchestra.createBus({ name: input.name });
-        return { bus, message: formatBusStatus(bus, `Created bus ${formatNamedEntityLabel(bus)}.`) };
+        return { bus, message: formatBusStatus(bus, store, `Created bus ${formatBusLabel(bus)}.`) };
       }
 
-      const bus = orchestra.getBus(input.id);
-      if (!bus) return { message: formatBusNotFound(input.id) };
+      const bus = orchestra.getBus(input.name);
+      if (!bus) return { message: formatBusNotFound(input.name) };
 
       if (input.action === "status") {
-        return { bus, message: formatBusStatus(bus) };
+        return { bus, message: formatBusStatus(bus, store) };
+      }
+
+      if (input.action === "subscribe") {
+        const subscription = subscribeMainToBus(store, bus);
+        return { bus, subscription, message: `Subscribed main to bus ${formatBusLabel(bus)} for new messages.` };
+      }
+
+      if (input.action === "unsubscribe") {
+        const subscriptionId = createBusSubscriptionId(bus.id, "main", "main");
+        store.deleteBusSubscription(subscriptionId);
+        return { bus, message: `Unsubscribed main from bus ${formatBusLabel(bus)}.` };
       }
 
-      const published = await orchestra.publishBus(input.id, input.message, input.from ?? "main");
+      const published = await orchestra.publishBus(input.name, input.message, input.from ?? "main");
       return {
         bus: published.bus,
         busMessage: published.busMessage,
-        message: formatBusStatus(published.bus, `Published message to bus ${formatNamedEntityLabel(published.bus)}.`),
+        message: formatBusStatus(published.bus, store, `Published message to bus ${formatBusLabel(published.bus)}.`),
       };
     },
   };
@@ -97,7 +121,8 @@ export function defineBusPiTool(resolveTool: (ctx: ExtensionContext) => BusTool)
     promptSnippet: "Use one bus per delegated work item; spawn related subagents or workgroups on it.",
     promptGuidelines: [
       "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.",
+      "Use bus publish with the bus name, not a bus id, to send shared context to subscribed agents; bus status shows published messages.",
+      "Use bus subscribe when main needs live bus messages; it starts from new messages after subscription. Unsubscribe when tracking is no longer useful.",
       "Do not wait on buses; pi-orchestra delivers subagent and workgroup finish events automatically.",
     ],
     parameters: BusToolParams,
@@ -117,35 +142,68 @@ function toBusInput(params: RawBusParams): BusInput {
   if (params.action === "create") return { action: "create", name: params.name };
 
   if (params.action === "status") {
-    if (!params.id) throw new Error("bus action=status requires id.");
-    return { action: "status", id: params.id };
+    if (!params.name) throw new Error("bus action=status requires name.");
+    return { action: "status", name: params.name };
   }
 
-  if (!params.id) throw new Error("bus action=publish requires id.");
+  if (params.action === "subscribe") {
+    if (!params.name) throw new Error("bus action=subscribe requires name.");
+    return { action: "subscribe", name: params.name };
+  }
+
+  if (params.action === "unsubscribe") {
+    if (!params.name) throw new Error("bus action=unsubscribe requires name.");
+    return { action: "unsubscribe", name: params.name };
+  }
+
+  if (!params.name) throw new Error("bus action=publish requires name.");
   if (!params.message) throw new Error("bus action=publish requires message.");
-  return { action: "publish", id: params.id, message: params.message };
+  return { action: "publish", name: params.name, message: params.message, from: "main" };
+}
+
+function subscribeMainToBus(store: AgentStore, bus: Bus): BusSubscription {
+  const id = createBusSubscriptionId(bus.id, "main", "main");
+  const subscription =
+    store.getBusSubscription(id) ??
+    createBusSubscription({
+      busId: bus.id,
+      subscriberId: "main",
+      subscriberKind: "main",
+      deliveredMessageIds: bus.messages.map((message) => message.id),
+    });
+  store.saveBusSubscription(subscription);
+  return subscription;
 }
 
-function formatBusNotFound(id: string): string {
-  return `Bus ${id} not found.`;
+function formatBusNotFound(name: string): string {
+  return `Bus ${name} not found.`;
 }
 
 function formatBusStatus(
   bus: Bus,
-  headline = `Bus ${formatNamedEntityLabel(bus)} has ${bus.messages.length} message(s).`,
+  store: AgentStore,
+  headline = `Bus ${formatBusLabel(bus)} has ${bus.messages.length} message(s).`,
 ): string {
   if (bus.messages.length === 0) return headline;
 
-  return [headline, "", "Messages:", ...bus.messages.map(formatBusMessage)].join("\n");
+  return [headline, "", "Messages:", ...bus.messages.map((message) => formatBusMessage(message, store))].join("\n");
+}
+
+function formatBusMessage(message: BusMessage, store: AgentStore): string {
+  return [`- ${message.id} from ${formatBusMessageFrom(message.from, store)}:`, message.message].join("\n");
+}
+
+function formatBusMessageFrom(from: string, store: AgentStore): string {
+  if (from === "main") return from;
+  return store.getRun(from)?.name ?? from;
 }
 
-function formatBusMessage(message: BusMessage): string {
-  return [`- ${message.id} from ${message.from}:`, message.message].join("\n");
+function formatBusLabel(bus: Bus): string {
+  return bus.name;
 }
 
 type RawBusParams = {
-  action: "create" | "status" | "publish";
+  action: "create" | "status" | "publish" | "subscribe" | "unsubscribe";
   name?: string;
-  id?: string;
   message?: string;
 };

package/src/tools/subagent.ts

@@ -9,7 +9,7 @@ export interface SubagentSpawnInput {
   profile: AgentProfile;
   task: string;
   busId: string;
-  name?: string;
+  name: string | undefined;
 }
 
 export type SubagentInput =
@@ -17,18 +17,18 @@ export type SubagentInput =
   | {
       action: "status";
       id: string;
-      busId?: string;
+      busId: string | undefined;
     }
   | {
       action: "message";
       id: string;
       message: string;
-      busId?: string;
+      busId: string | undefined;
     }
   | {
       action: "close";
       id: string;
-      busId?: string;
+      busId: string | undefined;
     };
 
 export interface SubagentOutput {
@@ -53,7 +53,10 @@ export const AgentProfileParams = Type.Object(
   {
     name: Type.String({ description: "Short role/name for the subagent." }),
     systemPrompt: Type.String({ description: "System prompt for the subagent." }),
-    tools: Type.Optional(Type.Array(Type.String(), { description: "Optional tool allowlist for the subagent." })),
+    tools: Type.Array(Type.String(), {
+      description:
+        "Explicit tool allowlist for the subagent. Use [] for no work tools; finish and publish_bus are added automatically.",
+    }),
     model: Type.Optional(
       Type.String({
         description: "Optional provider/model id.",
@@ -143,7 +146,7 @@ export function defineSubagentPiTool(resolveTool: (ctx: ExtensionContext) => Sub
     description: "Create and manage isolated subagents.",
     promptSnippet: "Spawn a subagent on an existing bus, then status/message/close it later.",
     promptGuidelines: [
-      "Create a bus first; spawn attaches the subagent via busId.",
+      "Create a bus first; spawn subscribes the subagent to busId.",
       "Attach cooperating subagents to the same bus.",
       "Use returned run id/name for status, message, or close.",
     ],
@@ -166,7 +169,13 @@ function toSubagentInput(params: RawSubagentParams): SubagentInput {
     if (!params.profile) throw new Error("subagent action=spawn requires profile.");
     if (!params.task) throw new Error("subagent action=spawn requires task.");
     if (!params.busId) throw new Error("subagent action=spawn requires busId.");
-    return { action: "spawn", profile: params.profile, task: params.task, busId: params.busId, name: params.name };
+    return {
+      action: "spawn",
+      profile: toAgentProfile(params.profile),
+      task: params.task,
+      busId: params.busId,
+      name: params.name,
+    };
   }
 
   if (params.action === "status") {
@@ -192,6 +201,16 @@ function withDefaultModel(input: SubagentInput, ctx: ExtensionContext): Subagent
   };
 }
 
+export function toAgentProfile(profile: RawAgentProfileParams): AgentProfile {
+  if (!Array.isArray(profile.tools)) throw new Error(`Profile "${profile.name}" requires tools.`);
+  return {
+    name: profile.name,
+    systemPrompt: profile.systemPrompt,
+    tools: profile.tools,
+    model: profile.model,
+  };
+}
+
 export function withDefaultProfileModel(profile: AgentProfile, ctx: ExtensionContext): AgentProfile {
   if (profile.model || !ctx.model) return profile;
   return {
@@ -232,7 +251,7 @@ function formatModelId(model: AgentProfileModel): string {
 
 type RawSubagentParams = {
   action: "spawn" | "status" | "message" | "close";
-  profile?: AgentProfile;
+  profile?: RawAgentProfileParams;
   task?: string;
   busId?: string;
   name?: string;
@@ -240,4 +259,6 @@ type RawSubagentParams = {
   message?: string;
 };
 
+export type RawAgentProfileParams = Omit<AgentProfile, "model"> & Partial<Pick<AgentProfile, "model">>;
+
 type AgentProfileModel = NonNullable<ExtensionContext["model"]>;

package/src/tools/workflow.ts

@@ -5,13 +5,13 @@ import type { OrchestraApi } from "../core/orchestra.ts";
 import type { AgentStore } from "../core/store.ts";
 import type { WorkflowRun, WorkflowStageOutput, WorkflowStageRun, WorkflowStageSpec } from "../core/workflow.ts";
 import { WORKGROUP_STRATEGY_VALUES, type WorkgroupMember, type WorkgroupStrategy } from "../core/workgroup.ts";
-import { createStageLeaderProfile } from "../profiles/stage-leader.ts";
 import {
   closeAgentRuns,
   createEntityIdentity,
   formatError,
   findWorkflow,
   formatNamedEntityLabel,
+  isAgentRunFinished,
   isTerminalAgentState,
   normalizeEntityName,
   requireWorkflow,
@@ -29,7 +29,7 @@ import {
 export type WorkflowInput =
   | {
       action: "start";
-      name?: string;
+      name: string | undefined;
       goal: string;
       stages: WorkflowStageSpec[];
     }
@@ -58,8 +58,8 @@ export interface WorkflowToolDeps {
 }
 
 export interface WorkflowPiToolOptions {
-  onWorkflowInput?: (ctx: ExtensionContext, input: WorkflowInput) => void;
-  onWorkflowOutput?: (ctx: ExtensionContext, output: WorkflowOutput) => void;
+  onWorkflowInput: ((ctx: ExtensionContext, input: WorkflowInput) => void) | undefined;
+  onWorkflowOutput: ((ctx: ExtensionContext, output: WorkflowOutput) => void) | undefined;
 }
 
 const WorkflowStageParams = Type.Object(
@@ -78,7 +78,7 @@ const WorkflowStageParams = Type.Object(
       description: "Worker subagents for this stage.",
       minItems: 1,
     }),
-    leader: Type.Optional(WorkgroupMemberParams),
+    leader: WorkgroupMemberParams,
   },
   { additionalProperties: false },
 );
@@ -108,7 +108,8 @@ const WorkflowToolParams = Type.Object(
     ),
     stages: Type.Optional(
       Type.Array(WorkflowStageParams, {
-        description: "Required for action=start. Linear stages executed in order with automatic stage leaders.",
+        description:
+          "Required for action=start. Linear stages executed in order; each stage specifies an explicit leader.",
         minItems: 1,
       }),
     ),
@@ -117,7 +118,12 @@ const WorkflowToolParams = Type.Object(
 );
 
 export function createWorkflowTool({ orchestra, store }: WorkflowToolDeps): WorkflowTool {
-  const workgroupTool = createWorkgroupTool({ orchestra });
+  const workgroupTool = createWorkgroupTool({
+    orchestra,
+    onWorkgroupLaunching: undefined,
+    onWorkgroupLaunched: undefined,
+    onWorkgroupLaunchFailed: undefined,
+  });
   const runnerTasks = new Map<string, Promise<void>>();
 
   const startRunner = (workflowId: string) => {
@@ -152,16 +158,17 @@ export function createWorkflowTool({ orchestra, store }: WorkflowToolDeps): Work
 
 export function defineWorkflowPiTool(
   resolveTool: (ctx: ExtensionContext) => WorkflowTool,
-  options: WorkflowPiToolOptions = {},
+  options: WorkflowPiToolOptions = { onWorkflowInput: undefined, onWorkflowOutput: undefined },
 ) {
   return defineTool({
     name: "workflow",
     label: "Workflow",
-    description: "Run linear workgroup stages with automatic restricted stage leaders.",
+    description: "Run linear workgroup stages, each with an explicit leader that synthesizes its workers' output.",
     promptSnippet: "Launch a multi-stage workflow; completion is delivered automatically as a pi-orchestra event.",
     promptGuidelines: [
       "Use workflow for ordered multi-stage work; not branching/DAG plans.",
-      "Each stage gets its own bus and automatic leader; previous outputs feed the next stage.",
+      "Each stage gets its own bus and requires an explicit leader that synthesizes its workers' output; previous stage outputs feed the next stage.",
+      "Prefer the evidence-synthesizer profile for stage leaders unless the stage needs a specialized synthesizer; give the leader an explicit tool allowlist (often the union of its workers' tools).",
       "Use compete when one worker success is enough; use synthesize when findings must be combined.",
       "Use workflow status for progress; workflow.finished events deliver terminal success/blocked/failed/closed results.",
     ],
@@ -195,7 +202,7 @@ async function runWorkflow(workflowId: string, deps: WorkflowRunnerDeps): Promis
 
     const stageIndex = workflow.stages.findIndex((stage) => stage.state === "idle" && !stage.phase);
     if (stageIndex < 0) {
-      if (workflow.state === "idle")
+      if (workflow.state === "running")
         deps.store.saveWorkflow({
           ...workflow,
           state: "success",
@@ -216,7 +223,12 @@ async function runStage(workflowId: string, stageIndex: number, deps: WorkflowRu
   const workflow = requireWorkflow(deps.store, workflowId);
   const stage = workflow.stages[stageIndex];
   const bus = deps.orchestra.createBus({ name: `${workflow.name}-${stage.name}` });
-  updateStage(deps.store, workflow, stageIndex, { state: "idle", phase: "workers", busId: bus.id });
+  updateStage(deps.store, workflow, stageIndex, {
+    state: "running",
+    phase: "workers",
+    startedAtMs: Date.now(),
+    busId: bus.id,
+  });
 
   const workgroupOutput = await deps.workgroupTool.execute({
     busId: bus.id,
@@ -251,10 +263,10 @@ async function runStage(workflowId: string, stageIndex: number, deps: WorkflowRu
     return;
   }
 
-  await runStageLeader(workflowId, stageIndex, bus.id, settledWorkgroup.workerResults, deps);
+  await runEvidenceSynthesizer(workflowId, stageIndex, bus.id, settledWorkgroup.workerResults, deps);
 }
 
-async function runStageLeader(
+async function runEvidenceSynthesizer(
   workflowId: string,
   stageIndex: number,
   busId: string,
@@ -270,12 +282,12 @@ async function runStageLeader(
     { name: stage.leader.name },
   );
   if (isWorkflowClosed(deps.store, workflowId)) {
-    await deps.orchestra.closeAgent(leaderRun.id);
+    await deps.orchestra.closeAgent(leaderRun.id, { busId: undefined });
     return;
   }
 
   updateStage(deps.store, requireWorkflow(deps.store, workflowId), stageIndex, {
-    state: "idle",
+    state: "running",
     phase: "leader",
     leaderRunId: leaderRun.id,
   });
@@ -309,21 +321,20 @@ function createWorkflowRun(
 ): WorkflowRun {
   validateStages(input.stages);
   const identity = createEntityIdentity(input.name, "workflow", existingWorkflows, "Workflow");
+  const startedAtMs = Date.now();
   return {
     ...identity,
     goal: input.goal,
-    startedAtMs: Date.now(),
-    state: "idle",
+    startedAtMs,
+    state: "running",
     currentStageIndex: 0,
-    stages: input.stages.map((stage) => {
-      const stageRun = {
-        ...stage,
-        name: normalizeEntityName(stage.name, "Workflow stage"),
-        state: "idle" as const,
-        workerRunIds: [],
-      };
-      return { ...stageRun, leader: resolveStageLeader(stage, identity.name) };
-    }),
+    stages: input.stages.map((stage) => ({
+      ...stage,
+      name: normalizeEntityName(stage.name, "Workflow stage"),
+      state: "idle" as const,
+      startedAtMs,
+      workerRunIds: [],
+    })),
   };
 }
 
@@ -339,20 +350,6 @@ function validateStages(stages: WorkflowStageSpec[]): void {
   }
 }
 
-function resolveStageLeader(stage: WorkflowStageSpec, workflowName: string): WorkgroupMember {
-  const stageName = normalizeEntityName(stage.name, "Workflow stage");
-  const leader = stage.leader ?? {
-    profile: createStageLeaderProfile({ name: `${workflowName}-${stageName}-leader` }),
-  };
-  return {
-    ...leader,
-    profile: {
-      ...leader.profile,
-      tools: [],
-    },
-  };
-}
-
 function toWorkflowInput(params: RawWorkflowParams): WorkflowInput {
   if (params.action === "start") {
     if (!params.goal) throw new Error("workflow action=start requires goal.");
@@ -369,15 +366,15 @@ function toWorkflowStageSpec(stage: RawWorkflowStageParams): WorkflowStageSpec {
   if (!stage.goal) throw new Error(`workflow stage ${stage.name} requires goal.`);
   if (!stage.strategy) throw new Error(`workflow stage ${stage.name} requires strategy.`);
   if (!stage.members || stage.members.length === 0) throw new Error(`workflow stage ${stage.name} requires members.`);
+  if (!stage.leader) throw new Error(`workflow stage ${stage.name} requires a leader.`);
 
-  const spec: WorkflowStageSpec = {
+  return {
     name: stage.name,
     goal: stage.goal,
     strategy: stage.strategy,
     members: stage.members.map((member, index) => toWorkgroupMember(member, `workflow member ${index + 1}`)),
+    leader: toWorkgroupMember(stage.leader, "workflow leader"),
   };
-  if (stage.leader) spec.leader = toWorkgroupMember(stage.leader, "workflow leader");
-  return spec;
 }
 
 function withDefaultModels(input: WorkflowInput, ctx: ExtensionContext): WorkflowInput {
@@ -387,7 +384,7 @@ function withDefaultModels(input: WorkflowInput, ctx: ExtensionContext): Workflo
     stages: input.stages.map((stage) => ({
       ...stage,
       members: withDefaultModelsForWorkgroupMembers(stage.members, ctx),
-      leader: stage.leader ? withDefaultModelForWorkgroupMember(stage.leader, ctx) : undefined,
+      leader: withDefaultModelForWorkgroupMember(stage.leader, ctx),
     })),
   };
 }
@@ -478,7 +475,7 @@ function buildLeaderTask(workflow: WorkflowRun, stageIndex: number, workerResult
   return [
     "You are the leader for this workflow stage.",
     ...strategyInstructions,
-    "Use supplied context only; prefer finish results over bus context.",
+    "Treat supplied context as primary; prefer finish results over bus context.",
     "",
     "Workflow goal:",
     workflow.goal,
@@ -572,7 +569,7 @@ function buildStageOutput(
   if (!leaderRun.result) {
     return {
       status: "failed",
-      summary: `Stage leader ${leaderRunId} reached ${leaderRun.state} without a result payload.`,
+      summary: `Evidence synthesizer ${leaderRunId} reached ${leaderRun.state} without a result payload.`,
       leaderRunId,
       workerResults: workerResults.map(toWorkflowRunResult),
     };
@@ -606,13 +603,13 @@ function formatStageOutput(output: WorkflowStageOutput): string {
 
 function terminalRunEvent(store: AgentStore, runId: string): Promise<AgentRun> {
   const initialRun = store.getRun(runId);
-  if (initialRun && isTerminalAgentState(initialRun.state)) return Promise.resolve(initialRun);
+  if (initialRun && isAgentRunFinished(initialRun)) return Promise.resolve(initialRun);
 
   return new Promise((resolve) => {
     let unsubscribe: () => void = () => undefined;
     unsubscribe = store.subscribeRuns(
       (run) => {
-        if (!isTerminalAgentState(run.state)) return;
+        if (!isAgentRunFinished(run)) return;
 
         unsubscribe();
         resolve(run);
@@ -632,7 +629,7 @@ function formatWorkflowMessage(
 ): string {
   const parts = [headline, "", `Goal: ${workflow.goal}`, "", "Stages:"];
   for (const [index, stage] of workflow.stages.entries()) {
-    const current = index === workflow.currentStageIndex && workflow.state === "idle" ? " current" : "";
+    const current = index === workflow.currentStageIndex && workflow.state === "running" ? " current" : "";
     parts.push(`- ${stage.name}: ${stage.state}${current}${stage.busId ? ` bus=${stage.busId}` : ""}`);
   }
   if (workflow.result) parts.push("", "Result:", formatStageOutput(workflow.result));