@zachwill/pi-orchestrate 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Pi Orchestrate
 
-[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) adds concurrent worker orchestration to [Pi](https://pi.dev). It helps a parent agent **delegate → dispatch → deliver**: delegate bounded work, dispatch independent tasks as one wave, then deliver one aggregate result to the parent.
+[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) adds concurrent worker orchestration to [Pi](https://pi.dev). It helps a parent agent delegate bounded work, message independent workers concurrently, and synthesize each response as it arrives.
 
 ## Install
 
@@ -22,11 +22,13 @@ Pi Orchestrate adds exactly five tools:
 
 An `orchestrate` wave first performs atomic input, catalog, and model preflight. No worker starts if any task fails that preflight. After acceptance, worker resources start independently: a resource startup failure becomes that worker's `failed` result and does not roll back or stop its peers.
 
-All tasks in a wave execute concurrently, including a full 12-task wave. Pi Orchestrate applies no hidden concurrency throttle. The aggregate result preserves task order.
+All tasks in a wave execute concurrently, including a full 12-task wave. Pi Orchestrate applies no hidden concurrency throttle. Exact unchanged worker instructions remain visible in each tool call: collapsed calls preview every message, and expanded calls show every full brief. Titles are labels, never replacements for instructions.
 
 For asynchronous behavior, `orchestrate` or `worker_send` must be the sole tool call in its assistant message. Mixing either with any sibling tool call makes its wave inline and blocking. Inline work receives the parent turn's cancellation signal. Accepted async work does not retain that signal and continues independently.
 
-A successful async call yields the parent turn until aggregate results arrive. Do not poll `orchestration_status` for completion. If the owning session becomes inactive, its workers continue and completed results remain queued. Those results become available only when that exact owning session resumes; they are never delivered to another session.
+A successful async call yields the parent turn. Responses enter the transcript individually as workers settle, and the final response starts the parent's synthesis turn. The bottom widget is ephemeral and shows active work only; completed, failed, aborted, and reusable ready workers disappear immediately. Inline responses accumulate in the live tool output while the call blocks.
+
+`orchestration_status` is for diagnostics and recovery, never a normal completion mechanism. Do not poll it for completion. If the owning session becomes inactive, its workers continue and completed results remain queued. Those results become available only when that exact owning session resumes; they are never delivered to another session.
 
 Worker IDs identify live worker sessions. A reusable worker keeps the same worker ID across `worker_send` follow-ups, with each follow-up result belonging to a new wave. One-shot workers finish as `completed`. Reusable workers deliver as `ready` and wait for `worker_send` or `worker_close`. Use `worker_abort` only for active work, not to close a ready worker.
 

package/extension/contract.ts

@@ -34,7 +34,9 @@ You are the parent orchestrator and own the task end to end.
 - Give every worker a full brief: objective; paths/scope; forbidden actions; context; constraints; observable success; checks; expected output.
 - Input, catalog, and model preflight is atomic before any worker starts. Resource startup failures become per-worker failed results and do not roll back peers.
 - For asynchronous behavior, \`orchestrate\` or \`worker_send\` must be the sole tool call in its assistant message. Mixing either with any sibling tool call makes its wave inline and blocking.
-- After an accepted async wave, yield the parent turn until aggregate results arrive. Do not duplicate delegated work or poll \`orchestration_status\` for completion.
+- Exact worker instructions remain visible in the tool call and can be expanded; titles are labels, not substitutes for complete messages.
+- After an accepted async wave, yield the parent turn. Worker responses arrive individually as each worker settles, and the final response starts parent synthesis. Do not duplicate delegated work, poll \`orchestration_status\`, or use it as a normal completion mechanism.
+- The active-work widget shows only workers currently starting, running, or stopping. Inline worker responses appear progressively in live tool output.
 - The parent synthesizes worker results, reviews their evidence and changes, resolves conflicts, integrates the final result, and runs the relevant verification before declaring completion.
 - Prefer one-shot workers. Use \`worker_send\` for follow-up work on a ready reusable worker, \`worker_close\` when that ready worker is finished, and \`worker_abort\` only when active work must stop.
 - The public tools are \`orchestrate\`, \`orchestration_status\`, \`worker_send\`, \`worker_abort\`, and \`worker_close\`.

package/extension/delivery.ts

@@ -1,28 +1,25 @@
-import type { CompletedWave } from "./runtime.js";
+import type { WorkerSettlement } from "./runtime.js";
 
 export const MAX_DELIVERY_MARKDOWN_BYTES = 50 * 1024;
+export const MAX_WORKER_DELIVERY_MARKDOWN_BYTES = 16 * 1024;
 export const DELIVERY_TRUNCATION_MARKER =
-  "\n\n[Worker results truncated at 50KB. Full structured results remain available.]";
+  "\n\n[Worker result truncated for parent context. Full output remains in structured details.]";
 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"];
-}
+/** Complete, immutable worker output for presentation and history consumers. */
+export type WorkerDeliveryDetails = WorkerSettlement;
 
-export interface WaveDeliveryMessage {
-  readonly customType: "pi-orchestrate-wave";
+export interface WorkerDeliveryMessage {
+  readonly customType: "pi-orchestrate-worker-result";
   readonly content: string;
   readonly display: true;
-  readonly details: WaveDeliveryDetails;
+  readonly details: WorkerDeliveryDetails;
 }
 
-export interface WaveDeliveryOptions {
+export interface WorkerDeliveryOptions {
   readonly triggerTurn: boolean;
 }
 
@@ -30,7 +27,7 @@ export interface ParentBinding {
   readonly ownerSessionId: string;
   readonly generation: ParentBindingGeneration;
   isIdle(): boolean;
-  sendMessage(message: WaveDeliveryMessage, options: WaveDeliveryOptions): void;
+  sendMessage(message: WorkerDeliveryMessage, options: WorkerDeliveryOptions): void;
 }
 
 interface BoundParent {
@@ -40,7 +37,9 @@ interface BoundParent {
 
 export class DeliveryCoordinator {
   private readonly boundParents = new Map<string, BoundParent>();
-  private readonly pendingWaves: CompletedWave[] = [];
+  private readonly pendingSettlements: WorkerSettlement[] = [];
+  private readonly flushingOwners = new Set<string>();
+  private highestAcceptedSequence = 0;
 
   bind(binding: ParentBinding): void {
     this.boundParents.set(binding.ownerSessionId, {
@@ -57,33 +56,42 @@ export class DeliveryCoordinator {
 
   markAgentStarted(ownerSessionId: string, generation: ParentBindingGeneration): void {
     if (!this.matchesBinding(ownerSessionId, generation)) return;
-    this.boundParents.get(ownerSessionId)!.agentRunning = true;
+    const parent = this.boundParents.get(ownerSessionId);
+    if (parent) parent.agentRunning = true;
   }
 
   markAgentSettled(ownerSessionId: string, generation: ParentBindingGeneration): void {
     if (!this.matchesBinding(ownerSessionId, generation)) return;
-    this.boundParents.get(ownerSessionId)!.agentRunning = false;
+    const parent = this.boundParents.get(ownerSessionId);
+    if (!parent) return;
+    parent.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);
+  accept(settlement: WorkerSettlement): boolean {
+    if (settlement.mode === "inline" || settlement.sequence <= this.highestAcceptedSequence) {
+      return false;
     }
+
+    this.highestAcceptedSequence = settlement.sequence;
+    this.pendingSettlements.push(settlement);
+
+    const parent = this.boundParents.get(settlement.ownerSessionId);
+    if (parent) this.flush(settlement.ownerSessionId, parent.binding.generation);
     return true;
   }
 
   pendingCount(ownerSessionId: string): number {
-    return this.pendingWaves.filter((wave) => wave.ownerSessionId === ownerSessionId).length;
+    return this.pendingSettlements.filter(
+      (settlement) => settlement.ownerSessionId === ownerSessionId,
+    ).length;
   }
 
   clear(): void {
     this.boundParents.clear();
-    this.pendingWaves.length = 0;
+    this.pendingSettlements.length = 0;
+    this.flushingOwners.clear();
+    this.highestAcceptedSequence = 0;
   }
 
   close(): void {
@@ -94,14 +102,10 @@ export class DeliveryCoordinator {
     ownerSessionId: string,
     generation: ParentBindingGeneration,
   ): boolean {
-    const binding = this.boundParents.get(ownerSessionId)?.binding;
-    return binding?.generation === generation;
+    return this.boundParents.get(ownerSessionId)?.binding.generation === generation;
   }
 
-  private canDeliver(
-    ownerSessionId: string,
-    generation: ParentBindingGeneration,
-  ): boolean {
+  private canDeliver(ownerSessionId: string, generation: ParentBindingGeneration): boolean {
     const parent = this.boundParents.get(ownerSessionId);
     return (
       parent !== undefined &&
@@ -111,73 +115,117 @@ export class DeliveryCoordinator {
     );
   }
 
-  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;
-      }
+  private flush(ownerSessionId: string, generation: ParentBindingGeneration): void {
+    if (this.flushingOwners.has(ownerSessionId) || !this.canDeliver(ownerSessionId, generation)) {
+      return;
+    }
 
-      const pendingIndex = this.pendingWaves.indexOf(wave);
-      if (pendingIndex >= 0) this.pendingWaves.splice(pendingIndex, 1);
+    this.flushingOwners.add(ownerSessionId);
+    try {
+      const queued = this.pendingSettlements.filter(
+        (settlement) => settlement.ownerSessionId === ownerSessionId,
+      );
+      let latestFinalIndex = -1;
+      for (let index = 0; index < queued.length; index += 1) {
+        if (queued[index]?.waveComplete) latestFinalIndex = index;
+      }
+      const flushThrough = latestFinalIndex >= 0 ? latestFinalIndex : queued.length - 1;
+      let flushBytesRemaining = MAX_DELIVERY_MARKDOWN_BYTES;
+
+      for (let index = 0; index <= flushThrough; index += 1) {
+        if (!this.canDeliver(ownerSessionId, generation)) return;
+        const settlement = queued[index];
+        if (!settlement || !this.pendingSettlements.includes(settlement)) continue;
+
+        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;
+        const message = this.renderWorkerMessage(settlement, byteLimit);
+        const parent = this.boundParents.get(ownerSessionId);
+        if (!parent || parent.binding.generation !== generation) return;
+
+        try {
+          parent.binding.sendMessage(message, { triggerTurn });
+        } catch {
+          return;
+        }
+
+        const deliveredBytes = Buffer.byteLength(message.content, "utf8");
+        flushBytesRemaining = Math.max(0, flushBytesRemaining - deliveredBytes);
+        const pendingIndex = this.pendingSettlements.indexOf(settlement);
+        if (pendingIndex >= 0) this.pendingSettlements.splice(pendingIndex, 1);
+
+        if (triggerTurn) {
+          parent.agentRunning = true;
+          return;
+        }
+      }
+    } finally {
+      this.flushingOwners.delete(ownerSessionId);
     }
   }
-}
 
-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,
-    },
-  };
+  private renderWorkerMessage(
+    settlement: WorkerSettlement,
+    byteLimit: number,
+  ): WorkerDeliveryMessage {
+    const heading = `## Worker result — ${settlement.worker}`;
+    const metadata = [
+      `Worker \`${settlement.workerId}\``,
+      `wave \`${settlement.waveId}\``,
+      `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
+      ? `\n\n---\n\n${DELIVERY_PARENT_INSTRUCTIONS}`
+      : "";
+
+    return Object.freeze({
+      customType: "pi-orchestrate-worker-result",
+      content: capMarkdown(content, appendix, byteLimit),
+      display: true,
+      details: settlement,
+    });
+  }
 }
 
-function capMarkdown(content: string, appendix: string): string {
+function capMarkdown(content: string, appendix: string, byteLimit: number): 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}`;
+  if (Buffer.byteLength(complete, "utf8") <= byteLimit) return complete;
+
+  const suffix = `${DELIVERY_TRUNCATION_MARKER}${appendix}`;
+  const suffixBytes = Buffer.byteLength(suffix, "utf8");
+  if (suffixBytes >= byteLimit) return truncateUtf8(suffix, byteLimit);
+  const prefix = truncateUtf8(content, byteLimit - suffixBytes);
+  return `${prefix}${suffix}`;
+}
+
+function truncateUtf8(content: string, byteLimit: number): string {
+  if (byteLimit <= 0) return "";
+  const bytes = Buffer.from(content, "utf8");
+  if (bytes.byteLength <= byteLimit) return content;
+  let end = byteLimit;
+  while (end > 0) {
+    const byte = bytes[end];
+    if (byte === undefined || (byte & 0xc0) !== 0x80) break;
+    end -= 1;
+  }
+  return bytes.subarray(0, end).toString("utf8");
 }
 
-function renderOutcome(outcome: CompletedWave["results"][number]["outcome"]): string {
+function renderOutcome(outcome: WorkerSettlement["outcome"]): string {
   switch (outcome.status) {
     case "completed":
     case "ready":

package/extension/domain.ts

@@ -228,6 +228,8 @@ export interface WorkerRecord {
   readonly lifecycle: WorkerLifecycle;
   readonly status: WorkerStatus;
   readonly usage: WorkerUsage;
+  readonly startedAt: number;
+  readonly settledAt?: number;
   readonly activity?: string;
   readonly outcome?: WorkerOutcome;
   readonly sessionFile?: string;

package/extension/host.ts

@@ -5,7 +5,8 @@ import {
 } from "./runtime.js";
 import { createWorkerSessionFactory } from "./worker-session.js";
 
-const PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v1");
+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");
 
 export interface ProcessHost {
   readonly runtime: OrchestratorRuntime;
@@ -21,12 +22,18 @@ interface AttachmentAwareProcessHost extends ProcessHost {
 }
 
 interface OwnedProcessHost extends AttachmentAwareProcessHost {
-  readonly unsubscribeCompletion: () => void;
+  readonly unsubscribeSettlement: () => void;
   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 {
@@ -42,6 +49,8 @@ export function createProcessHost(): ProcessHost {
   const existing = global[PROCESS_HOST_KEY];
   if (existing) return existing;
 
+  retireLegacyProcessHost(global);
+
   const runtime = createOrchestratorRuntime({
     workerSessionFactory: createWorkerSessionFactory(),
   });
@@ -50,8 +59,8 @@ export function createProcessHost(): ProcessHost {
     runtime,
     delivery,
     attachments: new Set(),
-    unsubscribeCompletion: runtime.subscribeCompletion((wave) => {
-      delivery.accept(wave);
+    unsubscribeSettlement: runtime.subscribeSettlement((settlement) => {
+      delivery.accept(settlement);
     }),
   };
   global[PROCESS_HOST_KEY] = host;
@@ -90,7 +99,7 @@ export async function destroyProcessHost(host: ProcessHost): Promise<void> {
       await ownedHost.runtime.shutdown();
     } finally {
       ownedHost.delivery.clear();
-      ownedHost.unsubscribeCompletion();
+      ownedHost.unsubscribeSettlement();
       const global = processGlobal();
       if (global[PROCESS_HOST_KEY] === ownedHost) {
         delete global[PROCESS_HOST_KEY];
@@ -105,3 +114,30 @@ 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.
+  }
+}