@zachwill/pi-orchestrate 0.1.0 → 0.2.0

package/extension/scheduler.ts

@@ -1,4 +1,4 @@
-import { Cause, Effect, Exit, FiberMap, Scope } from "effect";
+import { Cause, Context, Effect, FiberMap, Layer, ManagedRuntime } from "effect";
 
 export type WorkflowDefectHandler = (error: unknown) => void;
 
@@ -6,7 +6,7 @@ export interface WorkflowScheduler<Key> {
   /** Starts a workflow immediately, interrupting and replacing the previous workflow at the key. */
   start(
     key: Key,
-    workflow: () => Promise<void>,
+    workflow: Effect.Effect<void, never>,
     onDefect: WorkflowDefectHandler,
   ): void;
   /** Interrupts the current workflow at the key and waits for its fiber to settle. */
@@ -15,48 +15,67 @@ export interface WorkflowScheduler<Key> {
   close(): Promise<void>;
 }
 
+interface WorkflowSupervisorService {
+  readonly start: (
+    key: unknown,
+    workflow: Effect.Effect<void, never>,
+  ) => void;
+  readonly remove: (key: unknown) => Effect.Effect<void>;
+}
+
+class WorkflowSupervisor extends Context.Service<
+  WorkflowSupervisor,
+  WorkflowSupervisorService
+>()("@zachwill/pi-orchestrate/WorkflowSupervisor") {}
+
+const workflowSupervisorLayer = Layer.effect(
+  WorkflowSupervisor,
+  Effect.gen(function* () {
+    const fibers = yield* FiberMap.make<unknown, void, never>();
+    const run = yield* FiberMap.runtime(fibers)<never>();
+    return WorkflowSupervisor.of({
+      start(key, workflow) {
+        run(key, workflow);
+      },
+      remove: (key) => FiberMap.remove(fibers, key),
+    });
+  }),
+);
+
 class EffectWorkflowScheduler<Key> implements WorkflowScheduler<Key> {
-  private readonly scope = Scope.makeUnsafe("parallel");
-  private readonly fibers: FiberMap.FiberMap<Key, void, never>;
+  private readonly managedRuntime = ManagedRuntime.make(workflowSupervisorLayer);
+  private readonly supervisor = this.managedRuntime.runSync(WorkflowSupervisor);
   private closePromise: Promise<void> | undefined;
 
-  constructor() {
-    this.fibers = Effect.runSync(
-      Scope.provide(this.scope)(FiberMap.make<Key, void, never>()),
-    );
-  }
-
   start(
     key: Key,
-    workflow: () => Promise<void>,
+    workflow: Effect.Effect<void, never>,
     onDefect: WorkflowDefectHandler,
   ): void {
-    const supervised = Effect.promise(workflow).pipe(
+    const supervised = workflow.pipe(
       Effect.catchCause((cause) => {
         if (!Cause.hasInterruptsOnly(cause)) {
-          try {
-            onDefect(Cause.squash(cause));
-          } catch {
-            // Defect reporting must not become another unsupervised defect.
-          }
+          return Effect.sync(() => {
+            try {
+              onDefect(Cause.squash(cause));
+            } catch {
+              // Defect reporting must not become another unsupervised defect.
+            }
+          });
         }
         return Effect.void;
       }),
     );
 
-    Effect.runSync(
-      FiberMap.run(this.fibers, key, supervised, { startImmediately: true }),
-    );
+    this.supervisor.start(key, supervised);
   }
 
-  async remove(key: Key): Promise<void> {
-    await Effect.runPromise(FiberMap.remove(this.fibers, key));
+  remove(key: Key): Promise<void> {
+    return this.managedRuntime.runPromise(this.supervisor.remove(key));
   }
 
   close(): Promise<void> {
-    if (!this.closePromise) {
-      this.closePromise = Effect.runPromise(Scope.close(this.scope, Exit.void));
-    }
+    this.closePromise ??= this.managedRuntime.dispose();
     return this.closePromise;
   }
 }

package/extension/tools.ts

@@ -1,10 +1,23 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type {
   ExtensionAPI,
   ExtensionContext,
+  Theme,
 } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Markdown,
+  Spacer,
+  Text,
+  truncateToWidth,
+  wrapTextWithAnsi,
+  type Component,
+} from "@earendil-works/pi-tui";
 import {
   formatSize,
   getAgentDir,
+  getMarkdownTheme,
+  keyHint,
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -32,6 +45,7 @@ import type {
 
 const STRICT_OBJECT = { additionalProperties: false } as const;
 const MAX_TASKS_PER_WAVE = 12;
+const MAX_INSTRUCTION_PREVIEW_LINES = 2;
 
 const taskSchema = Type.Object(
   {
@@ -110,15 +124,30 @@ export function registerOrchestrationTools(
       "Use orchestrate for one independent worker wave, with a complete brief for every task.",
     ],
     parameters: orchestrateSchema,
-    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+    renderCall(args, theme, { expanded }) {
+      return renderDispatchCall(theme, args.tasks, expanded);
+    },
+    renderResult(result, { isPartial, expanded }, theme, context) {
+      return renderOrchestrationResult(result, isPartial, expanded, theme, context.lastComponent);
+    },
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
       const mode = deps.getDispatchMode(toolCallId);
       const runtimeContext = await buildRuntimeContext(ctx, deps);
+      const settlements: unknown[] = [];
+      const onSettlement = mode === "inline" ? (settlement: unknown) => {
+        settlements.push(settlement);
+        onUpdate?.({
+          content: [{ type: "text", text: `${settlements.length} worker response(s) received.` }],
+          details: { mode: "inline", settlements: [...settlements] },
+        });
+      } : undefined;
       const wave = await orchestrateWithMode(
         deps.runtime,
         runtimeContext,
         params.tasks,
         mode,
         signal,
+        onSettlement,
       );
 
       if (mode === "async") {
@@ -163,6 +192,12 @@ export function registerOrchestrationTools(
       "Use orchestration_status only for diagnostics or recovery; never poll it for completion.",
     ],
     parameters: statusSchema,
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("orchestration_status")), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme) {
+      return renderDiagnosticsResult(result, isPartial, theme);
+    },
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const ownerSessionId = requireNonblank(
         "owner session ID",
@@ -195,10 +230,24 @@ export function registerOrchestrationTools(
       "Use worker_send only for follow-up work on an owned ready reusable worker.",
     ],
     parameters: workerSendSchema,
-    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+    renderCall(args, theme, { expanded }) {
+      return renderWorkerMessageCall(theme, "worker_send", args.worker_id, args.instructions, expanded);
+    },
+    renderResult(result, { isPartial, expanded }, theme, context) {
+      return renderOrchestrationResult(result, isPartial, expanded, theme, context.lastComponent);
+    },
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
       const workerId = asWorkerId(params.worker_id);
       const mode = deps.getDispatchMode(toolCallId);
       const runtimeContext = await buildRuntimeContext(ctx, deps);
+      const settlements: unknown[] = [];
+      const onSettlement = mode === "inline" ? (settlement: unknown) => {
+        settlements.push(settlement);
+        onUpdate?.({
+          content: [{ type: "text", text: `${settlements.length} worker response(s) received.` }],
+          details: { mode: "inline", settlements: [...settlements] },
+        });
+      } : undefined;
       const wave = await sendWithMode(
         deps.runtime,
         runtimeContext,
@@ -206,6 +255,7 @@ export function registerOrchestrationTools(
         params.instructions,
         mode,
         signal,
+        onSettlement,
       );
 
       if (mode === "async") {
@@ -250,6 +300,17 @@ export function registerOrchestrationTools(
       "Use worker_abort only for active work; use worker_close for a ready reusable worker.",
     ],
     parameters: workerAbortSchema,
+    renderCall(args, theme) {
+      const target = "wave_id" in args
+        ? args.wave_id
+        : "worker_ids" in args
+          ? `${args.worker_ids.length} worker${args.worker_ids.length === 1 ? "" : "s"}`
+          : "all workers";
+      return renderCompactCall(theme, "worker_abort", target);
+    },
+    renderResult(result, { isPartial }, theme) {
+      return renderSimpleResult(result, isPartial ? "Requesting worker stop…" : "Worker stop requested", theme, "warning");
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const ownerSessionId = requireNonblank(
         "owner session ID",
@@ -279,6 +340,12 @@ export function registerOrchestrationTools(
       "Use worker_close when an owned ready reusable worker is finished.",
     ],
     parameters: workerCloseSchema,
+    renderCall(args, theme) {
+      return renderCompactCall(theme, "worker_close", args.worker_id);
+    },
+    renderResult(result, { isPartial }, theme) {
+      return renderSimpleResult(result, isPartial ? "Closing worker…" : "✓ Worker closed", theme);
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const ownerSessionId = requireNonblank(
         "owner session ID",
@@ -325,16 +392,10 @@ function orchestrateWithMode(
   tasks: readonly OrchestrateTaskInput[],
   mode: "async" | "inline",
   signal: AbortSignal | undefined,
+  onSettlement?: (settlement: unknown) => void,
 ): Promise<AcceptedWave | CompletedWave> {
   if (mode === "async") return runtime.orchestrate(context, tasks, "async");
-
-  const orchestrateInline = runtime.orchestrate as unknown as (
-    context: OrchestrationContext,
-    tasks: readonly OrchestrateTaskInput[],
-    mode: "inline",
-    signal?: AbortSignal,
-  ) => Promise<CompletedWave>;
-  return orchestrateInline.call(runtime, context, tasks, "inline", signal);
+  return runtime.orchestrate(context, tasks, "inline", signal, onSettlement);
 }
 
 function sendWithMode(
@@ -344,17 +405,10 @@ function sendWithMode(
   instructions: string,
   mode: "async" | "inline",
   signal: AbortSignal | undefined,
+  onSettlement?: (settlement: unknown) => void,
 ): Promise<AcceptedWave | CompletedWave> {
   if (mode === "async") return runtime.send(context, workerId, instructions, "async");
-
-  const sendInline = runtime.send as unknown as (
-    context: OrchestrationContext,
-    workerId: WorkerId,
-    instructions: string,
-    mode: "inline",
-    signal?: AbortSignal,
-  ) => Promise<CompletedWave>;
-  return sendInline.call(runtime, context, workerId, instructions, "inline", signal);
+  return runtime.send(context, workerId, instructions, "inline", signal, onSettlement);
 }
 
 function requireNonblank(name: string, value: string): string {
@@ -467,7 +521,7 @@ function catalogWorkerDetails(worker: WorkerDefinition) {
       file_path: worker.source.filePath,
     },
     tools: [...worker.tools],
-    skills: [...worker.skills],
+    skills: worker.skills === undefined ? undefined : [...worker.skills],
     model: worker.model
       ? { provider: worker.model.provider, model_id: worker.model.modelId }
       : undefined,
@@ -557,3 +611,266 @@ function readableDetails(title: string, details: unknown): string {
 
   return `${truncation.content}\n\n[Output truncated: ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}. Full structured details remain available.]`;
 }
+
+interface RenderableTask {
+  readonly worker?: unknown;
+  readonly title?: unknown;
+  readonly instructions?: unknown;
+}
+
+function renderDispatchCall(
+  theme: Theme,
+  tasks: readonly RenderableTask[] | undefined,
+  expanded: boolean,
+): Component {
+  const container = new Container();
+  const renderableTasks = Array.isArray(tasks) ? tasks : [];
+  const count = renderableTasks.length;
+  container.addChild(new Text(
+    theme.fg("toolTitle", theme.bold("orchestrate ")) + theme.fg("muted", `${count} worker${count === 1 ? "" : "s"}`),
+    0, 0,
+  ));
+  if (expanded) {
+    for (const task of renderableTasks) {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(`${theme.fg("accent", "→")} ${theme.fg("muted", safeTerminalText(task.worker))} · ${theme.fg("text", theme.bold(safeTerminalText(task.title)))}`, 0, 0));
+      container.addChild(new Text(safeTerminalText(task.instructions), 2, 0));
+    }
+    return new WidthBoundComponent(container);
+  }
+  container.addChild(new InstructionPreview(renderableTasks, theme));
+  container.addChild(new Text(theme.fg("dim", keyHint("app.tools.expand", "to inspect full instructions")), 0, 0));
+  return new WidthBoundComponent(container);
+}
+
+class InstructionPreview implements Component {
+  constructor(
+    private readonly tasks: readonly RenderableTask[],
+    private readonly theme: Theme,
+  ) {}
+  render(width: number): string[] {
+    const bounded = Math.max(1, width);
+    const lines: string[] = [];
+    for (const task of this.tasks) {
+      const heading = `${this.theme.fg("accent", "→")} ${this.theme.fg("muted", safeTerminalText(task.worker))} · ${this.theme.fg("text", this.theme.bold(safeTerminalText(task.title)))}`;
+      lines.push(truncateToWidth(heading, bounded, "…"));
+
+      const contentWidth = Math.max(1, bounded - 2);
+      const characterLimit = Math.max(256, Math.min(4096, contentWidth * 3));
+      const preview = compactInstructionPreview(task.instructions, characterLimit);
+      if (!preview.text) continue;
+      const wrapped = wrapTextWithAnsi(preview.text, contentWidth);
+      const previewLines = wrapped.slice(0, MAX_INSTRUCTION_PREVIEW_LINES);
+      if (preview.truncated || wrapped.length > MAX_INSTRUCTION_PREVIEW_LINES) {
+        const lastIndex = previewLines.length - 1;
+        previewLines[lastIndex] = truncateToWidth(`${previewLines[lastIndex] ?? ""}…`, contentWidth, "…");
+      }
+      for (const line of previewLines) lines.push(this.theme.fg("dim", `  ${line}`));
+    }
+    return lines.map((line) => truncateToWidth(line, bounded, "…"));
+  }
+  invalidate(): void {}
+}
+
+function renderWorkerMessageCall(
+  theme: Theme,
+  tool: string,
+  workerId: unknown,
+  instructions: unknown,
+  expanded: boolean,
+): Component {
+  const container = new Container();
+  container.addChild(new Text(theme.fg("toolTitle", theme.bold(`${tool} `)) + theme.fg("muted", safeTerminalText(workerId)), 0, 0));
+  if (expanded) container.addChild(new Text(safeTerminalText(instructions), 2, 0));
+  else {
+    container.addChild(new Text(`${theme.fg("accent", "→")} ${truncateInstruction(instructions, 240)}`, 0, 0));
+    container.addChild(new Text(theme.fg("dim", keyHint("app.tools.expand", "to inspect full message")), 0, 0));
+  }
+  return new WidthBoundComponent(container);
+}
+
+class WidthBoundComponent implements Component {
+  constructor(private readonly child: Component, private readonly maxLines?: number) {}
+  render(width: number): string[] {
+    const bounded = Math.max(1, Math.floor(width));
+    const lines = this.child.render(bounded);
+    return (this.maxLines === undefined ? lines : lines.slice(0, this.maxLines))
+      .map((line) => truncateToWidth(line, bounded, "…"));
+  }
+  invalidate(): void { this.child.invalidate(); }
+  dispose(): void { (this.child as Component & { dispose?: () => void }).dispose?.(); }
+}
+
+function safeTerminalText(value: unknown): string {
+  const text = typeof value === "string" ? value : value == null ? "" : String(value);
+  return text.replace(/\r\n?/g, "\n").replace(/\t/g, "    ").replace(/[\x00-\x08\x0B-\x1F\x7F]/g, (character) => {
+    const code = character.charCodeAt(0);
+    return code === 0x7f ? "␡" : String.fromCodePoint(0x2400 + code);
+  });
+}
+
+function compactInstructionPreview(instructions: unknown, characterLimit: number): { text: string; truncated: boolean } {
+  const text = typeof instructions === "string" ? instructions : instructions == null ? "" : String(instructions);
+  const source = text.slice(0, characterLimit);
+  return {
+    text: safeTerminalText(source).replace(/\s+/g, " ").trim(),
+    truncated: source.length < text.length,
+  };
+}
+
+function firstInstructionLine(instructions: unknown): string | undefined {
+  const text = typeof instructions === "string" ? instructions : instructions == null ? "" : String(instructions);
+  return text.split(/\r\n?|\n/).find((line) => line.trim().length > 0);
+}
+
+function truncateInstruction(instructions: unknown, limit: number): string {
+  const first = firstInstructionLine(instructions) ?? "";
+  return first.length > limit ? `${first.slice(0, limit - 1)}…` : first;
+}
+
+function renderCompactCall(theme: Theme, tool: string, target: unknown): Text {
+  return new Text(
+    theme.fg("toolTitle", theme.bold(`${tool} `)) + theme.fg("muted", safeTerminalText(target)),
+    0,
+    0,
+  );
+}
+
+function renderOrchestrationResult(
+  result: AgentToolResult<unknown>,
+  isPartial: boolean,
+  expanded: boolean,
+  theme: Theme,
+  lastComponent: unknown,
+): Component {
+  const details = result.details;
+  if (isRecord(details) && typeof details.id === "string" && Array.isArray(details.workerIds) && details.workerIds.every((id) => typeof id === "string")) {
+    const count = details.workerIds.length;
+    return new WidthBoundComponent(new Text(theme.fg("success", `Sent to ${count} worker${count === 1 ? "" : "s"}`) + theme.fg("dim", " · responses arrive as they complete"), 0, 0));
+  }
+  const settlements = inlineSettlements(details);
+  if (settlements.length > 0) {
+    const component = lastComponent instanceof InlineResultComponent
+      ? lastComponent
+      : new InlineResultComponent(theme);
+    component.update(settlements, isPartial, expanded);
+    return component;
+  }
+  if (isRecord(details) && (Array.isArray(details.settlements) || Array.isArray(details.results) || "workerIds" in details)) {
+    return new WidthBoundComponent(new Text(theme.fg("warning", "Worker result details unavailable"), 0, 0));
+  }
+  if (isPartial) return new WidthBoundComponent(new Text(theme.fg("warning", "Sending work…"), 0, 0));
+  return new WidthBoundComponent(renderSimpleResult(result, firstResultLine(result) || "Work sent", theme, "warning"));
+}
+
+interface InlineSettlement {
+  worker: string;
+  title: string;
+  status: "completed" | "ready" | "failed" | "aborted";
+  response: string;
+}
+
+class InlineResultComponent implements Component {
+  private settlements: readonly InlineSettlement[] = [];
+  private partial = false;
+  private expanded = false;
+  private child: Component = new Container();
+  constructor(private readonly theme: Theme) {}
+  update(settlements: readonly InlineSettlement[], partial: boolean, expanded: boolean): void {
+    this.settlements = settlements;
+    this.partial = partial;
+    this.expanded = expanded;
+    this.rebuild();
+  }
+  render(width: number): string[] { return new WidthBoundComponent(this.child).render(width); }
+  invalidate(): void { this.rebuild(); }
+  dispose(): void { (this.child as Component & { dispose?: () => void }).dispose?.(); }
+  private rebuild(): void {
+    (this.child as Component & { dispose?: () => void }).dispose?.();
+    const container = new Container();
+    for (const settlement of this.settlements) {
+      const failed = settlement.status === "failed";
+      const aborted = settlement.status === "aborted";
+      const color = failed ? "error" : aborted ? "warning" : "success";
+      const icon = failed ? "✗" : aborted ? "■" : "✓";
+      container.addChild(new WidthBoundComponent(new Text(this.theme.fg(color, this.theme.bold(`${icon} ${settlement.worker} · ${settlement.title} · ${settlement.status}`)), 0, 0), 1));
+      if (settlement.response) {
+        const markdown = new Markdown(settlement.response, this.expanded ? 2 : 0, 0, getMarkdownTheme());
+        container.addChild(new WidthBoundComponent(markdown, this.expanded ? undefined : 2));
+      }
+      container.addChild(new Spacer(1));
+    }
+    if (this.partial) container.addChild(new Text(this.theme.fg("warning", "Waiting for remaining workers…"), 0, 0));
+    else if (!this.expanded) container.addChild(new Text(this.theme.fg("dim", keyHint("app.tools.expand", "to inspect full responses")), 0, 0));
+    this.child = container;
+  }
+}
+
+function inlineSettlements(details: unknown): InlineSettlement[] {
+  if (!isRecord(details)) return [];
+  const values = Array.isArray(details.settlements) ? details.settlements : Array.isArray(details.results) ? details.results : [];
+  const parsed: InlineSettlement[] = [];
+  for (const value of values) {
+    const settlement = readInlineSettlement(value);
+    if (settlement) parsed.push(settlement);
+  }
+  return parsed;
+}
+
+function readInlineSettlement(value: unknown): InlineSettlement | undefined {
+  if (!isRecord(value) || typeof value.worker !== "string" || typeof value.title !== "string" || !isRecord(value.outcome)) return undefined;
+  const outcome = value.outcome;
+  const statuses = ["completed", "ready", "failed", "aborted"] as const;
+  const status = statuses.find((item) => item === value.status);
+  const outcomeStatus = statuses.find((item) => item === outcome.status);
+  if (!status || outcomeStatus !== status) return undefined;
+  const message = outcome.message;
+  const camelAssistant = outcome.assistantText;
+  const snakeAssistant = outcome.assistant_text;
+  if (message !== undefined && typeof message !== "string") return undefined;
+  if (camelAssistant !== undefined && typeof camelAssistant !== "string") return undefined;
+  if (snakeAssistant !== undefined && typeof snakeAssistant !== "string") return undefined;
+  const assistantText = typeof camelAssistant === "string" ? camelAssistant : snakeAssistant;
+  if ((status === "completed" || status === "ready") && typeof assistantText !== "string") return undefined;
+  if (status === "failed" && typeof message !== "string") return undefined;
+  return {
+    worker: value.worker,
+    title: value.title,
+    status,
+    response: [message, assistantText].filter((item): item is string => typeof item === "string" && item.length > 0).join("\n\n"),
+  };
+}
+
+function renderDiagnosticsResult(result: AgentToolResult<unknown>, isPartial: boolean, theme: Theme): Text {
+  if (isPartial) return new Text(theme.fg("muted", "Reading orchestration diagnostics…"), 0, 0);
+  const details = result.details;
+  if (isRecord(details) && isRecord(details.snapshot) && Array.isArray(details.snapshot.workers)) {
+    const workers = details.snapshot.workers.filter(isRecord);
+    const active = workers.filter((worker) => ["starting", "running", "stopping"].includes(String(worker.status))).length;
+    const ready = workers.filter((worker) => worker.status === "ready").length;
+    const diagnostics = isRecord(details.catalog) && Array.isArray(details.catalog.diagnostics) ? details.catalog.diagnostics.length : 0;
+    const facts = [active ? `${active} active` : "No active workers", ready ? `${ready} available for follow-up` : undefined, diagnostics ? `${diagnostics} catalog diagnostic${diagnostics === 1 ? "" : "s"}` : undefined].filter(Boolean);
+    return new Text(theme.fg("muted", facts.join(" · ")), 0, 0);
+  }
+  return new Text(theme.fg("muted", firstResultLine(result) || "Diagnostics unavailable"), 0, 0);
+}
+
+function renderSimpleResult(
+  result: AgentToolResult<unknown>,
+  message: string,
+  theme: Theme,
+  normalColor: "success" | "warning" = "success",
+): Text {
+  const failed = "isError" in result && result.isError === true;
+  return new Text(theme.fg(failed ? "error" : normalColor, failed ? firstResultLine(result) || message : message), 0, 0);
+}
+
+function firstResultLine(result: AgentToolResult<unknown>): string | undefined {
+  const first = result.content[0];
+  if (first?.type !== "text") return undefined;
+  return first.text.split("\n").find((line) => line.trim())?.trim();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}