@jameslovespancakes/pi-plus 1.0.11 → 1.0.13

package/src/domains/workflows/runtime/tree-fingerprint.ts

@@ -0,0 +1,404 @@
+import { createHash } from "node:crypto";
+import { constants, type BigIntStats } from "node:fs";
+import { lstat, open, readdir, type FileHandle } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { throwIfAborted } from "./cancellation.ts";
+import { isMissingPathError } from "./filesystem-error.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export type FingerprintCapture =
+  | { readonly kind: "verified"; readonly fingerprint: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export type TreeFileValidation =
+  | { readonly kind: "verified" }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface TreeFingerprintOptions {
+  readonly root: string;
+  /** Root-relative directory paths to exclude, never bare names at every depth. */
+  readonly excludedRelativePaths?: ReadonlySet<string>;
+  readonly maxBytes: number;
+  readonly maxFiles: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface TreeFileValidationOptions {
+  readonly root: string;
+  readonly path: string;
+  readonly excludedRelativePaths?: ReadonlySet<string>;
+  readonly signal?: AbortSignal;
+}
+
+export interface DeclaredInputFingerprintOptions {
+  readonly root: string;
+  /** Explicit paths relative to `root`. Files and directories are both supported. */
+  readonly inputs: readonly string[];
+  /** Paths with these segment sequences are never valid declared inputs. */
+  readonly excludedRelativePaths?: ReadonlySet<string>;
+  readonly maxBytes: number;
+  readonly maxEntries: number;
+  /** Record direct directory identity without recursively walking descendants. */
+  readonly shallowDirectories?: boolean;
+  readonly signal?: AbortSignal;
+}
+
+export type DeclaredInputPathResolution =
+  | { readonly kind: "verified"; readonly paths: readonly string[] }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface FingerprintFileOperations {
+  readonly open: (path: string, flags: number) => Promise<FileHandle>;
+  readonly lstat: (path: string) => Promise<BigIntStats>;
+}
+
+const NODE_FINGERPRINT_FILE_OPERATIONS: FingerprintFileOperations = {
+  open: async (path, flags) => await open(path, flags),
+  lstat: async (path) => await lstat(path, { bigint: true }),
+};
+
+/** A deterministic hash sink that enforces one shared byte budget across file reads. */
+export class BoundedFingerprint {
+  readonly #hash = createHash("sha256");
+  readonly #maxBytes: number;
+  #bytes = 0;
+
+  constructor(maxBytes: number) {
+    this.#maxBytes = maxBytes;
+  }
+
+  add(label: string, value: string | Buffer): void {
+    this.#hash.update(label);
+    this.#hash.update("\0");
+    this.#hash.update(value);
+    this.#hash.update("\0");
+  }
+
+  async addFileHandle(label: string, handle: FileHandle, signal?: AbortSignal): Promise<void> {
+    this.#hash.update(label);
+    this.#hash.update("\0");
+    const stream = handle.createReadStream({ autoClose: false, highWaterMark: 64 << 10, signal });
+    try {
+      for await (const chunk of stream) {
+        throwIfAborted(signal);
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        this.#bytes += buffer.length;
+        if (this.#bytes > this.#maxBytes) {
+          stream.destroy();
+          throw new Error(`content fingerprint exceeded ${this.#maxBytes} bytes`);
+        }
+        this.#hash.update(buffer);
+      }
+    } catch (error) {
+      throwIfAborted(signal);
+      throw error;
+    }
+    this.#hash.update("\0");
+  }
+
+  digest(): string {
+    return this.#hash.digest("hex");
+  }
+}
+
+/** Open, validate, and use one regular file without reopening its pathname. */
+export async function withValidatedFingerprintFile<T>(
+  path: string,
+  signal: AbortSignal | undefined,
+  use: (handle: FileHandle, info: BigIntStats) => Promise<T>,
+  operations: FingerprintFileOperations = NODE_FINGERPRINT_FILE_OPERATIONS,
+): Promise<T> {
+  throwIfAborted(signal);
+  const flags = process.platform === "win32"
+    ? constants.O_RDONLY
+    : constants.O_RDONLY | constants.O_NOFOLLOW;
+  const handle = await operations.open(path, flags);
+  try {
+    const [openedInfo, pathInfo] = await Promise.all([
+      handle.stat({ bigint: true }),
+      operations.lstat(path),
+    ]);
+    throwIfAborted(signal);
+    if (!openedInfo.isFile()) throw new Error(`content fingerprint opened an unsupported entry: ${path}`);
+    if (pathInfo.isSymbolicLink()) throw new Error(`content fingerprint encountered a symbolic link: ${path}`);
+    if (!pathInfo.isFile()) throw new Error(`content fingerprint encountered an unsupported entry: ${path}`);
+    if (openedInfo.dev !== pathInfo.dev || openedInfo.ino !== pathInfo.ino) {
+      throw new Error(`content fingerprint path changed while it was being opened: ${path}`);
+    }
+    return await use(handle, openedInfo);
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Fingerprint a bounded directory tree with stable path ordering and entry handling. */
+export async function captureTreeFingerprint(options: TreeFingerprintOptions): Promise<FingerprintCapture> {
+  try {
+    throwIfAborted(options.signal);
+    const root = resolve(options.root);
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory()) throw new Error(`fingerprint root is not a directory: ${root}`);
+
+    const fingerprint = new BoundedFingerprint(options.maxBytes);
+    const directories = [root];
+    let fileCount = 0;
+
+    for (let index = 0; index < directories.length; index++) {
+      throwIfAborted(options.signal);
+      const directory = directories[index]!;
+      const entries = await readdir(directory, { withFileTypes: true });
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+
+      for (const entry of entries) {
+        throwIfAborted(options.signal);
+        const path = join(directory, entry.name);
+        const relativePath = relative(root, path);
+        if (entry.isDirectory()) {
+          if (!isExcludedRelativePath(relativePath, options.excludedRelativePaths)) directories.push(path);
+          continue;
+        }
+
+        fileCount += 1;
+        if (fileCount > options.maxFiles) throw new Error(`content fingerprint exceeded ${options.maxFiles} files`);
+        fingerprint.add("path", relativePath);
+
+        if (entry.isSymbolicLink()) {
+          throw new Error(`content fingerprint encountered a symbolic link: ${path}`);
+        }
+        if (!entry.isFile()) throw new Error(`content fingerprint encountered an unsupported entry: ${path}`);
+
+        await withValidatedFingerprintFile(path, options.signal, async (handle, info) => {
+          fingerprint.add("mode", String(info.mode));
+          await fingerprint.addFileHandle("file", handle, options.signal);
+        });
+      }
+    }
+
+    return { kind: "verified", fingerprint: fingerprint.digest() };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+/** Fingerprint only explicitly declared files/directories under one shared bound. */
+export async function captureDeclaredInputFingerprint(
+  options: DeclaredInputFingerprintOptions,
+): Promise<FingerprintCapture> {
+  try {
+    throwIfAborted(options.signal);
+
+    const root = resolve(options.root);
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory()) throw new Error(`declared-input root is not a directory: ${root}`);
+
+    const resolvedInputs = resolveDeclaredInputPaths(root, options.inputs, options.excludedRelativePaths);
+    if (resolvedInputs.kind === "unverifiable") return resolvedInputs;
+    const inputs = resolvedInputs.paths;
+    const fingerprint = new BoundedFingerprint(options.maxBytes);
+    let entryCount = 0;
+
+    const recordEntry = (relativePath: string, kind: "directory" | "file" | "missing", mode?: number): void => {
+      entryCount += 1;
+      if (entryCount > options.maxEntries) {
+        throw new Error(`declared-input fingerprint exceeded ${options.maxEntries} entries`);
+      }
+      fingerprint.add("path", relativePath);
+      fingerprint.add("kind", kind);
+      if (mode !== undefined) fingerprint.add("mode", String(mode));
+    };
+
+    const visit = async (path: string, relativePath: string, directInput = false): Promise<boolean> => {
+      throwIfAborted(options.signal);
+
+      let info;
+      try {
+        info = await lstat(path);
+      } catch (error) {
+        if (!isMissingPathError(error)) throw error;
+        recordEntry(relativePath, "missing");
+        return true;
+      }
+
+      if (info.isSymbolicLink()) throw new Error(`declared input contains a symbolic link: ${relativePath}`);
+      if (info.isFile()) {
+        await withValidatedFingerprintFile(path, options.signal, async (handle, openedInfo) => {
+          recordEntry(relativePath, "file", Number(openedInfo.mode));
+          await fingerprint.addFileHandle("file", handle, options.signal);
+        });
+        return true;
+      }
+      if (!info.isDirectory()) throw new Error(`declared input contains an unsupported entry: ${relativePath}`);
+
+      if (options.shallowDirectories === true) {
+        recordEntry(relativePath, "directory", info.mode);
+        return true;
+      }
+
+      const entries = await readdir(path, { withFileTypes: true });
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+      let hasObservableChild = false;
+      for (const entry of entries) {
+        const childPath = join(path, entry.name);
+        const childRelativePath = relativePath === "." ? entry.name : `${relativePath}/${entry.name}`;
+        if (isExcludedDeclaredInput(childRelativePath, options.excludedRelativePaths)) continue;
+        hasObservableChild = (await visit(childPath, childRelativePath)) || hasObservableChild;
+      }
+      const observableEmptyDirectory = entries.length === 0 && !isExcludedAncestor(relativePath, options.excludedRelativePaths);
+      if (!directInput && !hasObservableChild && !observableEmptyDirectory) return false;
+      recordEntry(relativePath, "directory", info.mode);
+      return true;
+    };
+
+    for (const relativePath of inputs) {
+      throwIfAborted(options.signal);
+      fingerprint.add("input", relativePath);
+      const segments = relativePath === "." ? [] : relativePath.split("/");
+      let path = root;
+      let missing = false;
+      for (let index = 0; index < Math.max(0, segments.length - 1); index++) {
+        path = join(path, segments[index]!);
+        let info;
+        try {
+          info = await lstat(path);
+        } catch (error) {
+          if (!isMissingPathError(error)) throw error;
+          recordEntry(relativePath, "missing");
+          missing = true;
+          break;
+        }
+        if (info.isSymbolicLink()) throw new Error(`declared input traverses a symbolic link: ${relativePath}`);
+        if (!info.isDirectory()) {
+          recordEntry(relativePath, "missing");
+          missing = true;
+          break;
+        }
+      }
+      if (!missing) await visit(relativePath === "." ? root : join(root, ...segments), relativePath, true);
+    }
+
+    return { kind: "verified", fingerprint: fingerprint.digest() };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+/** Validate and canonicalize caller-authored paths before passing them to Git or the filesystem. */
+export function resolveDeclaredInputPaths(
+  root: string,
+  inputs: readonly string[],
+  excludedRelativePaths?: ReadonlySet<string>,
+  base = root,
+): DeclaredInputPathResolution {
+  try {
+    if (!Array.isArray(inputs)) throw new Error("declared inputs must be an array");
+    const paths = [...new Set(inputs.map((input) => declaredInputPath(root, base, input)))].sort();
+    for (const path of paths) rejectExcludedDeclaredInput(path, excludedRelativePaths);
+    return { kind: "verified", paths };
+  } catch (error) {
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+/** Verify that a regular file is reached only through directories included in the tree hash. */
+export async function validateTreeFile(options: TreeFileValidationOptions): Promise<TreeFileValidation> {
+  try {
+    throwIfAborted(options.signal);
+    const root = resolve(options.root);
+    const path = resolve(options.path);
+    if (!isPathWithin(root, path)) return { kind: "unverifiable", reason: "file is outside its fingerprint root" };
+
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory()) throw new Error(`fingerprint root is not a directory: ${root}`);
+    const pathFromRoot = relative(root, path);
+    if (pathFromRoot === "") return { kind: "unverifiable", reason: "fingerprint source resolves to its root directory" };
+
+    const segments = pathFromRoot.split(/[\\/]/).filter(Boolean);
+    let current = root;
+    for (let index = 0; index < segments.length; index++) {
+      throwIfAborted(options.signal);
+      const segment = segments[index]!;
+      const isFile = index === segments.length - 1;
+      if (!isFile && isExcludedRelativePath(relative(root, join(current, segment)), options.excludedRelativePaths)) {
+        return { kind: "unverifiable", reason: "file is inside an excluded fingerprint directory" };
+      }
+      current = join(current, segment);
+      const info = await lstat(current);
+      if (isFile ? !info.isFile() : !info.isDirectory()) {
+        return {
+          kind: "unverifiable",
+          reason: isFile ? "fingerprint source is not a regular file" : "fingerprint source path traverses a non-directory entry",
+        };
+      }
+    }
+    return { kind: "verified" };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+export function isPathWithin(root: string, path: string): boolean {
+  const pathFromRoot = relative(resolve(root), resolve(path));
+  return pathFromRoot === "" || (!isAbsolute(pathFromRoot) && pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`));
+}
+
+function isExcludedRelativePath(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+  if (!excluded || excluded.size === 0) return false;
+  const normalized = normalizeRelativePath(path);
+  for (const candidate of excluded) {
+    const normalizedCandidate = normalizeRelativePath(candidate);
+    if (normalized === normalizedCandidate || normalized.startsWith(`${normalizedCandidate}/`)) return true;
+  }
+  return false;
+}
+
+function normalizeRelativePath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+
+function declaredInputPath(root: string, base: string, input: string): string {
+  if (typeof input !== "string" || input.length === 0) throw new Error("declared input paths must be non-empty strings");
+  if (isAbsolute(input)) throw new Error(`declared input must be relative to the workflow cwd: ${input}`);
+  const path = resolve(base, input);
+  if (!isPathWithin(root, path)) throw new Error(`declared input escapes the repository root: ${input}`);
+  if (!isPathWithin(base, path)) throw new Error(`declared input escapes the workflow cwd: ${input}`);
+  const relativePath = relative(root, path).split(sep).join("/");
+  return relativePath.length === 0 ? "." : relativePath;
+}
+
+function rejectExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): void {
+  if (!isExcludedDeclaredInput(path, excluded)) return;
+  throw new Error(`declared input enters excluded path: ${path}`);
+}
+
+function isExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+  if (!excluded) return false;
+  const normalized = normalizeRelativePath(path);
+  for (const candidate of excluded) {
+    const normalizedCandidate = normalizeRelativePath(candidate);
+    if (
+      normalized === normalizedCandidate ||
+      normalized.startsWith(`${normalizedCandidate}/`) ||
+      normalized.endsWith(`/${normalizedCandidate}`) ||
+      normalized.includes(`/${normalizedCandidate}/`)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isExcludedAncestor(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+  if (!excluded) return false;
+  const segments = normalizeRelativePath(path).split("/").filter((segment) => segment !== ".");
+  for (const candidate of excluded) {
+    const normalizedCandidate = normalizeRelativePath(candidate);
+    for (let index = 0; index < segments.length; index++) {
+      const suffix = segments.slice(index).join("/");
+      if (normalizedCandidate.startsWith(`${suffix}/`)) return true;
+    }
+  }
+  return false;
+}

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

@@ -0,0 +1,255 @@
+import type { Static, TSchema } from "typebox";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { WorkflowBudget } from "./budget.ts";
+import type { Pipeline, WorkflowParallel } from "./concurrency.ts";
+import type { PerfSink, PerfSnapshot } from "./perf.ts";
+import type { AgentChatMessage, WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progress-types.ts";
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
+import type { WorkflowModelProfileName } from "./model-profiles.ts";
+
+export type { WorkflowLaneItemStatus } from "./progress-types.ts";
+
+/** A reference to a registered workflow by name. */
+export type WorkflowRef = string;
+
+/** Metadata every workflow module must export. */
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  phases?: Array<{ title: string }>;
+}
+
+export interface WorkflowRunStats {
+  files: number;
+  candidates: number;
+  verified: number;
+  kept: number;
+  [key: string]: string | number;
+}
+
+export interface WorkflowRunMetadata {
+  readonly runId: string;
+  readonly resumedFromRunId?: string;
+  readonly journalPath: string;
+  readonly recordPath: string;
+}
+
+export interface WorkflowBackgroundOrigin {
+  /** Stable pi session id used to route and deduplicate completion delivery. */
+  readonly sessionId: string;
+  readonly requestedAt: number;
+}
+
+export interface WorkflowRunOptions {
+  inspect?: boolean;
+  perf?: boolean;
+  concurrency?: number;
+  parallelSubmissionLimit?: number;
+  /** Maximum number of agent calls that may reach a live model session during this run. */
+  maxAgents?: number;
+  /** Maximum live duration of one agent call in milliseconds. */
+  agentTimeoutMs?: number;
+  /** Retry count for transient provider/session failures. Defaults to zero. */
+  agentRetries?: number;
+  /** Explicitly schedule resumable background runs after recognized provider usage windows. */
+  autoResumeOnUsageLimit?: boolean;
+  /** Maximum recognized usage-limit pauses before automatic scheduling stops. */
+  usageLimitMaxAttempts?: number;
+  /** Maximum delay accepted from a provider reset hint. */
+  usageLimitMaxDelayMs?: number;
+  /** Internal count carried into a scheduler-created successor run. */
+  usageLimitAttempt?: number;
+  /** Output-token ceiling across recorded subagent attempts. Omit for no limit (budget.total === null). */
+  budget?: number;
+  /** Internal/test override for the generated run id. Omit to generate a new id. */
+  runId?: string;
+  /** Internal origin metadata for an explicitly backgrounded tool invocation. */
+  background?: WorkflowBackgroundOrigin;
+  /** Replay completed agent results from this prior run id when call and execution context still match. */
+  resumeFromRunId?: string;
+  /** Explicitly allow resume to ignore only a workflow-source fingerprint mismatch. */
+  resumeEditedWorkflow?: boolean;
+  resultViewer?: "open" | "skip";
+  /** Additional abort signal to compose with the host context signal. */
+  signal?: AbortSignal;
+  /** Internal recorder override for command/tool invocation timing. */
+  perfRecorder?: PerfSink;
+  /** Resolve a sub-workflow reference to a module, enabling `api.workflow()`. When omitted, `api.workflow()` throws. */
+  resolveWorkflow?: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
+  /** Called with the final performance snapshot when perf is enabled. */
+  onPerfSnapshot?: (snapshot: PerfSnapshot) => void | Promise<void>;
+  /** Called with the final workflow subagent usage snapshot. */
+  onUsageSnapshot?: (snapshot: WorkflowUsageSnapshot) => void | Promise<void>;
+  /** Called once run identity and journal paths are known. */
+  onRunMetadata?: (metadata: WorkflowRunMetadata) => void | Promise<void>;
+  /** Called with the live progress source while a workflow is running, then undefined when it ends. */
+  onProgressSource?: (source: WorkflowProgressSource | undefined) => void | Promise<void>;
+  /** Called with the final completed progress snapshot after live workflow UI teardown. */
+  onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void | Promise<void>;
+}
+
+export interface WorkflowProgressSource {
+  snapshot(): WorkflowProgressSnapshot;
+  conversation(agentId: number): readonly AgentChatMessage[];
+  followUp(agentId: number, message: string): Promise<void>;
+  subscribe(listener: () => void): () => void;
+}
+
+/** Options for a single `agent()` call. */
+export type AgentToolHint = "search" | "external-search";
+export type AgentResumePolicy = "read-only" | "off";
+
+export interface IsolatedAgentResult<T> {
+  readonly baselineOid?: string;
+  readonly result: T;
+  readonly patch: string;
+  readonly changed: boolean;
+}
+
+export type WorkflowProgressEvent =
+  | { type: "counter"; key: string; label: string; value: number }
+  | { type: "counter_delta"; key: string; label: string; delta: number }
+  | {
+      type: "lane_item";
+      lane: string;
+      title: string;
+      subtitle?: string;
+      status: WorkflowLaneItemStatus;
+      details?: string;
+    }
+  | { type: "summary"; key: string; value: string | number };
+
+export interface AgentOptions<S extends TSchema = TSchema> {
+  /** Label shown in the progress tree (e.g. "find:logic-bugs"). */
+  label?: string;
+  /** Phase to group this agent under in the progress tree. */
+  phase?: string;
+  /**
+   * Optional model id. Overrides profile routing; when both model and profile are
+   * omitted, inherit the host model. Explicit refs are strict: bare ids resolve as
+   * Anthropic shorthand; use "provider/id" for other providers.
+   */
+  model?: string;
+  /** Reasoning effort for this agent. Overrides the profile's configured effort. */
+  thinkingLevel?: ThinkingLevel;
+  /** Exact configured model route to use when model/thinkingLevel do not override it. */
+  profile?: WorkflowModelProfileName;
+  /**
+   * Stable identity hint for resume replay. Use this for repeated logical calls
+   * with identical prompts/options, e.g. `${stage}:${item.id}`.
+   */
+  cacheKey?: string;
+  /**
+   * Resume policy for this call. Shared-workspace agents run live unless they
+   * explicitly declare themselves read-only. Those calls bind replay to the full
+   * Git-visible workspace; isolated agents bind to their isolated baseline.
+   * Use "off" to disable both journal reads and writes.
+   */
+  resume?: AgentResumePolicy;
+  /**
+   * Additional ignored/generated inputs under the workflow cwd that this
+   * read-only agent may observe. Git-visible files across the repository are
+   * captured automatically; list cwd-relative ignored paths here or use
+   * `resume: "off"` when their bounded contents cannot be captured.
+   */
+  resumeInputs?: readonly string[];
+  /** Run in an isolated git worktree. Successful runs clean it up; failed runs retain it for recovery. */
+  isolation?: "worktree";
+  /** Apply a captured candidate to a fresh isolated baseline before evaluation. */
+  candidatePatch?: { readonly baselineOid: string; readonly patch: string };
+  /** Allowlist of concrete tool names the agent may use (e.g. ["read", "bash"]). */
+  tools?: string[];
+  /**
+   * Dynamically include installed tools matching semantic categories. "search"
+   * matches local grep/find/code-search tools; "external-search" matches installed
+   * web search, browsing, and URL extraction tools.
+   */
+  toolHints?: readonly AgentToolHint[];
+  /** Fail before prompting unless every semantic tool hint matched an installed tool. */
+  requireToolHints?: boolean;
+  /**
+   * Skill names to expose to this subagent. Subagents receive no skills by default.
+   * When omitted, clear prompt text such as `/skill:name`, `include skill name`, or
+   * `use the name skill` is treated as a natural-language opt-in. Pass [] to suppress
+   * prompt inference for prompts that mention skills only as subject matter.
+   */
+  skills?: readonly string[];
+  /**
+   * typebox schema. The agent must call the validated `final_answer` tool; bounded
+   * repair exhaustion throws `WorkflowStructuredOutputError` instead of returning null.
+   */
+  schema?: S;
+}
+
+/**
+ * The primitives injected into every workflow run. A workflow is any module that
+ * exports `meta` plus a default `async (api: WorkflowApi) => result`.
+ */
+export interface WorkflowApi {
+  /** Run a schema subagent in an isolated worktree and return its structured result plus patch. */
+  agent<S extends TSchema>(
+    prompt: string,
+    opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
+  ): Promise<IsolatedAgentResult<Static<S>>>;
+  /** Run a text subagent in an isolated worktree and return its final text plus patch. */
+  agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
+  /** Run a subagent and return validated structured output; rejects with a recoverable typed error on repair exhaustion. */
+  agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S>>;
+  /** Run a subagent and return its final assistant text. */
+  agent(prompt: string, opts?: AgentOptions): Promise<string>;
+  /**
+   * Run another registered workflow inline as a sub-step and return its result. The child shares
+   * this run's concurrency cap, abort signal, and perf sink. Nests one level only: calling
+   * `workflow()` from within a sub-workflow rejects. Rejects on unknown name — catch it to handle
+   * a missing sub-workflow gracefully.
+   */
+  workflow(ref: WorkflowRef, args?: string): Promise<unknown>;
+  /**
+   * Run every thunk concurrently and wait for all (a barrier). Recoverable thunk
+   * failures become null slots by default; settled mode retains serialisable errors.
+   */
+  parallel: WorkflowParallel;
+  /**
+   * Run each item through all stages independently — no barrier between stages.
+   * A recoverable stage failure drops that item to null and skips its later stages.
+   */
+  pipeline: Pipeline;
+  /** Start a new phase; subsequent agents group under it in the progress tree. */
+  phase(title: string): void;
+  /** Emit a progress line. */
+  log(message: string): void;
+  /** Emit a structured progress event for native workflow UI surfaces. */
+  progress(event: WorkflowProgressEvent): void;
+  /** Raw argument string passed after the workflow name. */
+  args: string;
+  /** Working directory of the host session (typically the repo root). */
+  cwd: string;
+  /**
+   * Token budget for the run. `budget.total` is the output-token ceiling (null when unset),
+   * `spent()`/`remaining()` are live. Guard loops with `while (budget.total && budget.remaining() > N)`;
+   * `agent()` throws `WorkflowBudgetExceededError` once the ceiling is reached.
+   */
+  budget: WorkflowBudget;
+  /** Abort signal for the run, propagated from the host. */
+  signal: AbortSignal | undefined;
+}
+
+export type WorkflowRun = (api: WorkflowApi) => Promise<unknown>;
+
+export type WorkflowSourceIdentity =
+  | { readonly kind: "file"; readonly path: string; readonly root: string; readonly fingerprint: string }
+  | { readonly kind: "fingerprint"; readonly fingerprint: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+/** The authored exports of a workflow module. */
+export interface WorkflowModule {
+  meta: WorkflowMeta;
+  default: WorkflowRun;
+}
+
+/** A validated workflow plus engine-owned provenance used for safe resume replay. */
+export interface LoadedWorkflow extends WorkflowModule {
+  readonly source: WorkflowSourceIdentity;
+  readonly isolatedWorktreeBaseline?: WorktreeBaseline;
+}

package/src/domains/workflows/runtime/ui/display-text.ts

@@ -0,0 +1,28 @@
+const ANSI_PATTERN = /\u001B\[[0-9;?]*[ -/]*[@-~]/g;
+const CONTROL_PATTERN = /[\u0000-\u001F\u007F]/g;
+const MULTILINE_CONTROL_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+
+/** Flattens arbitrary text into one stable, printable row. */
+export function toDisplayLine(text: string, maxLength = 120): string {
+  const flat = text
+    .replace(ANSI_PATTERN, "")
+    .replace(CONTROL_PATTERN, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (maxLength <= 0 || flat.length <= maxLength) return flat;
+  return `${flat.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
+}
+
+/** Sanitizes chat content while preserving the line breaks and Markdown shown by Pi. */
+export function toDisplayText(text: string, maxLength = 2_000): string {
+  const value = text
+    .replace(ANSI_PATTERN, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(MULTILINE_CONTROL_PATTERN, " ")
+    .split("\n")
+    .map((line) => line.replace(/\t/g, "  ").trimEnd())
+    .join("\n")
+    .trim();
+  if (maxLength <= 0 || value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
+}