@zachwill/pi-orchestrate 0.9.2 → 0.11.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.ts";
 
 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/parent/contract.ts

@@ -0,0 +1,147 @@
+import type { WorkerCatalog } from "../catalog/definition.ts";
+
+const CONTRACT_START = "<!-- pi-orchestrate:contract:start -->";
+const CONTRACT_END = "<!-- pi-orchestrate:contract:end -->";
+
+function sortedWorkers(catalog: WorkerCatalog) {
+  return [...catalog.workers].sort((left, right) => {
+    if (left.name < right.name) return -1;
+    if (left.name > right.name) return 1;
+    return 0;
+  });
+}
+
+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.";
+
+  return workers
+    .map(
+      (worker) =>
+        `- \`${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
+
+You are the parent orchestrator and own the task end to end.
+
+### Delegation
+
+- Keep trivial or tightly coupled work in the parent. Delegate work that can proceed independently or benefit from independent judgment.
+- Choose worker scopes and counts from the task. Treat workers or counts named by the user as a floor unless the user sets an exact cap.
+- Each \`orchestrate\` call creates a fresh worker session. Multiple calls may use the same worker definition and identical instructions when independent judgments are useful. Do not vary briefs merely to make them appear different. Interactive follow-up instead continues one worker ID with its existing context.
+- Give each worker a self-contained brief with its objective, context, paths and scope, forbidden actions, success criteria, and expected output. Workers do not receive the parent conversation.
+
+### Parallel dispatch
+
+- Form the complete wave before emitting any tool call.
+- For one worker, make one fully briefed \`orchestrate\` call.
+- For N workers where N > 1, make exactly one \`multi_tool_use.parallel\` call. Its \`tool_uses\` must contain exactly N \`functions.orchestrate\` entries and no other tools.
+- If \`multi_tool_use.parallel\` is not present, emit all N \`orchestrate\` calls as native siblings in one assistant response.
+- Never dispatch a multi-worker wave as separate assistant responses. An admitted sole asynchronous \`orchestrate\` call ends the parent turn, so omitted workers cannot be added afterward.
+- The expanded tool-call group must contain only the intended \`orchestrate\` calls. Mixing another tool into the group makes orchestration inline and blocking.
+
+### Completion and lifecycle
+
+- Calls are admitted independently; a rejected call does not stop its siblings.
+- After dispatching, wait for automatic result delivery instead of polling \`worker_status\`. When results expose more independent work, dispatch another complete wave.
+- The parent reviews and synthesizes worker results, resolves conflicts, integrates changes, and runs the relevant verification.
+- Prefer one-shot workers. Use interactive workers only when retained context is useful, and follow the ownership and status requirements in the lifecycle tool descriptions.
+
+### Trusted worker catalog
+
+${formatCatalog(catalog)}
+${CONTRACT_END}`;
+}
+
+export function applyOrchestratorContract(
+  systemPrompt: string,
+  catalog: WorkerCatalog,
+): string {
+  const section = buildContract(catalog);
+  const cleaned = removeContractMarkers(systemPrompt);
+  if (cleaned.insertionOffset !== undefined) {
+    return `${cleaned.prompt.slice(0, cleaned.insertionOffset)}${section}${cleaned.prompt.slice(cleaned.insertionOffset)}`;
+  }
+
+  const separator =
+    systemPrompt.length === 0 || systemPrompt.endsWith("\n\n")
+      ? ""
+      : systemPrompt.endsWith("\n")
+        ? "\n"
+        : "\n\n";
+  return `${systemPrompt}${separator}${section}`;
+}

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.ts";
+import type { WorkerSettlement } from "../orchestration/settlement.ts";
 
 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.ts";
+
+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}

@@ -3,37 +3,42 @@ import {
   Delivery,
   deliveryLayer,
   type DeliveryService,
-} from "./delivery.js";
+} from "./delivery.ts";
 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.ts";
+import type {
+  AbortTarget,
+  OrchestrationContext,
+} from "../orchestration/admission.ts";
+import { createChildSessionsLayer } from "../worker/child-sessions.ts";
+import type { OrchestrateTaskInput, RunMode } from "../orchestration/model.ts";
+
+// Bump this key when ProcessHost/OrchestrationClient changes incompatibly.
+// Multiple package copies can coexist in one Pi process and adopt the same host.
 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 +46,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 +105,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 +197,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 +209,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);
   }
@@ -220,6 +225,8 @@ export class ProcessHostRuntimeAdapter<R = never> implements OrchestratorRuntime
     if (signal?.aborted) throw abortSignalReason(signal);
     if (!signal) return this.effectRuntime.runPromise(effect);
 
+    // Race with a private sentinel because Effect may transform failures; after
+    // interruption settles, Pi must receive the caller's exact AbortSignal.reason.
     const signalInterruption = {};
     const exit = await this.effectRuntime.runPromiseExit(
       Effect.raceFirst(effect, abortSignalEffect(signal, signalInterruption)),
@@ -232,15 +239,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 +265,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 +322,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);
   }