@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/src/index.ts

@@ -0,0 +1,29 @@
+export * from "./types.js";
+export * from "./package-identity.js";
+export { createToolTimingExtension, TOOL_TIMING_ENTRY_TYPE } from "./tool-timing.js";
+export type { ToolTimingEntry } from "./tool-timing.js";
+export * from "./utils.js";
+export { canonicalPath, sameFilesystemPath } from "./paths.js";
+export * from "./budget.js";
+export * from "./validation.js";
+export * from "./registry.js";
+export * from "./execution.js";
+export * from "./host.js";
+export * from "./workflow-artifacts.js";
+export { formatCost } from "./background-widget.js";
+export { agentActionLabels, formatAgentDetail, navigatorAttentionSortByState, themeWorkflowProgressStyles, visibleStandaloneAgentAttemptActions } from "./host-view.js";
+export type { AgentDetailPresentation, WorkflowProgressStyles } from "./host-view.js";
+export { default } from "./host.js";
+export { acquireSessionLease, hasLiveSessionLease, listPersistedSessionIds, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
+export type { AwaitingCheckpoint, CompletedOperation, PendingWorkflowDecision, PersistedOwnershipNode, PersistedRun, RunSummary, RunSummaryAgent, RunSummaryArtifacts, WorktreeReference } from "./persistence.js";
+export { FairAgentScheduler, WorkflowAgentExecutor, createLocalPiSession, createLocalWorkflowAgentSession, localAgentTransport, prepareAgentSetupForInspection } from "./agent-execution.js";
+export type { AgentAttempt, AgentBudgetHooks, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentInspectionMode, AgentProgress, AgentProviderFailure, AgentProviderRecovery, AgentToolCallProgress, AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PiPromptInspection, PiResourceInspection, PiRuntimeLaunchInfo, PiSession, PreparedAgentSession, PreparedAgentSetup, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./agent-execution.js";
+export { createLiveSessionHandoff } from "./session-handoff.js";
+export { createPiRuntimeSessionAdapter, createRuntimeHandoffAdapter, isTurnBoundaryEnd, isTurnBoundaryStart, isTurnEnd, normalizePiMessage, normalizePiSessionEvent, runtimeProgressToAgentProgress } from "./pi-runtime-adapter.js";
+export type { PiRuntimeProgressObservation, PiRuntimeSessionAdapter } from "./pi-runtime-adapter.js";
+export { PiRuntimeAgentRunner, createPiRuntimeAgentRunner, isRuntimeAgentProviderError, normalizePiRuntimeError } from "./pi-runtime-runner.js";
+export type { PiRuntimeAgentRunnerCallbacks, PiRuntimeAgentRunnerOptions } from "./pi-runtime-runner.js";
+export * from "./herdr.js";
+export * from "./runtime/index.js";
+export { retainTerminalRuns } from "./retention.js";
+export type { RetentionCleanupOptions, RetentionCleanupReport } from "./retention.js";

package/src/io.ts

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { WorkflowError } from "./types.js";
+import { isNodeError } from "./utils.js";
+
+const execute = promisify(execFile);
+// ponytail: retry window is capped at 1.585s; use durable lock coordination if holders outlive it.
+const RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 400, 800] as const;
+const syncSleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+function retryableRenameError(error: unknown): boolean { return isNodeError(error, "EPERM") || isNodeError(error, "EBUSY") || isNodeError(error, "EACCES"); }
+async function renameWithRetry(from: string, to: string): Promise<void> {
+  for (let attempt = 0; ; attempt += 1) {
+    try { await rename(from, to); return; }
+    catch (error) {
+      const delayMs = RENAME_RETRY_DELAYS_MS[attempt];
+      if (!retryableRenameError(error) || delayMs === undefined) throw error;
+      await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+}
+function renameSyncWithRetry(from: string, to: string): void {
+  for (let attempt = 0; ; attempt += 1) {
+    try { renameSync(from, to); return; }
+    catch (error) {
+      const delayMs = RENAME_RETRY_DELAYS_MS[attempt];
+      if (!retryableRenameError(error) || delayMs === undefined) throw error;
+      Atomics.wait(syncSleepBuffer, 0, 0, delayMs);
+    }
+  }
+}
+export const gitIdentity = {
+  GIT_AUTHOR_NAME: "pi-extensible-workflows", GIT_AUTHOR_EMAIL: "pi-extensible-workflows@localhost", GIT_COMMITTER_NAME: "pi-extensible-workflows", GIT_COMMITTER_EMAIL: "pi-extensible-workflows@localhost",
+  GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z",
+};
+
+export function atomicWriteFile(path: string, content: string): Promise<void>;
+export function atomicWriteFile(path: string, content: string, sync: true): void;
+export function atomicWriteFile(path: string, content: string, sync = false): Promise<void> | void {
+  const temporary = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
+  if (sync) {
+    try {
+      writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+      renameSyncWithRetry(temporary, path);
+    } catch (error) {
+      try { rmSync(temporary, { force: true }); } catch { /* Preserve the original write error. */ }
+      throw error;
+    }
+    return;
+  }
+  return writeFile(temporary, content, { encoding: "utf8", mode: 0o600 }).then(() => renameWithRetry(temporary, path)).catch(async (error: unknown) => {
+    try { await rm(temporary, { force: true }); } catch { /* Preserve the original write error. */ }
+    throw error;
+  });
+}
+
+export async function atomicJson(path: string, value: unknown): Promise<void> {
+  const serialized = JSON.stringify(value);
+  if (typeof serialized !== "string") throw new WorkflowError("INTERNAL_ERROR", `Cannot serialize JSON for ${path}`);
+  await atomicWriteFile(path, `${serialized}\n`);
+}
+
+export async function atomicPrettyJson(path: string, value: unknown): Promise<void> {
+  await atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function json(path: string): Promise<unknown> { return JSON.parse(await readFile(path, "utf8")); }
+export async function git(cwd: string, args: readonly string[], extraEnv: NodeJS.ProcessEnv = {}): Promise<string> {
+  const { stdout } = await execute("git", ["-c", "core.hooksPath=/dev/null", "-c", "commit.gpgSign=false", ...args], { cwd, env: { ...process.env, ...extraEnv }, encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+  return stdout;
+}

package/src/package-identity.ts

@@ -0,0 +1,7 @@
+export const CORE_PACKAGE_NAME = "@marcoscale98/pi-extensible-workflows";
+export const CORE_PACKAGE_COMPATIBILITY_NAME = "pi-extensible-workflows";
+export const CORE_PACKAGE_NAMES = [CORE_PACKAGE_NAME, CORE_PACKAGE_COMPATIBILITY_NAME] as const;
+
+export function isCorePackageName(value: unknown): boolean {
+  return typeof value === "string" && CORE_PACKAGE_NAMES.includes(value as (typeof CORE_PACKAGE_NAMES)[number]);
+}

package/src/paths.ts

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { WorkflowError } from "./types.js";
+import { isNodeError } from "./utils.js";
+
+export function safePart(value: string): string { return value.replace(/[^a-zA-Z0-9._-]/g, "_"); }
+
+/**
+ * Resolves a path to its filesystem spelling, including symlink and platform aliases.
+ * A missing path safely falls back to its absolute lexical spelling rather than
+ * guessing at the identity of an object that does not exist.
+ */
+export function canonicalPath(path: string): string {
+  const absolute = resolve(path);
+  try { return realpathSync(absolute); } catch { return absolute; }
+}
+
+export function sameFilesystemPath(left: string, right: string): boolean { return canonicalPath(left) === canonicalPath(right); }
+export function workflowProjectSettingsPath(cwd: string): string { return join(cwd, ".pi", "pi-extensible-workflows", "settings.json"); }
+
+export function projectStorageKey(cwd: string): string {
+  const exact = resolve(cwd);
+  const slug = safePart(basename(exact)) || "root";
+  return `${slug}-${createHash("sha256").update(exact).digest("hex").slice(0, 12)}`;
+}
+
+export function projectSessionsDirectory(cwd: string, home = homedir()): string {
+  return join(home, ".pi", "workflows", "projects", projectStorageKey(cwd), "sessions");
+}
+export function runsDirectory(cwd: string, sessionId: string, home = homedir()): string {
+  return join(projectSessionsDirectory(cwd, home), safePart(sessionId), "runs");
+}
+export async function listPersistedSessionIds(cwd: string, home = homedir()): Promise<string[]> {
+  try {
+    const entries = await readdir(projectSessionsDirectory(cwd, home), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map(({ name }) => name);
+  } catch (error) {
+    if (isNodeError(error, "ENOENT")) return [];
+    throw error;
+  }
+}
+
+export function structuralPath(...names: string[]): string {
+  if (names.length === 0 || names.some((name) => name.trim() === "")) throw new WorkflowError("INVALID_METADATA", "Structural paths require non-empty explicit names");
+  return names.map((name) => encodeURIComponent(name)).join("/");
+}

package/src/persistence.ts

@@ -0,0 +1,11 @@
+export { atomicJson, atomicWriteFile, json } from "./io.js";
+export {
+  projectStorageKey, projectSessionsDirectory, runsDirectory, listPersistedSessionIds, structuralPath,
+} from "./paths.js";
+export { hasLiveSessionLease, SessionLease, acquireSessionLease, listRunIds, processAlive } from "./session-lease.js";
+export { RunStore } from "./store.js";
+export {
+  EffectiveSystemPrompt, PersistedRun, RunSummaryAgent, RunSummaryArtifacts, RunSummary,
+  CompletedOperation, AwaitingCheckpoint, PendingWorkflowDecision, PersistedOwnershipNode,
+  WorktreeReference, BorrowedWorktreeBinding, isPersistedRun,
+} from "./decoders.js";

package/src/pi-runtime-adapter.ts

@@ -0,0 +1,247 @@
+import type { RuntimeAgentHandoff, RuntimeAgentProgress, RuntimeAgentState, RuntimeHandoffState, RuntimeToolCallProgress } from "./runtime/agent-runner.js";
+import type { AgentProgress } from "./agent-execution.js";
+import type { LiveSessionHandoff, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionState } from "./types.js";
+import { isThinkingLevel, sanitizeDisplayText } from "./utils.js";
+const TURN_START_EVENTS = new Set(["turn_start", "turn_started", "turnStarted"]);
+const MAX_ACTIVITY_TEXT_CHARS = 200;
+const AGENT_START_EVENTS = new Set(["agent_start"]);
+const TURN_END_EVENTS = new Set(["turn_end", "turnEnded", "agent_end", "agent_settled"]);
+type RecordValue = Record<string, unknown>;
+
+function record(value: unknown): RecordValue | undefined { return typeof value === "object" && value !== null && !Array.isArray(value) ? value as RecordValue : undefined; }
+function stringValue(value: unknown): string | undefined { return typeof value === "string" ? value : undefined; }
+function finiteNumber(value: unknown): number | undefined { return typeof value === "number" && Number.isFinite(value) ? value : undefined; }
+
+function normalizeMessage(value: unknown): WorkflowAgentMessage | undefined {
+  const candidate = record(value);
+  const role = stringValue(candidate?.role);
+  if (!candidate || role === undefined) return undefined;
+  const usage = record(candidate.usage);
+  const cost = record(usage?.cost);
+  const input = finiteNumber(usage?.input);
+  const output = finiteNumber(usage?.output);
+  const cacheRead = finiteNumber(usage?.cacheRead);
+  const cacheWrite = finiteNumber(usage?.cacheWrite);
+  const totalCost = finiteNumber(cost?.total);
+  const normalizedUsage = input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || totalCost === undefined ? undefined : { input, output, cacheRead, cacheWrite, cost: { total: totalCost } };
+  const stopReason = stringValue(candidate.stopReason);
+  const errorMessage = stringValue(candidate.errorMessage);
+  return {
+    role,
+    ...(candidate.content === undefined ? {} : { content: candidate.content }),
+    ...(stopReason === undefined ? {} : { stopReason }),
+    ...(errorMessage === undefined ? {} : { errorMessage }),
+    ...(normalizedUsage === undefined ? {} : { usage: normalizedUsage }),
+  };
+}
+
+export function normalizePiMessage(value: unknown): WorkflowAgentMessage | undefined { return normalizeMessage(value); }
+/** An assistant turn Pi aborted before it produced any content; it carries no usable result. */
+export function isEmptyAbortedAssistant(message: WorkflowAgentMessage | undefined): boolean { return message?.stopReason === "aborted" && Array.isArray(message.content) && message.content.length === 0; }
+
+function normalizeState(value: unknown): WorkflowAgentSessionState | undefined {
+  const candidate = record(value);
+  const model = record(candidate?.model);
+  const provider = stringValue(model?.provider);
+  const modelName = stringValue(model?.model);
+  const rawTools = candidate?.tools;
+  const tools = Array.isArray(rawTools) ? rawTools.filter((tool): tool is string => typeof tool === "string") : undefined;
+  if (!candidate || !model || provider === undefined || modelName === undefined || tools === undefined || !Array.isArray(rawTools) || tools.length !== rawTools.length) return undefined;
+  const thinking = candidate.thinking === undefined ? model.thinking : candidate.thinking;
+  if (thinking !== undefined && !isThinkingLevel(thinking)) return undefined;
+  const systemPrompt = candidate.systemPrompt;
+  if (systemPrompt !== undefined && typeof systemPrompt !== "string") return undefined;
+  return {
+    model: { provider, model: modelName, ...(thinking === undefined ? {} : { thinking }) },
+    ...(thinking === undefined ? {} : { thinking }),
+    tools: [...tools],
+    ...(systemPrompt === undefined ? {} : { systemPrompt }),
+  };
+}
+
+function normalizedEvent(value: unknown): WorkflowAgentSessionEvent | undefined {
+  const candidate = record(value);
+  const type = stringValue(candidate?.type);
+  if (!candidate || type === undefined) return undefined;
+  const state = normalizeState(candidate.state);
+  const message = normalizeMessage(candidate.message);
+  const assistantMessageEvent = record(candidate.assistantMessageEvent);
+  const assistantType = stringValue(assistantMessageEvent?.type);
+  const assistantDelta = stringValue(assistantMessageEvent?.delta);
+  const toolCallId = stringValue(candidate.toolCallId);
+  const toolName = stringValue(candidate.toolName);
+  const isError = candidate.isError;
+  return {
+    type,
+    ...(state === undefined ? {} : { state }),
+    ...(message === undefined ? {} : { message }),
+    ...(assistantType === undefined ? {} : { assistantMessageEvent: { type: assistantType, ...(assistantDelta === undefined ? {} : { delta: assistantDelta }) } }),
+    ...(toolCallId === undefined ? {} : { toolCallId }),
+    ...(toolName === undefined ? {} : { toolName }),
+    ...(typeof isError === "boolean" ? { isError } : {}),
+  };
+}
+
+export function normalizePiSessionEvent(value: unknown): WorkflowAgentSessionEvent | undefined { return normalizedEvent(value); }
+
+function stateFromSession(session: WorkflowAgentSession): RuntimeAgentState {
+  const current = session.getState();
+  return {
+    model: { ...current.model },
+    ...(current.thinking === undefined ? {} : { thinking: current.thinking }),
+    tools: [...current.tools],
+    ...(current.systemPrompt === undefined ? {} : { systemPrompt: current.systemPrompt }),
+  };
+}
+
+function runtimeState(state: WorkflowAgentSessionState): RuntimeAgentState { return { model: { ...state.model }, ...(state.thinking === undefined ? {} : { thinking: state.thinking }), tools: [...state.tools], ...(state.systemPrompt === undefined ? {} : { systemPrompt: state.systemPrompt }) }; }
+
+function runtimeUsage(session: WorkflowAgentSession): RuntimeAgentProgress["usage"] {
+  const stats = session.getSessionStats();
+  const values = [stats.tokens.input, stats.tokens.output, stats.tokens.cacheRead, stats.tokens.cacheWrite, stats.cost];
+  if (values.some((value) => !Number.isFinite(value))) return { availability: "unavailable" };
+  return { availability: "complete", input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, costUsd: stats.cost };
+}
+
+function sameActivity(left: RuntimeAgentProgress["activity"], right: RuntimeAgentProgress["activity"]): boolean { return left?.kind === right?.kind && left?.text === right?.text; }
+
+function runtimeHandoffState(state: LiveSessionHandoff["state"]): RuntimeHandoffState {
+  if (state === "handoff-pending") return "takeover-pending";
+  if (state === "herdr-running") return "remote-running";
+  return state;
+}
+
+export function isTurnBoundaryStart(type: string): boolean { return TURN_START_EVENTS.has(type); }
+/** A turn boundary start or an agent start: either one means the session is busy until the next turn end. */
+export function isTurnActivityStart(type: string): boolean { return TURN_START_EVENTS.has(type) || AGENT_START_EVENTS.has(type); }
+export function isTurnBoundaryEnd(type: string): boolean { return TURN_END_EVENTS.has(type); }
+export function isTurnEnd(type: string): boolean { return type === "turn_end" || type === "turnEnded"; }
+
+function boundaryEvent(type: string): "turn_started" | "turn_end" | undefined {
+  if (isTurnActivityStart(type)) return "turn_started";
+  if (isTurnBoundaryEnd(type)) return "turn_end";
+  return undefined;
+}
+
+export function createRuntimeHandoffAdapter(handoff: LiveSessionHandoff): RuntimeAgentHandoff {
+  return {
+    get state() { return runtimeHandoffState(handoff.state); },
+    get transferred() { return handoff.transferred; },
+    observe(event) {
+      const type = boundaryEvent(event.type);
+      if (type !== undefined) handoff.observe({ type });
+    },
+    request: (launch) => handoff.request(launch),
+    waitForTakeover: () => handoff.waitForTakeover(),
+    takeover: () => { handoff.takeover(); },
+    waitForResume: () => handoff.waitForResume(),
+    release: (reason?: string) => { handoff.release(reason); },
+  };
+}
+
+export interface PiRuntimeProgressObservation {
+  readonly event: WorkflowAgentSessionEvent;
+  readonly progress: RuntimeAgentProgress;
+  readonly report: boolean;
+  readonly persist: boolean;
+}
+
+export interface PiRuntimeSessionAdapter {
+  readonly handoff: RuntimeAgentHandoff;
+  observe(event: WorkflowAgentSessionEvent): PiRuntimeProgressObservation | undefined;
+  snapshot(persist: boolean): RuntimeAgentProgress;
+  dispose(): void;
+}
+
+export function createPiRuntimeSessionAdapter(session: WorkflowAgentSession, handoff: LiveSessionHandoff, clock: () => number = Date.now): PiRuntimeSessionAdapter {
+  const neutralHandoff = createRuntimeHandoffAdapter(handoff);
+  const toolCalls = new Map<string, RuntimeToolCallProgress>();
+  let activity: RuntimeAgentProgress["activity"];
+  let streamText = "";
+  let lastEventAt: number | undefined;
+  let lastReportedEventAt: number | undefined;
+  let disposed = false;
+
+  let toolCallsView: readonly RuntimeToolCallProgress[] = [];
+  const progressAt = (persist: boolean, stateOverride: RuntimeAgentState | undefined, toolCallsValue: readonly RuntimeToolCallProgress[], activityValue: RuntimeAgentProgress["activity"], eventAtValue: number | undefined): RuntimeAgentProgress => ({ usage: runtimeUsage(session), toolCalls: toolCallsValue, state: stateOverride ?? stateFromSession(session), ...(activityValue === undefined ? {} : { activity: activityValue }), ...(eventAtValue === undefined ? {} : { lastEventAt: eventAtValue }), persist });
+  const snapshot = (persist: boolean): RuntimeAgentProgress => progressAt(persist, undefined, [...toolCalls.values()], activity, lastEventAt);
+  return {
+    handoff: neutralHandoff,
+    observe(event) {
+      if (disposed) return undefined;
+      neutralHandoff.observe(event);
+      const eventAt = clock();
+      lastEventAt = eventAt;
+      const eventState = event.state === undefined ? undefined : runtimeState(event.state);
+      let report = false;
+      let persist = false;
+      const previousActivity = activity;
+      let eventToolCalls = toolCallsView;
+      if (event.type === "state_changed") { report = true; persist = true; }
+      if (event.type === "message_start" && event.message?.role === "assistant") { streamText = ""; activity = { kind: "text", text: "" }; report = true; }
+      if (event.type === "message_update") {
+        const updateType = event.assistantMessageEvent?.type;
+        if (updateType === "thinking_start" || updateType === "text_start") streamText = "";
+        const delta = event.assistantMessageEvent?.delta;
+        if ((updateType === "thinking_delta" || updateType === "text_delta") && delta) streamText = `${streamText}${delta}`.replace(/\s+/g, " ").slice(-MAX_ACTIVITY_TEXT_CHARS);
+        if (updateType && ["thinking_start", "thinking_delta", "thinking_end"].includes(updateType)) activity = { kind: "reasoning", text: streamText };
+        else if (updateType && ["text_start", "text_delta", "text_end", "toolcall_start", "toolcall_delta", "toolcall_end"].includes(updateType)) activity = { kind: "text", text: streamText };
+        report = previousActivity?.kind !== activity?.kind;
+      }
+      if (event.type === "message_end") {
+        streamText = "";
+        activity = undefined;
+        report = !sameActivity(previousActivity, activity);
+        if (event.message?.role === "assistant") { persist = true; report = true; }
+      }
+      if (event.type === "tool_execution_start" && event.toolCallId && event.toolName) {
+        toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" });
+        toolCallsView = [...toolCalls.values()];
+        activity = { kind: "tool", text: event.toolName };
+        report = true;
+      }
+      if (event.type === "tool_execution_update" && event.toolName) {
+        activity = { kind: "tool", text: event.toolName };
+        report = !sameActivity(previousActivity, activity);
+      }
+      let removeToolCallId: string | undefined;
+      if (event.type === "tool_execution_end" && event.toolCallId && event.toolName) {
+        toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" });
+        eventToolCalls = [...toolCalls.values()];
+        if (activity?.kind === "tool" && activity.text === event.toolName) activity = undefined;
+        report = true;
+        removeToolCallId = event.toolCallId;
+      }
+      if (removeToolCallId === undefined) eventToolCalls = toolCallsView;
+      if (!report && (lastReportedEventAt === undefined || eventAt - lastReportedEventAt >= 1000)) report = true;
+      const eventActivity = activity;
+      let materialized: RuntimeAgentProgress | undefined;
+      const result = { event, get progress() { return materialized ??= progressAt(persist, eventState, eventToolCalls, eventActivity, eventAt); }, report, persist };
+      if (report) lastReportedEventAt = eventAt;
+      if (removeToolCallId !== undefined) {
+        toolCalls.delete(removeToolCallId);
+        toolCallsView = [...toolCalls.values()];
+      }
+      return result;
+    },
+    snapshot,
+    dispose() { disposed = true; toolCalls.clear(); toolCallsView = []; activity = undefined; },
+  };
+}
+
+function requiredUsage(value: number | undefined, name: string): number {
+  if (value === undefined || !Number.isFinite(value)) throw new Error(`Pi runtime usage is missing ${name}`);
+  return value;
+}
+
+export function runtimeProgressToAgentProgress(value: RuntimeAgentProgress): AgentProgress {
+  if (value.usage.availability !== "complete") throw new Error(`Cannot convert ${value.usage.availability} runtime usage to Pi accounting`);
+  return {
+    accounting: { input: requiredUsage(value.usage.input, "input"), output: requiredUsage(value.usage.output, "output"), cacheRead: requiredUsage(value.usage.cacheRead, "cacheRead"), cacheWrite: requiredUsage(value.usage.cacheWrite, "cacheWrite"), cost: requiredUsage(value.usage.costUsd, "costUsd") },
+    toolCalls: value.toolCalls.map(({ id, name, state }) => ({ id, name, state })),
+    ...(value.state === undefined ? {} : { state: { model: { ...value.state.model }, ...(value.state.thinking === undefined ? {} : { thinking: value.state.thinking }), tools: [...value.state.tools], ...(value.state.systemPrompt === undefined ? {} : { systemPrompt: value.state.systemPrompt }) } }),
+    ...(value.activity === undefined ? {} : { activity: { ...value.activity, text: sanitizeDisplayText(value.activity.text) } }),
+    ...(value.lastEventAt === undefined ? {} : { lastEventAt: value.lastEventAt }),
+    persist: value.persist,
+  };
+}