@zachwill/pi-orchestrate 0.8.0 → 0.9.0

package/extension/catalog.ts

@@ -173,105 +173,100 @@ function fieldValue(frontmatter: unknown, field: string): unknown {
   return field in frontmatter ? frontmatter[field] : undefined;
 }
 
+function hasIssuePath(issuePaths: readonly IssuePath[], ...path: readonly PropertyKey[]): boolean {
+  return issuePaths.some((entry) => path.every((key, index) => entry.path[index] === key));
+}
+
+function unexpectedFieldsAt(
+  issuePaths: readonly IssuePath[],
+  parentPath: readonly PropertyKey[],
+): string[] {
+  return issuePaths
+    .filter(({ path, issue }) =>
+      issue._tag === "UnexpectedKey" &&
+      path.length === parentPath.length + 1 &&
+      parentPath.every((key, index) => path[index] === key) &&
+      typeof path[parentPath.length] === "string"
+    )
+    .map(({ path }) => String(path[parentPath.length]))
+    .sort(compareText);
+}
+
+function unknownFieldsDiagnostic(scope: string, fields: readonly string[]): string {
+  return `unknown ${scope} field${fields.length === 1 ? "" : "s"}: ${fields.join(", ")}`;
+}
+
 function listItems(value: unknown): readonly unknown[] {
   if (typeof value === "string") return value.split(",").map((item) => item.trim());
   return Array.isArray(value) ? value : [];
 }
 
+const ORDERED_FRONTMATTER_FIELDS = [
+  "name", "description", "model", "thinking", "tools", "skills", "compaction", "lifecycle",
+] as const;
+
+const FIXED_FIELD_DIAGNOSTICS: Partial<Record<(typeof ORDERED_FRONTMATTER_FIELDS)[number], string>> = {
+  name: "frontmatter field 'name' must be a non-empty string",
+  description: "frontmatter field 'description' must be a non-empty string",
+  skills: "frontmatter field 'skills' must be a comma string or string array",
+  lifecycle: "frontmatter field 'lifecycle' must be 'one-shot' or 'interactive'",
+};
+
+const COMPACTION_FIELD_DIAGNOSTICS = [
+  ["enabled", "frontmatter field 'compaction.enabled' must be a boolean"],
+  ["reserveTokens", "frontmatter field 'compaction.reserveTokens' must be a non-negative integer"],
+  ["keepRecentTokens", "frontmatter field 'compaction.keepRecentTokens' must be a non-negative integer"],
+] as const;
+
 function schemaDiagnostic(issue: SchemaIssue.Issue, frontmatter: unknown): string {
   const issuePaths = collectIssuePaths(issue);
-  const unexpected = issuePaths.filter(({ issue }) => issue._tag === "UnexpectedKey");
-  const frontmatterFields = unexpected
-    .filter(({ path }) => path.length === 1 && typeof path[0] === "string")
-    .map(({ path }) => String(path[0]))
-    .sort(compareText);
+  const frontmatterFields = unexpectedFieldsAt(issuePaths, []);
   if (frontmatterFields.length > 0) {
-    return `unknown frontmatter field${frontmatterFields.length === 1 ? "" : "s"}: ${frontmatterFields.join(", ")}`;
+    return unknownFieldsDiagnostic("frontmatter", frontmatterFields);
   }
+  if (!isUnknownRecord(frontmatter)) return "frontmatter must be a mapping";
 
-  const compactionFields = unexpected
-    .filter(
-      ({ path }) => path.length === 2 && path[0] === "compaction" && typeof path[1] === "string",
-    )
-    .map(({ path }) => String(path[1]))
-    .sort(compareText);
-
-  if (typeof frontmatter !== "object" || frontmatter === null || Array.isArray(frontmatter)) {
-    return "frontmatter must be a mapping";
-  }
-
-  const orderedFields = [
-    "name",
-    "description",
-    "model",
-    "thinking",
-    "tools",
-    "skills",
-    "compaction",
-    "lifecycle",
-  ];
-  const field = orderedFields.find((candidate) =>
-    issuePaths.some(({ path }) => path[0] === candidate)
+  const field = ORDERED_FRONTMATTER_FIELDS.find((candidate) =>
+    hasIssuePath(issuePaths, candidate)
   );
-  const value = field === undefined ? undefined : fieldValue(frontmatter, field);
+  if (field === undefined) return "invalid worker definition";
 
-  if (field === "name" || field === "description") {
-    return `frontmatter field '${field}' must be a non-empty string`;
-  }
+  const fixedDiagnostic = FIXED_FIELD_DIAGNOSTICS[field];
+  if (fixedDiagnostic !== undefined) return fixedDiagnostic;
+
+  const value = fieldValue(frontmatter, field);
   if (field === "model") {
-    if (typeof value !== "string" || value.trim() === "") {
-      return "frontmatter field 'model' must be a non-empty string";
-    }
-    return "frontmatter field 'model' must use provider/model format";
+    return typeof value !== "string" || value.trim() === ""
+      ? "frontmatter field 'model' must be a non-empty string"
+      : "frontmatter field 'model' must use provider/model format";
   }
   if (field === "thinking") {
-    if (typeof value !== "string" || value.trim() === "") {
-      return "frontmatter field 'thinking' must be a non-empty string";
-    }
-    return `unsupported thinking level '${value.trim()}'`;
+    return typeof value !== "string" || value.trim() === ""
+      ? "frontmatter field 'thinking' must be a non-empty string"
+      : `unsupported thinking level '${value.trim()}'`;
   }
   if (field === "tools") {
     const items = listItems(value);
     const validList = items.length > 0 && items.every(
       (item) => typeof item === "string" && item !== "",
     );
-    const unsupported = validList ? items.find(
-      (item) => typeof item === "string" && !isSupportedToolName(item),
-    ) : undefined;
+    const unsupported = validList
+      ? items.find((item) => typeof item === "string" && !isSupportedToolName(item))
+      : undefined;
     if (typeof unsupported === "string") return `unsupported tool '${unsupported}'`;
-    if (value === undefined) return "frontmatter field 'tools' is required";
-    return "frontmatter field 'tools' must be a non-empty comma string or string array";
-  }
-  if (field === "skills") {
-    return "frontmatter field 'skills' must be a comma string or string array";
+    return value === undefined
+      ? "frontmatter field 'tools' is required"
+      : "frontmatter field 'tools' must be a non-empty comma string or string array";
   }
-  if (field === "compaction") {
-    if (compactionFields.length > 0) {
-      return `unknown compaction field${compactionFields.length === 1 ? "" : "s"}: ${compactionFields.join(", ")}`;
-    }
-    if (issuePaths.some(({ path }) => path[0] === "compaction" && path[1] === "enabled")) {
-      return "frontmatter field 'compaction.enabled' must be a boolean";
-    }
-    if (
-      issuePaths.some(({ path }) =>
-        path[0] === "compaction" && path[1] === "reserveTokens"
-      )
-    ) {
-      return "frontmatter field 'compaction.reserveTokens' must be a non-negative integer";
-    }
-    if (
-      issuePaths.some(({ path }) =>
-        path[0] === "compaction" && path[1] === "keepRecentTokens"
-      )
-    ) {
-      return "frontmatter field 'compaction.keepRecentTokens' must be a non-negative integer";
-    }
-    return "frontmatter field 'compaction' must be a mapping";
-  }
-  if (field === "lifecycle") {
-    return "frontmatter field 'lifecycle' must be 'one-shot' or 'interactive'";
+
+  const compactionFields = unexpectedFieldsAt(issuePaths, ["compaction"]);
+  if (compactionFields.length > 0) {
+    return unknownFieldsDiagnostic("compaction", compactionFields);
   }
-  return "invalid worker definition";
+  const nestedDiagnostic = COMPACTION_FIELD_DIAGNOSTICS.find(([nestedField]) =>
+    hasIssuePath(issuePaths, "compaction", nestedField)
+  );
+  return nestedDiagnostic?.[1] ?? "frontmatter field 'compaction' must be a mapping";
 }
 
 function parseWorker(

package/extension/delivery.ts

@@ -1,4 +1,6 @@
-import type { WorkerSettlement } from "./runtime.js";
+import { Context, Effect, Layer } from "effect";
+import { Orchestration } from "./runtime.js";
+import type { WorkerSettlement } from "./worker-settlement.js";
 
 export const MAX_DELIVERY_MARKDOWN_BYTES = 50 * 1024;
 export const MAX_WORKER_DELIVERY_MARKDOWN_BYTES = 16 * 1024;
@@ -38,14 +40,33 @@ interface BoundParent {
 interface SynthesisGroupState {
   expected: number;
   readonly acceptedEventIds: string[];
+  finalEventId?: string;
 }
 
-export class DeliveryCoordinator {
+export interface DeliveryService {
+  bind(binding: ParentBinding): void;
+  unbind(ownerSessionId: string, generation: ParentBindingGeneration): void;
+  markAgentStarted(ownerSessionId: string, generation: ParentBindingGeneration): void;
+  markAgentSettled(ownerSessionId: string, generation: ParentBindingGeneration): void;
+  accept(settlement: WorkerSettlement): boolean;
+  skipSynthesisGroupMember(
+    ownerSessionId: string,
+    synthesisGroupId: string,
+    synthesisGroupSize: number,
+  ): void;
+  pendingCount(ownerSessionId: string): number;
+  clear(): void;
+}
+
+export class Delivery extends Context.Service<Delivery, DeliveryService>()(
+  "@zachwill/pi-orchestrate/Delivery",
+) {}
+
+export class DeliveryCoordinator implements DeliveryService {
   private readonly boundParents = new Map<string, BoundParent>();
   private readonly pendingSettlements: WorkerSettlement[] = [];
   private readonly flushingOwners = new Set<string>();
   private readonly synthesisGroups = new Map<string, SynthesisGroupState>();
-  private readonly finalSynthesisGroupEventIds = new Set<string>();
   private highestAcceptedSequence = 0;
 
   bind(binding: ParentBinding): void {
@@ -115,7 +136,6 @@ export class DeliveryCoordinator {
     this.pendingSettlements.length = 0;
     this.flushingOwners.clear();
     this.synthesisGroups.clear();
-    this.finalSynthesisGroupEventIds.clear();
     this.highestAcceptedSequence = 0;
   }
 
@@ -240,12 +260,15 @@ export class DeliveryCoordinator {
     }
     if (state.acceptedEventIds.length !== state.expected) return;
     const finalEventId = state.acceptedEventIds.at(-1);
-    if (finalEventId) this.finalSynthesisGroupEventIds.add(finalEventId);
+    if (finalEventId) state.finalEventId = finalEventId;
   }
 
   private isFinalBoundary(settlement: WorkerSettlement): boolean {
     if (!settlement.synthesisGroupId) return true;
-    return this.finalSynthesisGroupEventIds.has(settlement.eventId);
+    const state = this.synthesisGroups.get(
+      synthesisGroupKey(settlement.ownerSessionId, settlement.synthesisGroupId),
+    );
+    return state?.finalEventId === settlement.eventId;
   }
 
   private finishSynthesisGroup(settlement: WorkerSettlement): void {
@@ -253,10 +276,29 @@ export class DeliveryCoordinator {
     this.synthesisGroups.delete(
       synthesisGroupKey(settlement.ownerSessionId, settlement.synthesisGroupId),
     );
-    this.finalSynthesisGroupEventIds.delete(settlement.eventId);
   }
 }
 
+/** Process-scoped direct delivery state and its Orchestration settlement subscription. */
+export const deliveryLayer: Layer.Layer<Delivery, never, Orchestration> = Layer.effect(
+  Delivery,
+  Effect.gen(function* () {
+    const orchestration = yield* Orchestration;
+    const coordinator = new DeliveryCoordinator();
+
+    // Registered first so subscription release runs before delivery state is cleared.
+    yield* Effect.addFinalizer(() => Effect.sync(() => coordinator.clear()));
+    yield* Effect.acquireRelease(
+      Effect.sync(() => orchestration.subscribeSettlement((settlement) => {
+        coordinator.accept(settlement);
+      })),
+      (unsubscribe) => Effect.sync(unsubscribe),
+    );
+
+    return Delivery.of(coordinator);
+  }),
+);
+
 function synthesisGroupKey(ownerSessionId: string, synthesisGroupId: string): string {
   return `${ownerSessionId}\u0000${synthesisGroupId}`;
 }

package/extension/domain.ts

@@ -1,4 +1,5 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { Schema } from "effect";
 
 export const SUPPORTED_TOOL_NAMES = [
   "read",
@@ -88,17 +89,36 @@ function compareWorkersByName(left: WorkerDefinition, right: WorkerDefinition):
   return 0;
 }
 
-export interface OrchestrateTaskInput {
-  readonly worker: string;
-  readonly title: string;
-  readonly instructions: string;
-}
+export const MAX_WORKER_TITLE_LENGTH = 200;
+export const MAX_WORKER_INSTRUCTIONS_LENGTH = 100_000;
+export const CANCELLATION_GRACE_MS = 5_000;
 
-declare const workerIdBrand: unique symbol;
-declare const runIdBrand: unique symbol;
+const NonBlankString = Schema.String.check(Schema.isPattern(/\S/));
+const WorkerLabel = NonBlankString.check(
+  Schema.isMaxLength(MAX_WORKER_TITLE_LENGTH),
+);
+const WorkerInstructions = NonBlankString.check(
+  Schema.isMaxLength(MAX_WORKER_INSTRUCTIONS_LENGTH),
+);
+
+export const OrchestrateTaskInput = Schema.Struct({
+  worker: WorkerLabel,
+  title: WorkerLabel,
+  instructions: WorkerInstructions,
+});
+export interface OrchestrateTaskInput extends Schema.Schema.Type<typeof OrchestrateTaskInput> {}
 
-export type WorkerId = string & { readonly [workerIdBrand]: "WorkerId" };
-export type RunId = string & { readonly [runIdBrand]: "RunId" };
+/** A validated worker identity. Worker IDs are stable across interactive generations. */
+export const WorkerId = Schema.String.check(
+  Schema.isPattern(/^worker-\S+$/),
+).pipe(Schema.brand("WorkerId"));
+export type WorkerId = typeof WorkerId.Type;
+
+/** A validated identity for exactly one worker generation. */
+export const RunId = Schema.String.check(
+  Schema.isPattern(/^run-\S+$/),
+).pipe(Schema.brand("RunId"));
+export type RunId = typeof RunId.Type;
 
 export type WorkerIdFactory = () => WorkerId;
 export type RunIdFactory = () => RunId;
@@ -111,13 +131,13 @@ export interface OrchestrateIdFactories {
 export function createRandomWorkerIdFactory(
   randomId: () => string = defaultRandomId,
 ): WorkerIdFactory {
-  return () => `worker-${randomId()}` as WorkerId;
+  return () => WorkerId.make(`worker-${randomId()}`);
 }
 
 export function createRandomRunIdFactory(
   randomId: () => string = defaultRandomId,
 ): RunIdFactory {
-  return () => `run-${randomId()}` as RunId;
+  return () => RunId.make(`run-${randomId()}`);
 }
 
 export function createRandomIdFactories(
@@ -131,12 +151,12 @@ export function createRandomIdFactories(
 
 export function createSequentialWorkerIdFactory(startAt = 1): WorkerIdFactory {
   let next = startAt;
-  return () => `worker-${next++}` as WorkerId;
+  return () => WorkerId.make(`worker-${next++}`);
 }
 
 export function createSequentialRunIdFactory(startAt = 1): RunIdFactory {
   let next = startAt;
-  return () => `run-${next++}` as RunId;
+  return () => RunId.make(`run-${next++}`);
 }
 
 export function createSequentialIdFactories(startAt = 1): OrchestrateIdFactories {
@@ -150,15 +170,23 @@ function defaultRandomId(): string {
   return globalThis.crypto.randomUUID();
 }
 
-export interface WorkerUsage {
-  readonly input: number;
-  readonly output: number;
-  readonly cacheRead: number;
-  readonly cacheWrite: number;
-  readonly cost: number;
-  readonly contextTokens: number;
-  readonly turns: number;
-}
+const NonnegativeFinite = Schema.Finite.check(
+  Schema.isGreaterThanOrEqualTo(0),
+);
+const NonnegativeInteger = Schema.Int.check(
+  Schema.isGreaterThanOrEqualTo(0),
+);
+
+export const WorkerUsage = Schema.Struct({
+  input: NonnegativeFinite,
+  output: NonnegativeFinite,
+  cacheRead: NonnegativeFinite,
+  cacheWrite: NonnegativeFinite,
+  cost: NonnegativeFinite,
+  contextTokens: NonnegativeFinite,
+  turns: NonnegativeInteger,
+});
+export interface WorkerUsage extends Schema.Schema.Type<typeof WorkerUsage> {}
 
 /** Direction of the most recent message across the worker/model boundary. */
 export type WorkerMessageDirection = "to-model" | "from-model";
@@ -173,38 +201,39 @@ export const EMPTY_WORKER_USAGE: WorkerUsage = Object.freeze({
   turns: 0,
 });
 
-export interface WorkerCompletedOutcome {
-  readonly status: "completed";
-  readonly assistantText: string;
-}
-
-export interface WorkerReadyOutcome {
-  readonly status: "ready";
-  readonly assistantText: string;
-}
-
-export interface WorkerFailedOutcome {
-  readonly status: "failed";
-  readonly message: string;
-  readonly assistantText?: string;
-}
-
-export interface WorkerAbortedOutcome {
-  readonly status: "aborted";
-  readonly message?: string;
-  readonly assistantText?: string;
-}
-
-export interface WorkerClosedOutcome {
-  readonly status: "closed";
-}
-
-export type WorkerOutcome =
-  | WorkerCompletedOutcome
-  | WorkerReadyOutcome
-  | WorkerFailedOutcome
-  | WorkerAbortedOutcome
-  | WorkerClosedOutcome;
+export const WorkerCompletedOutcome = Schema.Struct({
+  status: Schema.Literal("completed"),
+  assistantText: Schema.String,
+});
+export const WorkerReadyOutcome = Schema.Struct({
+  status: Schema.Literal("ready"),
+  assistantText: Schema.String,
+});
+export const WorkerFailedOutcome = Schema.Struct({
+  status: Schema.Literal("failed"),
+  message: Schema.String,
+  assistantText: Schema.optionalKey(Schema.String),
+});
+export const WorkerAbortedOutcome = Schema.Struct({
+  status: Schema.Literal("aborted"),
+  message: Schema.optionalKey(Schema.String),
+  assistantText: Schema.optionalKey(Schema.String),
+});
+/** Outcomes emitted in response to a worker generation. */
+export const WorkerResponseOutcome = Schema.Union([
+  WorkerCompletedOutcome,
+  WorkerReadyOutcome,
+  WorkerFailedOutcome,
+  WorkerAbortedOutcome,
+]);
+export type WorkerResponseOutcome = typeof WorkerResponseOutcome.Type;
+
+/** Domain outcomes include closure, which is not a generation response. */
+export const WorkerOutcome = Schema.Union([
+  WorkerResponseOutcome,
+  Schema.Struct({ status: Schema.Literal("closed") }),
+]);
+export type WorkerOutcome = typeof WorkerOutcome.Type;
 export type WorkerStatus =
   | "starting"
   | "running"
@@ -301,7 +330,3 @@ export function transitionWorkerStatus(
 
   return { ...worker, status, outcome: undefined };
 }
-
-export const MAX_WORKER_TITLE_LENGTH = 200;
-export const MAX_WORKER_INSTRUCTIONS_LENGTH = 100_000;
-export const CANCELLATION_GRACE_MS = 5_000;