@zachwill/pi-orchestrate 0.9.0 → 0.10.0

package/extension/catalog/definition.ts

@@ -0,0 +1,89 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+
+export const SUPPORTED_TOOL_NAMES = [
+  "read",
+  "bash",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+] as const;
+
+export type SupportedToolName = (typeof SUPPORTED_TOOL_NAMES)[number];
+
+const supportedToolNames: ReadonlySet<string> = new Set(SUPPORTED_TOOL_NAMES);
+
+export function isSupportedToolName(value: unknown): value is SupportedToolName {
+  return typeof value === "string" && supportedToolNames.has(value);
+}
+
+export type WorkerSourceKind = "package" | "user" | "project";
+
+export interface WorkerSource {
+  readonly kind: WorkerSourceKind;
+  readonly filePath: string;
+}
+
+export interface WorkerModel {
+  readonly provider: string;
+  readonly modelId: string;
+}
+
+export interface WorkerCompaction {
+  readonly enabled?: boolean;
+  readonly reserveTokens?: number;
+  readonly keepRecentTokens?: number;
+}
+
+export type WorkerLifecycle = "one-shot" | "interactive";
+
+export interface WorkerDefinition {
+  readonly name: string;
+  readonly source: WorkerSource;
+  readonly description: string;
+  readonly systemPrompt: string;
+  readonly lifecycle: WorkerLifecycle;
+  readonly tools: readonly SupportedToolName[];
+  readonly skills?: readonly string[];
+  readonly model?: WorkerModel;
+  readonly thinking?: ThinkingLevel;
+  readonly compaction?: WorkerCompaction;
+}
+
+export type CatalogDiagnosticSeverity = "warning" | "error";
+
+export interface CatalogDiagnostic {
+  readonly severity: CatalogDiagnosticSeverity;
+  readonly source: WorkerSourceKind;
+  readonly message: string;
+  readonly filePath?: string;
+}
+
+export interface WorkerCatalog {
+  readonly workers: readonly WorkerDefinition[];
+  readonly diagnostics: readonly CatalogDiagnostic[];
+}
+
+export function createWorkerCatalog(
+  workers: readonly WorkerDefinition[],
+  diagnostics: readonly CatalogDiagnostic[] = [],
+): WorkerCatalog {
+  return {
+    workers: [...workers].sort(compareWorkersByName),
+    diagnostics: [...diagnostics],
+  };
+}
+
+export function findWorkerByName(
+  catalog: WorkerCatalog,
+  name: string,
+): WorkerDefinition | undefined {
+  return catalog.workers.find((worker) => worker.name === name);
+}
+
+function compareWorkersByName(left: WorkerDefinition, right: WorkerDefinition): number {
+  if (left.name < right.name) return -1;
+  if (left.name > right.name) return 1;
+  return 0;
+}

package/extension/{catalog.ts → catalog/discovery.ts}

@@ -5,19 +5,19 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Effect, Result, Schema, SchemaGetter, type SchemaIssue } from "effect";
 import type {
   CatalogDiagnostic,
   WorkerCatalog,
   WorkerDefinition,
   WorkerSourceKind,
-} from "./domain.js";
+} from "./definition.js";
 import {
   createWorkerCatalog,
   isSupportedToolName,
   SUPPORTED_TOOL_NAMES,
-} from "./domain.js";
+} from "./definition.js";
+import { PACKAGE_ROOT } from "../package-root.js";
 
 const MAX_WORKER_BYTES = 64 * 1024;
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -302,7 +302,7 @@ function parseWorker(
 }
 
 function sourceDirectories(options: DiscoverWorkerCatalogOptions): CatalogSource[] {
-  const packageRoot = options.packageRoot ?? fileURLToPath(new URL("..", import.meta.url));
+  const packageRoot = options.packageRoot ?? PACKAGE_ROOT;
   const agentDir = options.agentDir ?? getAgentDir();
   const sources: CatalogSource[] = [
     { kind: "package", directory: join(packageRoot, "examples", "workers") },

package/extension/index.ts

@@ -6,9 +6,9 @@ import type {
 import {
   discoverWorkerCatalog,
   type DiscoverWorkerCatalogOptions,
-} from "./catalog.js";
-import { appendOrchestratorContract } from "./contract.js";
-import type { WorkerCatalog } from "./domain.js";
+} from "./catalog/discovery.js";
+import type { WorkerCatalog } from "./catalog/definition.js";
+import { applyOrchestratorContract } from "./parent/contract.js";
 import {
   attachProcessHost,
   createProcessHost,
@@ -16,21 +16,18 @@ import {
   detachProcessHost,
   type ProcessHost,
   type ProcessHostAttachment,
-} from "./host.js";
+} from "./parent/process-host.js";
 import {
   createStatusController,
   registerOrchestrationPresentation,
   type StatusController,
-} from "./presentation.js";
+  type WorkerStateSource,
+} from "./pi/presentation.js";
 import {
-  registerOrchestrationTools,
+  classifyParentDispatches,
   type DispatchDecision,
-} from "./tools.js";
-
-const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set([
-  "orchestrate",
-  "interactive_send",
-]);
+} from "./parent/dispatch-policy.js";
+import { registerOrchestrationTools } from "./pi/tools.js";
 
 interface StoredDispatchDecision extends DispatchDecision {
   readonly ownerSessionId: string;
@@ -45,7 +42,7 @@ export interface OrchestrationExtensionDependencies {
   getHost?(): ProcessHost;
   destroyHost?(host: ProcessHost): Promise<void>;
   discoverCatalog?(options: DiscoverWorkerCatalogOptions): WorkerCatalog;
-  createStatusController?(runtime: ProcessHost["runtime"]): StatusController;
+  createStatusController?(workerState: WorkerStateSource): StatusController;
 }
 
 export function createOrchestrationExtension(
@@ -57,7 +54,6 @@ export function createOrchestrationExtension(
     let host: ProcessHost | undefined;
     let hostAttachment: ProcessHostAttachment | undefined;
     let statusController: StatusController | undefined;
-    let toolsRegistered = false;
     let activeBinding: OwnerBinding | undefined;
     let cachedCatalog: WorkerCatalog | undefined;
 
@@ -76,27 +72,16 @@ export function createOrchestrationExtension(
     registerOrchestrationPresentation(pi);
 
     pi.on("session_start", (_event, ctx) => {
-      if (activeBinding && host && statusController) {
-        host.delivery.unbind(
-          activeBinding.ownerSessionId,
-          activeBinding.generation,
-        );
-        statusController.unbind(activeBinding.ownerSessionId);
-      }
-
       host ??= dependencies.getHost?.() ?? createProcessHost();
       statusController ??=
-        dependencies.createStatusController?.(host.runtime) ??
-        createStatusController(host.runtime);
-      if (!toolsRegistered) {
-        registerOrchestrationTools(pi, {
-          runtime: host.runtime,
-          getCatalog: catalogFor,
-          getDispatchDecision: (toolCallId) =>
-            dispatchDecisions.get(toolCallId) ?? { mode: "inline" },
-        });
-        toolsRegistered = true;
-      }
+        dependencies.createStatusController?.(host.orchestration) ??
+        createStatusController(host.orchestration);
+      registerOrchestrationTools(pi, {
+        orchestration: host.orchestration,
+        getCatalog: catalogFor,
+        getDispatchDecision: (toolCallId) =>
+          dispatchDecisions.get(toolCallId) ?? { mode: "inline" },
+      });
       hostAttachment ??= attachProcessHost(host);
 
       dispatchDecisions.clear();
@@ -118,7 +103,7 @@ export function createOrchestrationExtension(
     pi.on("before_agent_start", (event, ctx) => {
       cachedCatalog = discoverCatalogFor(ctx);
       return {
-        systemPrompt: appendOrchestratorContract(
+        systemPrompt: applyOrchestratorContract(
           event.systemPrompt,
           cachedCatalog,
         ),
@@ -132,24 +117,10 @@ export function createOrchestrationExtension(
       );
       const ownerSessionId = activeBinding?.ownerSessionId;
       if (!ownerSessionId) return;
-      const isOrchestrateGroup =
-        toolCalls.length > 1 &&
-        toolCalls.every((toolCall) => toolCall.name === "orchestrate");
-      const synthesisGroup = isOrchestrateGroup
-        ? { id: `orchestrate:${toolCalls[0]?.id ?? "group"}`, size: toolCalls.length }
-        : undefined;
-
-      for (const toolCall of toolCalls) {
-        if (!DISPATCH_TOOL_NAMES.has(toolCall.name)) continue;
-        const mode = isOrchestrateGroup || toolCalls.length === 1
-          ? "async"
-          : "inline";
-        dispatchDecisions.set(toolCall.id, {
-          mode,
+      for (const dispatch of classifyParentDispatches(toolCalls)) {
+        dispatchDecisions.set(dispatch.toolCallId, {
+          ...dispatch.decision,
           ownerSessionId,
-          ...(toolCall.name === "orchestrate" && synthesisGroup
-            ? { synthesisGroup }
-            : {}),
         });
       }
     });

package/extension/orchestration/admission.ts

@@ -0,0 +1,297 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { Effect, Schema } from "effect";
+import {
+  findWorkerByName,
+  type WorkerCatalog,
+  type WorkerDefinition,
+} from "../catalog/definition.js";
+import {
+  MAX_WORKER_INSTRUCTIONS_LENGTH,
+  MAX_WORKER_TITLE_LENGTH,
+  OrchestrateTaskInput,
+  WorkerId,
+  type RunMode,
+  type SynthesisGroup,
+} from "./model.js";
+
+/** Everything one orchestration request needs from its owning parent session. */
+export interface OrchestrationContext {
+  readonly ownerSessionId: string;
+  readonly cwd: string;
+  readonly agentDir: string;
+  readonly parentSessionFile: string | undefined;
+  readonly projectTrusted: boolean;
+  readonly catalog: WorkerCatalog;
+  readonly parentModel?: Model<Api>;
+  readonly modelRegistry: ModelRegistry;
+  readonly synthesisGroup?: SynthesisGroup;
+}
+
+export interface AbortTarget {
+  readonly workerIds?: readonly string[];
+  readonly all?: boolean;
+}
+
+const OrchestrationOperation = Schema.Literals([
+  "orchestrate",
+  "sendInteractive",
+  "abort",
+  "closeInteractive",
+  "snapshot",
+]);
+export type OrchestrationOperation = typeof OrchestrationOperation.Type;
+
+const OrchestrationRejectionReason = Schema.Literals([
+  "shutdown",
+  "validation",
+  "ownership",
+  "target",
+  "worker-state",
+  "unknown-worker",
+  "model-unavailable",
+]);
+export type OrchestrationRejectionReason = typeof OrchestrationRejectionReason.Type;
+
+export class OrchestrationActionRejected extends Schema.TaggedError<OrchestrationActionRejected>()(
+  "Orchestration.ActionRejected",
+  {
+    operation: OrchestrationOperation,
+    reason: OrchestrationRejectionReason,
+    message: Schema.String,
+  },
+) {}
+
+/** Admission verdict shared by pure ingress checks and stateful orchestration decisions. */
+export type Decision<A> =
+  | {
+      readonly _tag: "accepted";
+      readonly value: A;
+    }
+  | {
+      readonly _tag: "rejected";
+      readonly error: OrchestrationActionRejected;
+    };
+
+export function accepted<A>(value: A): Decision<A> {
+  return { _tag: "accepted", value };
+}
+
+export function rejected(
+  operation: OrchestrationOperation,
+  reason: OrchestrationRejectionReason,
+  message: string,
+): Decision<never> {
+  return {
+    _tag: "rejected",
+    error: actionRejection(operation, reason, message),
+  };
+}
+
+export function actionRejection(
+  operation: OrchestrationOperation,
+  reason: OrchestrationRejectionReason,
+  message: string,
+): OrchestrationActionRejected {
+  return new OrchestrationActionRejected({ operation, reason, message });
+}
+
+export function rejectAction(
+  operation: OrchestrationOperation,
+  reason: OrchestrationRejectionReason,
+  message: string,
+): Effect.Effect<never, OrchestrationActionRejected> {
+  return Effect.fail(actionRejection(operation, reason, message));
+}
+
+export function validateContextOwner(
+  operation: OrchestrationOperation,
+  ownerSessionId: string,
+): Effect.Effect<void, OrchestrationActionRejected> {
+  return typeof ownerSessionId !== "string" || ownerSessionId.trim() === ""
+    ? rejectAction(
+        operation,
+        "validation",
+        "ownerSessionId must not be blank",
+      )
+    : Effect.void;
+}
+
+export function validateWorkerId(
+  operation: OrchestrationOperation,
+  workerId: string,
+): Effect.Effect<WorkerId, OrchestrationActionRejected> {
+  if (typeof workerId !== "string" || workerId.trim() === "") {
+    return rejectAction(
+      operation,
+      "validation",
+      "worker_id must not be blank",
+    );
+  }
+  return Schema.decodeUnknownEffect(WorkerId)(workerId).pipe(
+    Effect.mapError(() => actionRejection(
+      operation,
+      "validation",
+      "worker_id must use the canonical worker- prefix",
+    )),
+  );
+}
+
+export function validateMode(
+  operation: OrchestrationOperation,
+  mode: RunMode,
+): Effect.Effect<void, OrchestrationActionRejected> {
+  return mode !== "async" && mode !== "inline"
+    ? rejectAction(operation, "validation", "Invalid orchestration mode")
+    : Effect.void;
+}
+
+export function validateText(
+  operation: OrchestrationOperation,
+  name: string,
+  value: string,
+  maximumLength: number,
+): Effect.Effect<void, OrchestrationActionRejected> {
+  if (typeof value !== "string" || value.trim() === "") {
+    return rejectAction(operation, "validation", `${name} must not be blank`);
+  }
+  return value.length > maximumLength
+    ? rejectAction(
+        operation,
+        "validation",
+        `${name} must be at most ${maximumLength} characters`,
+      )
+    : Effect.void;
+}
+
+/** Validates one orchestrate request against its context; no orchestration state is read. */
+export function validateOrchestrateRequest(
+  context: OrchestrationContext,
+  task: OrchestrateTaskInput,
+  mode: RunMode,
+): Effect.Effect<
+  { definition: WorkerDefinition; task: OrchestrateTaskInput },
+  OrchestrationActionRejected
+> {
+  return Effect.gen(function* () {
+    yield* validateContextOwner("orchestrate", context.ownerSessionId);
+    yield* validateMode("orchestrate", mode);
+    if (!task || typeof task !== "object" || Array.isArray(task)) {
+      return yield* rejectAction(
+        "orchestrate",
+        "validation",
+        "orchestrate requires one task object",
+      );
+    }
+    if (context.synthesisGroup) {
+      yield* validateText(
+        "orchestrate",
+        "synthesis group ID",
+        context.synthesisGroup.id,
+        MAX_WORKER_TITLE_LENGTH,
+      );
+      if (mode !== "async") {
+        return yield* rejectAction(
+          "orchestrate",
+          "validation",
+          "Sibling synthesis requires an async task",
+        );
+      }
+      if (
+        !Number.isSafeInteger(context.synthesisGroup.size) ||
+        context.synthesisGroup.size < 2
+      ) {
+        return yield* rejectAction(
+          "orchestrate",
+          "validation",
+          "Synthesis group size must be an integer of at least 2",
+        );
+      }
+    }
+    yield* validateText(
+      "orchestrate",
+      "worker",
+      task.worker,
+      MAX_WORKER_TITLE_LENGTH,
+    );
+    yield* validateText(
+      "orchestrate",
+      "title",
+      task.title,
+      MAX_WORKER_TITLE_LENGTH,
+    );
+    yield* validateText(
+      "orchestrate",
+      "instructions",
+      task.instructions,
+      MAX_WORKER_INSTRUCTIONS_LENGTH,
+    );
+    const definition = findWorkerByName(context.catalog, task.worker);
+    if (!definition) {
+      return yield* rejectAction(
+        "orchestrate",
+        "unknown-worker",
+        `Unknown worker: ${task.worker}`,
+      );
+    }
+    const configured = definition.model;
+    if (!configured && !context.parentModel) {
+      return yield* rejectAction(
+        "orchestrate",
+        "model-unavailable",
+        `Worker "${definition.name}" has no configured model and no parent model is available`,
+      );
+    }
+    if (
+      configured &&
+      !context.modelRegistry.find(configured.provider, configured.modelId)
+    ) {
+      return yield* rejectAction(
+        "orchestrate",
+        "model-unavailable",
+        `Worker "${definition.name}" configured model "${configured.provider}/${configured.modelId}" was not found`,
+      );
+    }
+    return { definition, task };
+  });
+}
+
+export type ValidatedAbortTarget =
+  | {
+      readonly _tag: "ids";
+      readonly workerIds: readonly WorkerId[];
+    }
+  | {
+      readonly _tag: "all";
+    };
+
+export function validateAbortTarget(
+  target: AbortTarget,
+): Effect.Effect<ValidatedAbortTarget, OrchestrationActionRejected> {
+  return Effect.gen(function* () {
+    if (!target || typeof target !== "object") {
+      return yield* rejectAction("abort", "target", "Invalid abort target");
+    }
+    const selected = [target.workerIds !== undefined, target.all !== undefined]
+      .filter(Boolean).length;
+    if (selected !== 1 || (target.all !== undefined && target.all !== true)) {
+      return yield* rejectAction(
+        "abort",
+        "target",
+        "Abort target must specify exactly one of workerIds or all: true",
+      );
+    }
+    if (target.workerIds === undefined) return { _tag: "all" };
+    if (!Array.isArray(target.workerIds) || target.workerIds.length === 0) {
+      return yield* rejectAction(
+        "abort",
+        "target",
+        "workerIds must contain at least one worker ID",
+      );
+    }
+    const workerIds = yield* Effect.all(
+      [...new Set(target.workerIds)].map((id) => validateWorkerId("abort", id)),
+    );
+    return { _tag: "ids", workerIds };
+  });
+}

package/extension/{domain.ts → orchestration/model.ts}

@@ -1,93 +1,5 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { Schema } from "effect";
-
-export const SUPPORTED_TOOL_NAMES = [
-  "read",
-  "bash",
-  "edit",
-  "write",
-  "grep",
-  "find",
-  "ls",
-] as const;
-
-export type SupportedToolName = (typeof SUPPORTED_TOOL_NAMES)[number];
-
-const supportedToolNames: ReadonlySet<string> = new Set(SUPPORTED_TOOL_NAMES);
-
-export function isSupportedToolName(value: unknown): value is SupportedToolName {
-  return typeof value === "string" && supportedToolNames.has(value);
-}
-
-export type WorkerSourceKind = "package" | "user" | "project";
-
-export interface WorkerSource {
-  readonly kind: WorkerSourceKind;
-  readonly filePath: string;
-}
-
-export interface WorkerModel {
-  readonly provider: string;
-  readonly modelId: string;
-}
-
-export interface WorkerCompaction {
-  readonly enabled?: boolean;
-  readonly reserveTokens?: number;
-  readonly keepRecentTokens?: number;
-}
-
-export type WorkerLifecycle = "one-shot" | "interactive";
-
-export interface WorkerDefinition {
-  readonly name: string;
-  readonly source: WorkerSource;
-  readonly description: string;
-  readonly systemPrompt: string;
-  readonly lifecycle: WorkerLifecycle;
-  readonly tools: readonly SupportedToolName[];
-  readonly skills?: readonly string[];
-  readonly model?: WorkerModel;
-  readonly thinking?: ThinkingLevel;
-  readonly compaction?: WorkerCompaction;
-}
-
-export type CatalogDiagnosticSeverity = "warning" | "error";
-
-export interface CatalogDiagnostic {
-  readonly severity: CatalogDiagnosticSeverity;
-  readonly source: WorkerSourceKind;
-  readonly message: string;
-  readonly filePath?: string;
-}
-
-export interface WorkerCatalog {
-  readonly workers: readonly WorkerDefinition[];
-  readonly diagnostics: readonly CatalogDiagnostic[];
-}
-
-export function createWorkerCatalog(
-  workers: readonly WorkerDefinition[],
-  diagnostics: readonly CatalogDiagnostic[] = [],
-): WorkerCatalog {
-  return {
-    workers: [...workers].sort(compareWorkersByName),
-    diagnostics: [...diagnostics],
-  };
-}
-
-export function findWorkerByName(
-  catalog: WorkerCatalog,
-  name: string,
-): WorkerDefinition | undefined {
-  return catalog.workers.find((worker) => worker.name === name);
-}
-
-function compareWorkersByName(left: WorkerDefinition, right: WorkerDefinition): number {
-  if (left.name < right.name) return -1;
-  if (left.name > right.name) return 1;
-  return 0;
-}
+import type { WorkerLifecycle } from "../catalog/definition.js";
 
 export const MAX_WORKER_TITLE_LENGTH = 200;
 export const MAX_WORKER_INSTRUCTIONS_LENGTH = 100_000;
@@ -234,6 +146,13 @@ export const WorkerOutcome = Schema.Union([
   Schema.Struct({ status: Schema.Literal("closed") }),
 ]);
 export type WorkerOutcome = typeof WorkerOutcome.Type;
+
+/** Outcomes that can settle a generation; closure is not one of them. */
+export type SettledWorkerOutcome = Exclude<
+  WorkerOutcome,
+  { readonly status: "closed" }
+>;
+
 export type WorkerStatus =
   | "starting"
   | "running"
@@ -266,9 +185,28 @@ export interface WorkerRecord {
   readonly sessionFile?: string;
 }
 
+/** Status of a worker whose generation produced a response outcome. */
+export type SettledWorkerStatus = Extract<
+  WorkerStatus,
+  "completed" | "ready" | "failed" | "aborted"
+>;
+
+/** A worker record whose current generation has settled with a response outcome. */
+export interface SettledWorkerRecord extends WorkerRecord {
+  readonly status: SettledWorkerStatus;
+  readonly outcome: SettledWorkerOutcome;
+  readonly settledAt: number;
+}
+
 export type RunMode = "async" | "inline";
 export type RunState = "running" | "complete";
 
+/** One sibling wave whose settlements share a synthesis boundary. */
+export interface SynthesisGroup {
+  readonly id: string;
+  readonly size: number;
+}
+
 export interface RunRecord {
   readonly id: RunId;
   readonly ownerSessionId: string;