@zachwill/pi-orchestrate 0.7.1 → 0.8.0

package/README.md

@@ -134,9 +134,9 @@ lifecycle: interactive
 Inspect only the assigned scope. Do not modify files. Return concise findings with file paths.
 ```
 
-Required fields are `name`, `description`, a nonempty `tools` list, and `lifecycle` (`one-shot` or `interactive`). The Markdown body is the worker's nonempty system prompt.
+Required fields are `name`, `description`, and a nonempty `tools` list. The Markdown body is the worker's nonempty system prompt.
 
-Optional fields are `model`, `thinking`, `skills`, and `compaction`. An omitted `model` inherits the parent's model. For `skills`, omission uses normal discovery, a list is an exact allowlist, and `[]` disables skills.
+`lifecycle` is optional, accepts `one-shot` or `interactive`, and defaults to `one-shot`. Other optional fields are `model`, `thinking`, `skills`, and `compaction`. An omitted `model` inherits the parent's model. For `skills`, omission uses normal discovery, a list is an exact allowlist, and `[]` disables skills.
 
 Definitions are strict, regular non-symlink `.md` files up to 64 KiB. Supported Pi tools are `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`. Grant the smallest useful set: a read-only prompt does not prevent writes when the worker has tools with write authority.
 

package/extension/catalog.ts

@@ -6,7 +6,7 @@ import {
 import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Result, Schema, SchemaGetter, type SchemaIssue } from "effect";
+import { Effect, Result, Schema, SchemaGetter, type SchemaIssue } from "effect";
 import type {
   CatalogDiagnostic,
   WorkerCatalog,
@@ -76,7 +76,9 @@ const WorkerFrontmatter = Schema.Struct({
   tools: commaList(Schema.Literals(SUPPORTED_TOOL_NAMES)),
   skills: Schema.optionalKey(commaList(Schema.NonEmptyString, true)),
   compaction: Schema.optionalKey(Compaction),
-  lifecycle: Schema.Literals(["one-shot", "interactive"]),
+  lifecycle: Schema.Literals(["one-shot", "interactive"]).pipe(
+    Schema.withDecodingDefaultKey(Effect.succeed("one-shot")),
+  ),
 });
 const decodeWorkerFrontmatter = Schema.decodeUnknownResult(WorkerFrontmatter, {
   errors: "all",

package/extension/contract.ts

@@ -3,7 +3,7 @@ import type { WorkerCatalog } from "./domain.js";
 const CONTRACT_START = "<!-- pi-orchestrate:contract:start -->";
 const CONTRACT_END = "<!-- pi-orchestrate:contract:end -->";
 
-function contractWorkers(catalog: WorkerCatalog) {
+function sortedWorkers(catalog: WorkerCatalog) {
   return [...catalog.workers].sort((left, right) => {
     if (left.name < right.name) return -1;
     if (left.name > right.name) return 1;
@@ -12,7 +12,7 @@ function contractWorkers(catalog: WorkerCatalog) {
 }
 
 function formatCatalog(catalog: WorkerCatalog): string {
-  const workers = contractWorkers(catalog);
+  const workers = sortedWorkers(catalog);
   if (workers.length === 0) return "- No trusted workers are available for this session.";
 
   return workers

package/extension/delivery.ts

@@ -45,7 +45,7 @@ export class DeliveryCoordinator {
   private readonly pendingSettlements: WorkerSettlement[] = [];
   private readonly flushingOwners = new Set<string>();
   private readonly synthesisGroups = new Map<string, SynthesisGroupState>();
-  private readonly finalSynthesisGroupEvents = new Set<string>();
+  private readonly finalSynthesisGroupEventIds = new Set<string>();
   private highestAcceptedSequence = 0;
 
   bind(binding: ParentBinding): void {
@@ -115,7 +115,7 @@ export class DeliveryCoordinator {
     this.pendingSettlements.length = 0;
     this.flushingOwners.clear();
     this.synthesisGroups.clear();
-    this.finalSynthesisGroupEvents.clear();
+    this.finalSynthesisGroupEventIds.clear();
     this.highestAcceptedSequence = 0;
   }
 
@@ -240,12 +240,12 @@ export class DeliveryCoordinator {
     }
     if (state.acceptedEventIds.length !== state.expected) return;
     const finalEventId = state.acceptedEventIds.at(-1);
-    if (finalEventId) this.finalSynthesisGroupEvents.add(finalEventId);
+    if (finalEventId) this.finalSynthesisGroupEventIds.add(finalEventId);
   }
 
   private isFinalBoundary(settlement: WorkerSettlement): boolean {
     if (!settlement.synthesisGroupId) return true;
-    return this.finalSynthesisGroupEvents.has(settlement.eventId);
+    return this.finalSynthesisGroupEventIds.has(settlement.eventId);
   }
 
   private finishSynthesisGroup(settlement: WorkerSettlement): void {
@@ -253,7 +253,7 @@ export class DeliveryCoordinator {
     this.synthesisGroups.delete(
       synthesisGroupKey(settlement.ownerSessionId, settlement.synthesisGroupId),
     );
-    this.finalSynthesisGroupEvents.delete(settlement.eventId);
+    this.finalSynthesisGroupEventIds.delete(settlement.eventId);
   }
 }
 

package/extension/index.ts

@@ -125,16 +125,16 @@ export function createOrchestrationExtension(
       );
       const ownerSessionId = activeBinding?.ownerSessionId;
       if (!ownerSessionId) return;
-      const groupedOrchestration =
+      const isOrchestrateGroup =
         toolCalls.length > 1 &&
         toolCalls.every((toolCall) => toolCall.name === "orchestrate");
-      const synthesisGroup = groupedOrchestration
+      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 = groupedOrchestration || toolCalls.length === 1
+        const mode = isOrchestrateGroup || toolCalls.length === 1
           ? "async"
           : "inline";
         dispatchDecisions.set(toolCall.id, {

package/extension/presentation.ts

@@ -47,7 +47,7 @@ const ACTIVE_STATUSES: ReadonlySet<WorkerStatus> = new Set(["starting", "running
 
 export type PresentationRuntime = Pick<OrchestratorRuntime, "snapshot" | "subscribeState">;
 
-type SafeSettlement = WorkerSettlementDetails;
+type DecodedSettlement = WorkerSettlementDetails;
 
 interface StatusBinding {
   readonly ownerSessionId: string;
@@ -216,12 +216,12 @@ export class WorkerStatusComponent implements Component {
     const turns = formatTurnMarker(worker);
     const context = `${formatContextTokens(numberOrZero(worker.usage?.contextTokens))} ctx`;
     const usageFields = width >= 28 ? [turns, context] : width >= 12 ? [turns] : [];
-    const workerType = this.theme.fg("muted", this.theme.italic(worker.worker));
-    const workerTypeFits = visibleWidth(
+    const workerName = this.theme.fg("muted", this.theme.italic(worker.worker));
+    const workerNameFits = visibleWidth(
       `⠋  · ${worker.worker} · ${usageFields.join(" · ")}`,
     ) + 10 <= width;
-    const suffixFields = width >= 72 && workerTypeFits
-      ? [workerType, ...usageFields]
+    const suffixFields = width >= 72 && workerNameFits
+      ? [workerName, ...usageFields]
       : usageFields;
     const prefix = `${glyph} `;
     const suffix = suffixFields.length ? ` · ${suffixFields.join(" · ")}` : "";
@@ -280,11 +280,11 @@ export class WorkerResultComponent implements Component {
     const elapsed = elapsedBetween(details.startedAt, details.settledAt);
     const qualifier = resultQualifier(details);
     const title = this.theme.bold(details.title);
-    const workerType = this.theme.fg("muted", this.theme.italic(details.worker));
+    const workerName = this.theme.fg("muted", this.theme.italic(details.worker));
     const suffix = [qualifier, elapsed].filter(Boolean).join(" · ");
     const header = [
       this.theme.fg(color, `${statusIcon(details)} ${title}`),
-      workerType,
+      workerName,
       ...(suffix ? [this.theme.fg(color, suffix)] : []),
     ].join(" · ");
     const outcome = presentedOutcome(details);
@@ -308,7 +308,7 @@ export class WorkerResultComponent implements Component {
   }
 }
 
-function readSettlement(value: unknown): SafeSettlement | undefined {
+function readSettlement(value: unknown): DecodedSettlement | undefined {
   const decoded = decodePersistedWorkerSettlementDetails(value);
   return Result.isSuccess(decoded) ? decoded.success : undefined;
 }
@@ -319,13 +319,13 @@ function workerAnimation(status: WorkerStatus) {
   return WORKER_ANIMATIONS.running;
 }
 
-function resultColor(status: SafeSettlement["status"]): "success" | "error" | "warning" {
+function resultColor(status: DecodedSettlement["status"]): "success" | "error" | "warning" {
   if (status === "failed") return "error";
   if (status === "aborted") return "warning";
   return "success";
 }
 
-function resultQualifier(result: SafeSettlement): string | undefined {
+function resultQualifier(result: DecodedSettlement): string | undefined {
   if (result.status === "aborted") return "aborted";
   if (result.status === "failed" && result.failureStage === "startup") {
     return "could not start";
@@ -335,7 +335,7 @@ function resultQualifier(result: SafeSettlement): string | undefined {
   return undefined;
 }
 
-function statusIcon(result: SafeSettlement): string {
+function statusIcon(result: DecodedSettlement): string {
   if (result.status === "failed") return "✗";
   if (result.status === "aborted") return "■";
   return "✓";
@@ -348,7 +348,7 @@ function outcomeText(outcome: WorkerOutcome): string {
   return "Worker session closed.";
 }
 
-function presentedOutcome(result: SafeSettlement): string {
+function presentedOutcome(result: DecodedSettlement): string {
   const body = outcomeText(result.outcome);
   if (result.status !== "completed" && result.status !== "ready") return body;
 
@@ -363,7 +363,7 @@ function presentedOutcome(result: SafeSettlement): string {
   return lines.join("\n").trimEnd();
 }
 
-function settlementMetadata(result: SafeSettlement): string[] {
+function settlementMetadata(result: DecodedSettlement): string[] {
   return [
     `worker ID ${result.workerId} · run ID ${result.runId}`,
     `status ${result.status} · generation ${result.generation}`,

package/extension/runtime.ts

@@ -66,7 +66,7 @@ export interface AcceptedRun {
   readonly workerId: WorkerId;
 }
 
-export interface CompletedResult {
+export interface RunResult {
   readonly workerId: WorkerId;
   readonly worker: string;
   readonly title: string;
@@ -82,7 +82,7 @@ export interface CompletedRun {
   readonly id: RunId;
   readonly ownerSessionId: string;
   readonly mode: RunMode;
-  readonly result: CompletedResult;
+  readonly result: RunResult;
 }
 
 export interface RuntimeSnapshot {
@@ -1238,7 +1238,7 @@ function isActiveWorkerStatus(status: WorkerRecord["status"]): boolean {
 
 function isSettledWorkerStatus(
   status: WorkerRecord["status"],
-): status is CompletedResult["status"] {
+): status is RunResult["status"] {
   return status === "completed" || status === "ready" || status === "failed" || status === "aborted";
 }
 
@@ -1336,11 +1336,11 @@ function freezeCompletedRun(
   if (record.settledAt === undefined) {
     throw new Error("Completed run requires a settlement timestamp");
   }
-  const result: CompletedResult = Object.freeze({
+  const result: RunResult = Object.freeze({
     workerId: record.id,
     worker: record.worker,
     title: record.title,
-    status: record.status as CompletedResult["status"],
+    status: record.status as RunResult["status"],
     outcome: Object.freeze(copyOutcome(outcome)),
     usage: Object.freeze(copyUsage(record.usage)),
     startedAt: record.startedAt,

package/extension/tools.ts

@@ -34,10 +34,10 @@ import {
 import type {
   AbortTarget,
   AcceptedRun,
-  CompletedResult,
   CompletedRun,
   OrchestrationContext,
   OrchestratorRuntime,
+  RunResult,
   RuntimeSnapshot,
   SettlementListener,
   WorkerSettlement,
@@ -446,7 +446,7 @@ function completedRunDetails(run: CompletedRun) {
   };
 }
 
-function completedResultDetails(result: CompletedResult) {
+function completedResultDetails(result: RunResult) {
   return {
     worker_id: result.workerId,
     worker: result.worker,
@@ -766,10 +766,10 @@ class InlineResultComponent implements Component {
     const appearance = inlineResultAppearance(result.status);
     const suffix = [appearance.qualifier, result.elapsed].filter(Boolean).join(" · ");
     const title = this.theme.bold(result.title);
-    const workerType = this.theme.fg("muted", this.theme.italic(result.worker));
+    const workerName = this.theme.fg("muted", this.theme.italic(result.worker));
     const header = [
       this.theme.fg(appearance.color, `${appearance.icon} ${title}`),
-      workerType,
+      workerName,
       ...(suffix ? [this.theme.fg(appearance.color, suffix)] : []),
     ].join(" · ");
     container.addChild(new WidthBoundComponent(new Text(header, 0, 0), 1));

package/extension/worker-session.ts

@@ -106,17 +106,17 @@ const WorkerAgentSessionAcquisitionOperation = Schema.Literals([
 ]);
 type WorkerAgentSessionAcquisitionOperation = typeof WorkerAgentSessionAcquisitionOperation.Type;
 
-export class WorkerModelAcquisitionError extends Schema.TaggedErrorClass<WorkerModelAcquisitionError>()(
+export class WorkerModelAcquisitionError extends Schema.TaggedError<WorkerModelAcquisitionError>()(
   "WorkerSession.ModelAcquisitionError",
   { operation: WorkerModelAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}
 
-export class WorkerResourceAcquisitionError extends Schema.TaggedErrorClass<WorkerResourceAcquisitionError>()(
+export class WorkerResourceAcquisitionError extends Schema.TaggedError<WorkerResourceAcquisitionError>()(
   "WorkerSession.ResourceAcquisitionError",
   { operation: WorkerResourceAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}
 
-export class WorkerAgentSessionAcquisitionError extends Schema.TaggedErrorClass<WorkerAgentSessionAcquisitionError>()(
+export class WorkerAgentSessionAcquisitionError extends Schema.TaggedError<WorkerAgentSessionAcquisitionError>()(
   "WorkerSession.AgentSessionAcquisitionError",
   { operation: WorkerAgentSessionAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}

package/extension/worker-settlement.ts

@@ -3,6 +3,7 @@ import type { RunId, WorkerId } from "./domain.js";
 
 const NonnegativeFinite = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
 const NonnegativeInteger = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+const PositiveInteger = Schema.Int.check(Schema.isGreaterThan(0));
 
 const WorkerUsage = Schema.Struct({
   input: NonnegativeFinite,
@@ -45,11 +46,11 @@ const FailureStage = Schema.Literals([
 /** Canonical schema for settlement details written by the current runtime. */
 export const WorkerSettlementDetails = Schema.Struct({
   eventId: Schema.String,
-  sequence: NonnegativeInteger,
+  sequence: PositiveInteger,
   ownerSessionId: Schema.String,
   runId: Schema.String,
   workerId: Schema.String,
-  generation: NonnegativeInteger,
+  generation: PositiveInteger,
   mode: Schema.Literals(["async", "inline"]),
   worker: Schema.String,
   title: Schema.String,
@@ -60,7 +61,7 @@ export const WorkerSettlementDetails = Schema.Struct({
   startedAt: NonnegativeInteger,
   settledAt: NonnegativeInteger,
   synthesisGroupId: Schema.optionalKey(Schema.String),
-  synthesisGroupSize: Schema.optionalKey(NonnegativeInteger),
+  synthesisGroupSize: Schema.optionalKey(PositiveInteger),
   sessionFile: Schema.optionalKey(Schema.String),
   failureStage: Schema.optionalKey(FailureStage),
 }).check(
@@ -68,6 +69,24 @@ export const WorkerSettlementDetails = Schema.Struct({
     if (settlement.outcome.status !== settlement.status) {
       return "outcome status must match settlement status";
     }
+    if (settlement.status === "ready" && settlement.lifecycle !== "interactive") {
+      return "ready settlement requires an interactive lifecycle";
+    }
+    if (settlement.status === "completed" && settlement.lifecycle !== "one-shot") {
+      return "completed settlement requires a one-shot lifecycle";
+    }
+    if (
+      (settlement.synthesisGroupId === undefined) !==
+      (settlement.synthesisGroupSize === undefined)
+    ) {
+      return "synthesis group ID and size must occur together";
+    }
+    if (
+      settlement.synthesisGroupSize !== undefined &&
+      settlement.synthesisGroupSize < 2
+    ) {
+      return "synthesis group size must be at least 2";
+    }
     if (settlement.settledAt < settlement.startedAt) {
       return "settlement timestamp must not precede start timestamp";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachwill/pi-orchestrate",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Concurrent worker orchestration for Pi",
   "files": ["extension/", "examples/", "README.md", "LICENSE"],
@@ -25,7 +25,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.99"
+    "effect": "4.0.0-rc.111"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "^0.80.10",