@g3un/pi-orchestra 0.2.1 → 0.9.2

package/README.md

@@ -25,7 +25,7 @@ widget with the current stage and agent completion counts. Use
 
 ### Subagent
 
-A subagent is an isolated child agent with its own role, task, optional tool allowlist, and optional model. Subagents attach to a bus so they can receive shared reference context while working independently.
+A subagent is an isolated child agent with its own role, task, explicit tool allowlist, and optional model. Subagents attach to a bus so they can receive shared reference context while working independently.
 
 Use subagents when you want to delegate a focused task, such as review, research, implementation planning, or an alternative solution attempt.
 
@@ -40,12 +40,23 @@ Workgroups support two strategies:
 
 ### Workflow
 
-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.
+A workflow runs ordered workgroup stages. Each stage gets a fresh bus, starts its workers, collects results through internal finish-event subscriptions, and uses an evidence synthesizer 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.
 
+## Reusable profiles
+
+`src/profiles/` exports reusable `AgentProfile` factories:
+
+- `createSourceCodeQaProfile`: answer repository questions from local code, tests, and docs.
+- `createExternalResearcherProfile`: gather and synthesize external source material with citations and uncertainty handling.
+- `createCodeReviewerProfile`: review local code or changes with findings-first output.
+- `createEvidenceSynthesizerProfile`: synthesize supplied evidence and context, using tools only for targeted verification or gap-filling.
+
+Profile factories require an options object with an explicit `tools` allowlist. The main agent should inject the installed/active tool names each child actually needs. Pass `undefined` for `name` or `model` to use the factory default.
+
 ## Notes
 
 - Create a `bus` before spawning related subagents or workgroups.
-- Subagents report completion with `success`, `blocked`, or `failed`; completions are surfaced as pi-orchestra events.
+- Subagents report completion results with `success`, `blocked`, or `failed`; after `finish`, reusable runs return to `idle` until messaged or closed.
 - Use `workflow` for linear staged work, not branching/DAG execution.

package/docs/orchestration-model.md

@@ -3,7 +3,7 @@
 pi-orchestra builds delegation in four layers:
 
 1. **Bus** — shared context channel.
-2. **Subagent** — isolated child agent attached to a bus.
+2. **Subagent** — isolated child agent subscribed to a bus.
 3. **Workgroup** — multiple subagents working on one bus.
 4. **Workflow** — ordered workgroup stages with stage synthesis.
 
@@ -14,8 +14,9 @@ ordered `messages`.
 
 Bus messages are peer reference context only:
 
-- `publish_bus` sends useful findings to sibling agents on the same bus.
-- Bus context is injected as supplemental `<bus_reference_context>`.
+- `publish_bus` sends useful findings to subscribers of the same bus.
+- Subagents subscribe to their assigned bus when spawned.
+- Subscribed bus context is delivered as supplemental `<bus_reference_context>`.
 - Decisions and escalation do not go through the bus; call the `finish` tool with
   `status: "blocked"`.
 
@@ -24,8 +25,10 @@ Bus messages are peer reference context only:
 A subagent is an `AgentRun`: a child agent with a profile, task, bus id, state,
 and optional result.
 
-Profiles define the child agent's `systemPrompt`, optional tool allowlist, and
-optional model. The runtime attaches each subagent to exactly one bus.
+Profiles define the child agent's `systemPrompt`, explicit tool allowlist, and
+optional model. The runtime creates a bus subscription for each spawned subagent;
+`AgentRun.busId` remains the lifecycle/query scope, not the context delivery
+path.
 
 Every subagent must call the `finish` tool with:
 
@@ -33,8 +36,10 @@ Every subagent must call the `finish` tool with:
 - `summary`: concise handoff text
 - `data`: optional structured output
 
-State follows the result status. `closed` is separate and means the run has been
-disposed.
+While a subagent is working, its state is `running`. Calling `finish` records the
+result status and returns the reusable run to `idle`, so the leader can message it
+again without recreating the session. `closed` is separate and means the run has
+been disposed.
 
 ## Workgroup
 
@@ -56,18 +61,18 @@ Main receives finish events instead of blocking on completion calls:
 ## Workflow
 
 A workflow runs ordered stages. Each stage defines a goal, strategy, workers,
-and optional leader.
+and a leader.
 
 For each stage:
 
 1. Create a fresh bus.
-2. Spawn the worker workgroup.
+2. Spawn the worker workgroup; workers subscribe to the stage bus.
 3. Collect worker results through store finish-event subscriptions in the background.
-4. Spawn a restricted stage leader.
+4. Spawn the stage leader to synthesize the worker results.
 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.
+Each stage specifies its leader explicitly — the leader synthesizes the workers'
+results into that canonical stage output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3un/pi-orchestra",
-  "version": "0.2.1",
+  "version": "0.9.2",
   "description": "Subagent orchestration tools for Pi.",
   "keywords": [
     "orchestration",
@@ -22,6 +22,7 @@
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "docs/**/*.md",
+    "skills/**/*",
     "README.md",
     "LICENSE"
   ],
@@ -61,6 +62,9 @@
   "pi": {
     "extensions": [
       "./src/extension/index.ts"
+    ],
+    "skills": [
+      "./skills/pi-orchestra"
     ]
   }
 }

package/skills/pi-orchestra/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: pi-orchestra
+description: "Use when delegating work with Pi-Orchestra tools: bus, subagent, workgroup, or workflow. Helps choose the right orchestration primitive, create buses, brief child agents, use compete vs synthesize strategies, react to completion events, and avoid polling or over-delegation."
+---
+
+# Pi-Orchestra
+
+Use Pi-Orchestra to parallelize or structure work without losing the main thread. Do not delegate trivial tasks that you can finish faster yourself.
+
+## Tool choice
+
+- Use `subagent` for one focused, isolated task such as review, research, planning, or an independent implementation attempt.
+- Use `workgroup` when multiple agents should start together on the same goal.
+  - `compete`: agents try alternative solutions; one successful result may be enough.
+  - `synthesize`: agents cover complementary angles; collect and combine all useful findings.
+- Use `workflow` for ordered, linear stages where later stages should consume canonical outputs from earlier stages.
+- Use `bus` as the shared context scope for related subagents/workgroups. Buses are reference context, not a blocking queue or decision channel.
+
+## Default workflow
+
+1. Decide the smallest useful delegation unit and expected final output.
+2. Create one named bus per delegated work item before `subagent` or `workgroup`.
+3. Put stable shared context in the initial task/goal. Use `bus action=publish` only for new facts, constraints, artifacts, blockers, or course corrections useful to attached agents.
+4. Give every child agent a specific profile, assignment, success criteria, handoff shape, and explicit tool allowlist.
+5. Continue main-thread work while waiting. Pi-Orchestra completion events arrive automatically.
+6. On completion:
+   - For standalone subagents, consume the `subagent.finished` summary/data.
+   - For `workgroup compete`, use the first clearly successful result when sufficient; close pending losers if extra work is wasteful.
+   - For `workgroup synthesize`, combine complementary results and note gaps, conflicts, and confidence.
+   - For `workflow`, wait for `workflow.finished` or use `workflow status` only when you need progress.
+
+## Briefing child agents
+
+Prefer concise, outcome-oriented tasks:
+
+```text
+Role: <specialist role>
+Objective: <specific result needed>
+Context: <files, commands, constraints, prior findings>
+Do: <steps or focus areas>
+Do not: <boundaries, destructive actions, scope exclusions>
+Finish with: status success/blocked/failed, a concise summary, evidence, risks, and structured data if useful.
+```
+
+Profile defaults:
+
+- `name`: short role name, e.g. `reviewer`, `planner`, `doc-researcher`.
+- `systemPrompt`: one paragraph describing expertise, constraints, and output discipline.
+- `tools`: always inject an explicit allowlist from the tools available to the main agent. Include only tools the child needs, including installed extension tool names for research/browser work. Use `[]` for supplied-context-only roles.
+- `model`: omit unless the task needs a specific provider/model.
+
+## Patterns
+
+### Single specialist
+
+1. `bus create` with a short name.
+2. `subagent spawn` with the bus id/name, specialist profile, and focused task.
+3. Incorporate the finish event. Use `subagent message` only for meaningful new guidance; avoid micromanagement.
+
+### Alternative solution race
+
+1. `bus create`.
+2. `workgroup` with `strategy: "compete"` and 2-4 members with distinct approaches.
+3. When a strong success arrives, close remaining active runs unless their outputs are still valuable.
+
+### Multi-angle review
+
+1. `bus create`.
+2. `workgroup` with `strategy: "synthesize"` and members for complementary lenses, e.g. correctness, tests, UX/docs, risk/security.
+3. Synthesize results yourself; call out disagreements and unresolved blockers.
+
+### Linear pipeline
+
+Use `workflow action=start` when there are explicit stages such as discover → design → implement → review. Keep stages linear; do not model branching/DAG work as a workflow.
+
+Every stage requires an explicit `leader` that condenses its workers' output into the canonical stage result fed to the next stage. Prefer the `evidence-synthesizer` profile for this role unless a stage needs a specialized synthesizer; give the leader an explicit tool allowlist (often the union of its workers' tools) so it can verify evidence or fill concrete gaps without broadening scope.
+
+## Gotchas
+
+- Always create a bus before spawning related agents.
+- Reuse the same bus only for agents working on the same delegated work item.
+- Do not wait on or poll buses; use `bus status` only to inspect shared messages.
+- Do not rely on bus messages for leader-only decisions or urgent escalation; child agents should finish with `blocked` for that.
+- Keep child context bounded. Publish summaries and artifact paths, not long transcripts.
+- Prefer fewer, better-briefed agents over many vague agents.
+
+## Final response checklist
+
+- State which orchestration primitive was used and why, if relevant.
+- Include the winning/synthesized answer, not raw child transcripts.
+- Mention important blockers, risks, and follow-up actions.
+- Close or cancel unnecessary active runs/workflows when the task is done.

package/src/adapters/in-memory-store.ts

@@ -1,18 +1,27 @@
 import type { AgentRun } from "../core/subagent.ts";
-import type { Bus, BusMessage } from "../core/bus.ts";
+import {
+  matchesBusSubscription,
+  type Bus,
+  type BusMessage,
+  type BusMessageEvent,
+  type BusSubscription,
+  type ListBusSubscriptionsOptions,
+} from "../core/bus.ts";
 import type { AgentStore } from "../core/store.ts";
 import type { WorkflowRun } from "../core/workflow.ts";
+import { notifySubscribers, subscribeStore, type StoreSubscription } from "./store-subscriptions.ts";
 
-interface StoreSubscription<T> {
-  listener(value: T): void;
-  filter?: (value: T) => boolean;
-}
-
+/**
+ * In-memory {@link AgentStore} used as a lightweight fixture in tests.
+ * Production code persists state through {@link SqliteAgentStore} instead.
+ */
 export class InMemoryAgentStore implements AgentStore {
   private readonly runs = new Map<string, AgentRun>();
   private readonly buses = new Map<string, Bus>();
+  private readonly busSubscriptionsById = new Map<string, BusSubscription>();
   private readonly workflows = new Map<string, WorkflowRun>();
   private readonly runSubscriptions = new Set<StoreSubscription<AgentRun>>();
+  private readonly busMessageSubscriptions = new Set<StoreSubscription<BusMessageEvent>>();
   private readonly workflowSubscriptions = new Set<StoreSubscription<WorkflowRun>>();
 
   saveRun(run: AgentRun): void {
@@ -28,10 +37,8 @@ export class InMemoryAgentStore implements AgentStore {
     return [...this.runs.values()];
   }
 
-  subscribeRuns(listener: (run: AgentRun) => void, filter?: (run: AgentRun) => boolean): () => void {
-    const subscription = { listener, filter };
-    this.runSubscriptions.add(subscription);
-    return () => this.runSubscriptions.delete(subscription);
+  subscribeRuns(listener: (run: AgentRun) => void, filter: ((run: AgentRun) => boolean) | undefined): () => void {
+    return subscribeStore(this.runSubscriptions, listener, filter);
   }
 
   saveBus(bus: Bus): void {
@@ -57,6 +64,32 @@ export class InMemoryAgentStore implements AgentStore {
     }
 
     bus.messages.push(message);
+    notifySubscribers(this.busMessageSubscriptions, { busId, message });
+  }
+
+  subscribeBusMessages(
+    listener: (event: BusMessageEvent) => void,
+    filter: ((event: BusMessageEvent) => boolean) | undefined,
+  ): () => void {
+    return subscribeStore(this.busMessageSubscriptions, listener, filter);
+  }
+
+  saveBusSubscription(subscription: BusSubscription): void {
+    this.busSubscriptionsById.set(subscription.id, subscription);
+  }
+
+  getBusSubscription(id: string): BusSubscription | undefined {
+    return this.busSubscriptionsById.get(id);
+  }
+
+  listBusSubscriptions(options: ListBusSubscriptionsOptions): BusSubscription[] {
+    return [...this.busSubscriptionsById.values()].filter((subscription) =>
+      matchesBusSubscription(subscription, options),
+    );
+  }
+
+  deleteBusSubscription(id: string): void {
+    this.busSubscriptionsById.delete(id);
   }
 
   saveWorkflow(workflow: WorkflowRun): void {
@@ -74,16 +107,8 @@ export class InMemoryAgentStore implements AgentStore {
 
   subscribeWorkflows(
     listener: (workflow: WorkflowRun) => void,
-    filter?: (workflow: WorkflowRun) => boolean,
+    filter: ((workflow: WorkflowRun) => boolean) | undefined,
   ): () => void {
-    const subscription = { listener, filter };
-    this.workflowSubscriptions.add(subscription);
-    return () => this.workflowSubscriptions.delete(subscription);
-  }
-}
-
-function notifySubscribers<T>(subscriptions: Set<StoreSubscription<T>>, value: T): void {
-  for (const subscription of subscriptions) {
-    if (!subscription.filter || subscription.filter(value)) subscription.listener(value);
+    return subscribeStore(this.workflowSubscriptions, listener, filter);
   }
 }

package/src/adapters/index.ts

@@ -1,2 +1,3 @@
 export * from "./in-memory-store.ts";
 export * from "./pi-runtime.ts";
+export * from "./sqlite-store.ts";

package/src/adapters/pi-runtime.ts

@@ -14,20 +14,26 @@ import {
   type AgentResultStatus,
   type AgentRun,
 } from "../core/subagent.ts";
-import type { Bus, BusMessage } from "../core/bus.ts";
+import {
+  createBusSubscription,
+  isBusMessageDelivered,
+  markBusMessagesDelivered,
+  type Bus,
+  type BusMessage,
+  type BusSubscription,
+} from "../core/bus.ts";
 import { formatBusMessages } from "../core/bus-format.ts";
 import type { AgentRuntime, SpawnAgentRuntimeOptions } from "../core/runtime.ts";
 import type { AgentStore } from "../core/store.ts";
 
 export interface PiAgentRuntimeOptions {
   store: AgentStore;
-  cwd?: string;
-  resolveModel?: (model: string) => Model<any> | Promise<Model<any> | undefined> | undefined;
+  cwd: string | undefined;
+  resolveModel: ((model: string) => Model<any> | Promise<Model<any> | undefined> | undefined) | undefined;
 }
 
 interface RuntimeEntry {
   session: AgentSession;
-  seenBusMessageIds: Set<string>;
   promptTask?: Promise<void>;
 }
 
@@ -41,13 +47,11 @@ const PublishBusParams = Type.Object({
   message: Type.String(),
 });
 
-const DEFAULT_AGENT_TOOLS = ["read", "bash", "edit", "write"];
-
 export class PiAgentRuntime implements AgentRuntime {
   private readonly entries = new Map<string, RuntimeEntry>();
   private readonly store: AgentStore;
   private readonly cwd: string;
-  private readonly resolveModel?: PiAgentRuntimeOptions["resolveModel"];
+  private readonly resolveModel: PiAgentRuntimeOptions["resolveModel"];
 
   constructor(options: PiAgentRuntimeOptions) {
     this.store = options.store;
@@ -69,12 +73,12 @@ export class PiAgentRuntime implements AgentRuntime {
       profile: profile.name,
       task,
       busId,
-      state: "idle",
+      state: "running",
     };
 
     const childTools = this.createChildTools(run.id);
     const model = await this.resolveProfileModel(profile);
-    const baseTools = profile.tools ?? DEFAULT_AGENT_TOOLS;
+    const baseTools = requireProfileTools(profile);
     const activeTools = [...new Set([...baseTools, ...childTools.map((tool) => tool.name)])];
     const { session } = await createAgentSession({
       cwd: this.cwd,
@@ -85,12 +89,13 @@ export class PiAgentRuntime implements AgentRuntime {
     });
 
     this.store.saveRun(run);
-    const entry: RuntimeEntry = { session, seenBusMessageIds: new Set() };
+    this.store.saveBusSubscription(createAgentBusSubscription(run.id, busId));
+    const entry: RuntimeEntry = { session };
     this.entries.set(run.id, entry);
     this.startPromptTask(
       run.id,
       entry,
-      this.withBusMessages(run.id, entry, buildInitialPrompt(profile, task, run.name)),
+      this.withSubscribedBusMessages(run.id, buildInitialPrompt(profile, task, run.name)),
     );
     return run;
   }
@@ -99,15 +104,15 @@ export class PiAgentRuntime implements AgentRuntime {
     const entry = this.requireEntry(id);
     const run = this.requireRun(id);
     this.assertOpenRun(run);
-    const messageWithBusContext = this.withBusMessages(id, entry, message);
+    const messageWithBusContext = this.withSubscribedBusMessages(id, message);
 
-    if (run.state === "idle" && entry.session.isStreaming) {
+    if (run.state === "running" && entry.session.isStreaming) {
       await entry.session.steer(messageWithBusContext);
       return run;
     }
 
-    const messagedRun: AgentRun = run.state === "idle" ? run : { ...run, state: "idle", result: undefined };
-    if (messagedRun !== run) this.store.saveRun(messagedRun);
+    const messagedRun: AgentRun = { ...run, state: "running", result: undefined };
+    this.store.saveRun(messagedRun);
     this.startPromptTask(id, entry, messageWithBusContext);
     return messagedRun;
   }
@@ -122,15 +127,24 @@ export class PiAgentRuntime implements AgentRuntime {
 
     this.store.addBusMessage(busId, busMessage);
 
-    const steeringMessage = formatBusMessages([busMessage]);
+    const steeringMessage = this.formatBusMessagesForPrompt([busMessage]);
     const steerTasks: Array<Promise<void>> = [];
-    for (const [runId, entry] of this.entries) {
-      const run = this.store.getRun(runId);
-      if (!run || run.busId !== busId) continue;
-      if (run.id === from || run.state === "closed" || !entry.session.isStreaming) continue;
-
-      entry.seenBusMessageIds.add(busMessage.id);
-      steerTasks.push(entry.session.steer(steeringMessage));
+    for (const subscription of this.store.listBusSubscriptions({
+      busId,
+      subscriberId: undefined,
+      subscriberKind: "agent",
+    })) {
+      if (subscription.subscriberId === from || isBusMessageDelivered(subscription, busMessage.id)) continue;
+
+      const run = this.store.getRun(subscription.subscriberId);
+      const entry = this.entries.get(subscription.subscriberId);
+      if (!run || !entry || run.state !== "running" || !entry.session.isStreaming) continue;
+
+      steerTasks.push(
+        entry.session
+          .steer(steeringMessage)
+          .then(() => this.markSubscriptionMessagesDelivered(subscription, busMessage)),
+      );
     }
 
     await Promise.all(steerTasks);
@@ -149,6 +163,7 @@ export class PiAgentRuntime implements AgentRuntime {
 
     const closedRun: AgentRun = { ...run, state: "closed" };
     this.store.saveRun(closedRun);
+    this.deleteAgentBusSubscriptions(id);
     entry?.session.dispose();
     return closedRun;
   }
@@ -167,15 +182,15 @@ export class PiAgentRuntime implements AgentRuntime {
     try {
       await entry.session.prompt(message, { expandPromptTemplates: false });
       if (this.isClosed(id)) return;
-      if (this.store.getRun(id)?.state === "idle") {
+      if (this.isRunningWithoutResult(id)) {
         await entry.session.prompt(buildFinishRequiredPrompt(), { expandPromptTemplates: false });
       }
       if (this.isClosed(id)) return;
       const run = this.store.getRun(id);
-      if (run?.state === "idle") {
+      if (run && isRunningWithoutResult(run)) {
         this.store.saveRun({
           ...run,
-          state: "failed",
+          state: "idle",
           result: {
             status: "failed",
             summary: "Agent stopped without calling finish.",
@@ -189,7 +204,7 @@ export class PiAgentRuntime implements AgentRuntime {
       if (!run) return;
       this.store.saveRun({
         ...run,
-        state: "failed",
+        state: "idle",
         result: {
           status: "failed",
           summary: error instanceof Error ? error.message : String(error),
@@ -216,7 +231,7 @@ export class PiAgentRuntime implements AgentRuntime {
         this.store.saveRun({
           ...run,
           result,
-          state: result.status,
+          state: "idle",
         });
         return {
           content: [
@@ -276,30 +291,73 @@ export class PiAgentRuntime implements AgentRuntime {
     return this.store.getRun(id)?.state === "closed";
   }
 
+  private isRunningWithoutResult(id: string): boolean {
+    const run = this.store.getRun(id);
+    return run !== undefined && isRunningWithoutResult(run);
+  }
+
   private requireBus(id: string): Bus {
     const bus = this.store.getBus(id);
     if (!bus) throw new Error(`Bus ${id} not found.`);
     return bus;
   }
 
-  private withBusMessages(runId: string, entry: RuntimeEntry, message: string): string {
-    const busMessages = this.drainBusMessages(runId, entry);
+  private withSubscribedBusMessages(runId: string, message: string): string {
+    const busMessages = this.drainSubscribedBusMessages(runId);
     if (busMessages.length === 0) return message;
-    return [message, "", formatBusMessages(busMessages)].join("\n");
+    return [message, "", this.formatBusMessagesForPrompt(busMessages)].join("\n");
   }
 
-  private drainBusMessages(runId: string, entry: RuntimeEntry): BusMessage[] {
-    const run = this.requireRun(runId);
-    const bus = this.requireBus(run.busId);
-    const unreadMessages = bus.messages.filter((message) => {
-      if (message.from === run.id) return false;
-      return !entry.seenBusMessageIds.has(message.id);
+  private drainSubscribedBusMessages(runId: string): BusMessage[] {
+    const subscriptions = this.store.listBusSubscriptions({
+      busId: undefined,
+      subscriberId: runId,
+      subscriberKind: "agent",
     });
+    const unreadMessages: BusMessage[] = [];
+    for (const subscription of subscriptions) {
+      const bus = this.store.getBus(subscription.busId);
+      if (!bus) {
+        this.store.deleteBusSubscription(subscription.id);
+        continue;
+      }
+
+      const subscriptionUnreadMessages = bus.messages.filter((message) => {
+        if (message.from === runId) return false;
+        return !isBusMessageDelivered(subscription, message.id);
+      });
+      if (subscriptionUnreadMessages.length === 0) continue;
 
-    for (const message of unreadMessages) entry.seenBusMessageIds.add(message.id);
+      unreadMessages.push(...subscriptionUnreadMessages);
+      this.markSubscriptionMessagesDelivered(subscription, subscriptionUnreadMessages);
+    }
     return unreadMessages;
   }
 
+  private markSubscriptionMessagesDelivered(subscription: BusSubscription, messages: BusMessage | BusMessage[]): void {
+    const latestSubscription = this.store.getBusSubscription(subscription.id) ?? subscription;
+    this.store.saveBusSubscription(markBusMessagesDelivered(latestSubscription, messages));
+  }
+
+  private formatBusMessagesForPrompt(messages: BusMessage[]): string {
+    return formatBusMessages(messages, { formatFrom: (from) => this.formatBusMessageFrom(from) });
+  }
+
+  private formatBusMessageFrom(from: string): string {
+    if (from === "main") return from;
+    return this.store.getRun(from)?.name ?? from;
+  }
+
+  private deleteAgentBusSubscriptions(runId: string): void {
+    for (const subscription of this.store.listBusSubscriptions({
+      busId: undefined,
+      subscriberId: runId,
+      subscriberKind: "agent",
+    })) {
+      this.store.deleteBusSubscription(subscription.id);
+    }
+  }
+
   private async resolveProfileModel(profile: AgentProfile): Promise<Model<any> | undefined> {
     if (!profile.model) return undefined;
     if (!this.resolveModel) throw new Error(`No model resolver configured for profile model "${profile.model}".`);
@@ -326,6 +384,20 @@ function buildInitialPrompt(profile: AgentProfile, task: string, runName: string
   ].join("\n");
 }
 
+function requireProfileTools(profile: AgentProfile): string[] {
+  if (!Array.isArray(profile.tools)) throw new Error(`Profile "${profile.name}" must specify tools.`);
+  return profile.tools;
+}
+
+function createAgentBusSubscription(runId: string, busId: string): BusSubscription {
+  return createBusSubscription({
+    busId,
+    subscriberId: runId,
+    subscriberKind: "agent",
+    deliveredMessageIds: [],
+  });
+}
+
 function buildFinishRequiredPrompt(): string {
   return [
     "Your previous response ended without finish.",
@@ -333,6 +405,10 @@ function buildFinishRequiredPrompt(): string {
   ].join("\n");
 }
 
+function isRunningWithoutResult(run: AgentRun): boolean {
+  return run.state === "running" && run.result === undefined;
+}
+
 function getLastAssistantText(session: AgentSession): string | undefined {
   for (let i = session.messages.length - 1; i >= 0; i--) {
     const message = session.messages[i];