@zachwill/pi-orchestrate 0.1.0

package/extension/delivery.ts

@@ -0,0 +1,196 @@
+import type { CompletedWave } from "./runtime.js";
+
+export const MAX_DELIVERY_MARKDOWN_BYTES = 50 * 1024;
+export const DELIVERY_TRUNCATION_MARKER =
+  "\n\n[Worker results truncated at 50KB. Full structured results remain available.]";
+export const DELIVERY_PARENT_INSTRUCTIONS =
+  "Parent: Synthesize all results, resolve conflicts, review changes and evidence, run integration checks, and continue the user's task. Do not merely forward worker reports.";
+
+export type ParentBindingGeneration = string | number | symbol;
+
+export interface WaveDeliveryDetails {
+  readonly id: CompletedWave["id"];
+  readonly ownerSessionId: CompletedWave["ownerSessionId"];
+  readonly mode: CompletedWave["mode"];
+  readonly results: CompletedWave["results"];
+}
+
+export interface WaveDeliveryMessage {
+  readonly customType: "pi-orchestrate-wave";
+  readonly content: string;
+  readonly display: true;
+  readonly details: WaveDeliveryDetails;
+}
+
+export interface WaveDeliveryOptions {
+  readonly triggerTurn: boolean;
+}
+
+export interface ParentBinding {
+  readonly ownerSessionId: string;
+  readonly generation: ParentBindingGeneration;
+  isIdle(): boolean;
+  sendMessage(message: WaveDeliveryMessage, options: WaveDeliveryOptions): void;
+}
+
+interface BoundParent {
+  readonly binding: ParentBinding;
+  agentRunning: boolean;
+}
+
+export class DeliveryCoordinator {
+  private readonly boundParents = new Map<string, BoundParent>();
+  private readonly pendingWaves: CompletedWave[] = [];
+
+  bind(binding: ParentBinding): void {
+    this.boundParents.set(binding.ownerSessionId, {
+      binding,
+      agentRunning: !binding.isIdle(),
+    });
+    this.flush(binding.ownerSessionId, binding.generation);
+  }
+
+  unbind(ownerSessionId: string, generation: ParentBindingGeneration): void {
+    if (!this.matchesBinding(ownerSessionId, generation)) return;
+    this.boundParents.delete(ownerSessionId);
+  }
+
+  markAgentStarted(ownerSessionId: string, generation: ParentBindingGeneration): void {
+    if (!this.matchesBinding(ownerSessionId, generation)) return;
+    this.boundParents.get(ownerSessionId)!.agentRunning = true;
+  }
+
+  markAgentSettled(ownerSessionId: string, generation: ParentBindingGeneration): void {
+    if (!this.matchesBinding(ownerSessionId, generation)) return;
+    this.boundParents.get(ownerSessionId)!.agentRunning = false;
+    this.flush(ownerSessionId, generation);
+  }
+
+  accept(completedWave: CompletedWave): boolean {
+    if (completedWave.mode === "inline") return false;
+
+    this.pendingWaves.push(completedWave);
+    const generation = this.boundParents.get(completedWave.ownerSessionId)?.binding.generation;
+    if (generation !== undefined) {
+      this.flush(completedWave.ownerSessionId, generation);
+    }
+    return true;
+  }
+
+  pendingCount(ownerSessionId: string): number {
+    return this.pendingWaves.filter((wave) => wave.ownerSessionId === ownerSessionId).length;
+  }
+
+  clear(): void {
+    this.boundParents.clear();
+    this.pendingWaves.length = 0;
+  }
+
+  close(): void {
+    this.clear();
+  }
+
+  private matchesBinding(
+    ownerSessionId: string,
+    generation: ParentBindingGeneration,
+  ): boolean {
+    const binding = this.boundParents.get(ownerSessionId)?.binding;
+    return binding?.generation === generation;
+  }
+
+  private canDeliver(
+    ownerSessionId: string,
+    generation: ParentBindingGeneration,
+  ): boolean {
+    const parent = this.boundParents.get(ownerSessionId);
+    return (
+      parent !== undefined &&
+      parent.binding.generation === generation &&
+      !parent.agentRunning &&
+      parent.binding.isIdle()
+    );
+  }
+
+  private flush(
+    ownerSessionId: string,
+    generation: ParentBindingGeneration,
+  ): void {
+    if (!this.canDeliver(ownerSessionId, generation)) return;
+
+    const waves = this.pendingWaves.filter((wave) => wave.ownerSessionId === ownerSessionId);
+    for (let index = 0; index < waves.length; index += 1) {
+      if (!this.canDeliver(ownerSessionId, generation)) return;
+
+      const wave = waves[index];
+      if (!wave) return;
+
+      try {
+        // Pi 0.80.10 starts an idle turn only through triggerTurn. Omitting deliverAs keeps
+        // streaming races as steering; nextTurn would queue without starting a turn.
+        this.boundParents.get(ownerSessionId)!.binding.sendMessage(renderWaveMessage(wave), {
+          triggerTurn: index === waves.length - 1,
+        });
+      } catch {
+        return;
+      }
+
+      const pendingIndex = this.pendingWaves.indexOf(wave);
+      if (pendingIndex >= 0) this.pendingWaves.splice(pendingIndex, 1);
+    }
+  }
+}
+
+function renderWaveMessage(wave: CompletedWave): WaveDeliveryMessage {
+  const resultWord = wave.results.length === 1 ? "result" : "results";
+  const sections = wave.results.map((result) => {
+    const outcome = renderOutcome(result.outcome);
+    const heading = `### ${result.worker} — ${result.title}`;
+    const metadata = `Worker \`${result.workerId}\` · status \`${result.status}\``;
+    return outcome.length > 0 ? `${heading}\n${metadata}\n\n${outcome}` : `${heading}\n${metadata}`;
+  });
+  const summary = `## Worker results — wave \`${wave.id}\`\n\n${wave.results.length} ${resultWord}`;
+  const results = sections.length > 0 ? `${summary}\n\n${sections.join("\n\n")}` : summary;
+  const instructions = `\n\n---\n\n${DELIVERY_PARENT_INSTRUCTIONS}`;
+
+  return {
+    customType: "pi-orchestrate-wave",
+    content: capMarkdown(results, instructions),
+    display: true,
+    details: {
+      id: wave.id,
+      ownerSessionId: wave.ownerSessionId,
+      mode: wave.mode,
+      results: wave.results,
+    },
+  };
+}
+
+function capMarkdown(content: string, appendix: string): string {
+  const complete = `${content}${appendix}`;
+  const completeBytes = Buffer.from(complete, "utf8");
+  if (completeBytes.byteLength <= MAX_DELIVERY_MARKDOWN_BYTES) return complete;
+
+  const contentBytes = Buffer.from(content, "utf8");
+  const reservedBytes = Buffer.byteLength(`${DELIVERY_TRUNCATION_MARKER}${appendix}`, "utf8");
+  let prefixEnd = MAX_DELIVERY_MARKDOWN_BYTES - reservedBytes;
+  while (prefixEnd > 0 && (contentBytes[prefixEnd]! & 0xc0) === 0x80) prefixEnd -= 1;
+  return `${contentBytes.subarray(0, prefixEnd).toString("utf8")}${DELIVERY_TRUNCATION_MARKER}${appendix}`;
+}
+
+function renderOutcome(outcome: CompletedWave["results"][number]["outcome"]): string {
+  switch (outcome.status) {
+    case "completed":
+    case "ready":
+      return outcome.assistantText;
+    case "failed":
+      return outcome.assistantText
+        ? `Failed: ${outcome.message}\n\n${outcome.assistantText}`
+        : `Failed: ${outcome.message}`;
+    case "aborted": {
+      const reason = outcome.message ? `Aborted: ${outcome.message}` : "Aborted";
+      return outcome.assistantText ? `${reason}\n\n${outcome.assistantText}` : reason;
+    }
+    case "closed":
+      return "Closed";
+  }
+}

package/extension/domain.ts

@@ -0,0 +1,335 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+
+export const SUPPORTED_TOOL_NAMES = [
+  "read",
+  "bash",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+] as const;
+
+export type SupportedToolName = (typeof SUPPORTED_TOOL_NAMES)[number];
+
+const supportedToolNames: ReadonlySet<string> = new Set(SUPPORTED_TOOL_NAMES);
+
+export function isSupportedToolName(value: unknown): value is SupportedToolName {
+  return typeof value === "string" && supportedToolNames.has(value);
+}
+
+export type WorkerSourceKind = "package" | "user" | "project";
+
+export interface WorkerSource {
+  readonly kind: WorkerSourceKind;
+  readonly filePath: string;
+}
+
+export interface WorkerModel {
+  readonly provider: string;
+  readonly modelId: string;
+}
+
+export interface WorkerCompaction {
+  readonly enabled?: boolean;
+  readonly reserveTokens?: number;
+  readonly keepRecentTokens?: number;
+}
+
+export type WorkerLifecycle = "one-shot" | "reusable";
+
+export interface WorkerDefinition {
+  readonly name: string;
+  readonly source: WorkerSource;
+  readonly description: string;
+  readonly systemPrompt: string;
+  readonly lifecycle: WorkerLifecycle;
+  readonly tools: readonly SupportedToolName[];
+  readonly skills: readonly string[];
+  readonly model?: WorkerModel;
+  readonly thinking?: ThinkingLevel;
+  readonly compaction?: WorkerCompaction;
+}
+
+export type CatalogDiagnosticSeverity = "warning" | "error";
+
+export interface CatalogDiagnostic {
+  readonly severity: CatalogDiagnosticSeverity;
+  readonly source: WorkerSourceKind;
+  readonly message: string;
+  readonly filePath?: string;
+}
+
+export interface WorkerCatalog {
+  readonly workers: readonly WorkerDefinition[];
+  readonly diagnostics: readonly CatalogDiagnostic[];
+}
+
+export function createWorkerCatalog(
+  workers: readonly WorkerDefinition[],
+  diagnostics: readonly CatalogDiagnostic[] = [],
+): WorkerCatalog {
+  return {
+    workers: [...workers].sort(compareWorkersByName),
+    diagnostics: [...diagnostics],
+  };
+}
+
+export function findWorkerByName(
+  catalog: WorkerCatalog,
+  name: string,
+): WorkerDefinition | undefined {
+  return catalog.workers.find((worker) => worker.name === name);
+}
+
+function compareWorkersByName(left: WorkerDefinition, right: WorkerDefinition): number {
+  if (left.name < right.name) return -1;
+  if (left.name > right.name) return 1;
+  return 0;
+}
+
+export interface OrchestrateTaskInput {
+  readonly worker: string;
+  readonly title: string;
+  readonly instructions: string;
+}
+
+declare const workerIdBrand: unique symbol;
+declare const waveIdBrand: unique symbol;
+
+export type WorkerId = string & { readonly [workerIdBrand]: "WorkerId" };
+export type WaveId = string & { readonly [waveIdBrand]: "WaveId" };
+
+export type WorkerIdFactory = () => WorkerId;
+export type WaveIdFactory = () => WaveId;
+
+export interface OrchestrateIdFactories {
+  readonly workerId: WorkerIdFactory;
+  readonly waveId: WaveIdFactory;
+}
+
+export function createRandomWorkerIdFactory(
+  randomId: () => string = defaultRandomId,
+): WorkerIdFactory {
+  return () => `worker-${randomId()}` as WorkerId;
+}
+
+export function createRandomWaveIdFactory(
+  randomId: () => string = defaultRandomId,
+): WaveIdFactory {
+  return () => `wave-${randomId()}` as WaveId;
+}
+
+export function createRandomIdFactories(
+  randomId: () => string = defaultRandomId,
+): OrchestrateIdFactories {
+  return {
+    workerId: createRandomWorkerIdFactory(randomId),
+    waveId: createRandomWaveIdFactory(randomId),
+  };
+}
+
+export function createSequentialWorkerIdFactory(startAt = 1): WorkerIdFactory {
+  let next = startAt;
+  return () => `worker-${next++}` as WorkerId;
+}
+
+export function createSequentialWaveIdFactory(startAt = 1): WaveIdFactory {
+  let next = startAt;
+  return () => `wave-${next++}` as WaveId;
+}
+
+export function createSequentialIdFactories(startAt = 1): OrchestrateIdFactories {
+  return {
+    workerId: createSequentialWorkerIdFactory(startAt),
+    waveId: createSequentialWaveIdFactory(startAt),
+  };
+}
+
+function defaultRandomId(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+export interface WorkerUsage {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly cost: number;
+  readonly contextTokens: number;
+  readonly turns: number;
+}
+
+export const EMPTY_WORKER_USAGE: WorkerUsage = Object.freeze({
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  cost: 0,
+  contextTokens: 0,
+  turns: 0,
+});
+
+export interface WorkerCompletedOutcome {
+  readonly status: "completed";
+  readonly assistantText: string;
+}
+
+export interface WorkerReadyOutcome {
+  readonly status: "ready";
+  readonly assistantText: string;
+}
+
+export interface WorkerFailedOutcome {
+  readonly status: "failed";
+  readonly message: string;
+  readonly assistantText?: string;
+}
+
+export interface WorkerAbortedOutcome {
+  readonly status: "aborted";
+  readonly message?: string;
+  readonly assistantText?: string;
+}
+
+export interface WorkerClosedOutcome {
+  readonly status: "closed";
+}
+
+export type WorkerOutcome =
+  | WorkerCompletedOutcome
+  | WorkerReadyOutcome
+  | WorkerFailedOutcome
+  | WorkerAbortedOutcome
+  | WorkerClosedOutcome;
+export type TerminalWorkerOutcome = Exclude<WorkerOutcome, WorkerReadyOutcome>;
+export type WorkerStatus =
+  | "starting"
+  | "running"
+  | "ready"
+  | "stopping"
+  | "completed"
+  | "failed"
+  | "aborted"
+  | "closed";
+export type TerminalWorkerStatus = Extract<
+  WorkerStatus,
+  "completed" | "failed" | "aborted" | "closed"
+>;
+export type WaveCompleteWorkerStatus = TerminalWorkerStatus | "ready";
+
+export interface WorkerRecord {
+  readonly id: WorkerId;
+  readonly worker: string;
+  readonly ownerSessionId: string;
+  readonly waveId: WaveId;
+  readonly title: string;
+  readonly instructions: string;
+  readonly lifecycle: WorkerLifecycle;
+  readonly status: WorkerStatus;
+  readonly usage: WorkerUsage;
+  readonly activity?: string;
+  readonly outcome?: WorkerOutcome;
+  readonly sessionFile?: string;
+}
+
+export type WaveMode = "async" | "inline";
+export type WaveState = "running" | "complete";
+
+export interface WaveRecord {
+  readonly id: WaveId;
+  readonly ownerSessionId: string;
+  readonly workerIds: readonly WorkerId[];
+  readonly mode: WaveMode;
+  readonly state: WaveState;
+  readonly createdAt: number;
+}
+
+export class InvalidTransitionError extends Error {
+  readonly from: WorkerStatus;
+  readonly to: WorkerStatus;
+
+  constructor(from: WorkerStatus, to: WorkerStatus) {
+    super(`Invalid worker status transition: ${from} -> ${to}`);
+    this.name = "InvalidTransitionError";
+    this.from = from;
+    this.to = to;
+  }
+}
+
+export function isTerminalWorkerStatus(status: WorkerStatus): status is TerminalWorkerStatus {
+  return status === "completed" || status === "failed" || status === "aborted" || status === "closed";
+}
+
+export function isTerminalWorkerOutcome(outcome: WorkerOutcome): outcome is TerminalWorkerOutcome {
+  return outcome.status !== "ready";
+}
+
+export function canTransitionWorkerStatus(
+  from: WorkerStatus,
+  to: WorkerStatus,
+  lifecycle: WorkerLifecycle,
+): boolean {
+  if (from === to || isTerminalWorkerStatus(from)) return false;
+
+  switch (from) {
+    case "starting":
+      return to === "running" || to === "stopping" || to === "failed" || to === "aborted";
+    case "running":
+      if (to === "ready") return lifecycle === "reusable";
+      if (to === "completed") return lifecycle === "one-shot";
+      return to === "stopping" || to === "failed" || to === "aborted";
+    case "ready":
+      if (lifecycle !== "reusable") return false;
+      return to === "running" || to === "stopping" || to === "closed";
+    case "stopping":
+      return to === "aborted" || to === "failed";
+    default:
+      return false;
+  }
+}
+
+export function transitionWorkerStatus(
+  worker: WorkerRecord,
+  status: WorkerStatus,
+): WorkerRecord {
+  if (!canTransitionWorkerStatus(worker.status, status, worker.lifecycle)) {
+    throw new InvalidTransitionError(worker.status, status);
+  }
+
+  return { ...worker, status, outcome: undefined };
+}
+
+export function isWorkerCompleteForWave(
+  status: WorkerStatus,
+): status is WaveCompleteWorkerStatus {
+  return status === "ready" || isTerminalWorkerStatus(status);
+}
+
+export function getWaveWorkersInOrder(
+  wave: WaveRecord,
+  workersById: ReadonlyMap<WorkerId, WorkerRecord>,
+): readonly WorkerRecord[] | undefined {
+  const workers: WorkerRecord[] = [];
+
+  for (const workerId of wave.workerIds) {
+    const worker = workersById.get(workerId);
+    if (!worker) return undefined;
+    workers.push(worker);
+  }
+
+  return workers;
+}
+
+export function isWaveComplete(
+  wave: WaveRecord,
+  workersById: ReadonlyMap<WorkerId, WorkerRecord>,
+): boolean {
+  const workers = getWaveWorkersInOrder(wave, workersById);
+  return workers !== undefined && workers.every((worker) => isWorkerCompleteForWave(worker.status));
+}
+
+export const MAX_TASKS_PER_WAVE = 12;
+export const MAX_WORKER_TITLE_LENGTH = 200;
+export const MAX_WORKER_INSTRUCTIONS_LENGTH = 100_000;
+export const CANCELLATION_GRACE_MS = 5_000;

package/extension/host.ts

@@ -0,0 +1,107 @@
+import { DeliveryCoordinator } from "./delivery.js";
+import {
+  createOrchestratorRuntime,
+  type OrchestratorRuntime,
+} from "./runtime.js";
+import { createWorkerSessionFactory } from "./worker-session.js";
+
+const PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v1");
+
+export interface ProcessHost {
+  readonly runtime: OrchestratorRuntime;
+  readonly delivery: DeliveryCoordinator;
+}
+
+export interface ProcessHostAttachment {
+  readonly host: ProcessHost;
+}
+
+interface AttachmentAwareProcessHost extends ProcessHost {
+  attachments?: Set<ProcessHostAttachment>;
+}
+
+interface OwnedProcessHost extends AttachmentAwareProcessHost {
+  readonly unsubscribeCompletion: () => void;
+  destroyPromise?: Promise<void>;
+}
+
+type ProcessGlobal = typeof globalThis & {
+  [PROCESS_HOST_KEY]?: OwnedProcessHost;
+};
+
+function processGlobal(): ProcessGlobal {
+  return globalThis as ProcessGlobal;
+}
+
+export function getProcessHost(): ProcessHost | undefined {
+  return processGlobal()[PROCESS_HOST_KEY];
+}
+
+export function createProcessHost(): ProcessHost {
+  const global = processGlobal();
+  const existing = global[PROCESS_HOST_KEY];
+  if (existing) return existing;
+
+  const runtime = createOrchestratorRuntime({
+    workerSessionFactory: createWorkerSessionFactory(),
+  });
+  const delivery = new DeliveryCoordinator();
+  const host: OwnedProcessHost = {
+    runtime,
+    delivery,
+    attachments: new Set(),
+    unsubscribeCompletion: runtime.subscribeCompletion((wave) => {
+      delivery.accept(wave);
+    }),
+  };
+  global[PROCESS_HOST_KEY] = host;
+  return host;
+}
+
+export function attachProcessHost(host: ProcessHost): ProcessHostAttachment {
+  const attachment: ProcessHostAttachment = { host };
+  const attachmentAwareHost = host as AttachmentAwareProcessHost;
+  attachmentAwareHost.attachments ??= new Set();
+  attachmentAwareHost.attachments.add(attachment);
+  return attachment;
+}
+
+export function detachProcessHost(
+  host: ProcessHost,
+  attachment: ProcessHostAttachment,
+): boolean {
+  if (attachment.host !== host) return false;
+
+  const attachments = (host as AttachmentAwareProcessHost).attachments;
+  if (!attachments?.delete(attachment)) return false;
+  return attachments.size === 0;
+}
+
+export async function destroyProcessHost(host: ProcessHost): Promise<void> {
+  const ownedHost = host as OwnedProcessHost;
+  if ((ownedHost.attachments?.size ?? 0) > 0) return;
+  if (ownedHost.destroyPromise) {
+    await ownedHost.destroyPromise;
+    return;
+  }
+
+  ownedHost.destroyPromise = (async () => {
+    try {
+      await ownedHost.runtime.shutdown();
+    } finally {
+      ownedHost.delivery.clear();
+      ownedHost.unsubscribeCompletion();
+      const global = processGlobal();
+      if (global[PROCESS_HOST_KEY] === ownedHost) {
+        delete global[PROCESS_HOST_KEY];
+      }
+    }
+  })();
+  await ownedHost.destroyPromise;
+}
+
+export async function quitProcessHost(): Promise<void> {
+  const host = getProcessHost();
+  if (!host) return;
+  await destroyProcessHost(host);
+}