@zachwill/pi-orchestrate 0.9.0 → 0.10.0

package/extension/{worker-settlement.ts → orchestration/settlement.ts}

@@ -8,7 +8,9 @@ import {
   WorkerReadyOutcome,
   WorkerResponseOutcome,
   WorkerUsage,
-} from "./domain.js";
+  type RunRecord,
+  type SettledWorkerRecord,
+} from "./model.js";
 
 const NonnegativeInteger = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 const PositiveInteger = Schema.Int.check(Schema.isGreaterThan(0));
@@ -20,8 +22,8 @@ const FailureStage = Schema.Literals([
   "cancellation",
 ]);
 
-/** Canonical schema for settlement details written by the current runtime. */
-export const WorkerSettlementDetails = Schema.Struct({
+/** Canonical schema for settlements written and persisted by orchestration. */
+export const WorkerSettlement = Schema.Struct({
   eventId: Schema.String,
   sequence: PositiveInteger,
   ownerSessionId: Schema.String,
@@ -77,25 +79,69 @@ export const WorkerSettlementDetails = Schema.Struct({
   }),
 );
 
-export interface WorkerSettlementDetails
-  extends Schema.Schema.Type<typeof WorkerSettlementDetails> {}
+export interface WorkerSettlement
+  extends Schema.Schema.Type<typeof WorkerSettlement> {}
 
 export type SettlementFailureStage = NonNullable<
-  WorkerSettlementDetails["failureStage"]
->;
-
-export type WorkerSettlement = Schema.Schema.Type<
-  typeof WorkerSettlementDetails
+  WorkerSettlement["failureStage"]
 >;
 
 const decodeCurrentWorkerSettlement = Schema.decodeUnknownResult(
-  WorkerSettlementDetails,
+  WorkerSettlement,
 );
 
-export function decodePersistedWorkerSettlementDetails(value: unknown) {
+export function decodePersistedWorkerSettlement(value: unknown) {
   return decodeCurrentWorkerSettlement(value);
 }
 
+/** Every input a settlement needs; orchestration state entries stay private. */
+export interface WorkerSettlementInput {
+  readonly sequence: number;
+  readonly generation: number;
+  readonly run: RunRecord;
+  readonly worker: SettledWorkerRecord;
+  readonly settledAt: number;
+  readonly failureStage?: SettlementFailureStage;
+}
+
+/** Builds the canonical settlement published to listeners and persisted by Pi. */
+export function createWorkerSettlement({
+  sequence,
+  generation,
+  run,
+  worker,
+  settledAt,
+  failureStage,
+}: WorkerSettlementInput): WorkerSettlement {
+  return Object.freeze({
+    eventId: `${sequence}:${run.id}:${worker.id}:${generation}`,
+    sequence,
+    ownerSessionId: worker.ownerSessionId,
+    runId: run.id,
+    workerId: worker.id,
+    generation,
+    mode: run.mode,
+    worker: worker.worker,
+    title: worker.title,
+    lifecycle: worker.lifecycle,
+    status: worker.status,
+    outcome: Object.freeze({ ...worker.outcome }),
+    ...(failureStage ? { failureStage } : {}),
+    usage: Object.freeze({ ...worker.usage }),
+    startedAt: worker.startedAt,
+    settledAt,
+    ...(run.synthesisGroupId && run.synthesisGroupSize
+      ? {
+          synthesisGroupId: run.synthesisGroupId,
+          synthesisGroupSize: run.synthesisGroupSize,
+        }
+      : {}),
+    ...(worker.sessionFile !== undefined
+      ? { sessionFile: worker.sessionFile }
+      : {}),
+  });
+}
+
 const InlineWorkerOutcome = Schema.Union([
   WorkerCompletedOutcome.pipe(
     Schema.encodeKeys({ assistantText: "assistant_text" }),
@@ -121,15 +167,15 @@ const InlineWorkerUsage = WorkerUsage.pipe(
 
 /** Tool transport projection derived from the canonical settlement field schemas. */
 export const InlineWorkerSettlementDetails = Schema.Struct({
-  workerId: WorkerSettlementDetails.fields.workerId,
-  worker: WorkerSettlementDetails.fields.worker,
-  title: WorkerSettlementDetails.fields.title,
-  status: WorkerSettlementDetails.fields.status,
+  workerId: WorkerSettlement.fields.workerId,
+  worker: WorkerSettlement.fields.worker,
+  title: WorkerSettlement.fields.title,
+  status: WorkerSettlement.fields.status,
   outcome: InlineWorkerOutcome,
   usage: InlineWorkerUsage,
-  startedAt: WorkerSettlementDetails.fields.startedAt,
-  settledAt: WorkerSettlementDetails.fields.settledAt,
-  sessionFile: WorkerSettlementDetails.fields.sessionFile,
+  startedAt: WorkerSettlement.fields.startedAt,
+  settledAt: WorkerSettlement.fields.settledAt,
+  sessionFile: WorkerSettlement.fields.sessionFile,
 }).pipe(
   Schema.encodeKeys({
     workerId: "worker_id",
@@ -153,9 +199,9 @@ export interface InlineWorkerSettlementDetails
 
 export const InlineWorkerToolDetails = Schema.Struct({
   mode: Schema.Literal("inline"),
-  runId: Schema.optionalKey(WorkerSettlementDetails.fields.runId),
+  runId: Schema.optionalKey(WorkerSettlement.fields.runId),
   ownerSessionId: Schema.optionalKey(
-    WorkerSettlementDetails.fields.ownerSessionId,
+    WorkerSettlement.fields.ownerSessionId,
   ),
   result: InlineWorkerSettlementDetails,
 }).pipe(

package/extension/package-root.ts

@@ -0,0 +1,3 @@
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));

package/extension/{contract.ts → parent/contract.ts}

@@ -1,4 +1,4 @@
-import type { WorkerCatalog } from "./domain.js";
+import type { WorkerCatalog } from "../catalog/definition.js";
 
 const CONTRACT_START = "<!-- pi-orchestrate:contract:start -->";
 const CONTRACT_END = "<!-- pi-orchestrate:contract:end -->";
@@ -11,6 +11,12 @@ function sortedWorkers(catalog: WorkerCatalog) {
   });
 }
 
+function escapeContractMarkers(value: string): string {
+  return value
+    .replaceAll(CONTRACT_START, "&lt;!-- pi-orchestrate:contract:start --&gt;")
+    .replaceAll(CONTRACT_END, "&lt;!-- pi-orchestrate:contract:end --&gt;");
+}
+
 function formatCatalog(catalog: WorkerCatalog): string {
   const workers = sortedWorkers(catalog);
   if (workers.length === 0) return "- No trusted workers are available for this session.";
@@ -18,11 +24,74 @@ function formatCatalog(catalog: WorkerCatalog): string {
   return workers
     .map(
       (worker) =>
-        `- \`${worker.name}\` [${worker.source.kind}] (${worker.lifecycle}): ${worker.description}`,
+        `- \`${escapeContractMarkers(worker.name)}\` [${worker.source.kind}] (${worker.lifecycle}): ${escapeContractMarkers(worker.description)}`,
     )
     .join("\n");
 }
 
+interface ContractMarker {
+  readonly start: number;
+  readonly end: number;
+  readonly kind: "start" | "end";
+}
+
+function contractMarkers(prompt: string): ContractMarker[] {
+  const markers: ContractMarker[] = [];
+  for (const [value, kind] of [
+    [CONTRACT_START, "start"],
+    [CONTRACT_END, "end"],
+  ] as const) {
+    let offset = 0;
+    while (offset < prompt.length) {
+      const start = prompt.indexOf(value, offset);
+      if (start < 0) break;
+      markers.push({ start, end: start + value.length, kind });
+      offset = start + value.length;
+    }
+  }
+  return markers.sort((left, right) => left.start - right.start);
+}
+
+function removeContractMarkers(prompt: string): {
+  readonly prompt: string;
+  readonly insertionOffset?: number;
+} {
+  const markers = contractMarkers(prompt);
+  if (markers.length === 0) return { prompt };
+
+  const removed: Array<{ start: number; end: number }> = [];
+  const stack: ContractMarker[] = [];
+  for (const marker of markers) {
+    if (marker.kind === "start") {
+      stack.push(marker);
+      continue;
+    }
+    const start = stack.pop();
+    if (start && stack.length === 0) removed.push({ start: start.start, end: marker.end });
+  }
+
+  for (const marker of markers) {
+    if (!removed.some((range) => marker.start >= range.start && marker.end <= range.end)) {
+      removed.push({ start: marker.start, end: marker.end });
+    }
+  }
+  removed.sort((left, right) => left.start - right.start);
+
+  const insertionPoint = markers[0]!.start;
+  let insertionOffset = 0;
+  let cursor = 0;
+  let cleaned = "";
+  for (const range of removed) {
+    if (range.start < cursor) continue;
+    const retained = prompt.slice(cursor, range.start);
+    cleaned += retained;
+    if (range.start <= insertionPoint) insertionOffset = cleaned.length;
+    cursor = range.end;
+  }
+  cleaned += prompt.slice(cursor);
+  return { prompt: cleaned, insertionOffset };
+}
+
 function buildContract(catalog: WorkerCatalog): string {
   return `${CONTRACT_START}
 ## Pi Orchestrate Contract
@@ -55,17 +124,14 @@ ${formatCatalog(catalog)}
 ${CONTRACT_END}`;
 }
 
-export function appendOrchestratorContract(
+export function applyOrchestratorContract(
   systemPrompt: string,
   catalog: WorkerCatalog,
 ): string {
   const section = buildContract(catalog);
-  const start = systemPrompt.indexOf(CONTRACT_START);
-  if (start >= 0) {
-    const end = systemPrompt.indexOf(CONTRACT_END, start);
-    if (end >= 0) {
-      return `${systemPrompt.slice(0, start)}${section}${systemPrompt.slice(end + CONTRACT_END.length)}`;
-    }
+  const cleaned = removeContractMarkers(systemPrompt);
+  if (cleaned.insertionOffset !== undefined) {
+    return `${cleaned.prompt.slice(0, cleaned.insertionOffset)}${section}${cleaned.prompt.slice(cleaned.insertionOffset)}`;
   }
 
   const separator =

package/extension/{delivery.ts → parent/delivery.ts}

@@ -1,6 +1,6 @@
 import { Context, Effect, Layer } from "effect";
-import { Orchestration } from "./runtime.js";
-import type { WorkerSettlement } from "./worker-settlement.js";
+import { Orchestration } from "../orchestration/service.js";
+import type { WorkerSettlement } from "../orchestration/settlement.js";
 
 export const MAX_DELIVERY_MARKDOWN_BYTES = 50 * 1024;
 export const MAX_WORKER_DELIVERY_MARKDOWN_BYTES = 16 * 1024;
@@ -11,14 +11,11 @@ export const DELIVERY_PARENT_INSTRUCTIONS =
 
 export type ParentBindingGeneration = string | number | symbol;
 
-/** Complete, immutable worker output for presentation and history consumers. */
-export type WorkerDeliveryDetails = WorkerSettlement;
-
 export interface WorkerDeliveryMessage {
   readonly customType: "pi-orchestrate-worker-result";
   readonly content: string;
   readonly display: true;
-  readonly details: WorkerDeliveryDetails;
+  readonly details: WorkerSettlement;
 }
 
 export interface WorkerDeliveryOptions {
@@ -67,6 +64,8 @@ export class DeliveryCoordinator implements DeliveryService {
   private readonly pendingSettlements: WorkerSettlement[] = [];
   private readonly flushingOwners = new Set<string>();
   private readonly synthesisGroups = new Map<string, SynthesisGroupState>();
+  // Orchestration settlement sequences are process-scoped and monotonic across
+  // owners, so one watermark is valid.
   private highestAcceptedSequence = 0;
 
   bind(binding: ParentBinding): void {
@@ -83,15 +82,14 @@ export class DeliveryCoordinator implements DeliveryService {
   }
 
   markAgentStarted(ownerSessionId: string, generation: ParentBindingGeneration): void {
-    if (!this.matchesBinding(ownerSessionId, generation)) return;
     const parent = this.boundParents.get(ownerSessionId);
-    if (parent) parent.agentRunning = true;
+    if (parent?.binding.generation !== generation) return;
+    parent.agentRunning = true;
   }
 
   markAgentSettled(ownerSessionId: string, generation: ParentBindingGeneration): void {
-    if (!this.matchesBinding(ownerSessionId, generation)) return;
     const parent = this.boundParents.get(ownerSessionId);
-    if (!parent) return;
+    if (parent?.binding.generation !== generation) return;
     parent.agentRunning = false;
     this.flush(ownerSessionId, generation);
   }
@@ -163,21 +161,23 @@ export class DeliveryCoordinator implements DeliveryService {
 
     this.flushingOwners.add(ownerSessionId);
     try {
+      // Deliver a stable owner-ordered prefix, stopping at the latest complete synthesis boundary.
       const queued = this.pendingSettlements.filter(
         (settlement) => settlement.ownerSessionId === ownerSessionId,
       );
       let latestFinalIndex = -1;
-      for (let index = 0; index < queued.length; index += 1) {
-        const settlement = queued[index];
-        if (settlement && this.isFinalBoundary(settlement)) latestFinalIndex = index;
+      for (const [index, settlement] of queued.entries()) {
+        if (this.isFinalBoundary(settlement)) latestFinalIndex = index;
       }
       const flushThrough = latestFinalIndex >= 0 ? latestFinalIndex : queued.length - 1;
       let flushBytesRemaining = MAX_DELIVERY_MARKDOWN_BYTES;
 
-      for (let index = 0; index <= flushThrough; index += 1) {
+      for (const [index, settlement] of queued.entries()) {
+        if (index > flushThrough) break;
+        // Synchronous delivery callbacks can change owner, generation, or idle
+        // state before the next send.
         if (!this.canDeliver(ownerSessionId, generation)) return;
-        const settlement = queued[index];
-        if (!settlement || !this.pendingSettlements.includes(settlement)) continue;
+        if (!this.pendingSettlements.includes(settlement)) continue;
 
         const messagesRemaining = flushThrough - index + 1;
         const fairFlushBytes = Math.floor(flushBytesRemaining / messagesRemaining);
@@ -186,6 +186,8 @@ export class DeliveryCoordinator implements DeliveryService {
           fairFlushBytes,
           flushBytesRemaining,
         ));
+        // Intermediate results add context; only the completed boundary
+        // transfers work to a parent turn.
         const triggerTurn = latestFinalIndex >= 0 && index === flushThrough;
         const message = this.renderWorkerMessage(settlement, byteLimit);
         const parent = this.boundParents.get(ownerSessionId);
@@ -194,6 +196,7 @@ export class DeliveryCoordinator implements DeliveryService {
         try {
           parent.binding.sendMessage(message, { triggerTurn });
         } catch {
+          // Keep this settlement and the remaining prefix queued for a later retry.
           return;
         }
 

package/extension/parent/dispatch-policy.ts

@@ -0,0 +1,49 @@
+import type { SynthesisGroup } from "../orchestration/model.js";
+
+export interface ParentToolCall {
+  readonly id: string;
+  readonly name: string;
+}
+
+export interface DispatchDecision {
+  readonly mode: "async" | "inline";
+  readonly synthesisGroup?: SynthesisGroup;
+}
+
+export interface ClassifiedParentDispatch {
+  readonly toolCallId: string;
+  readonly decision: DispatchDecision;
+}
+
+const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set([
+  "orchestrate",
+  "interactive_send",
+]);
+
+// Sole dispatches and homogeneous orchestrate waves detach so the parent turn can
+// end while work continues. Mixed tools stay inline because their shared parent
+// turn still has sibling work; one wave boundary defers one synthesis turn until
+// every admitted member has settled.
+export function classifyParentDispatches(
+  toolCalls: readonly ParentToolCall[],
+): readonly ClassifiedParentDispatch[] {
+  const isOrchestrateGroup =
+    toolCalls.length > 1 &&
+    toolCalls.every((toolCall) => toolCall.name === "orchestrate");
+  const synthesisGroup = isOrchestrateGroup
+    ? { id: `orchestrate:${toolCalls[0]?.id ?? "group"}`, size: toolCalls.length }
+    : undefined;
+
+  return toolCalls.flatMap((toolCall): ClassifiedParentDispatch[] => {
+    if (!DISPATCH_TOOL_NAMES.has(toolCall.name)) return [];
+    return [{
+      toolCallId: toolCall.id,
+      decision: {
+        mode: isOrchestrateGroup || toolCalls.length === 1 ? "async" : "inline",
+        ...(toolCall.name === "orchestrate" && synthesisGroup
+          ? { synthesisGroup }
+          : {}),
+      },
+    }];
+  });
+}

package/extension/{host.ts → parent/process-host.ts}

@@ -7,33 +7,36 @@ import {
 import {
   Orchestration,
   orchestrationLayer,
-  type AbortTarget,
   type AcceptedRun,
   type CompletedRun,
-  type OrchestrationContext,
   type OrchestrationService,
   SHUTDOWN_CLEANUP_GRACE_MS,
-  type RuntimeSnapshot,
+  type OwnerSnapshot,
   type SettlementListener,
   type UnsubscribeSettlement,
-} from "./runtime.js";
-import { createChildSessionsLayer } from "./worker-session.js";
-import type { OrchestrateTaskInput, RunMode } from "./domain.js";
+} from "../orchestration/service.js";
+import type {
+  AbortTarget,
+  OrchestrationContext,
+} from "../orchestration/admission.js";
+import { createChildSessionsLayer } from "../worker/child-sessions.js";
+import type { OrchestrateTaskInput, RunMode } from "../orchestration/model.js";
 
 const PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v3");
 
-type RunResult<M extends RunMode> = M extends "async"
+type DispatchResult<M extends RunMode> = M extends "async"
   ? AcceptedRun
   : CompletedRun;
 
-export interface OrchestratorRuntime {
+/** Promise-facing orchestration API used by Pi tools and presentation. */
+export interface OrchestrationClient {
   orchestrate<M extends RunMode>(
     context: OrchestrationContext,
     task: OrchestrateTaskInput,
     mode: M,
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
-  ): Promise<RunResult<M>>;
+  ): Promise<DispatchResult<M>>;
   sendInteractive<M extends RunMode>(
     context: OrchestrationContext,
     workerId: string,
@@ -41,20 +44,20 @@ export interface OrchestratorRuntime {
     mode: M,
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
-  ): Promise<RunResult<M>>;
+  ): Promise<DispatchResult<M>>;
   abort(ownerSessionId: string, target: AbortTarget): Promise<void>;
   closeInteractive(ownerSessionId: string, workerId: string): Promise<void>;
-  snapshot(ownerSessionId: string): Promise<RuntimeSnapshot>;
+  snapshot(ownerSessionId: string): Promise<OwnerSnapshot>;
   subscribeSettlement(listener: SettlementListener): UnsubscribeSettlement;
   subscribeState(
     ownerSessionId: string,
-    listener: (snapshot: RuntimeSnapshot) => void,
+    listener: (snapshot: OwnerSnapshot) => void,
   ): () => void;
   shutdown(): Promise<void>;
 }
 
 export interface ProcessHost {
-  readonly runtime: OrchestratorRuntime;
+  readonly orchestration: OrchestrationClient;
   readonly delivery: DeliveryService;
 }
 
@@ -79,7 +82,7 @@ interface AttachmentAwareProcessHost extends ProcessHost {
   attachments?: Set<ProcessHostAttachment>;
 }
 
-type ProcessHostLifecycle = "active" | "destroying" | "destroyed";
+type ProcessHostLifecycle = "destroying" | "destroyed";
 
 interface OwnedProcessHost extends AttachmentAwareProcessHost {
   readonly effectRuntime?: ManagedRuntime.ManagedRuntime<Orchestration | Delivery, never>;
@@ -100,7 +103,7 @@ export function getProcessHost(): ProcessHost | undefined {
 }
 
 /** Pi-facing adapter. Every Promise operation executes one complete Orchestration Effect. */
-export class ProcessHostRuntimeAdapter<R = never> implements OrchestratorRuntime {
+export class ManagedOrchestrationClient<R = never> implements OrchestrationClient {
   constructor(
     private readonly effectRuntime: ManagedRuntime.ManagedRuntime<Orchestration | R, never>,
     private readonly orchestration: OrchestrationService,
@@ -192,7 +195,7 @@ export class ProcessHostRuntimeAdapter<R = never> implements OrchestratorRuntime
     return this.run(this.orchestration.closeInteractive(ownerSessionId, workerId));
   }
 
-  snapshot(ownerSessionId: string): Promise<RuntimeSnapshot> {
+  snapshot(ownerSessionId: string): Promise<OwnerSnapshot> {
     // Snapshot is dependency-free and remains readable from a retained host reference
     // after the process root has been disposed.
     return Effect.runPromise(this.orchestration.snapshot(ownerSessionId));
@@ -204,7 +207,7 @@ export class ProcessHostRuntimeAdapter<R = never> implements OrchestratorRuntime
 
   subscribeState(
     ownerSessionId: string,
-    listener: (snapshot: RuntimeSnapshot) => void,
+    listener: (snapshot: OwnerSnapshot) => void,
   ): () => void {
     return this.orchestration.subscribeState(ownerSessionId, listener);
   }
@@ -232,15 +235,15 @@ export class ProcessHostRuntimeAdapter<R = never> implements OrchestratorRuntime
   }
 }
 
-export function createProcessHostRuntimeAdapter<R>(
+export function createOrchestrationClient<R>(
   effectRuntime: ManagedRuntime.ManagedRuntime<Orchestration | R, never>,
-): OrchestratorRuntime {
+): OrchestrationClient {
   // Orchestration acquisition is synchronous; subscriptions must remain reentrant.
   const orchestration = effectRuntime.runSync(Orchestration);
-  return new ProcessHostRuntimeAdapter(effectRuntime, orchestration);
+  return new ManagedOrchestrationClient(effectRuntime, orchestration);
 }
 
-export function createProcessApplicationLayer(): Layer.Layer<Orchestration | Delivery> {
+export function makeProcessHostLayer(): Layer.Layer<Orchestration | Delivery> {
   const orchestration = orchestrationLayer().pipe(
     Layer.provide(createChildSessionsLayer()),
   );
@@ -254,21 +257,18 @@ export function createProcessHost(): ProcessHost {
     throw new Error("Cannot create a process host while the current host is being destroyed");
   }
   if (existing?.lifecycle === "destroyed") {
-    delete global[PROCESS_HOST_KEY];
-  } else if (existing) {
-    existing.lifecycle = "active";
-    return existing;
+    throw new Error("Cannot create a process host after the current host was destroyed");
   }
+  if (existing) return existing;
 
-  const effectRuntime = ManagedRuntime.make(createProcessApplicationLayer());
-  const runtime = createProcessHostRuntimeAdapter(effectRuntime);
+  const effectRuntime = ManagedRuntime.make(makeProcessHostLayer());
+  const orchestration = createOrchestrationClient(effectRuntime);
   const delivery = effectRuntime.runSync(Delivery);
   const host: OwnedProcessHost = {
-    runtime,
+    orchestration,
     delivery,
     effectRuntime,
     attachments: new Set(),
-    lifecycle: "active",
   };
   global[PROCESS_HOST_KEY] = host;
   return host;
@@ -304,7 +304,6 @@ export function destroyProcessHost(
   const ownedHost = host as OwnedProcessHost;
   if (ownedHost.destroyPromise) return ownedHost.destroyPromise;
   if ((ownedHost.attachments?.size ?? 0) > 0) return Promise.resolve();
-  if (ownedHost.lifecycle === "destroyed") return Promise.resolve();
 
   ownedHost.lifecycle = "destroying";
   let resolveDestruction!: () => void;
@@ -319,7 +318,7 @@ export function destroyProcessHost(
   let shutdown: Promise<void>;
   try {
     // shutdown() closes Orchestration admission before returning its bounded teardown Promise.
-    shutdown = ownedHost.runtime.shutdown();
+    shutdown = ownedHost.orchestration.shutdown();
   } catch (error) {
     shutdown = Promise.reject(error);
   }