pi-extensible-workflows 0.3.2 → 1.0.0

package/src/persistence.ts

@@ -4,17 +4,26 @@ import { access, link, mkdir, open, readFile, readdir, rename, rm, stat, writeFi
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
-import type { JsonValue, LaunchSnapshot, RunRecord } from "./index.js";
+import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./index.js";
 import type { OwnershipRecord } from "./agent-execution.js";
 import { loadLaunchSnapshot, WorkflowError } from "./index.js";
 
 export interface NativeSessionReference { sessionId: string; sessionFile: string }
 export interface EffectiveSystemPrompt { sessionId: string; attempt: number; turn: number; sha256: string; prompt: string }
+export interface ConversationHead { turn: number; sessionId: string; sessionFile: string; leafId: string; systemPrompt: string; systemPromptSha256: string; toolDefinitionsSha256: string }
+export interface PersistedConversation { id: string; policy: JsonValue; head: ConversationHead }
+type ConversationArtifact = { version: 1; conversations: Record<string, PersistedConversation> };
+function isConversationArtifact(value: unknown): value is ConversationArtifact {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const artifact = value as { version?: unknown; conversations?: unknown };
+  return artifact.version === 1 && Boolean(artifact.conversations) && typeof artifact.conversations === "object" && !Array.isArray(artifact.conversations);
+}
 export interface PersistedRun extends RunRecord { nativeSessions: readonly NativeSessionReference[] }
 export interface CompletedOperation { path: string; value: JsonValue }
 export interface AwaitingCheckpoint { path: string; name: string; prompt: string; context: JsonValue }
+export type PendingWorkflowDecision = BudgetApprovalRequest
 export type PersistedOwnershipNode = OwnershipRecord
-type Journal = { completed: Record<string, CompletedOperation>; awaiting?: Record<string, AwaitingCheckpoint> };
+type Journal = { completed: Record<string, CompletedOperation>; awaiting?: Record<string, AwaitingCheckpoint>; decisions?: Record<string, PendingWorkflowDecision> };
 export interface WorktreeReference { owner: string; path: string; branch: string; cwd: string; base: string }
 
 const execute = promisify(execFile);
@@ -164,8 +173,10 @@ export class RunStore {
   private stateWrite: Promise<void> = Promise.resolve();
   private worktreeWrite: Promise<void> = Promise.resolve();
   private snapshotWrite: Promise<void> = Promise.resolve();
+  private launchSnapshotWrite: Promise<void> = Promise.resolve();
   // ponytail: the session lease prevents concurrent RunStore writers for one run.
   private systemPromptWrite: Promise<void> = Promise.resolve();
+  private conversationWrite: Promise<void> = Promise.resolve();
   constructor(readonly cwd: string, readonly sessionId: string, readonly runId: string, home = homedir()) {
     this.cwd = resolve(cwd);
     this.directory = join(runsDirectory(this.cwd, sessionId, home), safePart(runId));
@@ -177,12 +188,14 @@ export class RunStore {
     await mkdir(dirname(this.directory), { recursive: true, mode: 0o700 });
     await mkdir(temporary, { mode: 0o700 });
     try {
+      await writeFile(join(temporary, "workflow.js"), snapshot.script, { encoding: "utf8", mode: 0o600 });
       await atomicJson(join(temporary, "snapshot.json"), snapshot);
-      await atomicJson(join(temporary, "journal.json"), { completed: {}, awaiting: {} });
+      await atomicJson(join(temporary, "journal.json"), { completed: {}, awaiting: {}, decisions: {} });
       await atomicJson(join(temporary, "ownership.json"), []);
       await atomicJson(join(temporary, "worktrees.json"), []);
       await atomicJson(join(temporary, "state.json"), run);
       await atomicJson(join(temporary, "system-prompts.json"), { version: 1, entries: [] });
+      await atomicJson(join(temporary, "conversations.json"), { version: 1, conversations: {} });
       await rename(temporary, this.directory);
     } catch (error) {
       await rm(temporary, { recursive: true, force: true });
@@ -225,6 +238,16 @@ export class RunStore {
     return result;
   }
 
+  async saveSnapshot(snapshot: Readonly<LaunchSnapshot>): Promise<void> {
+    const write = this.launchSnapshotWrite.then(() => atomicJson(join(this.directory, "snapshot.json"), snapshot));
+    this.launchSnapshotWrite = write.catch(() => undefined);
+    await write;
+  }
+
+  async appendEvent(event: WorkflowRunEvent): Promise<void> {
+    await this.updateState((run) => ({ ...run, events: [...(run.events ?? []), ...(run.events?.some((current) => current.message === event.message) ? [] : [event])] }));
+  }
+
   async saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void> {
     await atomicJson(join(this.directory, "ownership.json"), nodes);
   }
@@ -251,6 +274,27 @@ export class RunStore {
     return (await json<{ version: 1; entries: EffectiveSystemPrompt[] }>(this.systemPromptPath()).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1 as const, entries: [] }; throw error; })).entries;
   }
 
+  conversationPath(): string { return join(this.directory, "conversations.json"); }
+  async conversation(id: string): Promise<PersistedConversation | undefined> {
+    await this.conversationWrite;
+    let artifact: ConversationArtifact;
+    try { const raw = await json<unknown>(this.conversationPath()); if (!isConversationArtifact(raw)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt"); artifact = raw; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; if (error instanceof WorkflowError) throw error; throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
+    return artifact.conversations[id];
+  }
+  async saveConversation(conversation: PersistedConversation): Promise<void> {
+    const write = this.conversationWrite.then(async () => {
+      const path = this.conversationPath();
+      let artifact: ConversationArtifact;
+      try { const raw = await json<unknown>(path); if (!isConversationArtifact(raw)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt"); artifact = raw; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") artifact = { version: 1, conversations: {} }; else if (error instanceof WorkflowError) throw error; else throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
+      const previous = artifact.conversations[conversation.id];
+      if (previous && previous.head.turn + 1 !== conversation.head.turn) throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation head is not the previous turn: ${conversation.id}`);
+      if (!previous && conversation.head.turn !== 1) throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation must start at turn one: ${conversation.id}`);
+      artifact.conversations[conversation.id] = structuredClone(conversation);
+      await atomicJson(path, artifact);
+    });
+    this.conversationWrite = write.catch(() => undefined);
+    await write;
+  }
   private async updateJournal<T>(update: (journal: Journal) => T | Promise<T>): Promise<T> {
     let result!: T;
     const write = this.journalWrite.then(async () => {
@@ -291,13 +335,30 @@ export class RunStore {
     const journal = await json<Journal>(join(this.directory, "journal.json"));
     return Object.values(journal.awaiting ?? {});
   }
+  async requestWorkflowDecision(request: PendingWorkflowDecision): Promise<void> {
+    await this.updateJournal((journal) => { journal.decisions ??= {}; journal.decisions[request.proposalId] = request; });
+  }
+  async pendingWorkflowDecisions(): Promise<readonly PendingWorkflowDecision[]> {
+    await this.journalWrite;
+    const journal = await json<Journal>(join(this.directory, "journal.json"));
+    return Object.values(journal.decisions ?? {});
+  }
+  async answerWorkflowDecision(proposalId: string, approved: boolean): Promise<PendingWorkflowDecision | undefined> {
+    return this.updateJournal((journal) => {
+      const request = journal.decisions?.[proposalId];
+      if (!request) return undefined;
+      journal.completed[`decision/${proposalId}`] = { path: `decision/${proposalId}`, value: approved };
+      delete journal.decisions?.[proposalId];
+      return request;
+    });
+  }
 
   async answerCheckpoint(name: string, approved: boolean): Promise<AwaitingCheckpoint | undefined> {
     return this.updateJournal((journal) => {
-      const checkpoint = Object.values(journal.awaiting as Record<string, AwaitingCheckpoint>).find((item) => item.name === name);
+      const checkpoint = Object.values(journal.awaiting ?? {}).find((item) => item.name === name);
       if (!checkpoint || journal.completed[checkpoint.path]) return undefined;
       journal.completed[checkpoint.path] = { path: checkpoint.path, value: approved };
-      journal.awaiting = Object.fromEntries(Object.entries(journal.awaiting as Record<string, AwaitingCheckpoint>).filter(([path]) => path !== checkpoint.path));
+      journal.awaiting = Object.fromEntries(Object.entries(journal.awaiting ?? {}).filter(([path]) => path !== checkpoint.path));
       return checkpoint;
     });
   }
@@ -412,8 +473,16 @@ export class RunStore {
     try {
       const write = this.snapshotWrite.then(async () => {
         const record = await this.worktree(owner);
-        await git(record.path, ["add", "-A"]);
-        if ((await git(record.path, ["status", "--porcelain"])).trim()) await git(record.path, ["commit", "-m", "pi-extensible-workflows runtime snapshot"], gitIdentity);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+          await git(record.path, ["add", "-A"]);
+          if (!(await git(record.path, ["status", "--porcelain"])).trim()) break;
+          try {
+            await git(record.path, ["commit", "-m", "pi-extensible-workflows runtime snapshot"], gitIdentity);
+            break;
+          } catch (error) {
+            if (attempt === 2) throw error;
+          }
+        }
         return (await git(record.path, ["rev-parse", "HEAD"])).trim();
       });
       this.snapshotWrite = write.then(() => undefined, () => undefined);

package/src/session-inspector.ts

@@ -4,13 +4,13 @@ import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { highlightCode, initTheme, SessionManager, truncateToVisualLines, type SessionEntry, type SessionInfo } from "@earendil-works/pi-coding-agent";
-import { inspectWorkflowScript, type ModelSpec, type StaticWorkflowCall } from "./index.js";
+import { formatBudgetStatus, inspectWorkflowScript, type AgentSetupSummary, type ModelSpec, type StaticWorkflowCall } from "./index.js";
 import { listRunIds, RunStore, type PersistedRun } from "./persistence.js";
 
 export interface ModelUsage { model: string; cost: number }
-export interface AttemptReport { attempt: number; prompt: string; model: string; thinking?: ModelSpec["thinking"]; cost: number; models: readonly ModelUsage[]; error?: string }
-export interface AgentReport { name: string; label?: string; state: string; role?: string; model: string; thinking?: ModelSpec["thinking"]; cost: number; attempts: readonly AttemptReport[] }
-export interface WorkflowReport { name: string; description?: string; status: string; runId?: string; script?: string; calls: readonly StaticWorkflowCall[]; parseError?: string; cost: number; models: readonly ModelUsage[]; agents: readonly AgentReport[] }
+export interface AttemptReport { attempt: number; prompt: string; model: string; thinking?: ModelSpec["thinking"]; cost: number; models: readonly ModelUsage[]; error?: string; setup?: AgentSetupSummary }
+export interface AgentReport { name: string; label?: string; state: string; role?: string; requestedModel?: string; model: string; thinking?: ModelSpec["thinking"]; cost: number; attempts: readonly AttemptReport[]; setup?: AgentSetupSummary }
+export interface WorkflowReport { name: string; description?: string; status: string; runId?: string; script?: string; calls: readonly StaticWorkflowCall[]; parseError?: string; cost: number; models: readonly ModelUsage[]; agents: readonly AgentReport[]; budget?: PersistedRun["budget"]; budgetVersion?: number; usage?: PersistedRun["usage"]; budgetEvents?: PersistedRun["budgetEvents"]; events?: readonly { type: string; message: string }[] }
 export interface SessionReport { id: string; cwd: string; path: string; cost: number; models: readonly ModelUsage[]; workflows: readonly WorkflowReport[]; totalCost: number; totalModels: readonly ModelUsage[] }
 export interface InspectorViewState { view: "list" | "detail" | "script"; selected: number; scroll: number }
 
@@ -163,6 +163,7 @@ async function agentReport(agent: PersistedRun["agents"][number]): Promise<Agent
         cost,
         models: log.models.length ? log.models : [{ model, cost }],
         ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}),
+        ...(attempt.setup ? { setup: attempt.setup } : {}),
       });
       continue;
     }
@@ -175,6 +176,7 @@ async function agentReport(agent: PersistedRun["agents"][number]): Promise<Agent
       cost,
       models: [{ model: fallbackModel, cost }],
       ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}),
+      ...(attempt.setup ? { setup: attempt.setup } : {}),
     });
   }
   if (!attempts.length) {
@@ -182,7 +184,7 @@ async function agentReport(agent: PersistedRun["agents"][number]): Promise<Agent
     attempts.push({ attempt: 1, prompt: "(transcript unavailable)", model: fallbackModel, ...(fallbackThinking !== undefined ? { thinking: fallbackThinking } : {}), cost, models: [{ model: fallbackModel, cost }] });
   }
   const latest = attempts[attempts.length - 1];
-  return { name: agent.name, ...(agent.label ? { label: agent.label } : {}), state: agent.state, ...(agent.role ? { role: agent.role } : {}), model: latest?.model ?? fallbackModel, ...(latest?.thinking !== undefined ? { thinking: latest.thinking } : {}), cost: attempts.reduce((sum, attempt) => sum + attempt.cost, 0), attempts };
+  return { name: agent.name, ...(agent.label ? { label: agent.label } : {}), state: agent.state, ...(agent.role ? { role: agent.role } : {}), ...(agent.requestedModel ? { requestedModel: agent.requestedModel } : {}), model: latest?.model ?? fallbackModel, ...(latest?.thinking !== undefined ? { thinking: latest.thinking } : {}), cost: attempts.reduce((sum, attempt) => sum + attempt.cost, 0), attempts, ...(latest?.setup ? { setup: latest.setup } : {}) };
 }
 
 export function matchSession(query: string, sessions: readonly SessionInfo[]): SessionInfo {
@@ -229,6 +231,11 @@ export async function loadSessionReport(path: string, home = homedir()): Promise
       cost: agents.reduce((sum, agent) => sum + agent.cost, 0),
       models,
       agents,
+      ...(loaded?.run.budget ? { budget: loaded.run.budget } : {}),
+      ...(loaded?.run.budgetVersion !== undefined ? { budgetVersion: loaded.run.budgetVersion } : {}),
+      ...(loaded?.run.usage ? { usage: loaded.run.usage } : {}),
+      ...(loaded?.run.budgetEvents ? { budgetEvents: loaded.run.budgetEvents } : {}),
+      ...(loaded?.run.events?.length ? { events: loaded.run.events } : {})
     });
   }
   const workflowCost = workflows.reduce((sum, workflow) => sum + workflow.cost, 0);
@@ -253,7 +260,9 @@ function detailLines(workflow: WorkflowReport): string[] {
     style(ansi.bold + ansi.cyan, workflow.name),
     `${workflow.status} · ${money(workflow.cost)}${workflow.runId ? ` · ${workflow.runId}` : ""}`,
     workflow.description ?? "",
+    ...(workflow.events?.length ? ["", style(ansi.bold, "Run events"), ...workflow.events.map((event) => `${event.type}: ${event.message}`)] : []),
     "",
+    ...(workflow.budget ? formatBudgetStatus({ budget: workflow.budget, ...(workflow.budgetVersion !== undefined ? { budgetVersion: workflow.budgetVersion } : {}), ...(workflow.usage ? { usage: workflow.usage } : {}), ...(workflow.budgetEvents ? { budgetEvents: workflow.budgetEvents } : {}) }).map((line) => `Budget ${line}`) : []),
     style(ansi.bold, "Models"),
     modelSummary(workflow.models),
     "",
@@ -267,9 +276,18 @@ function detailLines(workflow: WorkflowReport): string[] {
   ];
   if (!workflow.agents.length) lines.push("(no agent run was persisted)");
   for (const agent of workflow.agents) {
-    lines.push("", style(agent.state === "completed" ? ansi.green : agent.state === "failed" ? ansi.red : ansi.yellow, `${agent.label ?? agent.name} [${agent.state}]`), `${agent.role ? `role=${agent.role} · ` : ""}${agent.model}${agent.thinking !== undefined ? `:${agent.thinking}` : ""} · ${money(agent.cost)}`);
+    lines.push("", style(agent.state === "completed" ? ansi.green : agent.state === "failed" ? ansi.red : ansi.yellow, `${agent.label ?? agent.name} [${agent.state}]`), `${agent.role ? `role=${agent.role} · ` : ""}${agent.requestedModel ? `requested=${agent.requestedModel} · ` : ""}${agent.model}${agent.thinking !== undefined ? `:${agent.thinking}` : ""} · ${money(agent.cost)}`);
     for (const attempt of agent.attempts) {
-      lines.push(`Attempt ${String(attempt.attempt)} · ${attempt.model}${attempt.thinking !== undefined ? `:${attempt.thinking}` : ""} · ${money(attempt.cost)}${attempt.error ? ` · ${attempt.error}` : ""}`, `Prompt: ${attempt.prompt}`);
+      lines.push(`Attempt ${String(attempt.attempt)} · ${attempt.model}${attempt.thinking !== undefined ? `:${attempt.thinking}` : ""} · ${money(attempt.cost)}${attempt.error ? ` · ${attempt.error}` : ""}`, `Prompt: ${attempt.prompt}`, ...(attempt.setup ? [
+        `Hooks: ${attempt.setup.hookNames.join(", ") || "(none)"}`,
+        `Effective: model=${attempt.setup.model.provider}/${attempt.setup.model.model}${attempt.setup.model.thinking ? `:${attempt.setup.model.thinking}` : ""} tools=${attempt.setup.tools.join(",") || "(none)"} cwd=${attempt.setup.cwd}`,
+        ...(attempt.setup.disabledAgentResources ? [
+          `Disabled skills: ${attempt.setup.disabledAgentResources.skills.join(", ") || "(none)"}`,
+          `Disabled extensions: ${attempt.setup.disabledAgentResources.extensions.join(", ") || "(none)"}`,
+          `Unmatched skills: ${attempt.setup.disabledAgentResources.unmatchedSkills.join(", ") || "(none)"}`,
+          `Unmatched extensions: ${attempt.setup.disabledAgentResources.unmatchedExtensions.join(", ") || "(none)"}`,
+        ] : []),
+      ] : []));
     }
   }
   return lines.filter((line, index) => line || index !== 2);

package/src/workflow-evals.ts

@@ -95,7 +95,7 @@ export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "ba
 const EVAL_MODEL_TOKEN = "$EVAL_MODEL";
 const semantic = (description: string): readonly SemanticCriterion[] => [{ id: "intent", description }];
 const JSON_RESULT_TYPES = ["null", "boolean", "number", "integer", "string", "array", "object"] as const;
-const WORKFLOW_CALL_KINDS = ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"] as const;
+const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"] as const;
 const AGENT_OPTION_NAMES = ["role", "model", "thinking", "tools", "retries"] as const;
 const expectationKeys = ["firstSignificantAction", "firstTool", "firstBatchToolSequence", "parentToolSequence", "workflowCallCount", "requiredOperations", "forbiddenOperations", "requiredRoles", "minimumAgentCalls", "requireOutputSchema", "expectedResults", "agentPolicies", "requiredAgentOrder", "requiredAgentStructures", "requiredDataFlow"] as const;
 const caseKeys = ["id", "prompt", "timeoutMs", "maxCost", "expectations", "expectedWorkflowCalls", "semanticCriteria"] as const;