@zachwill/pi-orchestrate 0.2.1 → 0.4.0

package/extension/delivery.ts

@@ -35,10 +35,17 @@ interface BoundParent {
   agentRunning: boolean;
 }
 
+interface SynthesisGroupState {
+  expected: number;
+  readonly acceptedEventIds: string[];
+}
+
 export class DeliveryCoordinator {
   private readonly boundParents = new Map<string, BoundParent>();
   private readonly pendingSettlements: WorkerSettlement[] = [];
   private readonly flushingOwners = new Set<string>();
+  private readonly synthesisGroups = new Map<string, SynthesisGroupState>();
+  private readonly finalSynthesisGroupEvents = new Set<string>();
   private highestAcceptedSequence = 0;
 
   bind(binding: ParentBinding): void {
@@ -75,12 +82,28 @@ export class DeliveryCoordinator {
 
     this.highestAcceptedSequence = settlement.sequence;
     this.pendingSettlements.push(settlement);
+    this.acceptSynthesisGroupSettlement(settlement);
 
     const parent = this.boundParents.get(settlement.ownerSessionId);
     if (parent) this.flush(settlement.ownerSessionId, parent.binding.generation);
     return true;
   }
 
+  skipSynthesisGroupMember(
+    ownerSessionId: string,
+    synthesisGroupId: string,
+    synthesisGroupSize: number,
+  ): void {
+    const key = synthesisGroupKey(ownerSessionId, synthesisGroupId);
+    const state = this.synthesisGroups.get(key) ?? {
+      expected: synthesisGroupSize,
+      acceptedEventIds: [],
+    };
+    state.expected = Math.max(0, state.expected - 1);
+    this.synthesisGroups.set(key, state);
+    this.refreshSynthesisGroupBoundary(key, state);
+  }
+
   pendingCount(ownerSessionId: string): number {
     return this.pendingSettlements.filter(
       (settlement) => settlement.ownerSessionId === ownerSessionId,
@@ -91,13 +114,11 @@ export class DeliveryCoordinator {
     this.boundParents.clear();
     this.pendingSettlements.length = 0;
     this.flushingOwners.clear();
+    this.synthesisGroups.clear();
+    this.finalSynthesisGroupEvents.clear();
     this.highestAcceptedSequence = 0;
   }
 
-  close(): void {
-    this.clear();
-  }
-
   private matchesBinding(
     ownerSessionId: string,
     generation: ParentBindingGeneration,
@@ -127,7 +148,8 @@ export class DeliveryCoordinator {
       );
       let latestFinalIndex = -1;
       for (let index = 0; index < queued.length; index += 1) {
-        if (queued[index]?.waveComplete) latestFinalIndex = index;
+        const settlement = queued[index];
+        if (settlement && this.isFinalBoundary(settlement)) latestFinalIndex = index;
       }
       const flushThrough = latestFinalIndex >= 0 ? latestFinalIndex : queued.length - 1;
       let flushBytesRemaining = MAX_DELIVERY_MARKDOWN_BYTES;
@@ -139,13 +161,9 @@ export class DeliveryCoordinator {
 
         const messagesRemaining = flushThrough - index + 1;
         const fairFlushBytes = Math.floor(flushBytesRemaining / messagesRemaining);
-        const fairWaveBytes = Math.floor(
-          MAX_DELIVERY_MARKDOWN_BYTES / Math.max(1, settlement.waveSize),
-        );
         const byteLimit = Math.max(0, Math.min(
           MAX_WORKER_DELIVERY_MARKDOWN_BYTES,
           fairFlushBytes,
-          fairWaveBytes,
           flushBytesRemaining,
         ));
         const triggerTurn = latestFinalIndex >= 0 && index === flushThrough;
@@ -165,6 +183,7 @@ export class DeliveryCoordinator {
         if (pendingIndex >= 0) this.pendingSettlements.splice(pendingIndex, 1);
 
         if (triggerTurn) {
+          this.finishSynthesisGroup(settlement);
           parent.agentRunning = true;
           return;
         }
@@ -178,17 +197,17 @@ export class DeliveryCoordinator {
     settlement: WorkerSettlement,
     byteLimit: number,
   ): WorkerDeliveryMessage {
-    const heading = `## Worker result — ${settlement.worker}`;
+    const heading = `## Worker result — ${settlement.title} · ${settlement.worker}`;
     const metadata = [
       `Worker \`${settlement.workerId}\``,
-      `wave \`${settlement.waveId}\``,
+      `run \`${settlement.runId}\``,
       `status \`${settlement.status}\``,
     ].join(" · ");
     const body = renderOutcome(settlement.outcome);
     const content = body.length > 0
-      ? `${heading}\n\n### ${settlement.title}\n${metadata}\n\n${body}`
-      : `${heading}\n\n### ${settlement.title}\n${metadata}`;
-    const appendix = settlement.waveComplete
+      ? `${heading}\n\n${metadata}\n\n${body}`
+      : `${heading}\n\n${metadata}`;
+    const appendix = this.isFinalBoundary(settlement)
       ? `\n\n---\n\n${DELIVERY_PARENT_INSTRUCTIONS}`
       : "";
 
@@ -199,6 +218,45 @@ export class DeliveryCoordinator {
       details: settlement,
     });
   }
+
+  private acceptSynthesisGroupSettlement(settlement: WorkerSettlement): void {
+    if (!settlement.synthesisGroupId || !settlement.synthesisGroupSize) return;
+    const key = synthesisGroupKey(settlement.ownerSessionId, settlement.synthesisGroupId);
+    const state = this.synthesisGroups.get(key) ?? {
+      expected: settlement.synthesisGroupSize,
+      acceptedEventIds: [],
+    };
+    state.acceptedEventIds.push(settlement.eventId);
+    this.synthesisGroups.set(key, state);
+    this.refreshSynthesisGroupBoundary(key, state);
+  }
+
+  private refreshSynthesisGroupBoundary(key: string, state: SynthesisGroupState): void {
+    if (state.expected === 0) {
+      this.synthesisGroups.delete(key);
+      return;
+    }
+    if (state.acceptedEventIds.length !== state.expected) return;
+    const finalEventId = state.acceptedEventIds.at(-1);
+    if (finalEventId) this.finalSynthesisGroupEvents.add(finalEventId);
+  }
+
+  private isFinalBoundary(settlement: WorkerSettlement): boolean {
+    if (!settlement.synthesisGroupId) return true;
+    return this.finalSynthesisGroupEvents.has(settlement.eventId);
+  }
+
+  private finishSynthesisGroup(settlement: WorkerSettlement): void {
+    if (!settlement.synthesisGroupId) return;
+    this.synthesisGroups.delete(
+      synthesisGroupKey(settlement.ownerSessionId, settlement.synthesisGroupId),
+    );
+    this.finalSynthesisGroupEvents.delete(settlement.eventId);
+  }
+}
+
+function synthesisGroupKey(ownerSessionId: string, synthesisGroupId: string): string {
+  return `${ownerSessionId}\u0000${synthesisGroupId}`;
 }
 
 function capMarkdown(content: string, appendix: string, byteLimit: number): string {
@@ -238,7 +296,5 @@ function renderOutcome(outcome: WorkerSettlement["outcome"]): string {
       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

@@ -95,17 +95,17 @@ export interface OrchestrateTaskInput {
 }
 
 declare const workerIdBrand: unique symbol;
-declare const waveIdBrand: unique symbol;
+declare const runIdBrand: unique symbol;
 
 export type WorkerId = string & { readonly [workerIdBrand]: "WorkerId" };
-export type WaveId = string & { readonly [waveIdBrand]: "WaveId" };
+export type RunId = string & { readonly [runIdBrand]: "RunId" };
 
 export type WorkerIdFactory = () => WorkerId;
-export type WaveIdFactory = () => WaveId;
+export type RunIdFactory = () => RunId;
 
 export interface OrchestrateIdFactories {
   readonly workerId: WorkerIdFactory;
-  readonly waveId: WaveIdFactory;
+  readonly runId: RunIdFactory;
 }
 
 export function createRandomWorkerIdFactory(
@@ -114,10 +114,10 @@ export function createRandomWorkerIdFactory(
   return () => `worker-${randomId()}` as WorkerId;
 }
 
-export function createRandomWaveIdFactory(
+export function createRandomRunIdFactory(
   randomId: () => string = defaultRandomId,
-): WaveIdFactory {
-  return () => `wave-${randomId()}` as WaveId;
+): RunIdFactory {
+  return () => `run-${randomId()}` as RunId;
 }
 
 export function createRandomIdFactories(
@@ -125,7 +125,7 @@ export function createRandomIdFactories(
 ): OrchestrateIdFactories {
   return {
     workerId: createRandomWorkerIdFactory(randomId),
-    waveId: createRandomWaveIdFactory(randomId),
+    runId: createRandomRunIdFactory(randomId),
   };
 }
 
@@ -134,15 +134,15 @@ export function createSequentialWorkerIdFactory(startAt = 1): WorkerIdFactory {
   return () => `worker-${next++}` as WorkerId;
 }
 
-export function createSequentialWaveIdFactory(startAt = 1): WaveIdFactory {
+export function createSequentialRunIdFactory(startAt = 1): RunIdFactory {
   let next = startAt;
-  return () => `wave-${next++}` as WaveId;
+  return () => `run-${next++}` as RunId;
 }
 
 export function createSequentialIdFactories(startAt = 1): OrchestrateIdFactories {
   return {
     workerId: createSequentialWorkerIdFactory(startAt),
-    waveId: createSequentialWaveIdFactory(startAt),
+    runId: createSequentialRunIdFactory(startAt),
   };
 }
 
@@ -205,7 +205,6 @@ export type WorkerOutcome =
   | WorkerFailedOutcome
   | WorkerAbortedOutcome
   | WorkerClosedOutcome;
-export type TerminalWorkerOutcome = Exclude<WorkerOutcome, WorkerReadyOutcome>;
 export type WorkerStatus =
   | "starting"
   | "running"
@@ -219,13 +218,12 @@ 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 runId: RunId;
   readonly title: string;
   readonly instructions: string;
   readonly lifecycle: WorkerLifecycle;
@@ -239,16 +237,18 @@ export interface WorkerRecord {
   readonly sessionFile?: string;
 }
 
-export type WaveMode = "async" | "inline";
-export type WaveState = "running" | "complete";
+export type RunMode = "async" | "inline";
+export type RunState = "running" | "complete";
 
-export interface WaveRecord {
-  readonly id: WaveId;
+export interface RunRecord {
+  readonly id: RunId;
   readonly ownerSessionId: string;
-  readonly workerIds: readonly WorkerId[];
-  readonly mode: WaveMode;
-  readonly state: WaveState;
+  readonly workerId: WorkerId;
+  readonly mode: RunMode;
+  readonly state: RunState;
   readonly createdAt: number;
+  readonly synthesisGroupId?: string;
+  readonly synthesisGroupSize?: number;
 }
 
 export class InvalidTransitionError extends Error {
@@ -267,10 +267,6 @@ export function isTerminalWorkerStatus(status: WorkerStatus): status is Terminal
   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,
@@ -306,36 +302,6 @@ export function transitionWorkerStatus(
   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

@@ -5,8 +5,7 @@ import {
 } from "./runtime.js";
 import { createWorkerSessionFactory } from "./worker-session.js";
 
-const PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v2");
-const LEGACY_PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v1");
+const PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v3");
 
 export interface ProcessHost {
   readonly runtime: OrchestratorRuntime;
@@ -26,14 +25,8 @@ interface OwnedProcessHost extends AttachmentAwareProcessHost {
   destroyPromise?: Promise<void>;
 }
 
-interface LegacyProcessHost extends ProcessHost {
-  unsubscribeCompletion?: () => void;
-  unsubscribeSettlement?: () => void;
-}
-
 type ProcessGlobal = typeof globalThis & {
   [PROCESS_HOST_KEY]?: OwnedProcessHost;
-  [LEGACY_PROCESS_HOST_KEY]?: LegacyProcessHost;
 };
 
 function processGlobal(): ProcessGlobal {
@@ -49,8 +42,6 @@ export function createProcessHost(): ProcessHost {
   const existing = global[PROCESS_HOST_KEY];
   if (existing) return existing;
 
-  retireLegacyProcessHost(global);
-
   const runtime = createOrchestratorRuntime({
     workerSessionFactory: createWorkerSessionFactory(),
   });
@@ -114,30 +105,3 @@ export async function quitProcessHost(): Promise<void> {
   if (!host) return;
   await destroyProcessHost(host);
 }
-
-function retireLegacyProcessHost(global: ProcessGlobal): void {
-  const legacy = global[LEGACY_PROCESS_HOST_KEY];
-  if (!legacy) return;
-
-  delete global[LEGACY_PROCESS_HOST_KEY];
-  try {
-    legacy.unsubscribeCompletion?.();
-  } catch {
-    // A stale subscription cannot prevent installation of the current host.
-  }
-  try {
-    legacy.unsubscribeSettlement?.();
-  } catch {
-    // A stale subscription cannot prevent installation of the current host.
-  }
-  try {
-    legacy.delivery.close();
-  } catch {
-    // Legacy delivery cleanup is best-effort during reload migration.
-  }
-  try {
-    void legacy.runtime.shutdown().catch(() => undefined);
-  } catch {
-    // Legacy runtime shutdown is best-effort during reload migration.
-  }
-}

package/extension/index.ts

@@ -22,14 +22,19 @@ import {
   registerOrchestrationPresentation,
   type StatusController,
 } from "./presentation.js";
-import { registerOrchestrationTools } from "./tools.js";
+import {
+  registerOrchestrationTools,
+  type DispatchDecision,
+} from "./tools.js";
 
 const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set([
   "orchestrate",
   "worker_send",
 ]);
 
-type DispatchMode = "async" | "inline";
+interface StoredDispatchDecision extends DispatchDecision {
+  readonly ownerSessionId: string;
+}
 
 interface OwnerBinding {
   readonly ownerSessionId: string;
@@ -52,7 +57,7 @@ export function createOrchestrationExtension(
     const statusController =
       dependencies.createStatusController?.(host.runtime) ??
       createStatusController(host.runtime);
-    const dispatchModes = new Map<string, DispatchMode>();
+    const dispatchDecisions = new Map<string, StoredDispatchDecision>();
     let hostAttachment: ProcessHostAttachment | undefined;
     let activeBinding: OwnerBinding | undefined;
     let cachedCatalog: WorkerCatalog | undefined;
@@ -69,7 +74,8 @@ export function createOrchestrationExtension(
     registerOrchestrationTools(pi, {
       runtime: host.runtime,
       getCatalog: catalogFor,
-      getDispatchMode: (toolCallId) => dispatchModes.get(toolCallId) ?? "inline",
+      getDispatchDecision: (toolCallId) =>
+        dispatchDecisions.get(toolCallId) ?? { mode: "inline" },
     });
     registerOrchestrationPresentation(pi);
 
@@ -83,7 +89,7 @@ export function createOrchestrationExtension(
         statusController.unbind(activeBinding.ownerSessionId);
       }
 
-      dispatchModes.clear();
+      dispatchDecisions.clear();
       cachedCatalog = undefined;
       const binding: OwnerBinding = {
         ownerSessionId: ctx.sessionManager.getSessionId(),
@@ -117,17 +123,39 @@ export function createOrchestrationExtension(
       const toolCalls = event.message.content.filter(
         (part) => part.type === "toolCall",
       );
-      const mode: DispatchMode = toolCalls.length === 1 ? "async" : "inline";
+      const ownerSessionId = activeBinding?.ownerSessionId;
+      if (!ownerSessionId) return;
+      const groupedOrchestration =
+        toolCalls.length > 1 &&
+        toolCalls.every((toolCall) => toolCall.name === "orchestrate");
+      const synthesisGroup = groupedOrchestration
+        ? { id: `orchestrate:${toolCalls[0]?.id ?? "group"}`, size: toolCalls.length }
+        : undefined;
 
       for (const toolCall of toolCalls) {
-        if (DISPATCH_TOOL_NAMES.has(toolCall.name)) {
-          dispatchModes.set(toolCall.id, mode);
-        }
+        if (!DISPATCH_TOOL_NAMES.has(toolCall.name)) continue;
+        const mode = groupedOrchestration || toolCalls.length === 1
+          ? "async"
+          : "inline";
+        dispatchDecisions.set(toolCall.id, {
+          mode,
+          ownerSessionId,
+          ...(toolCall.name === "orchestrate" && synthesisGroup
+            ? { synthesisGroup }
+            : {}),
+        });
       }
     });
 
     pi.on("tool_execution_end", (event) => {
-      dispatchModes.delete(event.toolCallId);
+      const decision = dispatchDecisions.get(event.toolCallId);
+      dispatchDecisions.delete(event.toolCallId);
+      if (!event.isError || !decision?.synthesisGroup) return;
+      host.delivery.skipSynthesisGroupMember(
+        decision.ownerSessionId,
+        decision.synthesisGroup.id,
+        decision.synthesisGroup.size,
+      );
     });
 
     pi.on("agent_start", () => {
@@ -152,7 +180,7 @@ export function createOrchestrationExtension(
       const binding = activeBinding;
       activeBinding = undefined;
       cachedCatalog = undefined;
-      dispatchModes.clear();
+      dispatchDecisions.clear();
 
       if (binding) {
         host.delivery.unbind(binding.ownerSessionId, binding.generation);