@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

package/src/domains/workflows/runtime/options.ts

@@ -0,0 +1,157 @@
+import type { WorkflowRunOptions } from "./types.ts";
+
+export const WORKFLOW_BUDGET_MIN = 1;
+export const WORKFLOW_BUDGET_MAX = 1_000_000_000;
+export const WORKFLOW_MAX_AGENTS_MIN = 1;
+export const WORKFLOW_MAX_AGENTS_MAX = 10_000;
+export const WORKFLOW_AGENT_TIMEOUT_MIN_MS = 1_000;
+export const WORKFLOW_AGENT_TIMEOUT_MAX_MS = 86_400_000;
+export const WORKFLOW_AGENT_RETRIES_MIN = 0;
+export const WORKFLOW_AGENT_RETRIES_MAX = 10;
+export const DEFAULT_WORKFLOW_AGENT_RETRIES = 0;
+export const WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN = 1;
+export const WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX = 10;
+export const DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS = 3;
+export const WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS = 5_000;
+export const WORKFLOW_USAGE_LIMIT_DELAY_MAX_MS = 86_400_000;
+export const DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS = 21_600_000;
+
+export type ResolvedWorkflowRunOptions = Omit<
+  WorkflowRunOptions,
+  | "perf"
+  | "concurrency"
+  | "parallelSubmissionLimit"
+  | "maxAgents"
+  | "agentTimeoutMs"
+  | "agentRetries"
+  | "autoResumeOnUsageLimit"
+  | "usageLimitMaxAttempts"
+  | "usageLimitMaxDelayMs"
+  | "usageLimitAttempt"
+  | "resumeEditedWorkflow"
+  | "budget"
+> & {
+  readonly perf: boolean;
+  readonly concurrency: number | null;
+  readonly parallelSubmissionLimit: number | null;
+  readonly maxAgents: number | null;
+  readonly agentTimeoutMs: number | null;
+  readonly agentRetries: number;
+  readonly autoResumeOnUsageLimit: boolean;
+  readonly usageLimitMaxAttempts: number;
+  readonly usageLimitMaxDelayMs: number;
+  readonly usageLimitAttempt: number;
+  readonly resumeEditedWorkflow: boolean;
+  readonly budget: number | null;
+};
+
+export function resolveWorkflowRunOptions(
+  input: WorkflowRunOptions = {},
+  env: Record<string, string | undefined> = process.env,
+): ResolvedWorkflowRunOptions {
+  const concurrency = optionalClampedInteger(
+    input.concurrency ?? parseInteger(env.PI_WORKFLOW_CONCURRENCY),
+    1,
+    64,
+  );
+  const parallelSubmissionLimit = optionalClampedInteger(
+    input.parallelSubmissionLimit ?? parseInteger(env.PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT),
+    1,
+    10_000,
+  );
+  const maxAgents = optionalClampedInteger(
+    input.maxAgents ?? parseWorkflowIntegerString(env.PI_WORKFLOW_MAX_AGENTS),
+    WORKFLOW_MAX_AGENTS_MIN,
+    WORKFLOW_MAX_AGENTS_MAX,
+  );
+  const agentTimeoutMs = optionalClampedInteger(
+    input.agentTimeoutMs ?? parseWorkflowIntegerString(env.PI_WORKFLOW_AGENT_TIMEOUT_MS),
+    WORKFLOW_AGENT_TIMEOUT_MIN_MS,
+    WORKFLOW_AGENT_TIMEOUT_MAX_MS,
+  );
+  const agentRetries = clampInteger(
+    input.agentRetries ?? parseWorkflowIntegerString(env.PI_WORKFLOW_AGENT_RETRIES),
+    WORKFLOW_AGENT_RETRIES_MIN,
+    WORKFLOW_AGENT_RETRIES_MAX,
+    DEFAULT_WORKFLOW_AGENT_RETRIES,
+  );
+  const budget = resolveBudget(input.budget, env.PI_WORKFLOW_BUDGET);
+  const usageLimitMaxAttempts = clampInteger(
+    input.usageLimitMaxAttempts ?? parseWorkflowIntegerString(env.PI_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS),
+    WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN,
+    WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
+    DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS,
+  );
+  const usageLimitMaxDelayMs = clampInteger(
+    input.usageLimitMaxDelayMs ?? parseWorkflowIntegerString(env.PI_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS),
+    WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+    WORKFLOW_USAGE_LIMIT_DELAY_MAX_MS,
+    DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS,
+  );
+  return {
+    ...input,
+    perf: input.perf ?? env.PI_WORKFLOW_PERF === "1",
+    concurrency: concurrency ?? null,
+    parallelSubmissionLimit: parallelSubmissionLimit ?? null,
+    maxAgents: maxAgents ?? null,
+    agentTimeoutMs: agentTimeoutMs ?? null,
+    agentRetries,
+    autoResumeOnUsageLimit: input.autoResumeOnUsageLimit ?? env.PI_WORKFLOW_USAGE_LIMIT_AUTO_RESUME === "1",
+    usageLimitMaxAttempts,
+    usageLimitMaxDelayMs,
+    usageLimitAttempt: clampInteger(
+      input.usageLimitAttempt,
+      0,
+      WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
+      0,
+    ),
+    resumeEditedWorkflow: input.resumeEditedWorkflow === true && hasResumeRunId(input.resumeFromRunId),
+    budget: budget ?? null,
+  };
+}
+
+function hasResumeRunId(value: string | undefined): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function optionalClampedInteger(value: number | undefined, min: number, max: number): number | undefined {
+  if (value === undefined || !Number.isFinite(value)) return undefined;
+  return clampInteger(value, min, max, value);
+}
+
+function clampInteger(value: number | undefined, min: number, max: number, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+function parseInteger(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : undefined;
+}
+
+export function parseWorkflowIntegerString(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function resolveBudget(inputBudget: number | undefined, envBudget: string | undefined): number | undefined {
+  if (inputBudget !== undefined) return normalizeExplicitBudget(inputBudget);
+  return envBudget === undefined ? undefined : parseWorkflowBudgetString(envBudget);
+}
+
+function normalizeExplicitBudget(value: number): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < WORKFLOW_BUDGET_MIN || value > WORKFLOW_BUDGET_MAX) {
+    throw new RangeError(`Workflow budget must be an integer between ${WORKFLOW_BUDGET_MIN} and ${WORKFLOW_BUDGET_MAX}.`);
+  }
+  return value;
+}
+
+export function parseWorkflowBudgetString(value: string): number | undefined {
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed) || parsed < WORKFLOW_BUDGET_MIN || parsed > WORKFLOW_BUDGET_MAX) return undefined;
+  return parsed;
+}

package/src/domains/workflows/runtime/perf.ts

@@ -0,0 +1,146 @@
+import { performance } from "node:perf_hooks";
+
+export type PerfTags = Record<string, string | number>;
+
+export interface PerfSample {
+  readonly name: string;
+  readonly durationMs?: number;
+  readonly value?: number;
+  readonly tags?: PerfTags;
+}
+
+export interface PerfAggregate {
+  readonly name: string;
+  readonly count: number;
+  readonly total: number;
+  readonly min: number;
+  readonly max: number;
+  readonly mean: number;
+  readonly p50: number;
+  readonly p95: number;
+}
+
+export interface PerfSnapshot {
+  readonly enabled: boolean;
+  readonly startedAt: number;
+  readonly samples: readonly PerfSample[];
+  readonly aggregates: readonly PerfAggregate[];
+}
+
+export interface PerfSink {
+  time<T>(name: string, fn: () => Promise<T>, tags?: PerfTags): Promise<T>;
+  timeSync<T>(name: string, fn: () => T, tags?: PerfTags): T;
+  observe(name: string, value: number, tags?: PerfTags): void;
+  counter(name: string, delta?: number, tags?: PerfTags): void;
+  snapshot(): PerfSnapshot;
+}
+
+export class PerfRecorder implements PerfSink {
+  private readonly samples: PerfSample[] = [];
+  private readonly startedAt: number;
+
+  constructor(startedAt = Date.now()) {
+    this.startedAt = startedAt;
+  }
+
+  async time<T>(name: string, fn: () => Promise<T>, tags?: PerfTags): Promise<T> {
+    const start = performance.now();
+    try {
+      return await fn();
+    } finally {
+      this.observeDuration(name, performance.now() - start, tags);
+    }
+  }
+
+  timeSync<T>(name: string, fn: () => T, tags?: PerfTags): T {
+    const start = performance.now();
+    try {
+      return fn();
+    } finally {
+      this.observeDuration(name, performance.now() - start, tags);
+    }
+  }
+
+  observe(name: string, value: number, tags?: PerfTags): void {
+    if (!Number.isFinite(value)) return;
+    this.samples.push({ name, value, tags });
+  }
+
+  counter(name: string, delta = 1, tags?: PerfTags): void {
+    this.observe(name, delta, tags);
+  }
+
+  snapshot(): PerfSnapshot {
+    return {
+      enabled: true,
+      startedAt: this.startedAt,
+      samples: this.samples.map((sample) => ({ ...sample, tags: sample.tags ? { ...sample.tags } : undefined })),
+      aggregates: aggregateSamples(this.samples),
+    };
+  }
+
+  private observeDuration(name: string, durationMs: number, tags?: PerfTags): void {
+    if (!Number.isFinite(durationMs)) return;
+    this.samples.push({ name, durationMs, tags });
+  }
+}
+
+export class NoopPerfRecorder implements PerfSink {
+  private readonly startedAt: number;
+
+  constructor(startedAt = Date.now()) {
+    this.startedAt = startedAt;
+  }
+
+  async time<T>(_name: string, fn: () => Promise<T>, _tags?: PerfTags): Promise<T> {
+    return await fn();
+  }
+
+  timeSync<T>(_name: string, fn: () => T, _tags?: PerfTags): T {
+    return fn();
+  }
+
+  observe(_name: string, _value: number, _tags?: PerfTags): void {}
+
+  counter(_name: string, _delta?: number, _tags?: PerfTags): void {}
+
+  snapshot(): PerfSnapshot {
+    return { enabled: false, startedAt: this.startedAt, samples: [], aggregates: [] };
+  }
+}
+
+export function createPerfRecorder(enabled: boolean, startedAt?: number): PerfSink {
+  return enabled ? new PerfRecorder(startedAt) : new NoopPerfRecorder(startedAt);
+}
+
+function aggregateSamples(samples: readonly PerfSample[]): PerfAggregate[] {
+  const byName = new Map<string, number[]>();
+  for (const sample of samples) {
+    const value = sample.durationMs ?? sample.value;
+    if (value === undefined || !Number.isFinite(value)) continue;
+    const values = byName.get(sample.name) ?? [];
+    values.push(value);
+    byName.set(sample.name, values);
+  }
+
+  return [...byName.entries()].map(([name, rawValues]) => {
+    const values = [...rawValues].sort((a, b) => a - b);
+    const total = values.reduce((sum, value) => sum + value, 0);
+    return {
+      name,
+      count: values.length,
+      total,
+      min: values[0] ?? 0,
+      max: values[values.length - 1] ?? 0,
+      mean: values.length === 0 ? 0 : total / values.length,
+      p50: percentile(values, 0.5),
+      p95: percentile(values, 0.95),
+    };
+  });
+}
+
+function percentile(sortedValues: readonly number[], p: number): number {
+  if (sortedValues.length === 0) return 0;
+  const index = Math.min(sortedValues.length - 1, Math.max(0, Math.ceil(sortedValues.length * p) - 1));
+  return sortedValues[index] ?? 0;
+}

package/src/domains/workflows/runtime/pi-compat.ts

@@ -0,0 +1,32 @@
+const MINIMUM_PI_VERSION = "0.80.10";
+
+const MINIMUM_PI_CORE = [0, 80, 10] as const;
+
+/** Fail during extension registration instead of failing later in a workflow. */
+export function assertSupportedPiVersion(version: string): void {
+  const core = parseVersionCore(version);
+  if (!core || compareVersionCore(core, MINIMUM_PI_CORE) < 0) {
+    throw new Error(
+      `The workflow engine requires pi ${MINIMUM_PI_VERSION} or newer; detected ${JSON.stringify(version)}. Update pi before loading this extension.`,
+    );
+  }
+}
+
+function parseVersionCore(version: string): readonly [number, number, number] | undefined {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+  if (!match) return undefined;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  if (![major, minor, patch].every(Number.isSafeInteger)) return undefined;
+  return [major, minor, patch];
+}
+
+function compareVersionCore(
+  left: readonly [number, number, number],
+  right: readonly [number, number, number],
+): number {
+  const [leftMajor, leftMinor, leftPatch] = left;
+  const [rightMajor, rightMinor, rightPatch] = right;
+  return leftMajor - rightMajor || leftMinor - rightMinor || leftPatch - rightPatch;
+}

package/src/domains/workflows/runtime/process-runner.ts

@@ -0,0 +1,260 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export interface BoundedProcessOptions {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly stdin?: string | Uint8Array;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes?: number;
+  readonly killGraceMs?: number;
+  readonly abortError: string;
+  readonly timeoutError: string;
+  readonly maxBufferError?: string;
+  readonly exitError: (stderr: string, code: number | null, signal: NodeJS.Signals | null) => string;
+}
+
+interface BoundedProcessResultBase {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly durationMs: number;
+  readonly bytes: number;
+}
+
+export interface UnconfirmedProcessTermination {
+  readonly status: "unconfirmed";
+  readonly reason: string;
+}
+
+export type BoundedProcessFailure =
+  | { readonly kind: "spawn" | "abort" | "timeout" | "max-buffer"; readonly message: string }
+  | {
+      readonly kind: "exit";
+      readonly message: string;
+      readonly code: number | null;
+      readonly signal: NodeJS.Signals | null;
+    };
+
+export type BoundedProcessResult =
+  | (BoundedProcessResultBase & { readonly ok: true; readonly error?: undefined; readonly failure?: undefined })
+  | (BoundedProcessResultBase & {
+      readonly ok: false;
+      /** Backward-compatible display message. Branch on `failure.kind` for control flow. */
+      readonly error: string;
+      readonly failure: BoundedProcessFailure;
+      /** Present only when the runner's final bound elapsed without observing child closure. */
+      readonly termination?: UnconfirmedProcessTermination;
+    });
+
+export type WindowsTaskkillResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+export interface ProcessRunnerDependencies {
+  readonly platform: NodeJS.Platform;
+  readonly runWindowsTaskkill: (pid: number, complete: (result: WindowsTaskkillResult) => void) => void;
+  readonly killChild: (child: ChildProcess, signal: NodeJS.Signals) => boolean;
+}
+
+const NODE_PROCESS_RUNNER_DEPENDENCIES: ProcessRunnerDependencies = {
+  platform: process.platform,
+  runWindowsTaskkill(pid, complete) {
+    let completed = false;
+    const finish = (result: WindowsTaskkillResult) => {
+      if (completed) return;
+      completed = true;
+      complete(result);
+    };
+    try {
+      const killer = spawn("taskkill.exe", ["/pid", String(pid), "/t", "/f"], {
+        detached: false,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      killer.once("error", (error) => finish({ ok: false, reason: `taskkill failed to start: ${unknownErrorMessage(error)}` }));
+      killer.once("close", (code, signal) => {
+        if (code === 0) {
+          finish({ ok: true });
+          return;
+        }
+        finish({
+          ok: false,
+          reason: `taskkill exited with ${code === null ? `signal ${signal ?? "unknown"}` : `code ${code}`}`,
+        });
+      });
+      killer.unref();
+    } catch (error) {
+      finish({ ok: false, reason: `taskkill could not be started: ${unknownErrorMessage(error)}` });
+    }
+  },
+  killChild: (child, signal) => child.kill(signal),
+};
+
+export async function runBoundedProcess(
+  options: BoundedProcessOptions,
+  dependencies: ProcessRunnerDependencies = NODE_PROCESS_RUNNER_DEPENDENCIES,
+): Promise<BoundedProcessResult> {
+  const start = performance.now();
+  let stdout = "";
+  let stderr = "";
+  let bytes = 0;
+  let pendingFailure: BoundedProcessFailure | undefined;
+  const child = spawn(options.file, [...options.args], {
+    cwd: options.cwd,
+    env: options.env ?? process.env,
+    detached: dependencies.platform !== "win32",
+    stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+  });
+
+  return await new Promise<BoundedProcessResult>((resolve) => {
+    let settled = false;
+    let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    let hardSettleTimer: ReturnType<typeof setTimeout> | undefined;
+    let directChildKillAttempted = false;
+    let windowsTerminationReason = "process close was not observed after taskkill and direct-child fallback";
+    const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      if (hardSettleTimer) clearTimeout(hardSettleTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (failure?: BoundedProcessFailure, termination?: UnconfirmedProcessTermination) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const base = { stdout, stderr, durationMs: performance.now() - start, bytes };
+      if (!failure) {
+        resolve({ ...base, ok: true });
+        return;
+      }
+      resolve({ ...base, ok: false, error: failure.message, failure, ...(termination ? { termination } : {}) });
+    };
+    const killDirectChild = (signal: NodeJS.Signals, reason: string) => {
+      if (directChildKillAttempted) return;
+      directChildKillAttempted = true;
+      windowsTerminationReason = reason;
+      try {
+        if (!dependencies.killChild(child, signal)) {
+          windowsTerminationReason = `${reason}; direct-child termination was not accepted`;
+        }
+      } catch (error) {
+        windowsTerminationReason = `${reason}; direct-child termination failed: ${unknownErrorMessage(error)}`;
+      }
+    };
+    const signalPosixProcess = (signal: NodeJS.Signals) => {
+      let groupSignalled = false;
+      if (child.pid !== undefined) {
+        try {
+          process.kill(-child.pid, signal);
+          groupSignalled = true;
+        } catch {
+          // The process may have exited before its descendants released stdio.
+          // Fall back to the direct child below.
+        }
+      }
+      if (!groupSignalled) {
+        try {
+          dependencies.killChild(child, signal);
+        } catch {
+          // The hard-settlement timer remains authoritative when signalling fails.
+        }
+      }
+    };
+    const destroyStdio = () => {
+      child.stdin?.destroy();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+    };
+    const terminate = (failure: BoundedProcessFailure) => {
+      pendingFailure ??= failure;
+      if (forceKillTimer) return;
+      if (dependencies.platform === "win32") {
+        if (child.pid === undefined) {
+          killDirectChild("SIGKILL", "taskkill was unavailable because the child process had no pid");
+        } else {
+          try {
+            dependencies.runWindowsTaskkill(child.pid, (result) => {
+              if (settled || result.ok) return;
+              killDirectChild("SIGKILL", result.reason);
+            });
+          } catch (error) {
+            killDirectChild("SIGKILL", `taskkill invocation failed: ${unknownErrorMessage(error)}`);
+          }
+        }
+      } else {
+        signalPosixProcess("SIGTERM");
+      }
+      forceKillTimer = setTimeout(() => {
+        if (dependencies.platform === "win32") {
+          if (directChildKillAttempted) {
+            windowsTerminationReason = `${windowsTerminationReason}; child did not close within the termination grace period`;
+          } else {
+            killDirectChild("SIGKILL", "taskkill did not close the child within the termination grace period");
+          }
+        } else {
+          signalPosixProcess("SIGKILL");
+        }
+        destroyStdio();
+        if (!settled) {
+          hardSettleTimer = setTimeout(() => {
+            if (!pendingFailure) return;
+            finish(
+              pendingFailure,
+              { status: "unconfirmed", reason: dependencies.platform === "win32"
+                ? windowsTerminationReason
+                : "process close was not observed after forced process-group termination" },
+            );
+          }, killGraceMs);
+        }
+      }, killGraceMs);
+    };
+    const onAbort = () => terminate({ kind: "abort", message: options.abortError });
+    const timeout = setTimeout(() => terminate({ kind: "timeout", message: options.timeoutError }), options.timeoutMs);
+
+    const captureChunk = (chunk: Buffer, append: (text: string) => void) => {
+      if (pendingFailure) return;
+      bytes += chunk.length;
+      if (options.maxBufferBytes !== undefined && bytes > options.maxBufferBytes) {
+        terminate({
+          kind: "max-buffer",
+          message: options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`,
+        });
+        return;
+      }
+      append(chunk.toString("utf8"));
+    };
+    child.stdout?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stdout += text)));
+    child.stderr?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stderr += text)));
+    child.on("error", (spawnError) => {
+      if (!pendingFailure) finish({ kind: "spawn", message: spawnError.message });
+    });
+    child.on("close", (code, signal) => {
+      if (pendingFailure) {
+        finish(pendingFailure);
+        return;
+      }
+      if (code === 0) {
+        finish();
+        return;
+      }
+      const message = options.exitError(stderr, code, signal);
+      finish({ kind: "exit", message, code, signal });
+    });
+    if (options.signal?.aborted) {
+      onAbort();
+    } else {
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+    }
+    if (options.stdin !== undefined) {
+      // The child may reject input and exit before consuming it. Its process exit
+      // remains the authoritative result; avoid surfacing a secondary EPIPE.
+      child.stdin?.on("error", () => undefined);
+      child.stdin?.end(options.stdin);
+    }
+  });
+}

package/src/domains/workflows/runtime/progress-types.ts

@@ -0,0 +1,59 @@
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+
+export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+export type AgentChatRole = "task" | "user" | "assistant" | "tool" | "status";
+export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
+
+export interface AgentChatMessage {
+  readonly role: AgentChatRole;
+  readonly text: string;
+  readonly createdAt: number;
+}
+
+export interface AgentRowSnapshot {
+  readonly id: number;
+  readonly label: string;
+  /** provider/id of the model actually routed to this agent. */
+  readonly model?: string;
+  readonly status: AgentRowStatus;
+  readonly startedAt?: number;
+  readonly doneAt?: number;
+  readonly toolUses: number;
+  readonly lastTool?: string;
+  readonly error?: string;
+}
+
+export interface PhaseSnapshot {
+  readonly title: string;
+  readonly agents: readonly AgentRowSnapshot[];
+}
+
+export interface WorkflowCounterSnapshot {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+}
+
+export interface WorkflowLaneItemSnapshot {
+  readonly lane: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly status: WorkflowLaneItemStatus;
+  readonly details?: string;
+  readonly createdAt: number;
+}
+
+export interface WorkflowProgressSnapshot {
+  readonly runId: string;
+  readonly title: string;
+  readonly startedAt: number;
+  readonly doneAt?: number;
+  readonly currentPhase: string;
+  readonly phases: readonly PhaseSnapshot[];
+  readonly counters: readonly WorkflowCounterSnapshot[];
+  readonly summary: readonly [string, string | number][];
+  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
+  readonly laneOverflow: readonly [string, number][];
+  readonly logs: readonly string[];
+  readonly usage?: WorkflowUsageSnapshot;
+}