pi-extensible-workflows 1.0.0 → 1.0.1

package/src/index.ts

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { fork, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,13 +12,13 @@ import { Value } from "typebox/value";
 import { copyToClipboard, getAgentDir, parseFrontmatter, highlightCode, SessionManager, truncateToVisualLines, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createNativeAgentSession, FairAgentScheduler, WorkflowAgentExecutor, type AgentActivity, type AgentAccounting, type AgentAttempt, type AgentBudgetHooks, type AgentDefinition, type AgentProgress, type AgentSetupHook, type RegisteredAgentSetupHook, type SessionFactory } from "./agent-execution.js";
 import { transcriptLines } from "./session-inspector.js";
-import { acquireSessionLease, listRunIds, RunStore, SessionLease, structuralPath as operationPath } from "./persistence.js";
+import { acquireSessionLease, atomicWriteFile, listRunIds, RunStore, SessionLease, structuralPath as operationPath } from "./persistence.js";
 import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
 
 export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"] as const;
 export const AGENT_STATES = ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"] as const;
-export const WORKFLOW_ASYNC_STARTED_EVENT = "workflow:async-started";
-export const WORKFLOW_ASYNC_COMPLETE_EVENT = "workflow:async-complete";
+export const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"] as const;
+export type WorkflowCallKind = (typeof WORKFLOW_CALL_KINDS)[number];
 export const WORKFLOW_RUN_STARTED_EVENT = "workflow:run-started";
 export const WORKFLOW_RUN_RESUMED_EVENT = "workflow:run-resumed";
 export const WORKFLOW_RUN_STATE_CHANGED_EVENT = "workflow:run-state-changed";
@@ -70,7 +70,7 @@ export interface AgentSetupSummary { hookNames: readonly string[]; model: ModelS
 export interface AgentAttemptSummary { attempt: number; sessionId: string; sessionFile: string; error?: { code: string; message: string }; accounting: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; setup?: AgentSetupSummary }
 export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase { owner: string; branch: string; path: string; base: string }
 export interface AgentRecord { id: string; name: string; label?: string; path: string; state: AgentState; parentId?: string; structuralPath?: readonly string[]; parentBreadcrumb?: string; worktreeOwner?: string; role?: string; requestedModel?: string; model: ModelSpec; tools: readonly string[]; attempts: number; attemptDetails?: readonly AgentAttemptSummary[]; accounting?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; toolCalls?: readonly { id: string; name: string; state: "running" | "completed" | "failed" }[]; activity?: AgentActivity | undefined }
-export interface WorkflowRunEvent { type: "warning"; message: string }
+export interface WorkflowRunEvent { type: string; message: string }
 export interface RunRecord { id: string; workflowName: string; cwd: string; sessionId: string; state: RunState; phase?: string; agents: readonly AgentRecord[]; error?: WorkflowErrorShape; budget?: WorkflowBudget; budgetVersion?: number; usage?: WorkflowBudgetUsage; budgetEvents?: readonly BudgetEvent[]; events?: readonly WorkflowRunEvent[] }
 export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
 export interface LaunchSnapshot { identityVersion?: number; script: string; args: JsonValue; metadata: WorkflowMetadata; settings: WorkflowSettings; budget?: WorkflowBudget; settingsPath?: string; modelAliases?: Readonly<Record<string, string>>; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[]; roles?: Readonly<Record<string, AgentDefinition>>; projectRoles?: readonly string[]; schemas: readonly JsonSchema[] }
@@ -87,7 +87,10 @@ export interface WorkflowOrchestrationContext {
   log: (message: string) => void;
 }
 export interface WorkflowRunContext { cwd: string; sessionId: string; runId: string; workflow: Readonly<WorkflowMetadata>; args: JsonValue; signal: AbortSignal }
-export interface WorkflowFunctionContext extends WorkflowOrchestrationContext { run: Readonly<WorkflowRunContext> }
+export interface WorkflowFunctionContext extends WorkflowOrchestrationContext {
+  run: Readonly<WorkflowRunContext>;
+  invoke: (name: string, input: Readonly<Record<string, JsonValue>>) => Promise<JsonValue>;
+}
 export interface WorkflowFunction { description: string; input: JsonSchema; output: JsonSchema; run: (input: Readonly<Record<string, JsonValue>>, context: Readonly<WorkflowFunctionContext>) => Promise<JsonValue> | JsonValue }
 export interface WorkflowVariable { description: string; schema: JsonSchema; resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue }
 export interface WorkflowScriptDefinition { description: string; script: string }
@@ -234,6 +237,7 @@ export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ conc
 
 function fail(code: WorkflowErrorCode, message: string): never { throw new WorkflowError(code, message); }
 function object(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+export { object as isObject };
 function nonNegativeInteger(value: unknown): value is number { return Number.isInteger(value) && (value as number) >= 0; }
 function nonNegativeFinite(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
 export function validateBudget(value: unknown): WorkflowBudget | undefined {
@@ -496,9 +500,7 @@ export function saveModelAliases(path = workflowSettingsPath(), aliases: Readonl
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
   }
   mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, { mode: 0o600 });
-  renameSync(temporary, path);
+  atomicWriteFile(path, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, true);
 }
 
 export function parseRoleMarkdown(content: string, strict = false, rolePath?: string): AgentDefinition {
@@ -613,15 +615,25 @@ type WorkflowCall = acorn.CallExpression & { callee: acorn.Identifier };
 function astNode(value: unknown): value is acorn.AnyNode {
   return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
 }
+function astChildren(node: acorn.AnyNode): acorn.AnyNode[] {
+  const children: acorn.AnyNode[] = [];
+  for (const value of Object.values(node) as unknown[]) {
+    if (Array.isArray(value)) {
+      for (const child of value) if (astNode(child)) children.push(child);
+    } else if (astNode(value)) children.push(value);
+  }
+  return children;
+}
+function workflowCallKind(node: acorn.AnyNode): WorkflowCallKind | undefined {
+  if (node.type !== "CallExpression" || node.callee.type !== "Identifier") return undefined;
+  const kind = node.callee.name as WorkflowCallKind;
+  return WORKFLOW_CALL_KINDS.includes(kind) ? kind : undefined;
+}
 function workflowCalls(program: acorn.Program): WorkflowCall[] {
   const calls: WorkflowCall[] = [];
   const visit = (node: acorn.AnyNode): void => {
-    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) calls.push(node as WorkflowCall);
-    for (const value of Object.values(node) as unknown[]) {
-      if (Array.isArray(value)) {
-        for (const child of value as unknown[]) if (astNode(child)) visit(child);
-      } else if (astNode(value)) visit(value);
-    }
+    if (workflowCallKind(node)) calls.push(node as WorkflowCall);
+    for (const child of astChildren(node)) visit(child);
   };
   visit(program);
   return calls.sort((left, right) => left.start - right.start);
@@ -638,9 +650,9 @@ function workflowCallsWithStructure(program: acorn.Program): Array<{ call: Workf
       const key = node.key.type === "Identifier" ? node.key.name : node.key.type === "Literal" ? String(node.key.value) : undefined;
       if (scope?.key === null && key) current = { ...current, structure: [...current.structure.slice(0, -1), { ...scope, key }] };
     }
-    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) {
+    const operation = workflowCallKind(node);
+    if (operation) {
       const call = node as WorkflowCall;
-      const operation = call.callee.name as StaticWorkflowCall["kind"];
       const execution = operation === "parallel" ? "parallel" : operation === "pipeline" ? "sequential" : current.execution;
       calls.push({ call, execution, structure: current.structure });
       for (const [index, argument] of call.arguments.entries()) {
@@ -650,16 +662,11 @@ function workflowCallsWithStructure(program: acorn.Program): Array<{ call: Workf
       }
       return;
     }
-    for (const value of Object.values(node) as unknown[]) {
-      if (Array.isArray(value)) {
-        for (const child of value as unknown[]) if (astNode(child)) visit(child, current);
-      } else if (astNode(value)) visit(value, current);
-    }
+    for (const child of astChildren(node)) visit(child, current);
   };
   visit(program, { execution: "sequential", structure: [] });
   return calls.sort((left, right) => left.call.start - right.call.start);
 }
-
 function validateDirectPrimitiveReferences(program: acorn.AnyNode, name: string): void {
   const visit = (node: acorn.AnyNode, parent?: acorn.AnyNode): void => {
     if (node.type === "Identifier" && node.name === name) {
@@ -667,18 +674,13 @@ function validateDirectPrimitiveReferences(program: acorn.AnyNode, name: string)
       const propertyKey = parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand;
       if (!directCall && !propertyKey) fail("INVALID_METADATA", `${name} calls must use a direct ${name}(...) call; aliases and indirect calls are unsupported`);
     }
-    for (const value of Object.values(node) as unknown[]) {
-      if (Array.isArray(value)) {
-        for (const child of value as unknown[]) if (astNode(child)) visit(child, node);
-      } else if (astNode(value)) visit(value, node);
-    }
+    for (const child of astChildren(node)) visit(child, node);
   };
   visit(program);
 }
-
 function hasIdentifier(node: acorn.AnyNode, name: string): boolean {
   if (node.type === "Identifier" && node.name === name) return true;
-  return Object.values(node).some((value) => Array.isArray(value) ? value.some((child) => astNode(child) && hasIdentifier(child, name)) : astNode(value) && hasIdentifier(value, name));
+  return astChildren(node).some((child) => hasIdentifier(child, name));
 }
 
 const INTERNAL_AGENT_NAME = "__pi_extensible_workflows_agent";
@@ -854,7 +856,7 @@ function staticValue(node: acorn.AnyNode | undefined): StaticValue {
 }
 
 export interface StaticWorkflowCall {
-  kind: "agent" | "conversation" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+  kind: WorkflowCallKind;
   start: number;
   end: number;
   name: string | null;
@@ -1022,7 +1024,7 @@ export class WorkflowRegistry {
       if (!jsonValue(replayed) || !Value.Check(fn.output, replayed)) fail("RESULT_INVALID", `Invalid replay for ${name}`);
       return structuredClone(replayed);
     }
-    const result: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, agent: context.agent, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
+    const result: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, invoke: context.invoke, agent: context.agent, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
     if (!jsonValue(result) || !Value.Check(fn.output, result)) fail("RESULT_INVALID", `Invalid output from ${name}`);
     const stored = structuredClone(result);
     journal.put(path, stored);
@@ -1212,7 +1214,6 @@ export function createLaunchSnapshot(input: LaunchSnapshotInput): Readonly<Launc
 }
 
 export function loadLaunchSnapshot(input: LaunchSnapshot): Readonly<LaunchSnapshot> {
-  if (object(input.settings) && Object.prototype.hasOwnProperty.call(input.settings, "maxAgentLaunches")) fail("RESUME_INCOMPATIBLE", "Persisted workflow settings contain removed maxAgentLaunches");
   return deepFreeze(structuredClone(input));
 }
 
@@ -1953,13 +1954,7 @@ class WorkflowEventPublisher {
     this.#budgetEvents.set(runId, seen);
   }
 
-  async runStarted(store: RunStore, metadata: WorkflowMetadata, background: boolean): Promise<void> {
-    await this.#publish(store, metadata, WORKFLOW_RUN_STARTED_EVENT, {});
-    if (background) await this.legacyStarted(store, metadata);
-  }
-
-  async legacyStarted(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_ASYNC_STARTED_EVENT, { id: store.runId, runId: store.runId, pid: process.pid, sessionId: store.sessionId, asyncDir: store.directory, agent: metadata.name }); }
-
+  async runStarted(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_STARTED_EVENT, {}); }
   async runResumed(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_RESUMED_EVENT, {}); }
 
   async runState(store: RunStore, metadata: WorkflowMetadata, previousState: RunState, state: RunState, reason?: string): Promise<void> {
@@ -1967,16 +1962,9 @@ class WorkflowEventPublisher {
     if ((previousState === "paused" || previousState === "interrupted" || previousState === "budget_exhausted") && state === "running") await this.runResumed(store, metadata);
   }
 
-  async runCompleted(store: RunStore, metadata: WorkflowMetadata, resultPath: string, background: boolean): Promise<void> {
-    await this.#publish(store, metadata, WORKFLOW_RUN_COMPLETED_EVENT, { resultPath });
-    if (background) await this.#publish(store, metadata, WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: true, state: "complete" });
-  }
-  async runFailed(store: RunStore, metadata: WorkflowMetadata, error: unknown, background: boolean, state: "failed" | "stopped" | "interrupted" | "budget_exhausted"): Promise<void> {
+  async runCompleted(store: RunStore, metadata: WorkflowMetadata, resultPath: string): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_COMPLETED_EVENT, { resultPath }); }
+  async runFailed(store: RunStore, metadata: WorkflowMetadata, error: unknown, state: "failed" | "stopped" | "interrupted" | "budget_exhausted"): Promise<void> {
     if (state === "failed") await this.#publish(store, metadata, WORKFLOW_RUN_FAILED_EVENT, { error: safeEventError(error) });
-    if (background) {
-      const legacyState = state === "interrupted" ? "failed" : state;
-      await this.#publish(store, metadata, WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: false, state: legacyState, ...(state === "stopped" ? { stopped: true } : {}), ...(legacyState === "budget_exhausted" || legacyState === "failed" ? { error: safeEventError(error).message } : {}) });
-    }
   }
 
   async agentState(store: RunStore, metadata: WorkflowMetadata, previous: AgentRecord | undefined, agent: AgentRecord): Promise<void> {
@@ -2133,16 +2121,26 @@ function nextNamedOccurrence(counters: Map<string, number>, label: string): stri
   return count === 1 ? label : `${label}#${String(count)}`;
 }
 
-
 function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runContext: Readonly<WorkflowRunContext>, variables: Readonly<Record<string, JsonValue>>, registry: WorkflowRegistryApi): WorkflowBridge {
   const functionAgentOccurrences = new Map<string, number>();
   const functionWorktreeOccurrences = new Map<string, number>();
-  return { ...bridge, functions: registry.globals(), variables, function: async (name, input, path, signal, worktreeOwner, structuralPath = []) => {
+  const functionInvokeOccurrences = new Map<string, number>();
+  const invokeFunction = async (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath: readonly string[] = [], breadcrumb?: string): Promise<JsonValue> => {
     const replayed = await store.replay(path);
     let stored: JsonValue | undefined;
     const sideEffects: Promise<void>[] = [];
+    const functionBreadcrumb = breadcrumb ?? name;
     const context: WorkflowFunctionContext = {
       run: runContext,
+      invoke: async (targetName, targetInput) => {
+        const inherited = inheritedHostAgentPath.getStore() ?? structuralPath;
+        const scopedWorktreeOwner = inheritedHostWorktreeOwner.getStore() ?? worktreeOwner;
+        const key = JSON.stringify([path, inherited, targetName]);
+        const occurrence = (functionInvokeOccurrences.get(key) ?? 0) + 1;
+        functionInvokeOccurrences.set(key, occurrence);
+        const nestedPath = operationPath("function", "nested", path, ...inherited, targetName, `occurrence:${String(occurrence)}`);
+        return invokeFunction(targetName, targetInput, nestedPath, signal, scopedWorktreeOwner, inherited, `${functionBreadcrumb} > ${targetName}`);
+      },
       agent: async (...args: readonly unknown[]) => {
         if (!bridge.agent || typeof args[0] !== "string") fail("AGENT_FAILED", "No agent bridge is available");
         const options = validateAgentOptions(args[1] === undefined ? {} : args[1]);
@@ -2151,7 +2149,7 @@ function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runConte
         const key = `${path}\0${JSON.stringify(inherited)}`;
         const occurrence = (functionAgentOccurrences.get(key) ?? 0) + 1;
         functionAgentOccurrences.set(key, occurrence);
-        return bridge.agent(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb: name, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
+        return bridge.agent(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb: functionBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
       },
       prompt: workflowPrompt,
       parallel: (...args: readonly unknown[]) => hostParallel(args[0], args[1]),
@@ -2168,14 +2166,62 @@ function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runConte
     await Promise.all(sideEffects);
     if (!replayed) await store.complete(path, stored ?? result);
     return result;
-  } };
+  };
+  return { ...bridge, functions: registry.globals(), variables, function: invokeFunction };
 }
 
 function projectTrusted(ctx: unknown): boolean {
   const check = object(ctx) ? ctx.isProjectTrusted : undefined;
   return typeof check === "function" ? Boolean(Reflect.apply(check, ctx, [])) : true;
 }
-
+type PiHostCapabilities = { registerEntryRenderer?: ExtensionAPI["registerEntryRenderer"]; events?: WorkflowEventSink };
+function isEntryRenderer(value: unknown): value is NonNullable<PiHostCapabilities["registerEntryRenderer"]> { return typeof value === "function"; }
+function isWorkflowEventSink(value: unknown): value is WorkflowEventSink { return object(value) && typeof value.emit === "function"; }
+function piHostCapabilities(pi: unknown): PiHostCapabilities {
+  if (!object(pi)) return {};
+  const registerEntryRenderer = pi.registerEntryRenderer;
+  const events = pi.events;
+  return { ...(isEntryRenderer(registerEntryRenderer) ? { registerEntryRenderer } : {}), ...(isWorkflowEventSink(events) ? { events } : {}) };
+}
+type ContextHostCapabilities = { modelRegistry?: ModelRegistryCapability };
+type ModelSummary = { provider: string; id: string };
+type ModelRegistryGetter = () => readonly ModelSummary[];
+type ModelRegistryCapability = { getAll?: ModelRegistryGetter; getAvailable?: ModelRegistryGetter };
+function isModelRegistryGetter(value: unknown): value is ModelRegistryGetter { return typeof value === "function"; }
+function contextHostCapabilities(ctx: unknown): ContextHostCapabilities {
+  if (!object(ctx) || !object(ctx.modelRegistry)) return {};
+  const registry = ctx.modelRegistry;
+  const getAll = registry.getAll;
+  const getAvailable = registry.getAvailable;
+  return { modelRegistry: { ...(isModelRegistryGetter(getAll) ? { getAll: () => getAll.call(registry) } : {}), ...(isModelRegistryGetter(getAvailable) ? { getAvailable: () => getAvailable.call(registry) } : {}) } };
+}
+type UiSelect = (title: string, options: string[]) => Promise<string | undefined>;
+type UiInput = (title: string, placeholder?: string) => Promise<string | undefined>;
+type UiSetStatus = (key: string, text?: string) => void;
+type UiHostCapabilities = { select?: UiSelect; input?: UiInput; setStatus?: UiSetStatus };
+function isUiSelect(value: unknown): value is UiSelect { return typeof value === "function"; }
+function isUiInput(value: unknown): value is UiInput { return typeof value === "function"; }
+function isUiSetStatus(value: unknown): value is UiSetStatus { return typeof value === "function"; }
+function uiHostCapabilities(ui: unknown): UiHostCapabilities | undefined {
+  if (!object(ui)) return undefined;
+  const select = ui.select;
+  const input = ui.input;
+  const setStatus = ui.setStatus;
+  return { ...(isUiSelect(select) ? { select } : {}), ...(isUiInput(input) ? { input } : {}), ...(isUiSetStatus(setStatus) ? { setStatus } : {}) };
+}
+type TuiHostCapabilities = { terminal?: { rows?: unknown } };
+function tuiHostCapabilities(tui: unknown): TuiHostCapabilities {
+  if (!object(tui) || !object(tui.terminal)) return {};
+  return { terminal: { ...(tui.terminal.rows === undefined ? {} : { rows: tui.terminal.rows }) } };
+}
+function tuiRows(tui: unknown): number { const rows = tuiHostCapabilities(tui).terminal?.rows; return typeof rows === "number" && Number.isFinite(rows) ? rows : 24; }
+type KeybindingsHostCapabilities = { getKeys?: (name: string) => readonly string[] };
+function isKeybindingGetter(value: unknown): value is NonNullable<KeybindingsHostCapabilities["getKeys"]> { return typeof value === "function"; }
+function keybindingsHostCapabilities(keybindings: unknown): KeybindingsHostCapabilities {
+  if (!object(keybindings) || !isKeybindingGetter(keybindings.getKeys)) return {};
+  return { getKeys: keybindings.getKeys };
+}
+function keybindingKeys(keybindings: unknown, name: string): readonly string[] | undefined { const getKeys = keybindingsHostCapabilities(keybindings).getKeys; return typeof getKeys === "function" ? getKeys.call(keybindings, name) : undefined; }
 function parseThinking(value: unknown): ModelSpec["thinking"] | undefined {
   switch (value) {
     case "off": case "minimal": case "low": case "medium": case "high": case "xhigh": case "max": return value;
@@ -2186,7 +2232,7 @@ function parseThinking(value: unknown): ModelSpec["thinking"] | undefined {
 export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard = copyToClipboard, createSession: SessionFactory = createNativeAgentSession) {
   beginWorkflowExtensionLoading();
   const registry = loadingRegistry();
-  const registerEntryRenderer = (pi as unknown as Partial<Pick<ExtensionAPI, "registerEntryRenderer">>).registerEntryRenderer;
+  const registerEntryRenderer = piHostCapabilities(pi).registerEntryRenderer;
   registerEntryRenderer?.<WorkflowLogEntry>(WORKFLOW_LOG_ENTRY, (entry) => {
     const data = entry.data;
     return textBlock(data ? `Workflow ${data.workflowName}: ${data.message}` : "");
@@ -2196,7 +2242,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     try { pi.appendEntry<WorkflowLogEntry>(WORKFLOW_LOG_ENTRY, { workflowName, message: utf8Prefix(message, DELIVERY_LIMIT_BYTES) }); }
     finally { await lifecycle.leave(); }
   };
-  const eventPublisher = new WorkflowEventPublisher((pi as unknown as { events?: WorkflowEventSink }).events);
+  const eventPublisher = new WorkflowEventPublisher(piHostCapabilities(pi).events);
   pi.on("resources_discover", () => {
     if (!pi.getActiveTools().includes("workflow")) return;
     const extensionDir = dirname(fileURLToPath(import.meta.url));
@@ -2205,6 +2251,24 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
   });
   type BudgetDecisionResult = { state: "running" | "budget_exhausted"; approved: boolean };
   const runs = new Map<string, { executor: WorkflowAgentExecutor; store: RunStore; metadata: WorkflowMetadata; model: ModelSpec; lifecycle: RunLifecycle; budget: WorkflowBudgetRuntime; abortController: AbortController; projectTrusted: () => boolean; execution?: WorkflowExecution; completion?: Promise<unknown>; checkpointResolvers: Map<string, (value: boolean) => void>; budgetResolvers: Map<string, (result: BudgetDecisionResult) => void>; update?: (result: WorkflowToolUpdate) => void }>();
+  const liveActivities = new Map<string, Map<string, AgentActivity>>();
+  const setLiveActivity = (runId: string, agentId: string, activity?: AgentActivity) => {
+    const activities = liveActivities.get(runId);
+    if (activity) {
+      if (activities) activities.set(agentId, activity);
+      else liveActivities.set(runId, new Map([[agentId, activity]]));
+    } else {
+      activities?.delete(agentId);
+      if (activities?.size === 0) liveActivities.delete(runId);
+    }
+  };
+  const withLiveActivities = (run: PersistedRun): PersistedRun => {
+    const activities = liveActivities.get(run.id);
+    return activities?.size ? { ...run, agents: run.agents.map((agent) => {
+      const activity = activities.get(agent.id);
+      return activity ? { ...agent, activity } : agent;
+    }) } : run;
+  };
   const conversationLocks = new Set<string>();
   const terminalRunStates = new Map<string, "completed" | "failed" | "stopped">();
   let sessionLease: SessionLease | undefined;
@@ -2240,7 +2304,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       return nextRun;
     });
     await eventPublisher.runState(store, metadata, previous, next, reason);
-    runs.get(store.runId)?.update?.(workflowToolUpdate(persisted));
+    runs.get(store.runId)?.update?.(workflowToolUpdate(withLiveActivities(persisted)));
   });
   const scheduler = new FairAgentScheduler(async ({ id, runId, parentId, prompt, options, signal, setSteer }) => {
     const run = runs.get(runId);
@@ -2257,7 +2321,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           runState = { ...loaded.run, ...run.budget.snapshot(), agents: loaded.run.agents.map((agent) => agent.id === id ? { ...agent, accounting: progress.accounting, toolCalls: progress.toolCalls, activity: progress.activity } : agent) };
         }
         if (!runState.agents.some((agent) => agent.id === id)) return;
-        run.update?.(workflowToolUpdate(runState));
+        setLiveActivity(runId, id, progress.activity);
+        run.update?.(workflowToolUpdate(withLiveActivities(runState)));
       };
       const onAttempt = async (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => {
         await scheduler.flush();
@@ -2268,7 +2333,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         const active = (await run.store.load()).run;
         await eventPublisher.agentStates(run.store, run.metadata, before.agents, active.agents);
         const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
-        run.update?.(workflowToolUpdate(persisted));
+        run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
       };
       const result = await run.executor.execute(prompt, { label: options.label, workflowName: run.metadata.name, onProgress, onAttempt, budget, ...(parentId ? { parent: parentId, cwd: options.cwd, ...(options.worktreeOwner ? { worktreeOwner: options.worktreeOwner } : {}) } : options.worktreeOwner ? { worktreeOwner: options.worktreeOwner } : {}), ...(options.model ? { model: options.model } : {}), ...(options.thinking ? { thinking: options.thinking } : {}), ...(options.role ? { role: options.role } : {}), ...(options.role ? {} : { tools: options.tools }), effectiveTools: options.tools, ...(options.schema ? { schema: options.schema } : {}), ...(options.retries === undefined ? {} : { retries: options.retries }), ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.agentOptions ? { agentOptions: options.agentOptions } : {}), ...(options.agentIdentity ? { agentIdentity: options.agentIdentity } : {}), ...(options.conversation ? { conversation: options.conversation } : {}) }, signal, scheduler.toolsFor(id, (role, tools, model, inheritedTools, thinking) => run.executor.resolve({ label: "child", workflowName: run.metadata.name, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(tools !== undefined ? { tools } : {}) }, inheritedTools).tools), setSteer, () => { scheduler.cancelChildren(id); scheduler.retry(id); });
       const before = (await run.store.load()).run;
@@ -2276,7 +2341,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       const completed = (await run.store.load()).run;
       await eventPublisher.agentStates(run.store, run.metadata, before.agents, completed.agents);
       const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
-      run.update?.(workflowToolUpdate(persisted));
+      setLiveActivity(runId, id);
+      run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
       return result.value;
     } catch (error) {
       const attempts = (error as WorkflowError & { attempts?: readonly AgentAttempt[] }).attempts;
@@ -2287,7 +2353,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         await eventPublisher.agentStates(run.store, run.metadata, before.agents, failed.agents);
       }
       const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
-      run.update?.(workflowToolUpdate(persisted));
+      setLiveActivity(runId, id);
+      run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
       throw error;
     }
   }, 16, async (runId, ownership) => {
@@ -2309,7 +2376,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       return { ...current, agents };
     });
     await eventPublisher.agentStates(run.store, run.metadata, previousAgents, runState.agents);
-    run.update?.(workflowToolUpdate(runState));
+    run.update?.(workflowToolUpdate(withLiveActivities(runState)));
   });
   type WorkflowStopResult = { runId: string; state: RunState | "unknown"; stopped: boolean; reason?: "unknown_run" | "already_terminal" };
   const stopWorkflowRun = async (runId: string): Promise<WorkflowStopResult> => {
@@ -2503,7 +2570,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     try { variables = await resolveWorkflowVariables(runContext, controller, registry); }
     catch (error) {
       const typed = asWorkflowError(error);
-      if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.lifecycle.terminal("failed", typed.code).catch(() => undefined); const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, error: { code: typed.code, message: typed.message } })); await eventPublisher.runFailed(run.store, run.metadata, typed, true, run.lifecycle.state === "interrupted" ? "interrupted" : "failed"); run.update?.(workflowToolUpdate(persisted)); }
+      if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.lifecycle.terminal("failed", typed.code).catch(() => undefined); const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, error: { code: typed.code, message: typed.message } })); await eventPublisher.runFailed(run.store, run.metadata, typed, run.lifecycle.state === "interrupted" ? "interrupted" : "failed"); run.update?.(workflowToolUpdate(persisted)); }
       throw typed;
     }
     await scheduler.cancelRun(run.store.runId);
@@ -2553,7 +2620,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       if (run.budget.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
       const resultPath = await run.store.saveResult(value);
       await run.lifecycle.terminal("completed", "completed");
-      await eventPublisher.runCompleted(run.store, run.metadata, resultPath, true);
+      await eventPublisher.runCompleted(run.store, run.metadata, resultPath);
       return { value, resultPath };
     }).catch(async (error: unknown) => {
       await scheduler.flush();
@@ -2561,7 +2628,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) await run.lifecycle.terminal(typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
       const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot(), error: { code: typed.code, message: typed.message } }));
       const state = run.lifecycle.state === "stopped" || run.lifecycle.state === "interrupted" || run.lifecycle.state === "budget_exhausted" ? run.lifecycle.state : "failed";
-      await eventPublisher.runFailed(run.store, run.metadata, typed, true, state);
+      await eventPublisher.runFailed(run.store, run.metadata, typed, state);
       run.update?.(workflowToolUpdate(persisted));
       if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) deliverFailure(pi, run.metadata.name, error);
     });
@@ -2650,7 +2717,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       for (const decision of await store.pendingWorkflowDecisions()) deliver(pi, budgetDecisionDelivery(loaded.snapshot.metadata, decision));
       scheduler.restoreRun(runId, loaded.snapshot.settings.concurrency, loaded.snapshot.identityVersion === LAUNCH_SNAPSHOT_IDENTITY_VERSION ? await store.loadOwnership() : [], () => runs.get(runId)?.budget.checkAgentLaunch());
     }
-    const resumeSelect = (ctx.ui as unknown as { select?: (prompt: string, options: string[]) => Promise<string | undefined> } | undefined)?.select;
+    const resumeSelect = uiHostCapabilities(ctx.ui)?.select;
     if (ctx.hasUI && resumeSelect) {
       const interrupted = [...runs.values()].filter((r) => r.lifecycle.state === "interrupted");
       if (interrupted.length > 0) {
@@ -2690,7 +2757,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       const budget = validateBudget(params.budget);
       const rootModel: ModelSpec = { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() };
       const rootModelName = `${rootModel.provider}/${rootModel.model}`;
-      const modelRegistry = (ctx as unknown as { modelRegistry?: { getAll?: () => Array<{ provider: string; id: string }>; getAvailable?: () => Array<{ provider: string; id: string }> } }).modelRegistry;
+      const modelRegistry = contextHostCapabilities(ctx).modelRegistry;
       const knownModels = new Set((modelRegistry?.getAll?.() ?? modelRegistry?.getAvailable?.() ?? [ctx.model]).map((model) => `${model.provider}/${model.id}`));
       knownModels.add(rootModelName);
       const availableModels = knownModels;
@@ -2771,13 +2838,13 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         } finally { await lifecycle.leave(); }
       }, log: logBridge(lifecycle, checked.metadata.name) }, store, runContext, variables, registry), runController.signal);
       (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).execution = execution;
-      await eventPublisher.runStarted(store, checked.metadata, background);
+      await eventPublisher.runStarted(store, checked.metadata);
       const finish = execution.result.then(async (value) => {
         await scheduler.flush();
         if (budgetRuntime.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
         const resultPath = await store.saveResult(value);
         await lifecycle.terminal("completed", "completed");
-        await eventPublisher.runCompleted(store, checked.metadata, resultPath, background);
+        await eventPublisher.runCompleted(store, checked.metadata, resultPath);
         return { value, resultPath };
       }).catch(async (error: unknown) => {
         await scheduler.flush();
@@ -2785,7 +2852,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         if (!["stopped", "interrupted", "budget_exhausted"].includes(lifecycle.state)) await lifecycle.terminal(typed.code === "CANCELLED" ? "stopped" : typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
         await persistRunState(store, checked.metadata, (current) => ({ ...current, ...budgetRuntime.snapshot(), error: { code: typed.code, message: typed.message } }));
         const state = lifecycle.state === "stopped" || lifecycle.state === "interrupted" || lifecycle.state === "budget_exhausted" ? lifecycle.state : "failed";
-        await eventPublisher.runFailed(store, checked.metadata, typed, background, state);
+        await eventPublisher.runFailed(store, checked.metadata, typed, state);
         throw typed;
       });
       (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).completion = finish;
@@ -2842,7 +2909,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       let stores = await loadStores();
       const usage = "Usage: /workflow [doctor|model-aliases], or /workflow pause|resume|stop|approve|reject|delete <run-id> [checkpoint or proposal-id]. Use workflow_resume for budget patches."
       const setWorkflowStatus = (text: string | undefined) => {
-        const setStatus = (ctx.ui as unknown as { setStatus?: (key: string, text?: string) => void }).setStatus;
+        const setStatus = uiHostCapabilities(ctx.ui)?.setStatus;
         setStatus?.call(ctx.ui, "workflow-stop", text);
       };
       const runAction = async (actionCommand: string, keepContext: boolean, status: (text: string | undefined) => void = setWorkflowStatus): Promise<"dashboard" | "picker" | "done"> => {
@@ -2883,7 +2950,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             return keepContext ? "dashboard" : "done";
           }
           if (action === "adjust" && run?.lifecycle.state === "budget_exhausted") {
-            const input = await (ctx.ui as unknown as { input?: (title: string, placeholder?: string) => Promise<string | undefined> }).input?.("Budget patch (JSON)", "{\"tokens\":{\"hard\":null}}" );
+            const input = await uiHostCapabilities(ctx.ui)?.input?.call(ctx.ui, "Budget patch (JSON)", "{\"tokens\":{\"hard\":null}}" );
             if (input === undefined) return keepContext ? "dashboard" : "done";
             const result = await resumeWorkflowRun(run.store.runId, JSON.parse(input));
             ctx.ui.notify(result.state === "running" ? `Resumed workflow ${run.store.runId}.` : `Budget adjustment for ${run.store.runId} is awaiting approval.`, result.state === "running" ? "info" : "warning");
@@ -2910,7 +2977,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       };
       const manageAliases = async (): Promise<void> => {
         const settingsPath = workflowSettingsPath();
-        const modelRegistry = (ctx as unknown as { modelRegistry?: { getAvailable?: () => Array<{ provider: string; id: string }> } }).modelRegistry;
+        const modelRegistry = contextHostCapabilities(ctx).modelRegistry;
         const available = () => [...new Set((modelRegistry?.getAvailable?.() ?? []).map((model) => `${model.provider}/${model.id}`))].sort();
         const selectTarget = async (): Promise<string | undefined> => {
           const models = available();
@@ -3016,7 +3083,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
               await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
                 let offset = 0;
                 let renderedLines: string[] = [];
-                const viewport = () => Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24) - 3);
+                const viewport = () => Math.max(1, tuiRows(tui) - 3);
                 const move = (delta: number) => { offset = Math.max(0, Math.min(Math.max(0, renderedLines.length - viewport()), offset + delta)); };
                 return {
                   render(width: number) {
@@ -3137,11 +3204,10 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                   let disposed = false;
                   let stopRequested = false;
                   let stopStatus: string | undefined;
-                  const terminalRows = () => Math.max(1, ((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24);
+                  const terminalRows = () => Math.max(1, tuiRows(tui));
                   const keyLabels: Record<string, string> = { up: "↑", down: "↓", pageUp: "pgup", pageDown: "pgdn", escape: "esc" };
                   const keyLabel = (binding: string, fallback: string) => {
-                    const getKeys = (keybindings as unknown as { getKeys?: (name: string) => readonly string[] }).getKeys;
-                    const keys = getKeys?.call(keybindings, binding);
+                    const keys = keybindingKeys(keybindings, binding);
                     return keys?.length ? keys.map((key) => keyLabels[key] ?? key).join("/") : fallback;
                   };
                   const dashboardLayout = () => {
@@ -3235,7 +3301,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                 const highlighted = highlightCode(view.script, "javascript");
                 let offset = 0;
                 let renderedLines: string[] = [];
-                const viewport = () => Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24) - 3);
+                const viewport = () => Math.max(1, tuiRows(tui) - 3);
                 const move = (delta: number) => {
                   const maxOffset = Math.max(0, renderedLines.length - viewport());
                   offset = Math.max(0, Math.min(maxOffset, offset + delta));
@@ -3289,7 +3355,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                 let offset = 0;
                 let renderedLines: string[] = [];
                 const layout = () => {
-                  const rows = Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24));
+                  const rows = Math.max(1, tuiRows(tui));
                   const compactControls = rows < 4;
                   const titleRows = rows >= 5 ? 1 : 0;
                   const hintRows = rows >= 8 ? 1 : 0;

package/src/persistence.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
 import { access, link, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
@@ -158,10 +159,28 @@ export function structuralPath(...names: string[]): string {
   return names.map((name) => encodeURIComponent(name)).join("/");
 }
 
-async function atomicJson(path: string, value: unknown): Promise<void> {
+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`;
-  await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600 });
-  await rename(temporary, path);
+  if (sync) {
+    try {
+      writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+      renameSync(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(() => rename(temporary, path)).catch(async (error: unknown) => {
+    try { await rm(temporary, { force: true }); } catch { /* Preserve the original write error. */ }
+    throw error;
+  });
+}
+
+async function atomicJson(path: string, value: unknown): Promise<void> {
+  await atomicWriteFile(path, `${JSON.stringify(value)}\n`);
 }
 
 async function json<T>(path: string): Promise<T> { return JSON.parse(await readFile(path, "utf8")) as T; }
@@ -245,7 +264,7 @@ export class RunStore {
   }
 
   async appendEvent(event: WorkflowRunEvent): Promise<void> {
-    await this.updateState((run) => ({ ...run, events: [...(run.events ?? []), ...(run.events?.some((current) => current.message === event.message) ? [] : [event])] }));
+    await this.updateState((run) => ({ ...run, events: [...(run.events ?? []), ...(run.events?.some((current) => current.type === event.type && current.message === event.message) ? [] : [event])] }));
   }
 
   async saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void> {