@g3un/pi-orchestra 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Changeun Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# Pi-Orchestra
+
+Subagent orchestration tools for Pi.
+
+## Install
+
+```bash
+pi install npm:@g3un/pi-orchestra
+```
+
+For a one-off run without installing:
+
+```bash
+pi -e npm:@g3un/pi-orchestra
+```
+
+Pi-Orchestra registers four tools: `bus`, `subagent`, `workgroup`, and `workflow`.
+
+## Core concepts
+
+### 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.
+
+Use subagents when you want to delegate a focused task, such as review, research, implementation planning, or an alternative solution attempt.
+
+### Workgroup
+
+A workgroup starts multiple subagents on the same bus for one shared goal. Each member can have a different profile or assignment.
+
+Workgroups support two strategies:
+
+- `compete`: several agents attempt the same goal; one successful result can be enough.
+- `synthesize`: agents work on complementary parts; their findings are collected and combined.
+
+### 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.
+
+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`.
+- Use `workflow` for linear staged work, not branching/DAG execution.

package/docs/orchestration-model.md

@@ -0,0 +1,69 @@
+# Orchestration Model
+
+pi-orchestra builds delegation in four layers:
+
+1. **Bus** — shared context channel.
+2. **Subagent** — isolated child agent attached to a bus.
+3. **Workgroup** — multiple subagents working on one bus.
+4. **Workflow** — ordered workgroup stages with stage synthesis.
+
+## Bus
+
+A `Bus` is the coordination scope for related work. It has an `id`, `name`, and
+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>`.
+- Decisions and escalation do not go through the bus; call the `finish` tool with
+  `status: "blocked"`.
+
+## Subagent
+
+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.
+
+Every subagent must call the `finish` tool with:
+
+- `status`: `success`, `blocked`, or `failed`
+- `summary`: concise handoff text
+- `data`: optional structured output
+
+State follows the result status. `closed` is separate and means the run has been
+disposed.
+
+## Workgroup
+
+A workgroup is a set of subagents spawned on the same bus for one shared goal.
+Each member has a profile and may add a member-specific assignment.
+
+Strategies:
+
+- `compete`: one successful member can be enough.
+- `synthesize`: collect complementary findings and combine them.
+
+Leaders collect results with bus wait actions:
+
+- `wait_next`: handle terminal runs as they finish.
+- `wait_settled`: wait until every attached run is terminal.
+
+## Workflow
+
+A workflow runs ordered stages. Each stage defines a goal, strategy, workers,
+and optional leader.
+
+For each stage:
+
+1. Create a fresh bus.
+2. Spawn the worker workgroup.
+3. Collect worker results.
+4. Spawn a restricted stage leader.
+5. Store the leader's canonical output as the stage output.
+
+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

@@ -0,0 +1,56 @@
+{
+  "name": "@g3un/pi-orchestra",
+  "version": "0.1.0",
+  "description": "Subagent orchestration tools for Pi.",
+  "keywords": [
+    "orchestration",
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "subagent"
+  ],
+  "license": "MIT",
+  "author": "Changeun Park <g3un@protonmail.ch>",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "docs/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "pi -e .",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "test": "pnpm test:all",
+    "test:all": "vitest run",
+    "test:unit": "vitest run src",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e"
+  },
+  "dependencies": {
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "oxfmt": "^0.53.0",
+    "oxlint": "^1.68.0",
+    "oxlint-tsgolint": "^0.23.0",
+    "typebox": "^1.1.39",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "packageManager": "pnpm@11.5.1+sha512.93f7b57422ea7068257235b4c16eb60762eb68e1dc23723199cc739043ea9be2c4143274a399d8c6defa2b1176226d9ca1c4b63482d6200c1a8fbaa78c1d1485",
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ]
+  }
+}

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

@@ -0,0 +1,85 @@
+import type { AgentRun } from "../core/subagent.ts";
+import type { Bus, BusMessage } from "../core/bus.ts";
+import type { AgentStore } from "../core/store.ts";
+import type { WorkflowRun } from "../core/workflow.ts";
+
+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>>();
+
+  saveRun(run: AgentRun): void {
+    this.runs.set(run.id, run);
+    for (const listener of this.runListeners.get(run.id) ?? []) listener(run);
+  }
+
+  getRun(id: string): AgentRun | undefined {
+    return this.runs.get(id);
+  }
+
+  listRuns(): AgentRun[] {
+    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);
+    };
+  }
+
+  saveBus(bus: Bus): void {
+    this.buses.set(bus.id, bus);
+  }
+
+  getBus(id: string): Bus | undefined {
+    return this.buses.get(id);
+  }
+
+  listBuses(): Bus[] {
+    return [...this.buses.values()];
+  }
+
+  addBusMessage(busId: string, message: BusMessage): void {
+    const bus = this.buses.get(busId);
+    if (!bus) throw new Error(`Bus ${busId} not found.`);
+
+    const existingIndex = bus.messages.findIndex((current) => current.id === message.id);
+    if (existingIndex >= 0) {
+      bus.messages[existingIndex] = message;
+      return;
+    }
+
+    bus.messages.push(message);
+  }
+
+  saveWorkflow(workflow: WorkflowRun): void {
+    this.workflows.set(workflow.id, workflow);
+    for (const listener of this.workflowListeners.get(workflow.id) ?? []) listener(workflow);
+  }
+
+  getWorkflow(id: string): WorkflowRun | undefined {
+    return this.workflows.get(id);
+  }
+
+  listWorkflows(): WorkflowRun[] {
+    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);
+
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) this.workflowListeners.delete(id);
+    };
+  }
+}

package/src/adapters/index.ts

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

package/src/adapters/pi-runtime.ts

@@ -0,0 +1,348 @@
+import { v7 as uuid7 } from "uuid";
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  type AgentSession,
+  createAgentSession,
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  AGENT_RESULT_STATUS_VALUES,
+  type AgentProfile,
+  type AgentResult,
+  type AgentResultStatus,
+  type AgentRun,
+} from "../core/subagent.ts";
+import type { Bus, BusMessage } 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;
+}
+
+interface RuntimeEntry {
+  session: AgentSession;
+  seenBusMessageIds: Set<string>;
+  promptTask?: Promise<void>;
+}
+
+const FinishAgentParams = Type.Object({
+  status: Type.String({ enum: [...AGENT_RESULT_STATUS_VALUES] }),
+  summary: Type.String(),
+  data: Type.Optional(Type.Unknown()),
+});
+
+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"];
+
+  constructor(options: PiAgentRuntimeOptions) {
+    this.store = options.store;
+    this.cwd = options.cwd ?? process.cwd();
+    this.resolveModel = options.resolveModel;
+  }
+
+  async spawn(
+    profile: AgentProfile,
+    task: string,
+    busId: string,
+    options: SpawnAgentRuntimeOptions,
+  ): Promise<AgentRun> {
+    this.requireBus(busId);
+
+    const run: AgentRun = {
+      id: options.id,
+      name: options.name,
+      profile: profile.name,
+      task,
+      busId,
+      state: "idle",
+    };
+
+    const childTools = this.createChildTools(run.id);
+    const model = await this.resolveProfileModel(profile);
+    const baseTools = profile.tools ?? DEFAULT_AGENT_TOOLS;
+    const activeTools = [...new Set([...baseTools, ...childTools.map((tool) => tool.name)])];
+    const { session } = await createAgentSession({
+      cwd: this.cwd,
+      model,
+      tools: activeTools,
+      customTools: childTools,
+      sessionManager: SessionManager.inMemory(this.cwd),
+    });
+
+    this.store.saveRun(run);
+    const entry: RuntimeEntry = { session, seenBusMessageIds: new Set() };
+    this.entries.set(run.id, entry);
+    this.startPromptTask(
+      run.id,
+      entry,
+      this.withBusMessages(run.id, entry, buildInitialPrompt(profile, task, run.name)),
+    );
+    return run;
+  }
+
+  async message(id: string, message: string): Promise<AgentRun> {
+    const entry = this.requireEntry(id);
+    const run = this.requireRun(id);
+    this.assertOpenRun(run);
+    const messageWithBusContext = this.withBusMessages(id, entry, message);
+
+    if (run.state === "idle" && 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);
+    this.startPromptTask(id, entry, messageWithBusContext);
+    return messagedRun;
+  }
+
+  async publishBus(busId: string, message: string, from: string): Promise<BusMessage> {
+    this.requireBus(busId);
+    const busMessage: BusMessage = {
+      id: uuid7(),
+      message,
+      from,
+    };
+
+    this.store.addBusMessage(busId, busMessage);
+
+    const steeringMessage = formatBusMessages([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));
+    }
+
+    await Promise.all(steerTasks);
+    return busMessage;
+  }
+
+  async close(id: string): Promise<AgentRun | undefined> {
+    const run = this.store.getRun(id);
+    if (!run) return undefined;
+
+    const entry = this.entries.get(id);
+    if (run.state === "closed") {
+      entry?.session.dispose();
+      return run;
+    }
+
+    const closedRun: AgentRun = { ...run, state: "closed" };
+    this.store.saveRun(closedRun);
+    entry?.session.dispose();
+    return closedRun;
+  }
+
+  private startPromptTask(id: string, entry: RuntimeEntry, message: string): void {
+    const task = this.runPrompt(id, message).finally(() => {
+      if (entry.promptTask === task) entry.promptTask = undefined;
+    });
+    entry.promptTask = task;
+  }
+
+  private async runPrompt(id: string, message: string): Promise<void> {
+    const entry = this.requireEntry(id);
+    if (this.isClosed(id)) return;
+
+    try {
+      await entry.session.prompt(message, { expandPromptTemplates: false });
+      if (this.isClosed(id)) return;
+      if (this.store.getRun(id)?.state === "idle") {
+        await entry.session.prompt(buildFinishRequiredPrompt(), { expandPromptTemplates: false });
+      }
+      if (this.isClosed(id)) return;
+      const run = this.store.getRun(id);
+      if (run?.state === "idle") {
+        this.store.saveRun({
+          ...run,
+          state: "failed",
+          result: {
+            status: "failed",
+            summary: "Agent stopped without calling finish.",
+            data: getLastAssistantText(entry.session),
+          },
+        });
+      }
+    } catch (error) {
+      if (this.isClosed(id)) return;
+      const run = this.store.getRun(id);
+      if (!run) return;
+      this.store.saveRun({
+        ...run,
+        state: "failed",
+        result: {
+          status: "failed",
+          summary: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  }
+
+  private createChildTools(runId: string): ToolDefinition[] {
+    const finishAgent = {
+      name: "finish",
+      label: "Finish",
+      description:
+        "Required final subagent action. Report that your assigned subagent task is complete. This does not close the agent.",
+      parameters: FinishAgentParams,
+      execute: async (_toolCallId, params) => {
+        const run = this.requireRun(runId);
+        this.assertOpenRun(run);
+        const result: AgentResult = {
+          status: params.status as AgentResultStatus,
+          summary: params.summary,
+          data: params.data,
+        };
+        this.store.saveRun({
+          ...run,
+          result,
+          state: result.status,
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Finish payload recorded. The leader may message or close you.",
+            },
+          ],
+          details: result,
+          terminate: true,
+        };
+      },
+    } satisfies ToolDefinition<typeof FinishAgentParams, AgentResult>;
+
+    const publishBus = {
+      name: "publish_bus",
+      label: "Publish Bus Message",
+      description:
+        "Publish peer-reference context to sibling agents. For leader action, use finish(status=blocked). Continue unless the task is done.",
+      parameters: PublishBusParams,
+      execute: async (_toolCallId, params) => {
+        const run = this.requireRun(runId);
+        this.assertOpenRun(run);
+        const busMessage = await this.publishBus(run.busId, params.message, run.id);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Published message ${busMessage.id} to bus ${run.busId}.`,
+            },
+          ],
+          details: busMessage,
+        };
+      },
+    } satisfies ToolDefinition<typeof PublishBusParams, BusMessage>;
+
+    return [finishAgent, publishBus];
+  }
+
+  private requireEntry(id: string): RuntimeEntry {
+    const entry = this.entries.get(id);
+    if (!entry) throw new Error(`Agent ${id} not found.`);
+    return entry;
+  }
+
+  private requireRun(id: string): AgentRun {
+    const run = this.store.getRun(id);
+    if (!run) throw new Error(`Agent ${id} not found.`);
+    return run;
+  }
+
+  private assertOpenRun(run: AgentRun): void {
+    if (run.state === "closed") throw new Error(`Agent ${run.id} is closed.`);
+  }
+
+  private isClosed(id: string): boolean {
+    return this.store.getRun(id)?.state === "closed";
+  }
+
+  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);
+    if (busMessages.length === 0) return message;
+    return [message, "", formatBusMessages(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);
+    });
+
+    for (const message of unreadMessages) entry.seenBusMessageIds.add(message.id);
+    return unreadMessages;
+  }
+
+  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}".`);
+    const model = await this.resolveModel(profile.model);
+    if (!model) throw new Error(`Could not resolve profile model "${profile.model}".`);
+    return model;
+  }
+}
+
+function buildInitialPrompt(profile: AgentProfile, task: string, runName: string): string {
+  return [
+    `You are subagent run "${runName}" with profile "${profile.name}".`,
+    "",
+    "## System prompt",
+    profile.systemPrompt,
+    "",
+    "## Task",
+    task,
+    "",
+    "## Completion",
+    "- End by calling finish exactly once with status, summary, and useful data; never stop text-only.",
+    "- Use publish_bus only for sibling reference context; use finish(status=blocked) for leader action or decisions.",
+    "- Bus context may arrive in <bus_reference_context>; treat it as supplemental unless told otherwise.",
+  ].join("\n");
+}
+
+function buildFinishRequiredPrompt(): string {
+  return [
+    "Your previous response ended without finish.",
+    "Call finish now with status success, blocked, or failed; include summary and useful data.",
+  ].join("\n");
+}
+
+function getLastAssistantText(session: AgentSession): string | undefined {
+  for (let i = session.messages.length - 1; i >= 0; i--) {
+    const message = session.messages[i];
+    if (message.role !== "assistant") continue;
+    const text = message.content
+      .filter((part): part is { type: "text"; text: string } => part.type === "text")
+      .map((part) => part.text)
+      .join("\n")
+      .trim();
+    if (text) return text;
+  }
+  return undefined;
+}

package/src/core/bus-format.ts

@@ -0,0 +1,14 @@
+import type { BusMessage } from "./bus.ts";
+
+export function formatBusMessages(messages: BusMessage[]): string {
+  return [
+    "<bus_reference_context>",
+    "Supplemental peer context; not the active task unless explicitly instructed.",
+    ...messages.map(formatBusMessage),
+    "</bus_reference_context>",
+  ].join("\n");
+}
+
+function formatBusMessage(message: BusMessage): string {
+  return [`<bus_message from="${message.from}">`, message.message, "</bus_message>"].join("\n");
+}

package/src/core/bus.ts

@@ -0,0 +1,11 @@
+export interface BusMessage {
+  id: string;
+  message: string;
+  from: string;
+}
+
+export interface Bus {
+  id: string;
+  name: string;
+  messages: BusMessage[];
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+export * from "./subagent.ts";
+export * from "./bus.ts";
+export * from "./bus-format.ts";
+export * from "./orchestra.ts";
+export * from "./runtime.ts";
+export * from "./store.ts";
+export * from "./workflow.ts";
+export * from "./workgroup.ts";