pi-workflow-engine 0.11.0 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/review/review-session-coordinator.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { dynamaxSessionKey } from "../dynamax.ts";
+import { sessionKey } from "../session-identity.ts";
 import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "../options.ts";
 import type { LoadedWorkflow } from "../types.ts";
 import type { WorkflowExecution } from "../workflow-execution.ts";
@@ -42,7 +42,7 @@ export class ReviewSessionCoordinator {
   ): void {
     const name = execution.envelope.name;
     if (name !== "code-review") return;
-    const key = dynamaxSessionKey(ctx);
+    const key = sessionKey(ctx);
     const report = codeReviewReport(name, execution.envelope.result);
     if (!report) {
       this.sessions.delete(key);
@@ -72,7 +72,7 @@ export class ReviewSessionCoordinator {
     });
     if (decision.kind !== "open") return;
 
-    const retained = this.sessions.get(dynamaxSessionKey(ctx));
+    const retained = this.sessions.get(sessionKey(ctx));
     if (!retained) return;
     await this.openAndHandle(ctx, retained, decision.issues);
   }
@@ -82,7 +82,7 @@ export class ReviewSessionCoordinator {
       ctx.ui.notify("Code-review results viewer requires the TUI", "warning");
       return;
     }
-    const retained = this.sessions.get(dynamaxSessionKey(ctx));
+    const retained = this.sessions.get(sessionKey(ctx));
     if (!retained) {
       ctx.ui.notify("No code-review result is available yet. Run /workflow code-review first.", "warning");
       return;
@@ -96,7 +96,7 @@ export class ReviewSessionCoordinator {
   }
 
   dispose(ctx: ExtensionContext): void {
-    this.sessions.delete(dynamaxSessionKey(ctx));
+    this.sessions.delete(sessionKey(ctx));
   }
 
   private async openAndHandle(

package/.pi/extensions/pi-workflow-engine/src/review/review-snapshot.ts

@@ -1,13 +1,12 @@
 import { createHash } from "node:crypto";
 import { throwIfAborted } from "../cancellation.ts";
+import { captureDiffTarget, type DiffCaptureFailure } from "../diff-capture.ts";
 import {
-  captureDiffTarget,
-  type DiffCaptureFailure,
+  reviewGitDiffBaseline,
   type GitReviewDiffTarget,
   type PullRequestReviewDiffTarget,
   type ReviewDiffTarget,
-  reviewGitDiffBaseline,
-} from "../diff-capture.ts";
+} from "../review-diff-target.ts";
 import { runBoundedProcess } from "../process-runner.ts";
 import { unknownErrorMessage } from "../unknown-error.ts";
 import type { WorktreeBaseline } from "../worktree.ts";

package/.pi/extensions/pi-workflow-engine/src/review-diff-target.ts

@@ -0,0 +1,130 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+export type GitDiffBaselineTarget =
+  | { readonly kind: "working-tree" }
+  | { readonly kind: "index" }
+  | { readonly kind: "range"; readonly ref: string };
+
+export const GitReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("git"),
+  args: Type.Array(Type.String()),
+});
+
+export const PullRequestReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("pull-request"),
+  number: Type.Integer({ minimum: 1 }),
+});
+
+export const ReviewDiffTargetSchema = Type.Union([GitReviewDiffTargetSchema, PullRequestReviewDiffTargetSchema]);
+
+export type GitReviewDiffTarget = Static<typeof GitReviewDiffTargetSchema>;
+export type PullRequestReviewDiffTarget = Static<typeof PullRequestReviewDiffTargetSchema>;
+
+/** Serializable semantic identity of the diff being reviewed. */
+export type ReviewDiffTarget = Static<typeof ReviewDiffTargetSchema>;
+
+const SAFE_REF_OR_PATH = /^[A-Za-z0-9_./:@~+=,\-]+$/;
+const SAFE_GH_DIFF_FLAGS = new Set(["--color=never"]);
+const SAFE_GIT_DIFF_FLAGS = new Set(["--binary", "--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
+
+export function parseAllowedDiffCommand(command: string): ReviewDiffTarget | { error: string } {
+  const tokens = command.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length < 2) return { error: "empty or incomplete diff command" };
+  if (tokens[0] === "git" && tokens[1] === "diff") {
+    const parsed = parseGitDiff(tokens);
+    return "error" in parsed ? parsed : parsed.target;
+  }
+  if (tokens[0] === "gh" && tokens[1] === "pr" && tokens[2] === "diff" && /^\d+$/.test(tokens[3] ?? "")) {
+    const number = Number(tokens[3]);
+    if (!Number.isSafeInteger(number) || number <= 0) return { error: "pull-request number must be a positive safe integer" };
+    const flags = tokens.slice(4);
+    if (flags.includes("--patch")) return { error: "gh pr diff --patch is not supported because reviews require the cumulative pull-request diff" };
+    const unsupported = flags.find((token) => !SAFE_GH_DIFF_FLAGS.has(token));
+    if (unsupported) return { error: `unsupported gh pr diff option: ${unsupported}` };
+    return { kind: "pull-request", number };
+  }
+  return { error: "diff command is not in the git/gh allowlist" };
+}
+
+function parseGitDiff(
+  tokens: readonly string[],
+): { readonly target: GitReviewDiffTarget; readonly baseline: GitDiffBaselineTarget } | { readonly error: string } {
+  const args = tokens.slice(2);
+  const safeArgs = ["diff", "--no-ext-diff"];
+  const operands: string[] = [];
+  let staged = false;
+  let pathMode = false;
+
+  for (const token of args) {
+    if (!SAFE_REF_OR_PATH.test(token)) return { error: `unsupported git diff token: ${token}` };
+    if (token === "--") {
+      pathMode = true;
+      safeArgs.push(token);
+      continue;
+    }
+    if (!pathMode && token.startsWith("-")) {
+      if (!isAllowedGitDiffFlag(token)) return { error: `unsupported git diff option: ${token}` };
+      staged ||= token === "--cached" || token === "--staged";
+      if (token !== "--no-ext-diff") safeArgs.push(token);
+      continue;
+    }
+    if (!pathMode) operands.push(token);
+    safeArgs.push(token);
+  }
+
+  const baseline = classifyGitDiffBaseline(staged, operands);
+  return "error" in baseline ? baseline : { target: { kind: "git", args: safeArgs }, baseline };
+}
+
+function classifyGitDiffBaseline(staged: boolean, operands: readonly string[]): GitDiffBaselineTarget | { readonly error: string } {
+  if (operands.length > 1) {
+    return { error: "ambiguous git diff operands; use A..B or A...B for revisions, or -- before multiple paths" };
+  }
+  if (staged) return { kind: "index" };
+
+  const range = operands.find((operand) => operand.includes(".."));
+  if (range) {
+    const separator = range.includes("...") ? "..." : "..";
+    return { kind: "range", ref: range.slice(range.indexOf(separator) + separator.length) || "HEAD" };
+  }
+
+  return { kind: "working-tree" };
+}
+
+function isAllowedGitDiffFlag(token: string): boolean {
+  return SAFE_GIT_DIFF_FLAGS.has(token) || /^-U\d+$/.test(token) || /^--unified=\d+$/.test(token) || /^--inter-hunk-context=\d+$/.test(token);
+}
+
+export function reviewDiffCommand(target: ReviewDiffTarget): { readonly file: "git" | "gh"; readonly args: readonly string[] } {
+  return target.kind === "pull-request"
+    ? { file: "gh", args: ["pr", "diff", String(target.number), "--color=never"] }
+    : { file: "git", args: target.args };
+}
+
+/** Canonical display form. Never execute this string directly; use reviewDiffCommand(). */
+export function formatReviewDiffTarget(target: ReviewDiffTarget): string {
+  const command = reviewDiffCommand(target);
+  return [command.file, ...command.args].join(" ");
+}
+
+/** Derive reconstruction semantics from the canonical git command instead of persisting duplicate state. */
+export function reviewGitDiffBaseline(target: GitReviewDiffTarget): GitDiffBaselineTarget {
+  const parsed = parseGitDiff(["git", ...target.args]);
+  if ("error" in parsed) throw new Error(`Invalid persisted git review target: ${parsed.error}`);
+  return parsed.baseline;
+}
+
+/** Validate persisted targets by round-tripping through the single command allowlist parser. */
+export function isReviewDiffTarget(value: unknown): value is ReviewDiffTarget {
+  if (!Value.Check(ReviewDiffTargetSchema, value)) return false;
+  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(value));
+  return !("error" in parsed) && sameReviewDiffTarget(parsed, value);
+}
+
+function sameReviewDiffTarget(left: ReviewDiffTarget, right: ReviewDiffTarget): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "pull-request") return right.kind === "pull-request" && left.number === right.number;
+  if (right.kind !== "git" || left.args.length !== right.args.length) return false;
+  return left.args.every((arg, index) => arg === right.args[index]);
+}

package/.pi/extensions/pi-workflow-engine/src/session-identity.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Stable identity for state retained for the lifetime of a pi session. */
+export function sessionKey(ctx: Pick<ExtensionContext, "sessionManager">): string {
+  return ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
+}

package/.pi/extensions/pi-workflow-engine/src/structured-output.ts

@@ -0,0 +1,32 @@
+export const MAX_SCHEMA_REPAIR_ATTEMPTS = 2;
+export const STRUCTURED_OUTPUT_ERROR_CODE = "WORKFLOW_STRUCTURED_OUTPUT_NONCOMPLIANCE";
+
+export interface StructuredOutputErrorDetails {
+  readonly agentLabel: string;
+  readonly promptAttempts: number;
+  readonly repairAttempts: number;
+}
+
+/** Recoverable failure raised when a schema agent never calls `final_answer`. */
+export class WorkflowStructuredOutputError extends Error {
+  readonly name = "WorkflowStructuredOutputError";
+  readonly code = STRUCTURED_OUTPUT_ERROR_CODE;
+  readonly details: StructuredOutputErrorDetails;
+
+  constructor(agentLabel: string, repairAttempts: number) {
+    const promptAttempts = repairAttempts + 1;
+    super(
+      `Schema agent "${agentLabel}" did not call final_answer after ${promptAttempts} prompt attempts (${repairAttempts} repairs).`,
+    );
+    this.details = { agentLabel, promptAttempts, repairAttempts };
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: StructuredOutputErrorDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/tool-capabilities.ts

@@ -0,0 +1,44 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { AgentToolHint } from "./types.ts";
+
+/** Raised before prompting when required semantic tool capabilities are unavailable. */
+export class WorkflowToolHintUnavailableError extends Error {
+  readonly code = "WORKFLOW_TOOL_HINT_UNAVAILABLE";
+  readonly hints: readonly AgentToolHint[];
+
+  constructor(hints: readonly AgentToolHint[]) {
+    super(`Required workflow tool capability unavailable: ${hints.join(", ")}`);
+    this.name = "WorkflowToolHintUnavailableError";
+    this.hints = [...hints];
+  }
+}
+
+export function matchesAgentToolHint(tool: ToolInfo, hint: AgentToolHint): boolean {
+  return hint === "search" ? isSearchLikeTool(tool) : isExternalSearchLikeTool(tool);
+}
+
+function isExternalSearchLikeTool(tool: ToolInfo): boolean {
+  if (isMutationLikeToolName(tool.name) || tool.sourceInfo.source === "builtin") return false;
+  const name = tool.name.toLowerCase();
+  const description = [tool.description, ...(tool.promptGuidelines ?? [])].join(" ").toLowerCase();
+  const text = `${name} ${description}`;
+  const hasResearchAction = /\b(?:browse|browser|search|fetch|extract|open|read|get)\b/.test(text)
+    || /(?:^|[-_])(?:browse|browser|search|fetch|extract)(?:$|[-_])/.test(name)
+    || /(?:^|[^a-z0-9])web(?:$|[^a-z0-9])/.test(name);
+  const hasExternalMedium = /(?:^|[-_])(?:web|browser|url|http|https|tavily|exa|firecrawl|brave|serper|parallel|perplexity)(?:$|[-_])/.test(name)
+    || /\b(?:search|browse)\s+(?:the\s+)?(?:web|internet)\b/.test(description)
+    || /\b(?:internet|web) search(?: engine)?\b/.test(description)
+    || /\b(?:fetch|extract|open|read|get)\s+(?:(?:the|a|an)\s+)?(?:url|web\s?page|website|https? page)\b/.test(description);
+  return hasResearchAction && hasExternalMedium;
+}
+
+function isSearchLikeTool(tool: ToolInfo): boolean {
+  if (isMutationLikeToolName(tool.name)) return false;
+  const name = tool.name.toLowerCase();
+  if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
+  return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description.toLowerCase());
+}
+
+function isMutationLikeToolName(name: string): boolean {
+  return /(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)/.test(name.toLowerCase());
+}

package/.pi/extensions/pi-workflow-engine/src/tool-source-identity.ts

@@ -1,5 +1,6 @@
 import { lstat } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
+import { isMissingPathError } from "./filesystem-error.ts";
 import { hashIdentity } from "./identity-fingerprint.ts";
 import { logicalWorkspacePath, portableRelativePath } from "./replay-path-identity.ts";
 import { captureTreeFingerprint, isPathWithin, validateTreeFile, type FingerprintCapture } from "./tree-fingerprint.ts";
@@ -147,7 +148,3 @@ function nonEmptyString(value: string, label: string): string {
   if (value.length === 0) throw new Error(`${label} is empty`);
   return value;
 }
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}

package/.pi/extensions/pi-workflow-engine/src/tree-fingerprint.ts

@@ -3,6 +3,7 @@ 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 =
@@ -398,7 +399,3 @@ function isExcludedAncestor(path: string, excluded: ReadonlySet<string> | undefi
   }
   return false;
 }
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}

package/.pi/extensions/pi-workflow-engine/src/types.ts

@@ -3,9 +3,12 @@ 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 { WorkflowProgressSnapshot } from "./progress.ts";
+import type { 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;
@@ -29,6 +32,13 @@ 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 {
@@ -36,12 +46,30 @@ export interface WorkflowRunOptions {
   perf?: boolean;
   concurrency?: number;
   parallelSubmissionLimit?: number;
-  /** Output-token ceiling for the whole run. Omit for no limit (budget.total === null). */
+  /** 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;
@@ -66,9 +94,7 @@ export interface WorkflowProgressSource {
 }
 
 /** Options for a single `agent()` call. */
-export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
-
-export type AgentToolHint = "search";
+export type AgentToolHint = "search" | "external-search";
 export type AgentResumePolicy = "read-only" | "off";
 
 export interface IsolatedAgentResult<T> {
@@ -96,12 +122,15 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   /** Phase to group this agent under in the progress tree. */
   phase?: string;
   /**
-   * Optional model id. Omit to inherit the host model. Explicit refs are strict:
-   * bare ids resolve as Anthropic shorthand; use "provider/id" for other providers.
+   * 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. */
+  /** 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}`.
@@ -126,11 +155,13 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   /** Allowlist of concrete tool names the agent may use (e.g. ["read", "bash"]). */
   tools?: string[];
   /**
-   * Dynamically include installed tools matching semantic categories. Currently
-   * "search" matches grep/find/code-search style tools such as ast-grep,
-   * mgrep, ffgrep, fffind, ripgrep wrappers, and pi's built-in grep/find/ls.
+   * 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
@@ -138,7 +169,10 @@ export interface AgentOptions<S extends TSchema = TSchema> {
    * prompt inference for prompts that mention skills only as subject matter.
    */
   skills?: readonly string[];
-  /** typebox schema. When set, the agent is forced to return matching structured data. */
+  /**
+   * typebox schema. The agent must call the validated `final_answer` tool; bounded
+   * repair exhaustion throws `WorkflowStructuredOutputError` instead of returning null.
+   */
   schema?: S;
 }
 
@@ -151,11 +185,11 @@ export interface WorkflowApi {
   agent<S extends TSchema>(
     prompt: string,
     opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
-  ): Promise<IsolatedAgentResult<Static<S> | null>>;
+  ): Promise<IsolatedAgentResult<Static<S>>>;
   /** Run a text subagent in a disposable worktree and return its final text plus patch. */
   agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
-  /** Run a subagent and return its validated structured output (null if it never produced one). */
-  agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S> | null>;
+  /** 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>;
   /**

package/.pi/extensions/pi-workflow-engine/src/ui/dynamax-editor-decoration.ts

@@ -0,0 +1,220 @@
+import { sliceByColumn, visibleWidth, type EditorComponent } from "@earendil-works/pi-tui";
+
+export type DynamaxEffect = "shine" | "static" | "off";
+
+export interface DynamaxAnimationScheduler {
+  now(): number;
+  schedule(callback: () => void, delayMs: number): () => void;
+}
+
+export interface DynamaxEditorDecoration {
+  readonly editor: EditorComponent;
+  dispose(): void;
+}
+
+interface DynamaxEditorDecorationOptions {
+  effect: Exclude<DynamaxEffect, "off">;
+  scheduler?: DynamaxAnimationScheduler;
+  isActive?: () => boolean;
+}
+
+const DYNAMAX_RENDER_PATTERN = /(^|[^A-Za-z0-9_])(dynamax)(?=[^A-Za-z0-9_]|$)/gi;
+const DYNAMAX_COLORS = [
+  [233, 137, 115],
+  [228, 186, 103],
+  [141, 192, 122],
+  [102, 194, 179],
+  [121, 157, 207],
+  [157, 134, 195],
+  [206, 130, 172],
+] as const;
+const RESET_FOREGROUND = "\x1b[39m";
+const DYNAMAX_EFFECT_ENV = "PI_DYNAMAX_EFFECT";
+export const DYNAMAX_ANIMATION_FRAME_MS = 135;
+const DYNAMAX_SHINE_FRAME_COUNT = DYNAMAX_COLORS.length;
+const DEFAULT_DYNAMAX_ANIMATION_SCHEDULER: DynamaxAnimationScheduler = {
+  now: () => performance.now(),
+  schedule(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    return () => clearTimeout(timer);
+  },
+};
+
+export function resolveDynamaxEffect(env: NodeJS.ProcessEnv = process.env): DynamaxEffect {
+  const configured = env[DYNAMAX_EFFECT_ENV]?.trim().toLowerCase();
+  if (configured === "shine" || configured === "static" || configured === "off") return configured;
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== "") return "off";
+  return "shine";
+}
+
+export function highlightDynamaxTokens(line: string, shinePosition?: number): string {
+  const { visibleText, rawPositions } = mapVisibleCharacters(line);
+  const insertions = new Map<number, string>();
+  for (const match of visibleText.matchAll(DYNAMAX_RENDER_PATTERN)) {
+    const token = match[2]!;
+    const visibleStart = match.index! + match[1]!.length;
+    for (let index = 0; index < token.length; index++) {
+      const rawPosition = rawPositions[visibleStart + index]!;
+      const color = DYNAMAX_COLORS[index % DYNAMAX_COLORS.length]!;
+      const shine = shinePosition === undefined ? (index === 0 ? 0.45 : 0) : shineFactor(index, shinePosition);
+      insertions.set(rawPosition, foregroundColor(color, shine));
+    }
+    const restorePosition = rawPositions[visibleStart + token.length] ?? line.length;
+    insertions.set(restorePosition, foregroundRestoreAt(line, restorePosition));
+  }
+  if (insertions.size === 0) return line;
+
+  let highlighted = "";
+  for (let rawPosition = 0; rawPosition <= line.length; rawPosition++) {
+    highlighted += insertions.get(rawPosition) ?? "";
+    if (rawPosition < line.length) highlighted += line[rawPosition];
+  }
+  return highlighted;
+}
+
+export function decorateDynamaxEditor(
+  editor: EditorComponent,
+  requestRender: () => void,
+  options: DynamaxEditorDecorationOptions,
+): DynamaxEditorDecoration {
+  const { effect } = options;
+  const originalRender = editor.render;
+  const scheduler = options.scheduler ?? DEFAULT_DYNAMAX_ANIMATION_SCHEDULER;
+  const isActive = options.isActive ?? (() => true);
+  let disposed = false;
+  let cancelScheduled: (() => void) | undefined;
+  let lastSignature: string | undefined;
+  let animationStartedAt: number | undefined;
+
+  const cancelAnimation = (): void => {
+    cancelScheduled?.();
+    cancelScheduled = undefined;
+    animationStartedAt = undefined;
+  };
+  const scheduleRender = (delayMs: number): void => {
+    if (cancelScheduled || disposed || !isActive()) return;
+    cancelScheduled = scheduler.schedule(() => {
+      cancelScheduled = undefined;
+      if (disposed || !isActive()) return;
+      requestRender();
+    }, Math.max(0, delayMs));
+  };
+
+  const decoratedRender = (width: number): string[] => {
+    const lines = originalRender.call(editor, width);
+    const signature = visibleDynamaxSignature(lines);
+    if (signature !== lastSignature) {
+      cancelAnimation();
+      lastSignature = signature;
+      if (signature && effect === "shine" && isActive()) animationStartedAt = scheduler.now();
+    }
+
+    let shinePosition: number | undefined;
+    if (animationStartedAt !== undefined && signature && effect === "shine" && isActive()) {
+      const now = scheduler.now();
+      const elapsed = Math.max(0, now - animationStartedAt);
+      const frame = Math.floor(elapsed / DYNAMAX_ANIMATION_FRAME_MS);
+      if (frame < DYNAMAX_SHINE_FRAME_COUNT) {
+        shinePosition = frame;
+        const nextFrameAt = animationStartedAt + (frame + 1) * DYNAMAX_ANIMATION_FRAME_MS;
+        scheduleRender(nextFrameAt - now);
+      } else {
+        cancelAnimation();
+      }
+    } else if (!signature || effect !== "shine" || !isActive()) {
+      cancelAnimation();
+    }
+
+    return lines.map((line) => highlightDynamaxTokens(line, shinePosition));
+  };
+
+  editor.render = decoratedRender;
+  return {
+    editor,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      cancelAnimation();
+      if (editor.render === decoratedRender) editor.render = originalRender;
+    },
+  };
+}
+
+function shineFactor(index: number, shinePosition: number): number {
+  const distance = Math.abs(index - shinePosition);
+  if (distance === 0) return 0.7;
+  if (distance === 1) return 0.3;
+  return 0;
+}
+
+function foregroundColor(color: readonly [number, number, number], shine: number): string {
+  const red = Math.round(color[0] + (255 - color[0]) * shine);
+  const green = Math.round(color[1] + (255 - color[1]) * shine);
+  const blue = Math.round(color[2] + (255 - color[2]) * shine);
+  return `\x1b[38;2;${red};${green};${blue}m`;
+}
+
+function mapVisibleCharacters(line: string): { visibleText: string; rawPositions: number[] } {
+  let visibleText = "";
+  const rawPositions: number[] = [];
+  let rawPosition = 0;
+  while (rawPosition < line.length) {
+    const controlLength = terminalControlSequenceLength(line, rawPosition);
+    if (controlLength > 0) {
+      rawPosition += controlLength;
+      continue;
+    }
+    visibleText += line[rawPosition];
+    rawPositions.push(rawPosition);
+    rawPosition += 1;
+  }
+  return { visibleText, rawPositions };
+}
+
+function terminalControlSequenceLength(line: string, position: number): number {
+  if (line[position] !== "\x1b") return 0;
+  const introducer = line[position + 1];
+  if (introducer === "[") {
+    for (let index = position + 2; index < line.length; index++) {
+      const code = line.charCodeAt(index);
+      if (code >= 0x40 && code <= 0x7e) return index - position + 1;
+    }
+    return line.length - position;
+  }
+  if (introducer === "]" || introducer === "_") {
+    for (let index = position + 2; index < line.length; index++) {
+      if (line[index] === "\x07") return index - position + 1;
+      if (line[index] === "\x1b" && line[index + 1] === "\\") return index - position + 2;
+    }
+    return line.length - position;
+  }
+  return Math.min(2, line.length - position);
+}
+
+function foregroundRestoreAt(line: string, rawPosition: number): string {
+  const column = visibleWidth(line.slice(0, rawPosition));
+  // The extra cell makes Pi emit the active SGR prefix even when the token ends the line.
+  const sliced = sliceByColumn(`${line} `, column, 1);
+  let controls = "";
+  let position = 0;
+  while (position < sliced.length) {
+    const controlLength = terminalControlSequenceLength(sliced, position);
+    if (controlLength === 0) break;
+    const sequence = sliced.slice(position, position + controlLength);
+    if (sequence.startsWith("\x1b[") && sequence.endsWith("m")) controls += sequence;
+    position += controlLength;
+  }
+  return `${RESET_FOREGROUND}${controls}`;
+}
+
+function visibleDynamaxSignature(lines: string[]): string {
+  const matches: string[] = [];
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const { visibleText } = mapVisibleCharacters(lines[lineIndex]!);
+    for (const match of visibleText.matchAll(DYNAMAX_RENDER_PATTERN)) {
+      const visibleStart = match.index! + match[1]!.length;
+      matches.push(`${lineIndex}:${visibleStart}:${match[2]!}`);
+    }
+  }
+  return matches.join("|");
+}