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

package/dist/extension.js

@@ -1,22 +1,38 @@
 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, loadAuthorReference, renderAuthorHostAddendum, } 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 { PI_HOST_ADDENDUM } from './host-addendum.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 { WorkflowStore, WorkflowStoreError } from './workflow-store.js';
+import { WorkflowObservation, workflowView, formatWorkflowView, progressLines, readable } from './workflow-view.js';
+import { showWorkflowInspector } from './workflow-inspector.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 · 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. */
@@ -61,15 +77,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,15 +102,47 @@ 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;
+        }
         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 } : {}), };
+        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,
         mode: s.draft ? s.demo ? 'scripted' : 'live' : undefined,
@@ -103,7 +153,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)/.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);
     };
@@ -138,11 +188,34 @@ function registerExtension(pi, configuration) {
         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;
+        if (workflow !== undefined || input !== undefined)
+            persist(s);
         return { inspection, tree: formatWorkflowTree(inspection) };
     };
+    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;
         const countTool = () => {
@@ -219,7 +292,7 @@ function registerExtension(pi, configuration) {
                         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 }) };
             },
         };
     };
@@ -247,46 +320,54 @@ 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();
+            s.observation = observation.data;
+            s.report = undefined;
+            s.runId = randomUUID();
+            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(deps), 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')}`));
                 },
             });
+            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;
@@ -314,10 +395,12 @@ 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. 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')]),
+            : '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: Type.Object({ action: Type.Union(['describe', 'inspect', 'run', 'save', 'load', 'list'].map(value => Type.Literal(value))),
+            name: Type.Optional(Type.String({ description: 'Saved procedure name: lowercase letters, digits, hyphens or underscores.' })),
+            digest: Type.Optional(Type.String({ description: 'Optional exact saved SHA-256 revision to load.' })),
             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())) }),
@@ -325,22 +408,56 @@ function registerExtension(pi, configuration) {
         renderResult(result, options) {
             const details = result.details;
             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: toolSet(ctx).map(t => ({ name: t.name, description: t.description, parameters: t.parameters,
+                        resultSchema: t.resultSchema ?? { type: 'object', properties: { content: { type: 'array', items: { type: 'object' } }, details: {} }, required: ['content'] },
+                        resultContract: t.resultSchema ? 'Host-declared direct workflow call result.' : 'Pi result envelope; tool-specific details are not declared. Do not invent fields inside details.',
+                    })),
+                    limits: { ...limits }, structuralLimits: { ...extensionStructuralLimits }, ...readiness(ctx, s), authoring: { language: loadAuthorReference('language'), workflow: loadAuthorReference('workflow-format'), jev: loadAuthorReference('jev-decisions'), host: renderAuthorHostAddendum(PI_HOST_ADDENDUM) } };
                 return textResult(JSON.stringify(details, null, 2), details);
             }
             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,21 +466,157 @@ 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|inspect)(?:\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));
                 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 (/^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:\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);
                 }
                 else if (command === 'stop') {
                     s.controller?.abort();
@@ -385,12 +638,12 @@ function registerExtension(pi, configuration) {
                 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 +651,41 @@ 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.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);
     });
 }

package/dist/host-addendum.d.ts

@@ -0,0 +1,4 @@
+import { type AuthorHostAddendum } from '@parcha/agentrun-dsl';
+/** What this extension adds to the shared workflow language: its commands, tools and unavailable transports.
+ *  The packaged skill is rendered with it, and `describe` returns it as `authoring.host`. */
+export declare const PI_HOST_ADDENDUM: AuthorHostAddendum;

package/dist/host-addendum.js

@@ -0,0 +1,19 @@
+import { WORKFLOW_NODE_KINDS } from '@parcha/agentrun-dsl';
+/** What this extension adds to the shared workflow language: its commands, tools and unavailable transports.
+ *  The packaged skill is rendered with it, and `describe` returns it as `authoring.host`. */
+export const PI_HOST_ADDENDUM = Object.freeze({
+    name: 'Pi extension',
+    nodeKinds: WORKFLOW_NODE_KINDS.filter(kind => kind !== 'artifact'),
+    rules: [
+        'Call agentrun with action describe first, then inspect the complete workflow with its input, then run without a workflow argument.',
+        'Use exactly the tools describe returns. Without host-configured tools these are the active read-only built-ins (read, grep, find, ls), and bash, edit and write exist only in a trusted run; a host that configures its tools offers only those, including in trusted runs. The search tool reads fictional demo sources only.',
+        'Code nodes and mutating tools run only after the user issues /agentrun run --trusted for that run. Trusted execution is local and unsandboxed.',
+        'A call uses via tool with a tool describe returns. Shell and executor calls and artifact delivery are unavailable.',
+        'This extension supplies no SOP text: do not run a workflow with sopSection here; it needs an SDK host that supplies the authoritative SOP.',
+        'Custom extension tools and outer permission hooks are not inherited, including in trusted runs.',
+        'A preview, procedure edit or input change does not authorize execution: inspect it, report Inspected — not run, and execute only when requested.',
+        'Use /agentrun to inspect the current graph, /agentrun input to change input, /agentrun save and /agentrun load for named definition revisions, /agentrun history for retained receipts, /agentrun run to restart, and /agentrun stop to request cancellation; closing the inspector does not stop a run.',
+        'Saving retains the definition without input or execution permission; loading rechecks current host capabilities and never resumes an interrupted run.',
+        'The structural limits describe returns bound node count, map concurrency and parallel branches.',
+    ],
+});

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./runner.js";
-export * from "./author.js";
 export * from "./types.js";
 export { createPiHostRunner, createPiHostSessionFactory } from './host-session.js';
 export { WorkflowExtensionService } from './extension-service.js';
-export { loadPiAuthorSkillBundle } from './skill-bundle.js';
+export { PI_HOST_ADDENDUM } from './host-addendum.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 export * from "./runner.js";
-export * from "./author.js";
 export * from "./types.js";
 export { createPiHostRunner, createPiHostSessionFactory } from './host-session.js';
 export { WorkflowExtensionService } from './extension-service.js';
-export { loadPiAuthorSkillBundle } from './skill-bundle.js';
+export { PI_HOST_ADDENDUM } from './host-addendum.js';

package/dist/presentation.js

@@ -12,7 +12,7 @@ function lines(value, depth = 0) {
         }).concat(value.length > 30 ? [`… ${value.length - 30} more items in the structured result`] : []);
     const entries = Object.entries(value);
     return entries.slice(0, 30).flatMap(([key, item]) => {
-        const label = key.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/_/g, ' ');
+        const label = key.replace(/([a-z])([A-Z])/g, (_, first, upper) => `${first} ${upper.toLowerCase()}`).replace(/_/g, ' ');
         const children = lines(item, depth + 1);
         return children.length === 1 ? [`${label}: ${children[0]}`] : [`${label}:`, ...children.map(line => `  ${line}`)];
     }).concat(entries.length > 30 ? [`… ${entries.length - 30} more fields in the structured result`] : []);
@@ -30,5 +30,5 @@ export function formatRunReport(report, scripted = false) {
     const trace = report.traceTruncated ? `\nTrace retention is partial${report.trace ? ` (${report.trace.droppedEvents} valid events omitted, ${report.trace.rejectedEvents} rejected)` : ''}; this does not mean the output is truncated.` : '';
     const clipped = body.length > 12_000 ? `${body.slice(0, 12_000)}\n… Full output is in the structured result.` : body;
     const status = report.status === 'escalated' ? 'stopped — needs attention (escalated)' : report.status;
-    return cleanText(`${scripted ? 'Scripted demo' : 'Workflow'}: ${status}${report.error ? ` (${report.error.code})` : ''}\n\n${clipped}${recovery}${uncertain}${trace}\n\nWorkflow calls: ${report.calls.tool} direct tool call${report.calls.tool === 1 ? '' : 's'}, ${report.calls.judge} system one decision${report.calls.judge === 1 ? '' : 's'}, ${report.calls.agent} model step${report.calls.agent === 1 ? '' : 's'}.${scripted ? '\nScripted responses; no model calls. Replay: /agentrun run. Real models: /agentrun demo live.' : ''}`);
+    return cleanText(`${scripted ? 'Scripted demo' : 'Workflow'}: ${status}${report.error ? ` (${report.error.code})` : ''}\n\n${clipped}${recovery}${uncertain}${trace}\n\nWorkflow calls: ${report.calls.tool} direct tool call${report.calls.tool === 1 ? '' : 's'}, ${report.calls.judge} system one decision${report.calls.judge === 1 ? '' : 's'}, ${report.calls.agent} model step${report.calls.agent === 1 ? '' : 's'}.${scripted ? '\nScripted responses; no model calls. Replay: /agentrun run. Example modes: /agentrun help.' : ''}`);
 }