@zachwill/pi-orchestrate 0.9.2 → 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 -->";
@@ -124,7 +124,7 @@ ${formatCatalog(catalog)}
 ${CONTRACT_END}`;
 }
 
-export function appendOrchestratorContract(
+export function applyOrchestratorContract(
   systemPrompt: string,
   catalog: WorkerCatalog,
 ): string {

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,8 +64,8 @@ export class DeliveryCoordinator implements DeliveryService {
   private readonly pendingSettlements: WorkerSettlement[] = [];
   private readonly flushingOwners = new Set<string>();
   private readonly synthesisGroups = new Map<string, SynthesisGroupState>();
-  // Runtime settlement sequences are process-scoped and monotonic across owners,
-  // so one watermark is valid.
+  // Orchestration settlement sequences are process-scoped and monotonic across
+  // owners, so one watermark is valid.
   private highestAcceptedSequence = 0;
 
   bind(binding: ParentBinding): void {

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;
 }
 
@@ -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()),
   );
@@ -258,11 +261,11 @@ export function createProcessHost(): ProcessHost {
   }
   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(),
@@ -315,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);
   }

package/extension/{presentation.ts → pi/presentation.ts}

@@ -15,9 +15,12 @@ import {
   type Component,
 } from "@earendil-works/pi-tui";
 import { Result } from "effect";
-import type { WorkerDeliveryDetails } from "./delivery.js";
-import type { WorkerOutcome, WorkerRecord, WorkerStatus } from "./domain.js";
-import type { RuntimeSnapshot } from "./runtime.js";
+import type {
+  WorkerOutcome,
+  WorkerRecord,
+  WorkerStatus,
+} from "../orchestration/model.js";
+import type { OwnerSnapshot } from "../orchestration/service.js";
 import {
   disposeComponent,
   formatElapsed,
@@ -25,9 +28,9 @@ import {
   WidthBoundComponent,
 } from "./tui.js";
 import {
-  decodePersistedWorkerSettlementDetails,
-  type WorkerSettlementDetails,
-} from "./worker-settlement.js";
+  decodePersistedWorkerSettlement,
+  type WorkerSettlement,
+} from "../orchestration/settlement.js";
 
 export const ORCHESTRATION_PRESENTATION_KEY = "pi-orchestrate";
 export const MAX_RESULT_PREVIEW_LINES = 6;
@@ -51,10 +54,11 @@ const ANIMATION_CYCLE_TICKS = 40;
 const SPINNER_INTERVAL_MS = 140;
 const ACTIVE_STATUSES: ReadonlySet<WorkerStatus> = new Set(["starting", "running", "stopping"]);
 
-export interface PresentationRuntime {
+/** Owner-scoped worker state feed consumed by the parent's status presentation. */
+export interface WorkerStateSource {
   subscribeState(
     ownerSessionId: string,
-    listener: (snapshot: RuntimeSnapshot) => void,
+    listener: (snapshot: OwnerSnapshot) => void,
   ): () => void;
 }
 
@@ -66,14 +70,14 @@ interface StatusBinding {
 interface RenderRequester { requestRender(): void }
 
 export function registerOrchestrationPresentation(pi: ExtensionAPI): void {
-  pi.registerMessageRenderer<WorkerDeliveryDetails>(
+  pi.registerMessageRenderer<WorkerSettlement>(
     "pi-orchestrate-worker-result",
     (message, { expanded }, theme) =>
       new WorkerResultComponent(messageText(message.content), message.details, expanded, theme),
   );
 }
 
-export function formatFooterStatus(snapshot: RuntimeSnapshot): string | undefined {
+export function formatFooterStatus(snapshot: OwnerSnapshot): string | undefined {
   const ready = snapshot.workers.filter((worker) => worker.status === "ready").length;
   return ready > 0 ? `${ready} interactive ready` : undefined;
 }
@@ -84,14 +88,14 @@ export class StatusController {
   private unsubscribeState: (() => void) | undefined;
   private widget: WorkerStatusComponent | undefined;
 
-  constructor(private readonly runtime: PresentationRuntime) {}
+  constructor(private readonly workerState: WorkerStateSource) {}
 
   bind(ownerSessionId: string, ctx: ExtensionContext): void {
     if (this.disposed) return;
     this.clearBinding();
     const binding = { ownerSessionId, ctx };
     this.binding = binding;
-    this.unsubscribeState = this.runtime.subscribeState(ownerSessionId, (snapshot) => {
+    this.unsubscribeState = this.workerState.subscribeState(ownerSessionId, (snapshot) => {
       if (this.binding !== binding) return;
       this.present(binding.ctx, snapshot);
     });
@@ -108,7 +112,7 @@ export class StatusController {
     this.clearBinding();
   }
 
-  private present(ctx: ExtensionContext, snapshot: RuntimeSnapshot): void {
+  private present(ctx: ExtensionContext, snapshot: OwnerSnapshot): void {
     ctx.ui.setStatus(ORCHESTRATION_PRESENTATION_KEY, formatFooterStatus(snapshot));
     if (ctx.mode !== "tui") return;
     const active = activeWorkers(snapshot);
@@ -145,21 +149,23 @@ export class StatusController {
   }
 }
 
-export function createStatusController(runtime: PresentationRuntime): StatusController {
-  return new StatusController(runtime);
+export function createStatusController(
+  workerState: WorkerStateSource,
+): StatusController {
+  return new StatusController(workerState);
 }
 
 export class WorkerStatusComponent implements Component {
   private frameIndex = 0;
-  private snapshot: RuntimeSnapshot;
+  private snapshot: OwnerSnapshot;
   private timer: ReturnType<typeof setInterval> | undefined;
 
-  constructor(snapshot: RuntimeSnapshot, private readonly theme: Theme, private readonly tui?: RenderRequester) {
+  constructor(snapshot: OwnerSnapshot, private readonly theme: Theme, private readonly tui?: RenderRequester) {
     this.snapshot = snapshot;
     this.startTimer();
   }
 
-  update(snapshot: RuntimeSnapshot): void {
+  update(snapshot: OwnerSnapshot): void {
     this.snapshot = snapshot;
     if (activeWorkers(snapshot).length > 0) this.startTimer();
     else this.stopTimer();
@@ -289,8 +295,8 @@ export class WorkerResultComponent implements Component {
   }
 }
 
-function readSettlement(value: unknown): WorkerSettlementDetails | undefined {
-  const decoded = decodePersistedWorkerSettlementDetails(value);
+function readSettlement(value: unknown): WorkerSettlement | undefined {
+  const decoded = decodePersistedWorkerSettlement(value);
   return Result.isSuccess(decoded) ? decoded.success : undefined;
 }
 
@@ -307,7 +313,7 @@ function outcomeText(outcome: WorkerOutcome): string {
   return "Worker session closed.";
 }
 
-function presentedOutcome(result: WorkerSettlementDetails): string {
+function presentedOutcome(result: WorkerSettlement): string {
   const body = outcomeText(result.outcome);
   if (result.status !== "completed" && result.status !== "ready") return body;
 
@@ -322,7 +328,7 @@ function presentedOutcome(result: WorkerSettlementDetails): string {
   return lines.join("\n").trimEnd();
 }
 
-function settlementMetadata(result: WorkerSettlementDetails): string[] {
+function settlementMetadata(result: WorkerSettlement): string[] {
   return [
     `worker ID ${result.workerId} · run ID ${result.runId}`,
     `status ${result.status} · generation ${result.generation}`,
@@ -338,7 +344,7 @@ function messageText(content: unknown): string {
   return content.flatMap((part) => isRecord(part) && part.type === "text" && typeof part.text === "string" ? [part.text] : []).join("\n");
 }
 
-function activeWorkers(snapshot: RuntimeSnapshot): WorkerRecord[] {
+function activeWorkers(snapshot: OwnerSnapshot): WorkerRecord[] {
   return snapshot.workers.filter((worker) => ACTIVE_STATUSES.has(worker.status));
 }