@zachwill/pi-orchestrate 0.1.0 → 0.2.0

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

@@ -45,7 +45,7 @@ export interface WorkerDefinition {
   readonly systemPrompt: string;
   readonly lifecycle: WorkerLifecycle;
   readonly tools: readonly SupportedToolName[];
-  readonly skills: readonly string[];
+  readonly skills?: readonly string[];
   readonly model?: WorkerModel;
   readonly thinking?: ThinkingLevel;
   readonly compaction?: WorkerCompaction;
@@ -160,6 +160,9 @@ export interface WorkerUsage {
   readonly turns: number;
 }
 
+/** Direction of the most recent message across the worker/model boundary. */
+export type WorkerMessageDirection = "to-model" | "from-model";
+
 export const EMPTY_WORKER_USAGE: WorkerUsage = Object.freeze({
   input: 0,
   output: 0,
@@ -228,7 +231,10 @@ export interface WorkerRecord {
   readonly lifecycle: WorkerLifecycle;
   readonly status: WorkerStatus;
   readonly usage: WorkerUsage;
+  readonly startedAt: number;
+  readonly settledAt?: number;
   readonly activity?: string;
+  readonly messageDirection?: WorkerMessageDirection;
   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.
+  }
+}