@parcha/agentrun-pi 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/extension.js

@@ -1,22 +1,43 @@
-import { Type } from 'typebox';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { Compile } from 'typebox/compile';
 import { Text } from '@earendil-works/pi-tui';
 import { createReadToolDefinition, createBashToolDefinition, createEditToolDefinition, createWriteToolDefinition, createGrepToolDefinition, createFindToolDefinition, createLsToolDefinition, VERSION as PI_VERSION, } from '@earendil-works/pi-coding-agent';
-import { formatWorkflowTree, inspectWorkflow } from '@parcha/agentrun-dsl';
+import { formatWorkflowTree, inspectWorkflow, AUTHOR_SKILL_NAME } from '@parcha/agentrun-dsl';
 import { createJevRunner } from '@parcha/agentrun-jev';
 import { createPiHostRunner, PI_MODEL_SETUP_MESSAGE } from './host-session.js';
-import { WorkflowExtensionService, extensionStructuralLimits } from './extension-service.js';
+import { piHostLine } from './pi-host.js';
+import { workflowToolContext } from './tool-context.js';
+import { WorkflowExtensionService, ExtensionServiceError, extensionStructuralLimits } from './extension-service.js';
 import { demoInput, demoSearchTool, demoWorkflow, scriptedDemoDeps } from './demo.js';
 import { cleanText as safe, formatRunReport, modelJson } from './presentation.js';
-import { loadPiJevGuide, loadPiWorkflowGuide } from './skill-bundle.js';
 import { ToolInputValidationError, toolInputProblems } from './tool-input-error.js';
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RecoveryError, fileStore, openRecovery, withRecovery } from '@parcha/agentrun-dsl/recovery';
+import { readSopFile, missingSopSections, sopDigest } from './sop.js';
+import { WorkflowStore, WorkflowStoreError } from './workflow-store.js';
+import { WorkflowObservation, workflowView, formatWorkflowView, progressLines, readable } from './workflow-view.js';
+import { showWorkflowInspector } from './workflow-inspector.js';
+import { authoringReferences, describeTools, dryRunDraft, formatDryRun, inspectCandidate, workflowToolParameters } from './workflow-tool.js';
+import { supportTriageWorkflow, supportTriageInputs, supportTriageTools, scriptedSupportTriageDeps } from './triage-demo.js';
+import { restoreWorkflowSession, workflowRunHistory } from './workflow-session.js';
 const constructors = {
     read: createReadToolDefinition, bash: createBashToolDefinition, edit: createEditToolDefinition,
     write: createWriteToolDefinition, grep: createGrepToolDefinition, find: createFindToolDefinition, ls: createLsToolDefinition,
 };
 const mutatingTools = new Set(['bash', 'edit', 'write']);
-const help = 'Describe a task: /agentrun <what you want done>\nTry it without keys: /agentrun demo | demo empty\nUse real Pi and Jev calls: /agentrun demo live\nInspect: /agentrun · Rerun: /agentrun run · Setup: /agentrun status\nStop: /agentrun stop (Escape does not cancel slash-started runs)';
+const help = 'Describe a task: /agentrun <what you want done>\nTry support triage: /agentrun triage (fictional, no model calls)\nInspect: /agentrun · Change input: /agentrun input\nSave: /agentrun save <name> · Load: /agentrun load <name>\nLibrary: /agentrun list · History: /agentrun history\nRun: /agentrun run · Dry run: /agentrun dry-run · SOP text: /agentrun sop <file> · Setup: /agentrun status\nStop: /agentrun stop (closing the inspector does not stop a run)\nOther examples: /agentrun demo | demo empty | demo live';
 const textResult = (text, details = {}) => ({ content: [{ type: 'text', text: safe(text) }], details });
+function singleTextInput(workflow) {
+    const source = workflow;
+    const schema = source?.input?.schemaId && source.schemas?.[source.input.schemaId];
+    if (schema?.type !== 'object' || !schema.properties || typeof schema.properties !== 'object')
+        return;
+    const keys = Object.keys(schema.properties);
+    return keys.length === 1 && schema.required?.length === 1 && schema.required[0] === keys[0]
+        && schema.properties[keys[0]]?.type === 'string' ? keys[0] : undefined;
+}
 const nativeLimits = Object.freeze({ deadlineMs: 600_000, modelRequests: 50, judgeCalls: 100, toolAttempts: 100,
     nodeMaxTurns: 8, nodeMaxSubmissions: 3, nodeTimeoutMs: 120_000 });
 /** Configure the native extension without granting configuration to workflow authors. */
@@ -29,13 +50,15 @@ export function createAgentRunExtension(options = {}) {
         throw new Error('onToolAttempt must be a host callback');
     if (options.onWorkflowEvent !== undefined && typeof options.onWorkflowEvent !== 'function')
         throw new Error('onWorkflowEvent must be a host callback');
+    if (options.sop !== undefined && (typeof options.sop !== 'string' || !options.sop.trim()))
+        throw new Error('sop must be nonempty text');
     const limits = { ...nativeLimits, ...options.runtimeLimits };
     for (const [key, value] of Object.entries(limits)) {
         if (!(key in nativeLimits) || value !== null && (!Number.isSafeInteger(value) || value < 1 || value > nativeLimits[key])) {
             throw new Error('runtimeLimits must use known fields with positive bounded integers or explicit null');
         }
     }
-    const configured = { hostTools: options.hostTools, createJudge: options.createJudge, onToolAttempt: options.onToolAttempt, onWorkflowEvent: options.onWorkflowEvent,
+    const configured = { hostTools: options.hostTools, createJudge: options.createJudge, onToolAttempt: options.onToolAttempt, onWorkflowEvent: options.onWorkflowEvent, sop: options.sop,
         runtimeLimits: Object.freeze(limits) };
     return pi => registerExtension(pi, configured);
 }
@@ -61,15 +84,17 @@ function registerExtension(pi, configuration) {
                 if (typeof tool.execute !== 'function' || !tool.parameters || typeof tool.parameters !== 'object')
                     throw new Error('Host tools require an executable definition and parameter schema');
                 Compile(tool.parameters);
+                if (tool.resultSchema)
+                    Compile(tool.resultSchema);
                 names.add(tool.name);
-                return { ...tool, parameters: structuredClone(tool.parameters) };
+                return { ...tool, parameters: structuredClone(tool.parameters), ...(tool.resultSchema ? { resultSchema: structuredClone(tool.resultSchema) } : {}) };
             });
         }
         const active = new Set(pi.getActiveTools());
         const builtins = new Set(pi.getAllTools().filter(t => t.sourceInfo.source === 'builtin').map(t => t.name));
         const definitions = Object.entries(constructors).filter(([name]) => active.has(name) && builtins.has(name) && (trusted || !mutatingTools.has(name)))
             .map(([, factory]) => factory(ctx.cwd));
-        return [demoSearchTool(), ...definitions];
+        return [demoSearchTool(), ...supportTriageTools(), ...definitions];
     };
     const state = async (ctx) => {
         const key = `${ctx.sessionManager.getSessionId()}:${ctx.cwd}`;
@@ -84,17 +109,50 @@ function registerExtension(pi, configuration) {
             await old.inFlight;
         }
         const tools = toolSet(ctx);
-        current = { key, clearStatus: () => { if (ctx.hasUI) {
+        current = { key, sessionFile: () => ctx.sessionManager.getSessionFile(), clearStatus: () => { if (ctx.hasUI) {
                 ctx.ui.setStatus('agentrun', undefined);
                 ctx.ui.setWidget('agentrun', undefined);
             } }, tools, toolNames: tools.map(t => t.name), input: {}, busy: false, closed: false,
             service: new WorkflowExtensionService({ allowedTools: tools.map(t => t.name), limits: serviceLimits }) };
+        const restored = restoreWorkflowSession(ctx.sessionManager.getBranch());
+        if (restored) {
+            current.draft = restored.workflow;
+            current.input = restored.input;
+            current.demo = restored.demo;
+            current.savedName = restored.savedName;
+            current.report = restored.report;
+            current.observation = restored.observation;
+            current.runId = restored.runId;
+            current.sop = restored.sop;
+        }
         return current;
     };
+    const persist = (s, running = false, closing = false) => {
+        if (current !== s || s.closed && !closing || !s.draft)
+            return;
+        const record = { version: 1, workflow: s.draft,
+            input: s.input, running, createdAt: new Date().toISOString(),
+            ...(s.savedName ? { savedName: s.savedName } : {}), ...(s.demo ? { demo: s.demo } : {}),
+            ...(s.runId ? { runId: s.runId } : {}), ...(s.report ? { report: s.report } : {}),
+            ...(s.observation ? { observation: s.observation } : {}), ...(s.sop ? { sop: s.sop } : {}), };
+        try {
+            const data = structuredClone(record);
+            // Never advertise history that this release cannot restore (including
+            // non-JSON or oversized receipts). Display/retention limits are not run limits.
+            if (!restoreWorkflowSession([{ type: 'custom', customType: 'agentrun:snapshot', data }]))
+                throw new Error('Unrestorable workflow receipt');
+            pi.appendEntry('agentrun:snapshot', data);
+            const file = s.sessionFile();
+            s.persistenceWarning = file && existsSync(file) ? undefined : 'Run receipts are in memory only: Pi has not yet persisted this session. Named procedure saves are durable; begin a normal Pi conversation to persist native session history.';
+        }
+        catch {
+            s.persistenceWarning = 'Run state could not be retained in the Pi session. Keep this session open; named workflow saving is separate.';
+        }
+    };
     const readiness = (ctx, s) => ({
-        skill: pi.getCommands().some(item => item.name === 'skill:agentrun-author' && item.source === 'skill'),
+        skill: pi.getCommands().some(item => item.name === `skill:${AUTHOR_SKILL_NAME}` && item.source === 'skill'),
         pi: !!ctx.model && ctx.modelRegistry.getAll().some(model => model.id === ctx.model?.id && model.provider === ctx.model?.provider && model.api === ctx.model?.api),
-        jev: !!configuration.createJudge || !!process.env.TYPESAFE_API_KEY?.trim(), sop: false, running: s.busy, workflow: !!s.draft,
+        jev: !!configuration.createJudge || !!process.env.TYPESAFE_API_KEY?.trim(), sop: !!configuration.sop || !!s.sop, running: s.busy, workflow: !!s.draft,
         mode: s.draft ? s.demo ? 'scripted' : 'live' : undefined,
     });
     const show = (s, content, details = {}) => {
@@ -103,7 +161,7 @@ function registerExtension(pi, configuration) {
         pi.sendMessage({ customType: 'agentrun', content: safe(content), display: true, details });
     };
     const commandError = (s, error) => {
-        const message = error instanceof Error && (error.name === 'ExtensionServiceError' || /^(No workflow|Inspect a workflow|A workflow|Cannot inspect|Workflow|Code|Executable|Unsupported|Invalid workflow|AgentRun requires|AgentRun authoring|The active Pi)/.test(error.message))
+        const message = error instanceof Error && (error instanceof WorkflowStoreError || error.name === 'ExtensionServiceError' || /^(No workflow|Inspect a workflow|A workflow|Cannot inspect|Workflow|Code|Executable|Unsupported|Invalid workflow|AgentRun requires|AgentRun authoring|The active Pi|Saved workflow|SOP|The SOP|Use \/agentrun sop)/.test(error.message))
             ? error.message.slice(0, 2000) : 'AgentRun could not complete this operation. Use /agentrun status to check setup and /agentrun to inspect the workflow. No fallback was selected.';
         show(s, message);
     };
@@ -118,30 +176,42 @@ function registerExtension(pi, configuration) {
         const candidate = workflow === undefined ? s.draft : workflow;
         if (candidate === undefined)
             throw new Error('No workflow yet. Describe a task with /agentrun <task>.');
-        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
-            throw new Error('Cannot inspect workflow: workflow must be a JSON object, not a JSON-encoded string or array. Pass the complete object directly.');
-        }
         // Include active tools available only with operator trust, without granting that trust.
         // Execution rechecks the actual per-run permissions and captures implementations.
         const checker = new WorkflowExtensionService({ allowedTools: toolSet(ctx, true).map(tool => tool.name), limits: serviceLimits });
-        let inspection;
-        try {
-            inspection = checker.preflight(candidate, input);
-            if (inspection.requires.sopSections.length)
-                throw new Error('Native Pi does not supply SOP text in V1; use a configured SDK host. Keep the required sections intact.');
-        }
-        catch (error) {
-            throw new Error(`Cannot inspect workflow: ${error instanceof Error ? error.message : 'Invalid workflow'}`);
-        }
+        const { inspection, tree } = inspectCandidate(checker, candidate, input);
         // Stage the definition and input together only after nonexecuting checks succeed.
         const nextDraft = workflow === undefined ? s.draft : structuredClone(workflow);
         const changed = !s.draft || inspectWorkflow(s.draft).sha256 !== inspection.sha256;
         const nextInput = input === undefined ? changed ? {} : s.input : structuredClone(input);
         s.draft = nextDraft;
-        if (changed)
+        if (changed) {
             s.demo = undefined;
+            s.savedName = undefined;
+            s.observation = undefined;
+            s.report = undefined;
+            s.runId = undefined;
+        }
+        if (input !== undefined) {
+            s.observation = undefined;
+            s.report = undefined;
+            s.runId = undefined;
+        }
         s.input = nextInput;
-        return { inspection, tree: formatWorkflowTree(inspection) };
+        if (workflow !== undefined || input !== undefined)
+            persist(s);
+        return { inspection, tree };
+    };
+    const view = (ctx, s) => {
+        const result = workflowView(s.draft, { input: s.input,
+            observation: s.observation, report: s.report, running: s.busy, savedName: s.savedName,
+            mode: s.demo ? 'scripted · fictional · no model calls' : 'live adapters',
+            model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : 'not selected', limits,
+            availableTools: toolSet(ctx).map(tool => tool.name),
+        });
+        if (s.persistenceWarning)
+            result.summary.push(s.persistenceWarning);
+        return result;
     };
     const depsFor = (ctx, s, signal) => {
         let modelCalls = 0, toolCalls = 0;
@@ -212,17 +282,37 @@ function registerExtension(pi, configuration) {
                     throw new Error('Workflow requested an unavailable tool');
                 let result;
                 try {
-                    result = await tool.execute('agentrun-effect', input, effectSignal, undefined, ctx);
+                    result = await tool.execute('agentrun-effect', input, effectSignal, undefined, workflowToolContext(ctx));
                 }
                 catch (error) {
                     if (error instanceof ToolInputValidationError)
                         throw new ToolInputValidationError(node.label, tool.name, error.problems);
                     throw error;
                 }
-                return !configuration.hostTools && node.tool === 'search' ? result.details : { content: result.content, ...(result.details === undefined ? {} : { details: result.details }) };
+                return !configuration.hostTools && ['search', 'support_demo_lookup', 'support_demo_handoff'].includes(node.tool ?? '') ? result.details : { content: result.content, ...(result.details === undefined ? {} : { details: result.details }) };
             },
         };
     };
+    /** The SOP text a run of a workflow naming `needed` sections uses: the host's, else the file the operator named. */
+    const sopFor = async (ctx, s, needed) => {
+        if (!needed.length)
+            return undefined;
+        let sop;
+        if (configuration.sop)
+            sop = { text: configuration.sop, sha256: sopDigest(configuration.sop) };
+        else if (s.sop) {
+            const read = await readSopFile(ctx.cwd, s.sop.file);
+            if (read.sha256 !== s.sop.sha256)
+                throw new Error(`SOP file ${s.sop.file} changed since it was supplied. Run /agentrun sop ${s.sop.file} again to use the new text.`);
+            sop = read;
+        }
+        else
+            throw new Error(`Workflow requires SOP text for ${needed.map(name => `"${name}"`).join(', ')}. Supply it with /agentrun sop <file>.`);
+        const missing = missingSopSections(sop.text, needed);
+        if (missing.length)
+            throw new Error(`SOP text has no "## <section>" heading for ${missing.map(name => `"${name}"`).join(', ')}.`);
+        return sop;
+    };
     const execute = async (ctx, s, input, options = {}) => {
         if (s.busy)
             throw new Error('A workflow is already running. Use /agentrun stop first.');
@@ -233,9 +323,9 @@ function registerExtension(pi, configuration) {
         s.controller = new AbortController();
         const signals = [s.controller.signal, options.signal, ctx.signal].filter((v) => !!v);
         const signal = AbortSignal.any(signals);
+        let driver;
         try {
-            if (inspectWorkflow(s.draft).requires.sopSections.length)
-                throw new Error('Workflow requires SOP text. Native Pi does not supply SOP text in V1; use a configured SDK host. Keep the required sections intact.');
+            const sop = await sopFor(ctx, s, inspectWorkflow(s.draft).requires.sopSections);
             signal.throwIfAborted();
             const available = toolSet(ctx, options.trusted);
             if (available.map(t => t.name).join(',') !== s.toolNames.join(',')) {
@@ -247,55 +337,129 @@ function registerExtension(pi, configuration) {
             }
             // Resolve implementations from the execution context even if names are unchanged.
             s.tools = available;
+            // Validate the actual input before asking for model credentials or executing code probes.
+            s.service.preflight(s.draft, input);
             const prepared = s.service.prepare(s.draft, { allowExecutableCandidates: options.trusted ?? false });
+            // Adapter admission is not a run. Failed setup must not leave a running receipt.
+            const deps = scripted
+                ? s.demo === 'triage' || s.demo === 'triage-failure' ? scriptedSupportTriageDeps({ failLookup: s.demo === 'triage-failure' }) : scriptedDemoDeps(s.demo === 'empty')
+                : depsFor(ctx, s, signal);
             s.input = structuredClone(input);
             const tree = formatWorkflowTree(inspectWorkflow(s.draft));
             const label = scripted ? 'Scripted demo — fictional sources; no model calls.' : `Running with Pi · ${limits.deadlineMs === null ? 'no workflow deadline; operator cancellation remains available' : `${limits.deadlineMs / 1000}-second workflow deadline`}. Jev is used only for system one nodes.`;
             options.update?.(textResult(`${label}\n\n${tree}`));
             stage(ctx, s, 'agent.run() · starting');
-            let completed = 0;
-            const active = new Map();
+            const observation = new WorkflowObservation();
+            // A run this session left interrupted or failed, over the same draft and input, continues from its journal;
+            // anything else starts a new run.
+            const runRoot = join(ctx.cwd, '.pi', 'agentrun', 'runs');
+            const resumable = !scripted && s.runId !== undefined && ['interrupted', 'failed'].includes(s.report?.status ?? '') && existsSync(join(runRoot, s.runId));
+            let runId = resumable ? s.runId : randomUUID();
+            if (!scripted) {
+                await mkdir(runRoot, { recursive: true });
+                const bind = { input: s.input, tools: [...s.toolNames].sort(), ...(sop ? { sop: sop.sha256 } : {}) };
+                const open = (id) => openRecovery(fileStore(join(runRoot, id)), s.draft, { key: id, view: prepared.workflow, bind });
+                try {
+                    try {
+                        driver = await open(runId);
+                    }
+                    catch (error) {
+                        // A run bound to other input, SOP text or tools is a different run: it starts anew, and the old journal stays.
+                        if (!resumable || !(error instanceof RecoveryError) || error.code !== 'RUN_STORE_BINDING_MISMATCH')
+                            throw error;
+                        runId = randomUUID();
+                        driver = await open(runId);
+                    }
+                }
+                catch (error) {
+                    throw new Error(`Cannot ${resumable ? 'resume' : 'start'} run ${runId}: ${error instanceof Error ? error.message : 'recovery store refused'}`);
+                }
+                s.pause = () => driver.stop({ action: 'pause', source: 'operator' });
+            }
+            s.observation = observation.data;
+            s.report = undefined;
+            s.runId = runId;
+            persist(s, true);
             const ordinal = ++runOrdinal;
             let sequence = 0;
             const report = await s.service.run(s.input, {
-                deps: scripted ? scriptedDemoDeps(s.demo === 'empty') : depsFor(ctx, s, signal), signal,
+                deps: observation.observe(driver ? withRecovery(driver, sop ? { ...deps, sop: sop.text } : deps) : sop ? { ...deps, sop: sop.text } : deps),
+                signal: driver ? AbortSignal.any([signal, driver.signal]) : signal,
                 ...(configuration.onWorkflowEvent ? { onTraceEvent: (event) => configuration.onWorkflowEvent({ workflowDigest: prepared.digest, runOrdinal: ordinal, sequence: ++sequence, event }) } : {}),
                 onEvent: event => {
-                    if (current !== s || s.closed || !event.label)
+                    observation.record(event);
+                    if (current !== s || s.closed)
                         return;
-                    if (event.type === 'node.start')
-                        active.set(event.label, (active.get(event.label) ?? 0) + 1);
-                    else if (event.type === 'node.end') {
-                        const count = (active.get(event.label) ?? 1) - 1;
-                        if (count)
-                            active.set(event.label, count);
-                        else
-                            active.delete(event.label);
-                        completed++;
-                    }
+                    const progress = progressLines(observation.data);
+                    if (ctx.mode === 'tui')
+                        ctx.ui.setWidget('agentrun', [safe(prepared.inspection.name), ...progress.map(safe), '/agentrun inspect · /agentrun stop']);
                     else
-                        return;
-                    const running = [...active].map(([name, count]) => count > 1 ? `${name} ×${count}` : name).join(', ');
-                    const progress = `agent.run() · ${completed} finished${running ? ` · ${running}` : ''}`;
-                    stage(ctx, s, progress);
-                    if (ctx.hasUI)
-                        ctx.ui.setWidget('agentrun', [safe(progress), '/agentrun stop to cancel']);
-                    options.update?.(textResult(`${label}\n\n${tree}\n\n${progress}`));
+                        options.update?.(textResult(`${label}\n\n${progress.join('\n')}`));
                 },
             });
+            if (driver && report.error?.code === 'FROZEN_EFFECT_UNKNOWN') {
+                // The journal names what the driver refused to repeat. Read it once the driver has let go of it.
+                await driver.close().catch(() => { });
+                const journal = await readFile(join(runRoot, runId, 'journal.json'), 'utf8').then(text => JSON.parse(text), () => undefined);
+                const unknown = (journal?.effects ?? []).filter(effect => effect.status === 'unknown').slice(0, 100);
+                if (unknown.length)
+                    report.uncertainEffects = unknown.map(effect => ({ idempotencyKey: effect.id, outcome: 'unknown' }));
+            }
+            s.report = report;
+            persist(s);
             const summary = formatRunReport(report, scripted);
             const { events: _events, ...modelReport } = report;
             const mode = scripted ? 'scripted' : 'live';
-            return textResult(options.modelResult ? modelJson({ mode, ...modelReport }) : summary, { mode, ...report });
+            return textResult(options.modelResult ? modelJson({ mode, ...modelReport }) : summary + (s.persistenceWarning ? `\n${s.persistenceWarning}` : ''), { mode, ...report,
+                // Failure diagnostics must not echo rejected raw arguments. The operator
+                // can inspect the retained draft explicitly; the error receipt stays sanitized.
+                ...(report.error ? {} : { view: workflowView(s.draft, { input: s.input, observation: s.observation, report, mode }) }) });
+        }
+        catch (error) {
+            if (error instanceof ExtensionServiceError && error.code === 'admission' && error.message.includes('code requires allowExecutableCandidates')) {
+                throw new ExtensionServiceError(error.code, error.message.replaceAll('code requires allowExecutableCandidates', 'Code requires the user command /agentrun run --trusted for each run. This permits local, unsandboxed execution.'));
+            }
+            throw error;
         }
         finally {
             s.busy = false;
             s.controller = undefined;
+            s.pause = undefined;
+            await driver?.close().catch(() => { });
             stage(ctx, s);
             if (current === s && !s.closed && ctx.hasUI)
                 ctx.ui.setWidget('agentrun', undefined);
         }
     };
+    /** The inspected draft on synthetic values, or `input`: nothing is paid, and the session's run is untouched. Code runs
+     *  only when the user's command trusts this dry run. */
+    const dryRun = async (ctx, s, input, trusted, signal) => {
+        if (!s.draft)
+            throw new Error('Inspect a workflow first. Try /agentrun demo, or describe a task with /agentrun <task>.');
+        const draft = s.draft;
+        // /agentrun stop, the tool call's own abort and the session's end each stop it, from before its first await on.
+        const controller = new AbortController();
+        s.dryRun?.abort();
+        s.dryRun = controller;
+        const stopped = AbortSignal.any([controller.signal, ...[signal, ctx.signal].filter((v) => !!v)]);
+        try {
+            let sop, sopUnavailable;
+            try {
+                sop = await sopFor(ctx, s, inspectWorkflow(draft).requires.sopSections);
+            }
+            catch (error) {
+                sopUnavailable = error instanceof Error ? error.message : String(error);
+            }
+            if (stopped.aborted || s.closed)
+                return { status: 'not_run', ok: true, skipped: ['The dry run was stopped before it started.'] };
+            return await dryRunDraft(draft, { ...(input === undefined ? {} : { input }), ...(sop ? { sop: sop.text } : {}), ...(sopUnavailable ? { sopUnavailable } : {}),
+                trusted, trustedCommand: '/agentrun dry-run --trusted', signal: stopped });
+        }
+        finally {
+            if (s.dryRun === controller)
+                s.dryRun = undefined;
+        }
+    };
     const launch = async (ctx, s, input, trusted = false) => {
         if (s.busy)
             throw new Error('A workflow is already running. Use /agentrun stop first.');
@@ -314,33 +478,69 @@ function registerExtension(pi, configuration) {
     };
     pi.registerTool({
         name: 'agentrun', label: 'AgentRun workflow',
-        description: 'Use the agentrun-author skill to compose workflows. Describe lists available tools and their schemas. Inspect or run an AgentRun DSL workflow in this Pi session. First inspect to show its graph. Agent nodes capture the active Pi model when execution starts. Code needs the user command /agentrun run --trusted for each run. ' + (configuration.hostTools
+        description: `Use the ${AUTHOR_SKILL_NAME} skill to compose workflows.` + ' Describe lists available tools and their schemas. Inspect or run an AgentRun DSL workflow in this Pi session. First inspect to show its graph. Dry-run checks the inspected workflow on synthetic values (or the given input) with no model, Jev or tool call; code runs only with the user command /agentrun dry-run --trusted. Agent nodes capture the active Pi model when execution starts. Code needs the user command /agentrun run --trusted for each run. ' + (configuration.hostTools
             ? 'Only the explicit host-configured tools are available, including during trusted runs. Outer permission hooks are not inherited. '
-            : 'Enabled read-only Pi built-ins are available to declared steps. Shell/write/edit need the trusted command for each run; custom extension tools and permission hooks are not inherited. The search tool reads fictional demo sources only. ') + 'Scripted demos stay scripted on rerun; use /agentrun demo live to switch. Saving workflows is not part of v1.',
-        parameters: Type.Object({ action: Type.Union([Type.Literal('describe'), Type.Literal('inspect'), Type.Literal('run')]),
-            workflow: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
-                description: 'The complete AgentRun workflow JSON object. Pass the object directly, not a JSON-encoded string. Inspection validates its DSL structure.',
-            })), input: Type.Optional(Type.Record(Type.String(), Type.Unknown())) }),
+            : 'Enabled read-only Pi built-ins are available to declared steps. Shell/write/edit need the trusted command for each run; custom extension tools and permission hooks are not inherited. The search and support_demo tools use fictional supplied sources only. ') + 'Save stores a named procedure revision, not its input or permission. Load preflights current host capabilities. Run always restarts; there is no checkpoint resume. Scripted demos stay scripted on rerun.',
+        parameters: workflowToolParameters(),
         executionMode: 'sequential',
         renderResult(result, options) {
             const details = result.details;
+            if (details?.dryRun)
+                return new Text(safe(formatDryRun(details.dryRun)), 0, 0);
             const text = details?.status && details.calls ? options?.expanded
-                ? JSON.stringify(details, null, 2) : formatRunReport(details, details.mode === 'scripted')
-                : result.content.filter(part => part.type === 'text').map(part => part.text).join('\n');
+                ? details.view ? formatWorkflowView({ ...details.view, output: undefined }) + (details.output === undefined ? '' : `\n\nOutput:\n${readable(details.output, Number.MAX_SAFE_INTEGER)}`) : formatRunReport(details, details.mode === 'scripted') : formatRunReport(details, details.mode === 'scripted')
+                : details?.view ? formatWorkflowView(details.view) : result.content.filter(part => part.type === 'text').map(part => part.text).join('\n');
             return new Text(safe(text), 0, 0);
         },
         async execute(_id, args, signal, onUpdate, ctx) {
             const s = await state(ctx);
+            const store = new WorkflowStore(ctx.cwd);
+            if (args.action === 'save') {
+                if (s.busy)
+                    throw new Error('A workflow is running. Save after it stops.');
+                if (!s.draft)
+                    throw new Error('No workflow to save. Inspect a workflow first.');
+                const saved = await store.save(args.name ?? '', s.draft);
+                s.savedName = saved.name;
+                persist(s);
+                return textResult(`Saved ${saved.name} · ${saved.digest.slice(0, 12)}. Input and execution permission are not saved.\nLoad this revision: /agentrun load ${saved.name} ${saved.digest}${s.demo ? '\nScripted demo adapters are not saved. Loading this definition uses live adapters.' : ''}`, saved);
+            }
+            if (args.action === 'list') {
+                const workflows = await store.list();
+                return textResult(modelJson(workflows), { workflows });
+            }
+            if (args.action === 'load') {
+                const saved = await store.load(args.name ?? '', args.digest);
+                const result = inspect(ctx, s, saved.workflow, args.input);
+                s.input = structuredClone(args.input ?? {});
+                s.savedName = saved.name;
+                s.demo = undefined;
+                s.report = undefined;
+                s.observation = undefined;
+                s.runId = undefined;
+                persist(s);
+                const preview = view(ctx, s);
+                return textResult(modelJson({ preview: formatWorkflowView(preview), workflow: s.draft, input: s.input }), { ...result, saved, view: preview });
+            }
             if (args.action === 'describe') {
-                const details = { tools: toolSet(ctx).map(t => ({ name: t.name, description: t.description, parameters: t.parameters })),
-                    limits: { ...limits }, structuralLimits: { ...extensionStructuralLimits }, ...readiness(ctx, s), authoring: { workflow: loadPiWorkflowGuide(), jev: loadPiJevGuide() } };
+                const details = { tools: describeTools(toolSet(ctx)),
+                    limits: { ...limits }, structuralLimits: { ...extensionStructuralLimits }, ...readiness(ctx, s), authoring: authoringReferences() };
                 return textResult(JSON.stringify(details, null, 2), details);
             }
+            if (args.action === 'dry-run') {
+                if (args.workflow !== undefined)
+                    throw new Error('Inspect the workflow first with action inspect, then dry-run without a workflow argument.');
+                const report = await dryRun(ctx, s, args.input, false, signal);
+                return textResult(modelJson({ dryRun: report }), { dryRun: report });
+            }
             if (args.action === 'run' && args.workflow !== undefined)
                 throw new Error('Inspect the workflow first with action inspect, then run without a workflow argument.');
             if (args.action === 'inspect') {
                 const result = inspect(ctx, s, args.workflow, args.input);
-                return textResult(result.tree, { ...result, tools: toolSet(ctx).map(t => t.name) });
+                const preview = view(ctx, s);
+                // The author needs the exact definition when editing a restored procedure.
+                // Pi's renderer shows the readable view, not this model-facing JSON.
+                return textResult(modelJson({ preview: formatWorkflowView(preview), workflow: s.draft, input: s.input }), { ...result, view: preview, tools: toolSet(ctx).map(t => t.name) });
             }
             return execute(ctx, s, args.input ?? s.input, { signal, update: onUpdate, modelResult: true });
         },
@@ -349,26 +549,184 @@ function registerExtension(pi, configuration) {
         description: 'Describe a task, inspect its workflow, or try /agentrun demo',
         async handler(args, ctx) {
             const s = await state(ctx);
-            const raw = args.trim();
-            const command = /^(help|status|stop|demo|run)(?:\s|$)/i.test(raw) ? raw.toLowerCase().replace(/\s+/g, ' ') : raw;
-            const words = command.split(/\s+/);
-            const commandLike = /^(help|status|stop|demo|run)(?:-|$)/i.test(words[0])
-                && words.slice(1).every(word => word.startsWith('-') || ['live', 'empty'].includes(word));
+            let raw = args.trim();
             try {
+                if ((!raw || raw === 'inspect') && s.draft && ctx.mode === 'tui') {
+                    const action = await showWorkflowInspector(ctx, () => view(ctx, s));
+                    if (!action)
+                        return;
+                    if (action === 'save') {
+                        const name = await ctx.ui.input('Save procedure', s.savedName ?? 'support-triage');
+                        if (!name)
+                            return;
+                        raw = `save ${name}`;
+                    }
+                    else if (action === 'load') {
+                        const stored = await new WorkflowStore(ctx.cwd).list();
+                        const names = [...new Set(stored.map(item => item.name))];
+                        if (!names.length) {
+                            show(s, 'No saved procedures yet. Use /agentrun save <name>.');
+                            return;
+                        }
+                        const name = await ctx.ui.select('Load procedure', names);
+                        if (!name)
+                            return;
+                        raw = `load ${name}`;
+                    }
+                    else if (action === 'edit') {
+                        const request = await ctx.ui.input('Edit procedure', 'Describe the change; Pi will preview a candidate before running it.');
+                        if (!request)
+                            return;
+                        pi.sendUserMessage(`/skill:agentrun-author Edit the current procedure: ${request}. Inspect the candidate and explain the change. Do not run it yet.`, { expandPromptTemplates: true });
+                        return;
+                    }
+                    else
+                        raw = action;
+                }
+                const command = /^(help|status|stop|demo|triage|run|dry-run|inspect)(?:\s|$)/i.test(raw) ? raw.toLowerCase().replace(/\s+/g, ' ') : raw;
+                const words = command.split(/\s+/);
+                const commandLike = /^(help|status|stop|demo|run|dry-run)(?:-|$)/i.test(words[0])
+                    && words.slice(1).every(word => word.startsWith('-') || ['live', 'empty'].includes(word));
                 if (command === 'help' || command === '--help' || command === '-h') {
                     show(s, help);
                 }
-                else if (!command) {
-                    show(s, s.draft ? `${inspect(ctx, s).tree}\n\n${s.busy ? 'Running. /agentrun stop to cancel.' : s.demo ? 'Replay: /agentrun run (scripted, no model calls). Switch to real models: /agentrun demo live.' : 'Run: /agentrun run. Ask Pi to change this workflow.'}` : help);
+                else if (!command || command === 'inspect') {
+                    show(s, s.draft ? formatWorkflowView(view(ctx, s)) : help);
+                }
+                else if (/^save(?:\s|$)/.test(command)) {
+                    if (s.busy)
+                        throw new Error('A workflow is running. Save after it stops.');
+                    if (!s.draft)
+                        throw new Error('No workflow to save. Inspect a workflow first.');
+                    const saved = await new WorkflowStore(ctx.cwd).save(command.slice(4).trim(), s.draft);
+                    s.savedName = saved.name;
+                    persist(s);
+                    show(s, `Saved ${saved.name} · ${saved.digest.slice(0, 12)}. Input and execution permission are not saved.\nReuse: /agentrun load ${saved.name}\nLoad this revision: /agentrun load ${saved.name} ${saved.digest}${s.demo ? '\nScripted demo adapters are not saved. Loading this definition uses live adapters.' : ''}`, saved);
+                }
+                else if (/^load(?:\s|$)/.test(command)) {
+                    const [, name, digest] = command.split(/\s+/);
+                    const saved = await new WorkflowStore(ctx.cwd).load(name ?? '', digest);
+                    inspect(ctx, s, saved.workflow);
+                    s.savedName = saved.name;
+                    s.input = {};
+                    s.demo = undefined;
+                    s.report = undefined;
+                    s.observation = undefined;
+                    s.runId = undefined;
+                    persist(s);
+                    show(s, `Loaded procedure. Supply new input with /agentrun input. Loading never executes it.\n\n${formatWorkflowView(view(ctx, s))}`);
+                }
+                else if (command === 'list') {
+                    const stored = await new WorkflowStore(ctx.cwd).list();
+                    show(s, stored.length ? stored.map(item => `${item.name} · ${item.workflowName}\n/agentrun load ${item.name} ${item.digest}`).join('\n') : 'No saved procedures yet. Use /agentrun save <name>.', { workflows: stored });
+                }
+                else if (/^history(?:\s|$)/.test(command)) {
+                    const history = workflowRunHistory(ctx.sessionManager.getBranch());
+                    if (!history.length) {
+                        show(s, 'No retained runs on this Pi session branch yet.');
+                        return;
+                    }
+                    const labels = history.map((run, index) => `${index + 1}. ${inspectWorkflow(run.workflow).name} · ${run.report?.status ?? 'interrupted'} · ${run.createdAt}`);
+                    let index = Number(command.slice(7).trim()) - 1;
+                    if (command === 'history' && ctx.mode === 'tui') {
+                        const selected = await ctx.ui.select('Retained runs on this session branch', labels);
+                        if (!selected)
+                            return;
+                        index = labels.indexOf(selected);
+                    }
+                    if (!Number.isInteger(index) || index < 0 || index >= history.length) {
+                        show(s, `${labels.join('\n')}\n\nInspect: /agentrun history <number>`, { runs: history.map(run => ({ runId: run.runId, createdAt: run.createdAt, digest: run.report?.digest, status: run.report?.status })) });
+                        return;
+                    }
+                    const run = history[index];
+                    const receipt = workflowView(run.workflow, { input: run.input, observation: run.observation, report: run.report, mode: run.demo ? 'scripted' : 'live adapters', savedName: run.savedName });
+                    // History is read-only. It never replaces the active draft or replays a run.
+                    if (ctx.mode === 'tui')
+                        await showWorkflowInspector(ctx, () => ({ ...receipt, readOnly: true }));
+                    else
+                        show(s, formatWorkflowView(receipt), { run });
+                }
+                else if (/^sop(?:\s|$)/.test(command)) {
+                    const file = raw.trim().slice(3).trim();
+                    if (!file) {
+                        show(s, configuration.sop ? 'SOP text comes from the host.' : s.sop ? `SOP: ${s.sop.file} (${s.sop.sha256.slice(0, 12)}). Supply another with /agentrun sop <file>.` : 'No SOP supplied. Use /agentrun sop <file> for a workflow that names sopSection.');
+                        return;
+                    }
+                    if (s.busy)
+                        throw new Error('A workflow is running. Stop it before changing its SOP.');
+                    if (configuration.sop)
+                        throw new Error('SOP text comes from the host; /agentrun sop is not used.');
+                    const read = await readSopFile(ctx.cwd, file);
+                    const needed = s.draft ? inspectWorkflow(s.draft).requires.sopSections : [];
+                    const missing = missingSopSections(read.text, needed);
+                    if (missing.length)
+                        throw new Error(`SOP text has no "## <section>" heading for ${missing.map(name => `"${name}"`).join(', ')}. Nothing was changed.`);
+                    s.sop = { file: read.file, sha256: read.sha256 };
+                    persist(s);
+                    show(s, `SOP set: ${read.file} (${read.text.length} characters). ${needed.length ? `Covers ${needed.map(name => `"${name}"`).join(', ')}.` : 'The current workflow names no section.'}`);
+                }
+                else if (/^input(?:\s|$)/.test(command)) {
+                    if (!s.draft)
+                        throw new Error('No workflow yet. Load or describe a procedure first.');
+                    if (s.busy)
+                        throw new Error('A workflow is running. Stop it before changing its input.');
+                    let supplied = raw.slice(5).trim();
+                    if (!supplied && ctx.hasUI)
+                        supplied = await ctx.ui.input('New workflow input', 'Describe the new case in plain language, or paste a JSON object.') ?? '';
+                    if (!supplied) {
+                        show(s, 'Use /agentrun input <describe the new case>, or ask Pi to use new input. Nothing was run.');
+                        return;
+                    }
+                    if (supplied.startsWith('{')) {
+                        let input;
+                        try {
+                            input = JSON.parse(supplied);
+                        }
+                        catch {
+                            throw new Error('Workflow input must be valid JSON, or describe it in plain language.');
+                        }
+                        if (!input || typeof input !== 'object' || Array.isArray(input))
+                            throw new Error('Workflow input must be an object.');
+                        inspect(ctx, s, undefined, input);
+                        show(s, `Input updated. Nothing was run.\n\n${formatWorkflowView(view(ctx, s))}`);
+                    }
+                    else {
+                        const key = singleTextInput(s.draft);
+                        if (key) {
+                            inspect(ctx, s, undefined, { [key]: supplied });
+                            show(s, `Input updated. Nothing was run.\n\n${formatWorkflowView(view(ctx, s))}`);
+                        }
+                        else {
+                            pi.sendUserMessage(`/skill:agentrun-author Set new input for the current inspected workflow: ${supplied}. Keep the procedure unchanged; inspect with input only. Ask for missing facts instead of inventing them. Do not run yet.`, { expandPromptTemplates: true });
+                        }
+                    }
+                }
+                else if (/^triage(?:\s|$)/.test(command)) {
+                    const parts = command.split(/\s+/).slice(1);
+                    const live = parts[0] === 'live';
+                    const name = parts[live ? 1 : 0] ?? 'billing';
+                    if (!['billing', 'technical', 'ambiguous', 'failure'].includes(name) || parts.length > (live ? 2 : 1) || live && name === 'failure') {
+                        show(s, 'Use /agentrun triage [billing|technical|ambiguous|failure], or /agentrun triage live [billing|technical|ambiguous].');
+                        return;
+                    }
+                    const input = structuredClone(supportTriageInputs[name === 'failure' ? 'billing' : name]);
+                    inspect(ctx, s, supportTriageWorkflow, input);
+                    s.demo = live ? undefined : name === 'failure' ? 'triage-failure' : 'triage';
+                    show(s, `Fictional support triage · ${live ? 'real model calls' : 'scripted, no model calls'}. No customer actions.\n${formatWorkflowView(view(ctx, s))}`);
+                    const result = await execute(ctx, s, input);
+                    show(s, result.content[0].text, result.details);
                 }
                 else if (command === 'status') {
                     const ready = readiness(ctx, s);
-                    show(s, `agent.run() · ${s.busy ? 'running' : 'idle'}\nDemo: ready — /agentrun demo (no keys or model calls)\nWorkflow: ${s.draft ? `${modelJson(inspectWorkflow(s.draft).name)} · ${s.demo ? 'scripted' : 'live adapters'}` : 'none — run the demo or describe a task; /reload clears the previous workflow'}\n\nFor your own workflows:\nPi host: ${PI_VERSION}${PI_VERSION === '0.87.0' ? '' : ' (tested on 0.87.0; use the bundled ./node_modules/.bin/pi)'}\nSkill: ${ready.skill ? 'loaded — /agentrun <task>' : 'missing — enable package skills, then /reload'}\nPi: ${ready.pi ? 'selected model available (connection not tested)' : 'no usable active model — /login to connect a provider, then /model to select it'}\nJev: ${ready.jev ? 'configuration present (connection not tested)' : 'not configured — only needed for system one decisions; set TYPESAFE_API_KEY before starting Pi'}`, ready);
+                    show(s, `agent.run() · ${s.busy ? 'running' : 'idle'}\nDemo: ready — /agentrun demo (no keys or model calls)\nWorkflow: ${s.draft ? `${modelJson(inspectWorkflow(s.draft).name)} · ${s.demo ? 'scripted' : 'live adapters'}` : 'none — load a saved procedure, run the demo, or describe a task'}\n\nFor your own workflows:\n${piHostLine(PI_VERSION)}\nSkill: ${ready.skill ? 'loaded — /agentrun <task>' : 'missing — enable package skills, then /reload'}\nPi: ${ready.pi ? 'selected model available (connection not tested)' : 'no usable active model — /login to connect a provider, then /model to select it'}\nJev: ${ready.jev ? 'configuration present (connection not tested)' : 'not configured — only needed for system one decisions; set TYPESAFE_API_KEY before starting Pi'}`, ready);
                 }
                 else if (command === 'stop') {
+                    const dry = s.dryRun;
+                    dry?.abort();
+                    s.pause?.();
                     s.controller?.abort();
                     s.service.stop();
-                    show(s, s.busy ? 'Stop requested. Already-started tool effects may still finish.' : 'Nothing is running.');
+                    show(s, s.busy ? 'Stop requested. Already-started tool effects may still finish.' : dry ? 'Dry run stopped.' : 'Nothing is running.');
                 }
                 else if (command === 'demo' || command === 'demo live' || command === 'demo empty') {
                     inspect(ctx, s, demoWorkflow);
@@ -379,18 +737,28 @@ function registerExtension(pi, configuration) {
                 else if (command === 'run' || command === 'run --trusted') {
                     await launch(ctx, s, s.input, command === 'run --trusted');
                 }
+                else if (command === 'dry-run' || command === 'dry-run --trusted') {
+                    // As with /agentrun run: interactive Pi reads the next command only once this handler returns, so the dry run
+                    // goes on in the background, where /agentrun stop reaches it. Headless callers await its answer.
+                    stage(ctx, s, 'agent.run() · dry run · /agentrun stop ends it');
+                    const pending = dryRun(ctx, s, undefined, command === 'dry-run --trusted')
+                        .then(report => show(s, formatDryRun(report), { dryRun: report }), error => commandError(s, error))
+                        .finally(() => stage(ctx, s));
+                    if (!ctx.hasUI)
+                        await pending;
+                }
                 else if (commandLike || command.startsWith('-')) {
                     show(s, `Unknown AgentRun command: ${raw}\n\n${help}`);
                 }
                 else {
                     if (s.busy)
                         throw new Error('A workflow is running. Stop it before starting another.');
-                    if (!pi.getCommands().some(item => item.name === 'skill:agentrun-author' && item.source === 'skill')) {
+                    if (!pi.getCommands().some(item => item.name === `skill:${AUTHOR_SKILL_NAME}` && item.source === 'skill')) {
                         throw new Error('AgentRun authoring skill is unavailable. Enable package skills, then /reload. Run /agentrun status to check discovery.');
                     }
                     if (!readiness(ctx, s).pi)
                         throw new Error(PI_MODEL_SETUP_MESSAGE);
-                    pi.sendUserMessage(`/skill:agentrun-author ${raw}`, { expandPromptTemplates: true });
+                    pi.sendUserMessage(`/skill:${AUTHOR_SKILL_NAME} ${raw}`, { expandPromptTemplates: true });
                 }
             }
             catch (error) {
@@ -398,22 +766,43 @@ function registerExtension(pi, configuration) {
             }
         },
     });
-    const closeSession = async () => {
+    const closeSession = async (retainFinal = false) => {
         if (!current)
             return;
-        const old = current;
+        const old = current, wasRunning = old.busy;
         old.clearStatus();
-        current = undefined;
         old.closed = true;
+        old.dryRun?.abort();
+        old.pause?.();
         old.controller?.abort();
         await old.service.dispose();
         await old.inFlight;
+        // Only before-switch/shutdown hooks still own the originating branch. A
+        // session_tree event is already on another branch and must never receive this receipt.
+        if (retainFinal && wasRunning && old.report)
+            persist(old, false, true);
+        if (current === old)
+            current = undefined;
     };
-    pi.on('session_shutdown', closeSession);
-    pi.on('session_before_switch', closeSession);
-    pi.on('session_before_fork', closeSession);
+    pi.on('session_shutdown', () => closeSession(true));
+    pi.on('session_before_switch', () => closeSession(true));
+    pi.on('session_before_fork', () => closeSession(true));
     pi.on('session_start', async (_event, ctx) => {
         if (current && current.key !== `${ctx.sessionManager.getSessionId()}:${ctx.cwd}`)
             await closeSession();
+        await state(ctx);
+    });
+    pi.on('session_tree', async (_event, ctx) => { await closeSession(); await state(ctx); });
+    pi.registerEntryRenderer('agentrun:snapshot', (entry, options) => {
+        if (entry.data?.running)
+            return undefined;
+        const snapshot = restoreWorkflowSession([entry]);
+        if (!snapshot)
+            return undefined;
+        if (!snapshot.report && !snapshot.running)
+            return undefined;
+        return new Text(safe(options.expanded ? formatWorkflowView(workflowView(snapshot.workflow, {
+            input: snapshot.input, report: snapshot.report, observation: snapshot.observation, mode: snapshot.demo ? 'scripted' : 'live adapters',
+        })) : `AgentRun receipt · ${snapshot.report?.status ?? 'interrupted'} · ${inspectWorkflow(snapshot.workflow).name}`), 0, 0);
     });
 }