@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

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

@@ -0,0 +1,400 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowProgressEvent } from "./types.ts";
+import type { AgentChatMessage, AgentChatRole, AgentRowStatus, WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progress-types.ts";
+import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "./usage.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import { statusTextFromCounts, type WorkflowStatusCounts } from "./ui/workflow-format.ts";
+import { toDisplayLine } from "./ui/display-text.ts";
+import { renderWorkflowWidgetLines } from "./ui/workflow-widget.ts";
+
+export type {
+  AgentChatMessage,
+  AgentChatRole,
+  AgentRowSnapshot,
+  AgentRowStatus,
+  PhaseSnapshot,
+  WorkflowCounterSnapshot,
+  WorkflowLaneItemSnapshot,
+  WorkflowLaneItemStatus,
+  WorkflowProgressSnapshot,
+} from "./progress-types.ts";
+
+interface AgentRow {
+  id: number;
+  label: string;
+  model?: string;
+  status: AgentRowStatus;
+  startedAt?: number;
+  doneAt?: number;
+  toolUses: number;
+  lastTool?: string;
+  error?: string;
+}
+
+interface Phase {
+  title: string;
+  agents: AgentRow[];
+}
+
+interface WorkflowCounter {
+  key: string;
+  label: string;
+  value: number;
+}
+
+interface WorkflowLaneItem {
+  lane: string;
+  title: string;
+  subtitle?: string;
+  status: WorkflowLaneItemStatus;
+  details?: string;
+  createdAt: number;
+}
+
+const LOG_LIMIT = 24;
+const AGENT_CHAT_LIMIT = 80;
+const AGENT_CHAT_TEXT_LIMIT = 2_000;
+/** Stored breadcrumbs stay single-line so every live surface keeps a stable height. */
+const LOG_DISPLAY_LIMIT = 200;
+const AGENT_ERROR_DISPLAY_LIMIT = 300;
+const WIDGET_REFRESH_INTERVAL_MS = 1_000;
+export const DEFAULT_LANE_ITEM_LIMIT = 200;
+
+/**
+ * Tracks live workflow state for widgets, footer/status text, result renderers,
+ * and headless stderr breadcrumbs.
+ */
+export class ProgressTracker {
+  private readonly phases: Phase[] = [];
+  private readonly logs: string[] = [];
+  private readonly counters = new Map<string, WorkflowCounter>();
+  private readonly summary = new Map<string, string | number>();
+  private readonly lanes = new Map<string, WorkflowLaneItem[]>();
+  private readonly laneOverflow = new Map<string, number>();
+  private readonly rowsById = new Map<number, AgentRow>();
+  private readonly agentChats = new Map<number, AgentChatMessage[]>();
+  private readonly agentFollowUps = new Map<number, (message: string) => Promise<void>>();
+  private readonly listeners = new Set<() => void>();
+  private readonly agentCounts: Record<AgentRowStatus, number> = { queued: 0, running: 0, done: 0, failed: 0 };
+  private readonly startedAt = Date.now();
+  private readonly laneItemLimit = laneItemLimitFromEnv();
+  private doneAt: number | undefined;
+  private currentPhase = "Workflow";
+  private nextAgentId = 1;
+  private lastStatusText: string | undefined;
+  private usageSnapshot: WorkflowUsageSnapshot | undefined;
+  private widgetRefreshInterval: ReturnType<typeof setInterval> | undefined;
+  private readonly surfaceKey: string;
+
+  constructor(
+    private readonly ctx: ExtensionContext,
+    private readonly title: string,
+    private readonly runId: string,
+    private readonly onSnapshot?: (snapshot: WorkflowProgressSnapshot) => void,
+  ) {
+    this.surfaceKey = `workflow:${runId}`;
+    this.ensurePhase(this.currentPhase);
+  }
+
+  private ensurePhase(title: string): Phase {
+    let phase = this.phases.find((candidate) => candidate.title === title);
+    if (!phase) {
+      phase = { title, agents: [] };
+      this.phases.push(phase);
+    }
+    return phase;
+  }
+
+  phase(title: string): void {
+    this.currentPhase = title;
+    this.ensurePhase(title);
+    if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${title}\n`);
+    this.publish();
+  }
+
+  log(message: string): void {
+    this.logs.push(toDisplayLine(message, LOG_DISPLAY_LIMIT));
+    while (this.logs.length > LOG_LIMIT) this.logs.shift();
+    if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${message}\n`);
+    this.publish();
+  }
+
+  event(event: WorkflowProgressEvent): void {
+    switch (event.type) {
+      case "counter":
+        this.counters.set(event.key, { key: event.key, label: event.label, value: event.value });
+        break;
+      case "counter_delta": {
+        const current = this.counters.get(event.key);
+        this.counters.set(event.key, {
+          key: event.key,
+          label: event.label,
+          value: (current?.value ?? 0) + event.delta,
+        });
+        break;
+      }
+      case "lane_item": {
+        const lane = this.lanes.get(event.lane) ?? [];
+        lane.push({
+          lane: event.lane,
+          title: event.title,
+          subtitle: event.subtitle,
+          status: event.status,
+          details: event.details,
+          createdAt: Date.now(),
+        });
+        this.pruneLane(event.lane, lane);
+        this.lanes.set(event.lane, lane);
+        break;
+      }
+      case "summary":
+        this.summary.set(event.key, event.value);
+        break;
+    }
+    this.publish();
+  }
+
+  agentQueued(phase: string | undefined, label: string, model?: string): number {
+    const id = this.nextAgentId++;
+    const row = { label, model, id, status: "queued" as const, toolUses: 0 };
+    this.ensurePhase(phase ?? this.currentPhase).agents.push(row);
+    this.rowsById.set(id, row);
+    this.agentCounts.queued++;
+    this.publish();
+    return id;
+  }
+
+  agentStart(phase: string | undefined, label: string, id?: number, model?: string): void {
+    const row = id === undefined ? undefined : this.findRowById(id);
+    if (row) {
+      this.transitionAgentStatus(row, "running");
+      row.startedAt = Date.now();
+      row.error = undefined;
+    } else {
+      const nextRow = {
+        label,
+        model,
+        id: this.nextAgentId++,
+        status: "running" as const,
+        startedAt: Date.now(),
+        toolUses: 0,
+      };
+      this.ensurePhase(phase ?? this.currentPhase).agents.push(nextRow);
+      this.rowsById.set(nextRow.id, nextRow);
+      this.agentCounts.running++;
+    }
+    this.publish();
+  }
+
+  agentTool(label: string, tool: string, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row) {
+      row.lastTool = tool;
+      row.toolUses += 1;
+      this.appendAgentChat(row.id, "tool", tool);
+    }
+    this.publish();
+  }
+
+  agentMessage(id: number, role: AgentChatRole, text: string): void {
+    this.appendAgentChat(id, role, text);
+    this.publish();
+  }
+
+  bindAgentFollowUp(id: number, send: (message: string) => Promise<void>): () => void {
+    this.agentFollowUps.set(id, send);
+    this.publish();
+    return () => {
+      if (this.agentFollowUps.get(id) === send) this.agentFollowUps.delete(id);
+      this.publish();
+    };
+  }
+
+  conversation(id: number): readonly AgentChatMessage[] {
+    return (this.agentChats.get(id) ?? []).map((message) => ({ ...message }));
+  }
+
+  async followUp(id: number, message: string): Promise<void> {
+    const text = toDisplayLine(message, AGENT_CHAT_TEXT_LIMIT);
+    if (!text) throw new Error("Enter a follow-up message.");
+    const send = this.agentFollowUps.get(id);
+    if (!send) throw new Error("This agent is no longer accepting follow-ups.");
+    await send(text);
+    this.appendAgentChat(id, "user", text);
+    this.publish();
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  agentDone(label: string, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row && row.status !== "failed") {
+      this.transitionAgentStatus(row, "done");
+      row.doneAt = Date.now();
+    }
+    this.publish();
+  }
+
+  agentFailed(label: string, error: unknown, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row) {
+      this.transitionAgentStatus(row, "failed");
+      row.doneAt = Date.now();
+      row.error = toDisplayLine(unknownErrorMessage(error), AGENT_ERROR_DISPLAY_LIMIT) || "agent failed";
+      this.appendAgentChat(row.id, "status", row.error);
+    }
+    this.publish();
+  }
+
+  updateUsage(snapshot: WorkflowUsageSnapshot): void {
+    this.usageSnapshot = snapshot;
+    this.publish();
+  }
+
+  snapshot(): WorkflowProgressSnapshot {
+    return {
+      runId: this.runId,
+      title: this.title,
+      startedAt: this.startedAt,
+      doneAt: this.doneAt,
+      currentPhase: this.currentPhase,
+      phases: this.phases.map((phase) => ({
+        title: phase.title,
+        agents: phase.agents.map((agent) => ({ ...agent })),
+      })),
+      counters: [...this.counters.values()].map((counter) => ({ ...counter })),
+      summary: [...this.summary.entries()],
+      lanes: [...this.lanes.entries()].map(([lane, items]) => [lane, items.map((item) => ({ ...item }))]),
+      laneOverflow: [...this.laneOverflow.entries()],
+      logs: [...this.logs],
+      usage: this.usageSnapshot,
+    };
+  }
+
+  statusCounts(): WorkflowStatusCounts {
+    return this.statusCountsSnapshot();
+  }
+
+  private statusCountsSnapshot(): WorkflowStatusCounts {
+    return {
+      queued: this.agentCounts.queued,
+      running: this.agentCounts.running,
+      done: this.agentCounts.done,
+      failed: this.agentCounts.failed,
+      total: this.agentCounts.queued + this.agentCounts.running + this.agentCounts.done + this.agentCounts.failed,
+    };
+  }
+
+  private transitionAgentStatus(row: AgentRow, nextStatus: AgentRowStatus): void {
+    if (row.status === nextStatus) return;
+    this.agentCounts[row.status]--;
+    row.status = nextStatus;
+    this.agentCounts[nextStatus]++;
+  }
+
+  private pruneLane(laneName: string, lane: WorkflowLaneItem[]): void {
+    if (this.laneItemLimit <= 0) return;
+    while (lane.length > this.laneItemLimit) {
+      lane.shift();
+      this.laneOverflow.set(laneName, (this.laneOverflow.get(laneName) ?? 0) + 1);
+    }
+  }
+
+  private appendAgentChat(id: number, role: AgentChatRole, text: string): void {
+    const value = toDisplayLine(text, AGENT_CHAT_TEXT_LIMIT);
+    if (!value) return;
+    const messages = this.agentChats.get(id) ?? [];
+    messages.push({ role, text: value, createdAt: Date.now() });
+    while (messages.length > AGENT_CHAT_LIMIT) messages.shift();
+    this.agentChats.set(id, messages);
+  }
+
+  private findRow(label: string, id?: number): AgentRow | undefined {
+    if (id !== undefined) return this.findRowById(id);
+    for (let i = this.phases.length - 1; i >= 0; i--) {
+      const running = this.phases[i].agents.find(
+        (agent) => agent.label === label && (agent.status === "running" || agent.status === "queued"),
+      );
+      if (running) return running;
+    }
+    for (let i = this.phases.length - 1; i >= 0; i--) {
+      const matching = this.phases[i].agents.find((agent) => agent.label === label);
+      if (matching) return matching;
+    }
+    return undefined;
+  }
+
+  private findRowById(id: number): AgentRow | undefined {
+    return this.rowsById.get(id);
+  }
+
+  private publish(): void {
+    this.publishSnapshot();
+    if (!this.ctx.hasUI) return;
+    this.publishWidget();
+    this.startWidgetRefresh();
+    this.publishStatus();
+  }
+
+  private publishWidget(): void {
+    this.ctx.ui.setWidget(
+      this.surfaceKey,
+      renderWorkflowWidgetLines(this.snapshot(), this.ctx.ui.theme),
+      { placement: "aboveEditor" },
+    );
+  }
+
+  private startWidgetRefresh(): void {
+    if (this.widgetRefreshInterval !== undefined) return;
+    this.widgetRefreshInterval = setInterval(() => this.publishWidget(), WIDGET_REFRESH_INTERVAL_MS);
+  }
+
+  private stopWidgetRefresh(): void {
+    if (this.widgetRefreshInterval === undefined) return;
+    clearInterval(this.widgetRefreshInterval);
+    this.widgetRefreshInterval = undefined;
+  }
+
+  private publishStatus(): void {
+    const status = statusTextFromCounts(
+      {
+        title: this.title,
+        doneAt: this.doneAt,
+        currentPhase: this.currentPhase,
+        counters: [...this.counters.values()].map((counter) => ({ ...counter })),
+      },
+      this.statusCountsSnapshot(),
+      this.ctx.ui.theme,
+    );
+    const usage = formatWorkflowUsageLine(this.usageSnapshot);
+    const next = usage ? `${status} · ${usage}` : status;
+    if (next === this.lastStatusText) return;
+    this.ctx.ui.setStatus(this.surfaceKey, next);
+    this.lastStatusText = next;
+  }
+
+  /** Clear this run's live workflow surfaces. Final feedback is delivered by the result surface. */
+  done(): void {
+    this.doneAt = Date.now();
+    this.stopWidgetRefresh();
+    this.publishSnapshot();
+    if (!this.ctx.hasUI) return;
+    this.ctx.ui.setWidget(this.surfaceKey, undefined);
+    this.ctx.ui.setStatus(this.surfaceKey, undefined);
+    this.lastStatusText = undefined;
+  }
+
+  private publishSnapshot(): void {
+    this.onSnapshot?.(this.snapshot());
+    for (const listener of this.listeners) listener();
+  }
+}
+
+function laneItemLimitFromEnv(): number {
+  const parsed = Number(process.env.PI_WORKFLOW_LANE_ITEM_LIMIT ?? "");
+  if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_LANE_ITEM_LIMIT;
+  return Math.trunc(parsed);
+}

package/src/domains/workflows/runtime/provider-usage-limit.ts

@@ -0,0 +1,191 @@
+import { WorkflowPauseError } from "./cancellation.ts";
+import {
+  WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+  type ResolvedWorkflowRunOptions,
+} from "./options.ts";
+import type { WorkflowProviderUsageLimitPause } from "./workflow-run-record.ts";
+
+export const WORKFLOW_PROVIDER_USAGE_LIMIT_CODE = "WORKFLOW_PROVIDER_USAGE_LIMIT";
+export const WORKFLOW_USAGE_LIMIT_FALLBACK_DELAY_MS = 60_000;
+const MAX_RESET_HINT_LENGTH = 512;
+
+export interface ProviderUsageLimitDetails {
+  readonly stopReason: "error";
+  readonly providerMessage: string;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly api?: string;
+  readonly resetHint?: string;
+  readonly resetAt?: number;
+}
+
+export interface ProviderUsageLimitPauseRecord {
+  readonly message: string;
+  readonly pause: WorkflowProviderUsageLimitPause;
+}
+
+/** Fatal-to-the-current-run provider limit that remains resumable from its journal boundary. */
+export class WorkflowProviderUsageLimitError extends WorkflowPauseError {
+  override readonly name = "WorkflowProviderUsageLimitError";
+  readonly code = WORKFLOW_PROVIDER_USAGE_LIMIT_CODE;
+  readonly details: ProviderUsageLimitDetails;
+
+  constructor(details: ProviderUsageLimitDetails) {
+    super(details.providerMessage);
+    this.details = details;
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: ProviderUsageLimitDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}
+
+export function providerUsageLimitFromMessages(
+  messages: readonly unknown[],
+  now = Date.now(),
+): WorkflowProviderUsageLimitError | undefined {
+  const message = messages.findLast(isAssistantMessage);
+  if (!message || message.stopReason !== "error") return undefined;
+  const providerMessage = typeof message.errorMessage === "string" ? message.errorMessage.trim() : "";
+  if (!providerMessage || !isUsageLimitMessage(providerMessage)) return undefined;
+  const reset = parseProviderResetHint(providerMessage, now);
+  const provider = stringDetail(message.provider);
+  const model = stringDetail(message.model);
+  const api = stringDetail(message.api);
+  return new WorkflowProviderUsageLimitError({
+    stopReason: "error",
+    providerMessage,
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(api ? { api } : {}),
+    ...reset,
+  });
+}
+
+export function createProviderUsageLimitPauseRecord(
+  error: WorkflowProviderUsageLimitError,
+  options: ResolvedWorkflowRunOptions,
+  replayableInvocation: boolean,
+  now = Date.now(),
+): ProviderUsageLimitPauseRecord {
+  const attempt = options.usageLimitAttempt + 1;
+  const hintedDelay = error.details.resetAt === undefined
+    ? WORKFLOW_USAGE_LIMIT_FALLBACK_DELAY_MS
+    : error.details.resetAt - now;
+  const delayMs = Math.min(
+    options.usageLimitMaxDelayMs,
+    Math.max(
+      WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+      hintedDelay > 0 ? hintedDelay : WORKFLOW_USAGE_LIMIT_FALLBACK_DELAY_MS,
+    ),
+  );
+  const autoResume = options.autoResumeOnUsageLimit
+    && attempt < options.usageLimitMaxAttempts
+    && replayableInvocation;
+  return {
+    message: autoResume
+      ? `Provider usage limit paused this run; automatic attempt ${attempt + 1}/${options.usageLimitMaxAttempts} is scheduled.`
+      : `Provider usage limit paused this run at attempt ${attempt}/${options.usageLimitMaxAttempts}.`,
+    pause: {
+      kind: "provider_usage_limit",
+      reason: "provider_usage_limit",
+      providerMessage: error.details.providerMessage,
+      provider: error.details.provider,
+      model: error.details.model,
+      api: error.details.api,
+      resetHint: error.details.resetHint,
+      attempt,
+      nextEligibleAt: now + delayMs,
+      autoResume,
+      maxAttempts: options.usageLimitMaxAttempts,
+    },
+  };
+}
+
+export function parseProviderResetHint(
+  message: string,
+  now = Date.now(),
+): { readonly resetHint?: string; readonly resetAt?: number } {
+  const iso = message.match(
+    /(?:[a-z-]*reset[a-z-]*|resets?\s+at|available\s+again\s+at)\s*[:=]?\s*(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))/i,
+  )?.[1];
+  if (iso) {
+    const parsed = Date.parse(iso);
+    return Number.isFinite(parsed) && parsed > now
+      ? { resetHint: boundedHint(iso), resetAt: parsed }
+      : { resetHint: boundedHint(iso) };
+  }
+
+  const labelled = message.match(
+    /(?:retry[- ]after|try again in|resets? in|available again in|x-ratelimit-reset(?:-[a-z-]+)?)\s*[:=]?\s*((?:\d+(?:\.\d+)?\s*(?:milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\s*)+)/i,
+  );
+  if (labelled?.[1]) {
+    const delayMs = parseDurationMs(labelled[1]);
+    return delayMs === undefined
+      ? { resetHint: boundedHint(labelled[0]) }
+      : { resetHint: boundedHint(labelled[0]), resetAt: now + delayMs };
+  }
+
+  const retryAfter = message.match(/retry[- ]after\s*[:=]\s*([^\s,;]+)/i);
+  if (retryAfter?.[1]) {
+    const seconds = Number(retryAfter[1]);
+    return Number.isFinite(seconds) && seconds >= 0
+      ? { resetHint: boundedHint(retryAfter[0]), resetAt: now + seconds * 1_000 }
+      : { resetHint: boundedHint(retryAfter[0]) };
+  }
+  return {};
+}
+
+function isUsageLimitMessage(message: string): boolean {
+  return /(?:GoUsageLimitError|FreeUsageLimitError|insufficient_quota|rate_limit_error|ResourceExhausted)/i.test(message)
+    || /\btoo many requests\b/i.test(message)
+    || /\b(?:http|status(?: code)?|error)\s*[:=]?\s*429\b/i.test(message)
+    || /\b429\b[^\n]*(?:rate|requests?|quota|limit)/i.test(message)
+    || /\b(?:usage|quota|monthly|weekly|daily)\s+(?:window\s+)?limit\b/i.test(message)
+    || /\bquota\s+(?:has\s+been\s+)?exceeded\b/i.test(message)
+    || /\bexceeded\b[^\n]*\bquota\b/i.test(message)
+    || /\b(?:usage|rate)\s+limit\s+(?:(?:has\s+been|was)\s+)?(?:reached|exceeded)\b/i.test(message);
+}
+
+function parseDurationMs(value: string): number | undefined {
+  const unitPattern = /(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)/gi;
+  let total = 0;
+  let matched = "";
+  for (const part of value.matchAll(unitPattern)) {
+    const amount = Number(part[1]);
+    const unit = part[2]?.toLowerCase();
+    if (!Number.isFinite(amount) || !unit) return undefined;
+    matched += part[0];
+    if (unit === "ms" || unit.startsWith("millisecond")) total += amount;
+    else if (unit === "s" || unit.startsWith("sec")) total += amount * 1_000;
+    else if (unit === "m" || unit.startsWith("min")) total += amount * 60_000;
+    else if (unit === "h" || unit.startsWith("hr") || unit.startsWith("hour")) total += amount * 3_600_000;
+    else total += amount * 86_400_000;
+  }
+  if (!matched || value.replace(/\s+/g, "") !== matched.replace(/\s+/g, "")) return undefined;
+  return Number.isFinite(total) && total >= 0 ? total : undefined;
+}
+
+function boundedHint(value: string): string {
+  return value.length <= MAX_RESET_HINT_LENGTH ? value : `${value.slice(0, MAX_RESET_HINT_LENGTH - 1)}…`;
+}
+
+function isAssistantMessage(value: unknown): value is {
+  readonly role: "assistant";
+  readonly stopReason?: unknown;
+  readonly errorMessage?: unknown;
+  readonly provider?: unknown;
+  readonly model?: unknown;
+  readonly api?: unknown;
+} {
+  return typeof value === "object" && value !== null && "role" in value && value.role === "assistant";
+}
+
+function stringDetail(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/domains/workflows/runtime/replay-path-identity.ts

@@ -0,0 +1,48 @@
+import { relative, resolve, sep } from "node:path";
+import { isPathWithin } from "./tree-fingerprint.ts";
+
+export interface ReplayWorkspaceRoots {
+  readonly sessionCwd: string;
+  readonly workspaceRoot: string;
+}
+
+/** Map a path in either the disposable session or main workspace to one stable namespace. */
+export function logicalWorkspacePath(path: string, roots: ReplayWorkspaceRoots): string | undefined {
+  for (const root of resolvedWorkspaceRoots(roots)) {
+    if (isPathWithin(root, path)) return `workspace:${portableRelativePath(root, path)}`;
+  }
+  return undefined;
+}
+
+/** Normalize absolute workspace paths embedded in generated system prompts. */
+export function normalizeWorkspaceReferences(value: string, roots: ReplayWorkspaceRoots): string {
+  const paths = [...resolvedWorkspaceRoots(roots)].sort((left, right) => right.length - left.length);
+  return paths.reduce((normalized, path) => replacePathPrefix(normalized, path, "<workspace>"), value);
+}
+
+export function portableRelativePath(root: string, path: string): string {
+  const value = relative(root, path).split(sep).join("/");
+  return value.length === 0 ? "." : value;
+}
+
+function resolvedWorkspaceRoots(roots: ReplayWorkspaceRoots): readonly string[] {
+  return [...new Set([resolve(roots.sessionCwd), resolve(roots.workspaceRoot)])];
+}
+
+function replacePathPrefix(value: string, prefix: string, replacement: string): string {
+  let result = "";
+  let cursor = 0;
+  while (cursor < value.length) {
+    const index = value.indexOf(prefix, cursor);
+    if (index === -1) return result + value.slice(cursor);
+    const next = value[index + prefix.length];
+    if (next !== undefined && next !== "/" && next !== "\\" && /[\p{L}\p{N}._-]/u.test(next)) {
+      result += value.slice(cursor, index + prefix.length);
+      cursor = index + prefix.length;
+      continue;
+    }
+    result += value.slice(cursor, index) + replacement;
+    cursor = index + prefix.length;
+  }
+  return result;
+}