@parcha/agentrun-pi 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/durable/workflow-tool.js

@@ -0,0 +1,188 @@
+// The agentrun tool for a pi-durable session. describe, inspect, dry-run, save, load and list do what the coding-agent
+// extension's tool does, through the same module (../workflow-tool.ts); run starts the workflow as one background task
+// of the calling conversation through createWorkflowExtension, from the tool's own invocation, and answers with its
+// outcome, writing the run's progress to the tool's running output as it goes. The draft a conversation inspected is a
+// document of the session, so a reopened session keeps it. Code nodes run only through the host's code executor.
+import { defineDocFamily, defineExtension, defineTool } from "@earendil-works/pi-durable";
+import { Type } from "typebox";
+import { inspectWorkflow, WORKFLOW_NODE_KINDS } from "@parcha/agentrun-dsl";
+import { canonicalHash } from "@parcha/agentrun-dsl/recovery";
+import { extensionStructuralLimits, WorkflowExtensionService } from "../extension-service.js";
+import { modelJson } from "../presentation.js";
+import { WorkflowStore } from "../workflow-store.js";
+import { progressLines, WorkflowObservation } from "../workflow-view.js";
+import { authoringReferences, describeTools, dryRunDraft, inspectCandidate, workflowToolProperties } from "../workflow-tool.js";
+import { toolResult } from "./pi-versions.js";
+import { createWorkflowExtension } from "./task.js";
+/** What a pi-durable session adds to the workflow language, rendered for describe's `authoring.host`. */
+export const DURABLE_HOST_ADDENDUM = Object.freeze({
+    name: "pi-durable session",
+    nodeKinds: WORKFLOW_NODE_KINDS.filter((kind) => kind !== "artifact"),
+    rules: [
+        "Call agentrun with action describe first, then inspect the complete workflow with its input, then dry-run it (action dry-run, without a workflow argument), then run without a workflow argument.",
+        "A dry run runs the inspected workflow on synthetic values, or the input you give it, with no model, Jev or tool call. Its status is passed, not_run (a check could not run; skipped says why, and it proves nothing) or failed (problems say why). Report not_run as not run, never as passed.",
+        "Use exactly the tools describe returns, as a call's tool and as an agent node's tools: the host registers them, and inspect refuses any other, naming it. A call uses via tool with one of them. Shell and executor calls and artifact delivery are unavailable.",
+        "Code nodes run only through the host's code executor. Without one, a dry run of a workflow with code is not_run and a run of it is refused.",
+        "A run is a pi-durable task of this conversation: it continues after the session reopens, and the run action answers with its outcome once it ends. Running the same draft on the same input again reaches that run: a live one is waited for, a finished one answers with its outcome, and its effects are not made again. To run the same draft on the same input anew, pass again: true; a later run without it reaches the newest one.",
+        "Save keeps a named revision of the inspected definition, not its input. Load replaces the draft with a saved revision and checks it against this host's tools. List shows the saved revisions.",
+        "The structural limits describe returns bound node count, map concurrency and parallel branches.",
+    ],
+});
+const DraftDoc = defineDocFamily({ kind: "agentrun.draft", version: 1, scope: "session", family: true, initial: () => ({ workflow: null, input: {} }) });
+/** How many times `again` asked for a fresh run of one draft and input in a conversation: the newest run's number. */
+const RunsDoc = defineDocFamily({ kind: "agentrun.runs", version: 1, scope: "session", family: true, initial: () => ({ generation: 0 }) });
+const json = (value) => (value === undefined ? null : JSON.parse(JSON.stringify(value)));
+const answer = (value) => toolResult([{ type: "text", text: modelJson(value) }], { details: json(value) });
+/** The tool, and the workflow task its runs are: install `extension` (it carries both) and list the tool's name in the
+ *  agent definition. `workflow` reads and stops runs from the host's side. */
+export function createWorkflowTool(host) {
+    const names = (host.tools ?? []).map((tool) => tool.name);
+    const checker = () => new WorkflowExtensionService({ allowedTools: names });
+    /** Inspect's checks, after naming any tool the workflow uses (a call's, or an agent node's) that the host did not
+     *  register: the host decides what a drafted workflow may use. */
+    const admit = (candidate, input) => {
+        let used = [];
+        try {
+            used = inspectWorkflow(candidate).requires.tools;
+        }
+        catch { /* inspect names what is wrong */ }
+        const missing = used.filter((name) => !names.includes(name));
+        if (missing.length)
+            throw new Error(`Cannot inspect workflow: it uses ${missing.length === 1 ? "a tool" : "tools"} this session's host has not registered: ${missing.map((name) => JSON.stringify(name)).join(", ")}. A workflow may call, or give an agent node, only the tools describe lists; a host registers them in createWorkflowTool's tools.`);
+        return inspectCandidate(checker(), candidate, input);
+    };
+    const store = () => new WorkflowStore(host.projectDir);
+    // A run's events reach the tool call that started it, while both live in this process.
+    const listeners = new Map();
+    const listen = (key, listener) => {
+        const set = listeners.get(key) ?? new Set();
+        listeners.set(key, set.add(listener));
+        return () => { set.delete(listener); if (!set.size)
+            listeners.delete(key); };
+    };
+    const given = { ...(host.runCode ? { runCode: host.runCode } : {}), ...(host.sop === undefined ? {} : { sop: host.sop }) };
+    const workflow = createWorkflowExtension({
+        ...host.task,
+        run: async (invocation) => {
+            const parts = await host.task.run(invocation);
+            // The host's own observer's result goes back to the interpreter, which consumes a rejected one; a progress listener
+            // that fails (its call ended, say) changes nothing in the run.
+            const tee = (own) => (event) => {
+                for (const listener of listeners.get(invocation.key) ?? []) {
+                    try {
+                        listener(event);
+                    }
+                    catch { /* progress only */ }
+                }
+                return own?.(event);
+            };
+            // The executor and SOP text the host gave the tool are the run's, as they are its dry run's.
+            return "deps" in parts
+                ? { ...parts, deps: { ...parts.deps, ...given, onEvent: tee(parts.deps.onEvent) } }
+                : { ...parts, adapters: { ...parts.adapters, ...given, onEvent: tee(parts.adapters.onEvent) } };
+        },
+    });
+    const tool = defineTool({
+        name: host.name ?? "agentrun",
+        description: "Compose and run AgentRun workflows in this session. Describe lists the tools a workflow may use, as a call's tool or an agent node's tools, and the language; a workflow uses only the tools describe lists, which the host registers. Inspect validates a complete workflow and keeps it as this conversation's draft. Dry-run checks the draft on synthetic values (or the given input) with no model, Jev or tool call. Run starts the draft as a durable task of this conversation and answers with its outcome. Running the same draft on the same input again, after a restart too, reaches the same run and makes no effect twice; again: true starts a fresh run of them, which a later run then reaches. Save, load and list keep named definition revisions.",
+        parameters: Type.Object({ ...workflowToolProperties(), again: Type.Optional(Type.Boolean({ description: "Run only: start a fresh run of the same draft and input instead of reaching the one already run." })) }),
+        executionMode: "sequential",
+        async execute(given, api, context) {
+            const args = given;
+            const key = String(api.conversationId);
+            const held = async () => {
+                const draft = await api.snapshot(DraftDoc, key, context);
+                return draft && draft.workflow !== null ? draft : undefined;
+            };
+            const keep = (candidate, input) => api.commit(async (tx) => {
+                const draft = await tx.doc(DraftDoc, key, null);
+                draft.workflow = json(candidate);
+                draft.input = json(input);
+                return undefined;
+            }, context);
+            const needDraft = async (action) => {
+                if (args.workflow !== undefined)
+                    throw new Error(`Inspect the workflow first with action inspect, then ${action} without a workflow argument.`);
+                const draft = await held();
+                if (!draft)
+                    throw new Error(`Inspect a workflow first, then ${action} it.`);
+                return draft;
+            };
+            switch (args.action) {
+                case "describe":
+                    return answer({ tools: describeTools(host.tools ?? []), structuralLimits: { ...extensionStructuralLimits }, authoring: authoringReferences(DURABLE_HOST_ADDENDUM) });
+                case "inspect": {
+                    const draft = await held();
+                    const candidate = args.workflow ?? draft?.workflow;
+                    if (candidate === undefined)
+                        throw new Error("No workflow yet. Pass the complete workflow to inspect.");
+                    // Without input, the input is not checked, as the coding-agent tool's inspect does; the draft keeps none.
+                    const input = args.input ?? (args.workflow === undefined ? draft?.input : undefined);
+                    const { tree } = admit(candidate, input);
+                    await keep(candidate, input ?? {});
+                    return answer({ preview: tree, workflow: candidate, input: input ?? {} });
+                }
+                case "dry-run": {
+                    const draft = await needDraft("dry-run");
+                    const dryRun = await dryRunDraft(draft.workflow, {
+                        ...(args.input === undefined ? {} : { input: args.input }), ...(host.sop === undefined ? {} : { sop: host.sop }),
+                        ...(host.runCode ? { runCode: host.runCode } : {}),
+                    });
+                    return answer({ dryRun });
+                }
+                case "save": {
+                    const draft = await needDraft("save");
+                    return answer(await store().save(args.name ?? "", draft.workflow));
+                }
+                case "list":
+                    return answer({ workflows: await store().list() });
+                case "load": {
+                    const saved = await store().load(args.name ?? "", args.digest);
+                    const { tree } = admit(saved.workflow, args.input);
+                    await keep(saved.workflow, args.input ?? {});
+                    return answer({ preview: tree, workflow: saved.workflow, input: args.input ?? {}, saved: { name: saved.name, digest: saved.digest } });
+                }
+                case "run": {
+                    const draft = await needDraft("run");
+                    const input = args.input ?? draft.input;
+                    const { inspection } = admit(draft.workflow, input);
+                    const code = inspection.nodes.filter((node) => node.kind === "code").map((node) => JSON.stringify(node.label));
+                    if (code.length && !host.runCode)
+                        throw new Error(`Code node${code.length === 1 ? "" : "s"} ${code.join(", ")}: this host runs code only through its own executor and gave none, so the workflow does not run here. Nothing ran.`);
+                    if (inspection.requires.sopSections.length && host.sop === undefined)
+                        throw new Error(`The workflow needs SOP text for ${inspection.requires.sopSections.map((name) => JSON.stringify(name)).join(", ")}, and this host supplies none. Nothing ran.`);
+                    // One run per draft and input in a conversation: a run asked for again (after a restart, say) reaches the same
+                    // task, so its effects happen once. A live run is attached to, and a finished one answers with its outcome.
+                    // `again` starts the next one; the count is a session document, so a later run, after a restart too, reaches it.
+                    const base = `agentrun:${api.conversationId}:${inspection.sha256}:${canonicalHash(input)}`;
+                    const generation = args.again
+                        ? await api.commit(async (tx) => { const runs = await tx.doc(RunsDoc, base, null); runs.generation += 1; return runs.generation; }, context)
+                        : (await api.snapshot(RunsDoc, base, context))?.generation ?? 0;
+                    const runKey = generation ? `${base}:${generation}` : base;
+                    const observation = new WorkflowObservation();
+                    let shown = "";
+                    const stop = listen(runKey, (event) => {
+                        observation.record(event);
+                        const text = progressLines(observation.data).join(" · ");
+                        if (text !== shown) {
+                            shown = text;
+                            api.output(`${text}\n`);
+                        }
+                    });
+                    try {
+                        const run = await workflow.start(api, { key: runKey, workflow: draft.workflow, input }, context, { conversationId: Number(api.conversationId), background: true });
+                        const outcome = await run.wait(context);
+                        // Only this call's events are counted: a run that had ended sends none, and one joined after a restart sent some before.
+                        const progress = run.started === "settled" ? ["The run had ended; its progress is not kept, and its outcome is above."]
+                            : run.started === "attached" ? ["Steps before this call are not counted.", ...progressLines(observation.data)] : progressLines(observation.data);
+                        return answer({ run: { key: runKey, taskId: run.taskId, started: run.started }, outcome, progress });
+                    }
+                    finally {
+                        stop();
+                    }
+                }
+            }
+        },
+    });
+    return { extension: defineExtension({ name: "agentrun.tool", tools: [tool], tasks: workflow.extension.tasks }), workflow };
+}

package/dist/extension.js

@@ -1,13 +1,12 @@
-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, AUTHOR_SKILL_NAME, loadAuthorReference, renderAuthorHostAddendum, } 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 { PI_HOST_ADDENDUM } from './host-addendum.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';
@@ -20,6 +19,7 @@ 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 = {
@@ -27,8 +27,7 @@ const constructors = {
     write: createWriteToolDefinition, grep: createGrepToolDefinition, find: createFindToolDefinition, ls: createLsToolDefinition,
 };
 const mutatingTools = new Set(['bash', 'edit', 'write']);
-const TESTED_PI_VERSION = '1.1.0';
-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 · 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 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;
@@ -177,19 +176,10 @@ 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);
-        }
-        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;
@@ -210,7 +200,7 @@ function registerExtension(pi, configuration) {
         s.input = nextInput;
         if (workflow !== undefined || input !== undefined)
             persist(s);
-        return { inspection, tree: formatWorkflowTree(inspection) };
+        return { inspection, tree };
     };
     const view = (ctx, s) => {
         const result = workflowView(s.draft, { input: s.input,
@@ -441,6 +431,35 @@ function registerExtension(pi, configuration) {
                 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.');
@@ -459,18 +478,15 @@ function registerExtension(pi, configuration) {
     };
     pi.registerTool({
         name: 'agentrun', label: 'AgentRun workflow',
-        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
+        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 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())) }),
+        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
                 ? 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');
@@ -507,13 +523,16 @@ function registerExtension(pi, configuration) {
                 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,
-                        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) } };
+                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') {
@@ -564,9 +583,9 @@ function registerExtension(pi, configuration) {
                     else
                         raw = action;
                 }
-                const command = /^(help|status|stop|demo|triage|run|inspect)(?:\s|$)/i.test(raw) ? raw.toLowerCase().replace(/\s+/g, ' ') : raw;
+                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)(?:-|$)/i.test(words[0])
+                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);
@@ -699,13 +718,15 @@ function registerExtension(pi, configuration) {
                 }
                 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 — load a saved procedure, run the demo, or describe a task'}\n\nFor your own workflows:\nPi host: ${PI_VERSION}${PI_VERSION === TESTED_PI_VERSION ? '' : ` (tested on ${TESTED_PI_VERSION}; install that host: npm install -g @earendil-works/pi-coding-agent@${TESTED_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);
+                    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);
@@ -716,6 +737,16 @@ 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}`);
                 }
@@ -741,6 +772,7 @@ function registerExtension(pi, configuration) {
         const old = current, wasRunning = old.busy;
         old.clearStatus();
         old.closed = true;
+        old.dryRun?.abort();
         old.pause?.();
         old.controller?.abort();
         await old.service.dispose();

package/dist/host-addendum.js

@@ -5,9 +5,10 @@ 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.',
+        'Call agentrun with action describe first, then inspect the complete workflow with its input, then dry-run it (action dry-run, without a workflow argument), then run without a workflow argument.',
+        'A dry run runs the inspected workflow on synthetic values, or the input you give it, with no model, Jev or tool call. Its status is passed, not_run (a check could not run; skipped says why, and it proves nothing) or failed (problems say why). Report not_run as not run, never as passed.',
         '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.',
+        'Code nodes and mutating tools run only after the user issues /agentrun run --trusted for that run. Trusted execution is local and unsandboxed. A dry run of a workflow with code nodes is not_run until the user issues /agentrun dry-run --trusted.',
         '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.',

package/dist/pi-host.d.ts

@@ -0,0 +1,7 @@
+export declare const SUPPORTED_PI_RANGE: string;
+export declare const NEWEST_TESTED_PI_VERSION = "1.3.0";
+/** Whether Pi `version` is in the supported range. As npm reads the range, a prerelease is not; nor is a version that
+ *  is not `x.y.z`. */
+export declare function isSupportedPi(version: string): boolean;
+/** The status line for Pi host `version`: the supported range, and for a host outside it the newest tested one. */
+export declare function piHostLine(version: string): string;

package/dist/pi-host.js

@@ -0,0 +1,22 @@
+// The Pi hosts this release supports: the range of its pi-durable and chord peers. `/agentrun status` flags a host
+// outside it, without blocking it, and names the newest version CI runs (the `pi-1-2` job) as the one to install.
+const FLOOR = [1, 0, 4];
+const CEILING = [1, 4, 0];
+export const SUPPORTED_PI_RANGE = `>=${FLOOR.join(".")} <${CEILING.join(".")}`;
+export const NEWEST_TESTED_PI_VERSION = "1.3.0";
+const compare = (a, b) => (a[0] - b[0]) || (a[1] - b[1]) || (a[2] - b[2]);
+/** Whether Pi `version` is in the supported range. As npm reads the range, a prerelease is not; nor is a version that
+ *  is not `x.y.z`. */
+export function isSupportedPi(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match)
+        return false;
+    const parsed = match.slice(1).map(Number);
+    return compare(parsed, FLOOR) >= 0 && compare(parsed, CEILING) < 0;
+}
+/** The status line for Pi host `version`: the supported range, and for a host outside it the newest tested one. */
+export function piHostLine(version) {
+    return isSupportedPi(version)
+        ? `Pi host: ${version} (supported: ${SUPPORTED_PI_RANGE})`
+        : `Pi host: ${version} (outside the supported range ${SUPPORTED_PI_RANGE}; the newest tested host: npm install -g @earendil-works/pi-coding-agent@${NEWEST_TESTED_PI_VERSION})`;
+}

package/dist/signin/index.d.ts

@@ -0,0 +1,9 @@
+export { checkKeys, checkSetupPrompt, JEV_KEYS } from "./spec.js";
+export type { CheckOptions, Choice, DemoSpec, EyesNeed, Key, KeyReport, ModelNeed, Package, Platform, Program, ReportItem, RunMode, SetupPromptReport } from "./spec.js";
+export { AGENT_NAME, CHATGPT_PROVIDER, consoleInteraction, signIn, SignInError } from "./signin.js";
+export type { ConsoleIo, SignedIn, SignInOptions } from "./signin.js";
+export { CHATGPT_UNSUPPORTED, resolveModel, ResolveError } from "./resolve.js";
+export type { EyesModel, ResolvedModel, ResolveOptions } from "./resolve.js";
+export { USAGE_LIMIT_CODE, UsageLimitError, usageLimitError } from "./limit.js";
+export { agentrunHome, AuthStoreError, FileCredentialStore, fileCredentialStore } from "./store.js";
+export type { FileCredentialStoreOptions } from "./store.js";

package/dist/signin/index.js

@@ -0,0 +1,7 @@
+// Sign in, pick a model, check keys: the shared piece every demo runs first. The only entry of this package that
+// reaches pi-ai, an optional peer; every other entry stays free of it.
+export { checkKeys, checkSetupPrompt, JEV_KEYS } from "./spec.js";
+export { AGENT_NAME, CHATGPT_PROVIDER, consoleInteraction, signIn, SignInError } from "./signin.js";
+export { CHATGPT_UNSUPPORTED, resolveModel, ResolveError } from "./resolve.js";
+export { USAGE_LIMIT_CODE, UsageLimitError, usageLimitError } from "./limit.js";
+export { agentrunHome, AuthStoreError, FileCredentialStore, fileCredentialStore } from "./store.js";

package/dist/signin/limit.d.ts

@@ -0,0 +1,10 @@
+export declare const USAGE_LIMIT_CODE = "subscription_sharing_usage_limit_exceeded";
+export declare class UsageLimitError extends Error {
+    readonly code = "USAGE_LIMIT";
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** The typed limit error when `value` (an error, an assistant message from a failed request, or its text) is the plan's
+ *  usage limit; undefined otherwise. */
+export declare function usageLimitError(value: unknown): UsageLimitError | undefined;

package/dist/signin/limit.js

@@ -0,0 +1,23 @@
+// The ChatGPT plan's usage limit (five hours on Plus, shared with every other app the user signed in to). OpenAI answers
+// a request past it with 429 `subscription_sharing_usage_limit_exceeded`, at the start or mid-stream. It resets after
+// hours, not seconds, so it is never retried: pi-ai sends a request once by default and classes the code as not
+// retryable, and this maps it to one typed error.
+export const USAGE_LIMIT_CODE = "subscription_sharing_usage_limit_exceeded";
+export class UsageLimitError extends Error {
+    code = "USAGE_LIMIT";
+    constructor(options) {
+        super("Your ChatGPT plan's usage limit is reached; wait, or set a provider key.", options);
+        this.name = "UsageLimitError";
+    }
+}
+/** The typed limit error when `value` (an error, an assistant message from a failed request, or its text) is the plan's
+ *  usage limit; undefined otherwise. */
+export function usageLimitError(value) {
+    if (value instanceof UsageLimitError)
+        return value;
+    const text = typeof value === "string" ? value
+        : value instanceof Error ? value.message
+            : value && typeof value === "object" && "errorMessage" in value ? String(value.errorMessage ?? "")
+                : "";
+    return text.includes(USAGE_LIMIT_CODE) ? new UsageLimitError({ cause: value }) : undefined;
+}

package/dist/signin/resolve.d.ts

@@ -0,0 +1,47 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { type SignInOptions } from "./signin.js";
+import type { DemoSpec } from "./spec.js";
+/** What Sign in with ChatGPT covers: streaming Responses calls with `store: false`, without these. */
+export declare const CHATGPT_UNSUPPORTED: readonly string[];
+export type ResolveOptions = Omit<SignInOptions, "home"> & {
+    provider?: string;
+    model?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    /** An explicit eyes model (`--eyes-model`); `model` defaults to the spec's eyes default. */
+    eyes?: {
+        provider: string;
+        model?: string;
+    };
+    signal?: AbortSignal;
+};
+type Resolved = {
+    model: Model<Api>;
+    /** The key valid now. Not enumerable, and left out of `toJSON`. */
+    readonly apiKey: string;
+    /** A key valid at the time of the call: a sign-in's token is refreshed under the store's lock when it is near expiry. */
+    getApiKey(): Promise<string>;
+    /** Only streaming Responses calls with `store: false`, without `unsupported`. */
+    responsesOnly: boolean;
+    unsupported: readonly string[];
+    toJSON(): Record<string, unknown>;
+};
+export type ResolvedModel = Resolved & {
+    source: "flag" | "chatgpt";
+    limit?: string;
+    eyes?: EyesModel;
+};
+export type EyesModel = Resolved & {
+    source: "flag" | "lead";
+};
+export declare class ResolveError extends Error {
+    readonly code: "FLAGS" | "UNKNOWN_PROVIDER" | "UNKNOWN_MODEL" | "MISSING_KEY" | "NEEDS" | "EYES" | "NO_MODEL" | "MODEL_LIST" | "SIGNED_OUT";
+    constructor(code: "FLAGS" | "UNKNOWN_PROVIDER" | "UNKNOWN_MODEL" | "MISSING_KEY" | "NEEDS" | "EYES" | "NO_MODEL" | "MODEL_LIST" | "SIGNED_OUT", message: string);
+}
+/**
+ * The model this run uses and the key to send, in the order above. The eyes model, when the spec has one, resolves the
+ * same way: an explicit eyes model with its provider's key, else the lead's model when it meets the eyes' needs, else
+ * a `ResolveError` ("EYES") naming the gap. The ChatGPT plan takes no video input.
+ */
+export declare function resolveModel(spec: DemoSpec, options?: ResolveOptions): Promise<ResolvedModel>;
+export {};