@parcha/agentrun-pi 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/signin/store.d.ts

@@ -0,0 +1,40 @@
+import type { AuthOperationOptions, Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
+/** Where the sign-in lives: `home`, else $AGENTRUN_HOME, else ~/.config/agentrun. */
+export declare function agentrunHome(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare class AuthStoreError extends Error {
+    readonly code: "HOME_MODE" | "LOCK_TIMEOUT" | "CORRUPT";
+    constructor(code: "HOME_MODE" | "LOCK_TIMEOUT" | "CORRUPT", message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type FileCredentialStoreOptions = {
+    /** How long a writer waits for another process's lock before failing. Default 60 s; pi-ai bounds a refresh at 15 s. */
+    lockTimeoutMs?: number;
+};
+export declare class FileCredentialStore implements CredentialStore {
+    readonly home: string;
+    readonly file: string;
+    private readonly lockFile;
+    private readonly lockTimeoutMs;
+    constructor(home: string, options?: FileCredentialStoreOptions);
+    read(providerId: string, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    list(options?: AuthOperationOptions): Promise<readonly CredentialInfo[]>;
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    delete(providerId: string, options?: AuthOperationOptions): Promise<void>;
+    /** This install's host id, a UUID made once and kept in auth.json: the `getDeviceId` of every sign-in from here. */
+    hostId(options?: AuthOperationOptions): Promise<string>;
+    /** Run `fn` on the file as it is under the lock. `signal` cancels only the wait: once `fn` starts, a refresh may have
+     *  rotated the token at the server, so it and its write run to the end. */
+    private exclusive;
+    private load;
+    /** The whole file, written to a new file in the same directory, flushed, then renamed over auth.json. */
+    private save;
+    /** The directory, made 0700 when missing. An existing one that others can reach is refused, not changed. */
+    private ensureHome;
+    /** The cross-process lock: an exclusive transaction on the lock database, taken without blocking the event loop (a
+     *  busy database answers at once and the wait is a timer). Closing the connection ends the transaction and frees it.
+     *  The lock file is created with O_EXCL and never opened or closed by hand afterwards: closing any descriptor of a file
+     *  drops every lock this process holds on it. */
+    private lock;
+}
+export declare function fileCredentialStore(home: string, options?: FileCredentialStoreOptions): FileCredentialStore;

package/dist/signin/store.js

@@ -0,0 +1,206 @@
+// The sign-in's token store: $AGENTRUN_HOME/auth.json, as pi-ai's `CredentialStore`.
+//
+// The directory is 0700 and the file 0600. Every write is the whole file, written beside it and renamed into place, so a
+// reader without the lock always sees one complete version. Writes are serialized inside a process by one chain per file,
+// and across processes by an operating-system lock: an exclusive SQLite transaction on auth.json.lock, an empty
+// database. The system drops that lock when its holder exits or is killed, so there is no abandoned lock to detect or
+// break, and a lock another writer holds is never moved or removed. `modify` re-reads the file under the lock, so
+// pi-ai's refresh, which runs inside `modify` and re-checks expiry there, refreshes once: a process that waited sees the
+// rotated token and leaves it. A token is never written anywhere else, logged or printed.
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/** Where the sign-in lives: `home`, else $AGENTRUN_HOME, else ~/.config/agentrun. */
+export function agentrunHome(home, env = process.env) {
+    return resolve(home ?? env.AGENTRUN_HOME ?? join(homedir(), ".config", "agentrun"));
+}
+export class AuthStoreError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AuthStoreError";
+    }
+}
+/** One chain per auth file in this process: every instance on the same file queues on it, so the lock file only ever
+ *  arbitrates between processes. */
+const chains = new Map();
+const sleep = (ms, signal) => new Promise((done, fail) => {
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); done(); }, ms);
+    const onAbort = () => { clearTimeout(timer); fail(signal?.reason); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+/** node:sqlite, loaded on the first write: Node 22 marks it experimental and warns once when it loads. */
+let sqlite;
+const SQLITE_BUSY = 5;
+/** Every lock connection this process holds, until its writer releases it. A connection nothing references is closed
+ *  by the garbage collector, and closing it frees the lock: a writer whose own code no longer references its wait would
+ *  otherwise lose the lock while still inside. */
+const held = new Set();
+export class FileCredentialStore {
+    home;
+    file;
+    lockFile;
+    lockTimeoutMs;
+    constructor(home, options = {}) {
+        this.home = home;
+        this.file = join(home, "auth.json");
+        this.lockFile = `${this.file}.lock`;
+        this.lockTimeoutMs = options.lockTimeoutMs ?? 60_000;
+    }
+    async read(providerId, options) {
+        options?.signal?.throwIfAborted();
+        return this.load().credentials[providerId];
+    }
+    async list(options) {
+        options?.signal?.throwIfAborted();
+        return Object.entries(this.load().credentials).map(([providerId, credential]) => ({ providerId, type: credential.type }));
+    }
+    modify(providerId, fn, options) {
+        return this.exclusive(async (file) => {
+            const current = file.credentials[providerId];
+            const next = await fn(current);
+            if (next === undefined)
+                return current;
+            file.credentials[providerId] = next;
+            this.save(file);
+            return next;
+        }, options?.signal);
+    }
+    delete(providerId, options) {
+        return this.exclusive(async (file) => {
+            if (!(providerId in file.credentials))
+                return;
+            delete file.credentials[providerId];
+            this.save(file);
+        }, options?.signal);
+    }
+    /** This install's host id, a UUID made once and kept in auth.json: the `getDeviceId` of every sign-in from here. */
+    hostId(options) {
+        return this.exclusive(async (file) => {
+            if (file.hostId)
+                return file.hostId;
+            file.hostId = randomUUID();
+            this.save(file);
+            return file.hostId;
+        }, options?.signal);
+    }
+    /** Run `fn` on the file as it is under the lock. `signal` cancels only the wait: once `fn` starts, a refresh may have
+     *  rotated the token at the server, so it and its write run to the end. */
+    exclusive(fn, signal) {
+        const previous = chains.get(this.file) ?? Promise.resolve();
+        const run = previous.catch(() => { }).then(async () => {
+            signal?.throwIfAborted();
+            const lock = await this.lock(signal);
+            try {
+                return await fn(this.load());
+            }
+            finally {
+                held.delete(lock);
+                lock.close();
+            }
+        });
+        const tail = run.catch(() => { });
+        chains.set(this.file, tail);
+        void tail.then(() => { if (chains.get(this.file) === tail)
+            chains.delete(this.file); });
+        return run;
+    }
+    load() {
+        let text;
+        try {
+            text = readFileSync(this.file, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { version: 1, credentials: {} };
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed?.version !== 1 || typeof parsed.credentials !== "object" || parsed.credentials === null)
+                throw new Error("not an auth file");
+            return parsed;
+        }
+        catch (error) {
+            throw new AuthStoreError("CORRUPT", `${this.file} is not a sign-in file this version reads; move it aside and sign in again`, { cause: error });
+        }
+    }
+    /** The whole file, written to a new file in the same directory, flushed, then renamed over auth.json. */
+    save(file) {
+        this.ensureHome();
+        const temp = join(this.home, `.auth.json.${process.pid}.${randomUUID()}.tmp`);
+        const fd = openSync(temp, "wx", 0o600);
+        try {
+            try {
+                writeSync(fd, `${JSON.stringify(file, null, 2)}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(temp, this.file);
+        }
+        catch (error) {
+            try {
+                unlinkSync(temp);
+            }
+            catch { /* already renamed or never written */ }
+            throw error;
+        }
+    }
+    /** The directory, made 0700 when missing. An existing one that others can reach is refused, not changed. */
+    ensureHome() {
+        mkdirSync(this.home, { recursive: true, mode: 0o700 });
+        if (process.platform === "win32")
+            return;
+        const stat = statSync(this.home);
+        if ((stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid())) {
+            throw new AuthStoreError("HOME_MODE", `${this.home} must be a directory only you can read (mode 0700, owned by you); it is ${(stat.mode & 0o777).toString(8)}. Run chmod 700 on it, or set AGENTRUN_HOME to a new directory.`);
+        }
+    }
+    /** The cross-process lock: an exclusive transaction on the lock database, taken without blocking the event loop (a
+     *  busy database answers at once and the wait is a timer). Closing the connection ends the transaction and frees it.
+     *  The lock file is created with O_EXCL and never opened or closed by hand afterwards: closing any descriptor of a file
+     *  drops every lock this process holds on it. */
+    async lock(signal) {
+        this.ensureHome();
+        try {
+            closeSync(openSync(this.lockFile, "wx", 0o600));
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        sqlite ??= createRequire(import.meta.url)("node:sqlite");
+        const db = new sqlite.DatabaseSync(this.lockFile);
+        const deadline = Date.now() + this.lockTimeoutMs;
+        try {
+            for (let delay = 5;; delay = Math.min(delay * 2, 100)) {
+                signal?.throwIfAborted();
+                try {
+                    db.exec("BEGIN EXCLUSIVE");
+                    held.add(db);
+                    return db;
+                }
+                catch (error) {
+                    if (error.errcode !== SQLITE_BUSY)
+                        throw error;
+                }
+                if (Date.now() > deadline) {
+                    throw new AuthStoreError("LOCK_TIMEOUT", `${this.lockFile} is held by another process; it was not released within ${Math.round(this.lockTimeoutMs / 1000)} s`);
+                }
+                await sleep(delay + Math.random() * delay, signal);
+            }
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+}
+export function fileCredentialStore(home, options) {
+    return new FileCredentialStore(home, options);
+}

package/dist/skills/author/SKILL.md

@@ -123,9 +123,10 @@ Read [the SDK authoring path](references/sdk-authoring.md) only when a host call
 
 These host rules add to the language above; they never change it.
 - This host runs only these node kinds: `chain`, `code`, `agent`, `decide`, `extract`, `report`, `map`, `parallel`, `loop`, `escalate`, `call`, `workflow`, `judge`, `pick`, `sift`, `route`. Author no other kind.
-- 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/skills/author/references/language.md

@@ -76,7 +76,7 @@ Typed questions answered by the host's judge in one request each: no tools, no s
 ### Control nodes
 
 - `chain`: non-empty `steps`, run in order.
-- `map`: `itemsPath` (an upstream list), `body` and `as`. The body sees `item` and `item_index`; `maxConcurrency` is a positive integer (default 4); `resultPath` selects one path from each completed item's state.
+- `map`: `itemsPath` (an upstream list), `body` and `as`. The body sees `item` and `item_index`; `maxConcurrency` is a positive integer (default 4); `resultPath` selects one path from each completed item's state. Without `resultPath`, and with no `as` in the body, each item's result is its whole state, the mapped list included: set `resultPath` (or an `as` in the body) for a large map; the validator warns.
 - `parallel`: at least two `branches`, each starting from the state before the parallel node. Branches write disjoint keys and never read a sibling's writes.
 - `loop`: `body`, `until` (a predicate) and an integer `maxIters` of at least 1 (no maximum), optionally an integer `expect_iters` of at least 1 (priced passes). At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
 - `escalate`: `when` (a predicate), and non-empty `kind`, `stage` and `summary`. When the predicate holds the run stops without output and returns the escalation with its interpolated summary.
@@ -121,9 +121,10 @@ A predicate is one JSON object that names itself in its `predicate` field beside
 
 These host rules add to the language above; they never change it.
 - This host runs only these node kinds: `chain`, `code`, `agent`, `decide`, `extract`, `report`, `map`, `parallel`, `loop`, `escalate`, `call`, `workflow`, `judge`, `pick`, `sift`, `route`. Author no other kind.
-- 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/skills/author/references/sdk-authoring.md

@@ -7,3 +7,5 @@ The session's system text is the [language reference](language.md) followed by t
 With `rubricSections`, every generated LLM node must reference every supplied section, including child workflows. This conservative author policy rejects Jev nodes, semantic `ask` predicates, and `verify` clauses until the host has a separately reviewed question contract. Execution must receive the same authoritative SOP text. A schema field named `node`, `verify`, or `predicate` is ordinary data, not a judgment clause.
 
 Host-owned acceptance callbacks and fixtures remain outside generated workflows. Do not edit them to obtain a pass. Structural acceptance alone does not establish behavior. Keep request text, rubric text, candidates, and reviews in storage appropriate for their contents.
+
+A host that ships a workflow with the input it runs on exports a `Job` (`{ workflow, input, files? }`, files as bytes by path); `defineJob(job)` returns its argument and keeps the workflow's literal type, so `export const workflow = {...} as const satisfies Workflow` and `export default defineJob({ workflow, input })` compile together.

package/dist/workflow-inspector.d.ts

@@ -17,7 +17,7 @@ export interface InspectorView {
     output?: string[];
     readOnly?: boolean;
 }
-export type InspectorAction = 'run' | 'save' | 'load' | 'input' | 'history' | 'stop' | 'edit';
+export type InspectorAction = 'run' | 'dry-run' | 'save' | 'load' | 'input' | 'history' | 'stop' | 'edit';
 /** Exported for deterministic rendering/navigation tests, without a terminal or model. */
 export declare class WorkflowInspector implements Component {
     private readonly getView;

package/dist/workflow-inspector.js

@@ -49,7 +49,7 @@ export class WorkflowInspector {
     actions(view) {
         if (view.readOnly)
             return [];
-        return view.status === 'running' ? ['stop', 'history'] : ['run', 'input', 'edit', 'save', 'load', 'history'];
+        return view.status === 'running' ? ['stop', 'history'] : ['run', 'dry-run', 'input', 'edit', 'save', 'load', 'history'];
     }
     fingerprint() {
         const view = this.view();
@@ -190,7 +190,7 @@ export class WorkflowInspector {
         else if (this.page === 'actions') {
             const actions = this.actions(view);
             this.actionIndex = Math.min(this.actionIndex, actions.length - 1);
-            const labels = { run: 'Run this workflow', save: 'Save procedure', load: 'Load procedure', input: 'Change input', history: 'Inspect run history', stop: 'Stop running workflow', edit: 'Edit procedure' };
+            const labels = { run: 'Run this workflow', 'dry-run': 'Dry-run on synthetic values (no model calls)', save: 'Save procedure', load: 'Load procedure', input: 'Change input', history: 'Inspect run history', stop: 'Stop running workflow', edit: 'Edit procedure' };
             const first = Math.max(0, this.actionIndex - this.viewport + 1);
             body = actions.slice(first, first + this.viewport).map((action, index) => cut(`${first + index === this.actionIndex ? '›' : ' '} ${labels[action]}`));
             position = 'Choose an action; execution stays with Pi.';

package/dist/workflow-store.d.ts

@@ -15,6 +15,12 @@ export declare class WorkflowStoreError extends Error {
 /** Local procedure revisions, not execution state or authority. The host still
  * preflights loaded workflows against current capabilities and approves each run.
  * This is not a sandbox against a process concurrently replacing project directories.
+ *
+ * Public through `@parcha/agentrun-pi/workflows`. The constructor takes a project directory, never the
+ * workflows directory itself: records live in `<projectDirectory>/.pi/agentrun/workflows/<name>/`, the same
+ * place the extension keeps them for its `ctx.cwd`, so the extension and a host that passes that directory
+ * read each other's records. The directory is resolved once when it is used; everything under it must be
+ * real directories and regular files.
  */
 export declare class WorkflowStore {
     private readonly projectDirectory;

package/dist/workflow-store.js

@@ -38,6 +38,12 @@ function checkedWorkflow(value) {
 /** Local procedure revisions, not execution state or authority. The host still
  * preflights loaded workflows against current capabilities and approves each run.
  * This is not a sandbox against a process concurrently replacing project directories.
+ *
+ * Public through `@parcha/agentrun-pi/workflows`. The constructor takes a project directory, never the
+ * workflows directory itself: records live in `<projectDirectory>/.pi/agentrun/workflows/<name>/`, the same
+ * place the extension keeps them for its `ctx.cwd`, so the extension and a host that passes that directory
+ * read each other's records. The directory is resolved once when it is used; everything under it must be
+ * real directories and regular files.
  */
 export class WorkflowStore {
     projectDirectory;

package/dist/workflow-tool.d.ts

@@ -0,0 +1,81 @@
+import { Type } from 'typebox';
+import { type AuthorHostAddendum, type DryRunResult, type WorkflowDeps } from '@parcha/agentrun-dsl';
+import type { WorkflowExtensionService } from './extension-service.js';
+export declare const WORKFLOW_TOOL_ACTIONS: readonly ["describe", "inspect", "dry-run", "run", "save", "load", "list"];
+/** The tool's fields: one action, and the fields an action reads. A host's tool may add its own. */
+export declare const workflowToolProperties: () => {
+    action: Type.TUnion<Type.TLiteral<"run" | "dry-run" | "save" | "load" | "describe" | "inspect" | "list">[]>;
+    name: Type.TOptional<Type.TString>;
+    digest: Type.TOptional<Type.TString>;
+    workflow: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    input: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+};
+/** The tool's parameters. */
+export declare const workflowToolParameters: () => Type.TObject<{
+    action: Type.TUnion<Type.TLiteral<"run" | "dry-run" | "save" | "load" | "describe" | "inspect" | "list">[]>;
+    name: Type.TOptional<Type.TString>;
+    digest: Type.TOptional<Type.TString>;
+    workflow: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    input: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+}>;
+/** What describe says of each tool a workflow may call: its schemas, and the result contract it is called under. */
+export declare const describeTools: (tools: readonly {
+    name: string;
+    description?: string;
+    parameters: unknown;
+    resultSchema?: unknown;
+}[]) => {
+    name: string;
+    description: string | undefined;
+    parameters: unknown;
+    resultSchema: {};
+    resultContract: string;
+}[];
+/** The author references describe returns, with the host's addendum (the coding-agent extension's by default). */
+export declare const authoringReferences: (host?: AuthorHostAddendum) => {
+    language: string;
+    workflow: string;
+    jev: string;
+    host: string;
+};
+/** The checks that run no code (admission by `checker`, structure, a supplied input), and the workflow's tree. A
+ *  refusal throws, naming why. */
+export declare function inspectCandidate(checker: WorkflowExtensionService, candidate: unknown, input?: Record<string, unknown>): {
+    inspection: import("@parcha/agentrun-dsl").WorkflowInspection;
+    tree: string;
+};
+/** A dry run's answer. `status` says whether every check ran: `passed`, `not_run` (a check could not run; `skipped`
+ *  says which, so it is no proof the workflow works) or `failed` (`problems` say why). */
+export type WorkflowDryRun = {
+    status: 'passed' | 'not_run';
+    ok: true;
+    skipped?: string[];
+} | {
+    status: 'failed';
+    ok: false;
+    problems: string[];
+    stage?: string;
+};
+export type DryRunDraftOptions = {
+    /** The input to run on; without one the dry run synthesizes it from the workflow's input schema. */
+    input?: Record<string, unknown>;
+    /** The SOP text for a workflow that names sections. */
+    sop?: string;
+    /** Why no SOP text is available, said when the workflow names sections. */
+    sopUnavailable?: string;
+    /** The operator authorized code for this dry run: code nodes run in this process. A host's `runCode` runs them instead. */
+    trusted?: boolean;
+    runCode?: WorkflowDeps['runCode'];
+    /** How code is authorized in this host, named when a code node does not run. */
+    trustedCommand?: string;
+    /** Ends the dry run at its next step, as not run. */
+    signal?: AbortSignal;
+};
+/** The status of a dry run's result: its own once the DSL gives one, else read from `ok` and `skipped`. */
+export declare function dryRunStatus(result: DryRunResult): WorkflowDryRun['status'];
+/** Dry-runs an inspected draft on synthetic values, or `options.input`: model, Jev and tool calls are synthesized, so
+ *  nothing is paid and nothing outside this process is touched. Code runs only when authorized, and a code failure is
+ *  reported without what it threw. */
+export declare function dryRunDraft(draft: unknown, options?: DryRunDraftOptions): Promise<WorkflowDryRun>;
+/** A dry run as a person reads it. */
+export declare function formatDryRun(report: WorkflowDryRun): string;

package/dist/workflow-tool.js

@@ -0,0 +1,94 @@
+// The agentrun tool's own work, for any host that offers it to an agent: its actions and parameters, describe, inspect
+// and the dry run. Nothing here imports pi's coding agent, its agent core or its TUI, so a pi-durable host can use it.
+import { Type } from 'typebox';
+import { compileTransform, dryRunWorkflow, formatWorkflowTree, inspectWorkflow, loadAuthorReference, renderAuthorHostAddendum, } from '@parcha/agentrun-dsl';
+import { PI_HOST_ADDENDUM } from './host-addendum.js';
+export const WORKFLOW_TOOL_ACTIONS = ['describe', 'inspect', 'dry-run', 'run', 'save', 'load', 'list'];
+/** The tool's fields: one action, and the fields an action reads. A host's tool may add its own. */
+export const workflowToolProperties = () => ({ action: Type.Union(WORKFLOW_TOOL_ACTIONS.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())) });
+/** The tool's parameters. */
+export const workflowToolParameters = () => Type.Object(workflowToolProperties());
+/** What describe says of each tool a workflow may call: its schemas, and the result contract it is called under. */
+export const describeTools = (tools) => tools.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.',
+}));
+/** The author references describe returns, with the host's addendum (the coding-agent extension's by default). */
+export const authoringReferences = (host = PI_HOST_ADDENDUM) => ({
+    language: loadAuthorReference('language'), workflow: loadAuthorReference('workflow-format'), jev: loadAuthorReference('jev-decisions'),
+    host: renderAuthorHostAddendum(host),
+});
+/** The checks that run no code (admission by `checker`, structure, a supplied input), and the workflow's tree. A
+ *  refusal throws, naming why. */
+export function inspectCandidate(checker, candidate, input) {
+    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.');
+    }
+    let inspection;
+    try {
+        inspection = checker.preflight(candidate, input);
+    }
+    catch (error) {
+        throw new Error(`Cannot inspect workflow: ${error instanceof Error ? error.message : 'Invalid workflow'}`);
+    }
+    return { inspection, tree: formatWorkflowTree(inspection) };
+}
+/** The status of a dry run's result: its own once the DSL gives one, else read from `ok` and `skipped`. */
+export function dryRunStatus(result) {
+    const given = result.status;
+    if (given === 'passed' || given === 'not_run' || given === 'failed')
+        return given;
+    return !result.ok ? 'failed' : result.skipped?.length ? 'not_run' : 'passed';
+}
+/** A code node run in this process, as the interpreter runs one; a failure names the node and not what it threw. */
+const inProcessCode = async (node, state, ctx) => {
+    let transform;
+    try {
+        transform = compileTransform(node.code);
+    }
+    catch {
+        throw new Error(`code node "${ctx.label}" did not compile`);
+    }
+    try {
+        return transform(state, { sop: ctx.sop });
+    }
+    catch {
+        throw new Error(`code node "${ctx.label}" threw; what it threw is not shown`);
+    }
+};
+/** Never reached: a draft with code runs it only when authorized, and this keeps validation from running any. */
+const noCode = async (_node, _state, ctx) => { throw new Error(`code node "${ctx.label}" did not run`); };
+/** Dry-runs an inspected draft on synthetic values, or `options.input`: model, Jev and tool calls are synthesized, so
+ *  nothing is paid and nothing outside this process is touched. Code runs only when authorized, and a code failure is
+ *  reported without what it threw. */
+export async function dryRunDraft(draft, options = {}) {
+    const inspection = inspectWorkflow(draft);
+    const code = inspection.nodes.filter(node => node.kind === 'code').map(node => JSON.stringify(node.label));
+    if (code.length && !options.trusted && !options.runCode) {
+        return { status: 'not_run', ok: true, skipped: [`Code node${code.length === 1 ? '' : 's'} ${code.join(', ')} did not run, and nothing else ran: code runs only ${options.trustedCommand ? `with the user command ${options.trustedCommand}` : 'with the host\'s code executor'}.`] };
+    }
+    const sections = inspection.requires.sopSections;
+    if (sections.length && options.sop === undefined) {
+        return { status: 'not_run', ok: true, skipped: [options.sopUnavailable ?? `The workflow needs SOP text for ${sections.map(name => JSON.stringify(name)).join(', ')}, and none was supplied.`] };
+    }
+    const result = await dryRunWorkflow(draft, {
+        ...(options.input === undefined ? {} : { input: options.input }), ...(options.sop === undefined ? {} : { sop: options.sop }),
+        ...(options.signal ? { signal: options.signal } : {}),
+        runCode: options.runCode ?? (code.length ? inProcessCode : noCode),
+    });
+    return { ...result, status: dryRunStatus(result) };
+}
+/** A dry run as a person reads it. */
+export function formatDryRun(report) {
+    const head = !report.ok ? `Dry run failed${report.stage ? ` at "${report.stage}"` : ''}.`
+        : report.status === 'passed' ? 'Dry run passed: every step ran on synthetic values. It checks the wiring, not the answers.'
+            : 'Dry run not run: a check could not run, so this is not proof the workflow works.';
+    const lines = report.ok ? report.skipped ?? [] : report.problems;
+    return [`${head} No model, Jev or tool call was made.`, ...lines.map(line => `- ${line}`)].join('\n');
+}

package/dist/workflow-view.js

@@ -1,4 +1,5 @@
 import { inspectWorkflow } from '@parcha/agentrun-dsl';
+import { workflowGraph } from '@parcha/agentrun-dsl/graph';
 import { cleanText } from './presentation.js';
 import { types as utilTypes } from 'node:util';
 /** Display limits never admit, cancel, or modify execution. */
@@ -188,7 +189,10 @@ export function workflowView(workflow, options = {}) {
     const missing = required.filter((key) => !Object.hasOwn(options.input ?? {}, key));
     const tools = inspection.requires.tools;
     const unavailable = options.availableTools ? tools.filter(name => !options.availableTools.includes(name)) : [];
-    const nodes = inspection.nodes.map(node => {
+    // The nodes are the graph's (`@parcha/agentrun-dsl/graph`, the one the viewer's graph panel draws); inspection only adds what a step writes.
+    const writes = new Map(inspection.nodes.map(node => [node.path, node.writes]));
+    const nodes = workflowGraph(workflow).nodes.map(graphNode => {
+        const node = { ...graphNode, writes: writes.get(graphNode.path) };
         const source = at(definition, node.path) ?? {};
         const childRoot = node.path.lastIndexOf('/workflow/root');
         const owner = childRoot < 0 ? definition : at(definition, node.path.slice(0, childRoot + '/workflow'.length));

package/dist/workflows.d.ts

@@ -0,0 +1 @@
+export { WorkflowStore, WorkflowStoreError, type StoredWorkflow, type WorkflowRevision } from './workflow-store.js';

package/dist/workflows.js

@@ -0,0 +1,3 @@
+// Saved workflows for a host: the store the /agentrun extension keeps for its project directory, against a directory the host passes.
+// It loads nothing from pi, so a host that never runs the extension can import it.
+export { WorkflowStore, WorkflowStoreError } from './workflow-store.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-pi",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.15",
   "description": "Pi extension for building, running and evaluating AgentRun workflows",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,6 +19,14 @@
     "./durable": {
       "types": "./dist/durable/index.d.ts",
       "import": "./dist/durable/index.js"
+    },
+    "./signin": {
+      "types": "./dist/signin/index.d.ts",
+      "import": "./dist/signin/index.js"
+    },
+    "./workflows": {
+      "types": "./dist/workflows.d.ts",
+      "import": "./dist/workflows.js"
     }
   },
   "bin": {
@@ -42,25 +50,29 @@
     "@earendil-works/pi-coding-agent": "1.1.0",
     "@earendil-works/pi-durable": "1.1.0",
     "@earendil-works/pi-tui": "1.1.0",
-    "@parcha/pi-durable-disk": "0.1.0-beta.13",
+    "@parcha/pi-durable-disk": "0.1.0-beta.15",
     "typebox": "1.3.7"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.13",
-    "@parcha/agentrun-jev": "0.1.0-beta.13"
+    "@parcha/agentrun-dsl": "0.1.0-beta.15",
+    "@parcha/agentrun-jev": "0.1.0-beta.15"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
-    "@earendil-works/pi-durable": ">=1.0.4 <1.3.0",
-    "@earendil-works/chord": ">=1.0.4 <1.3.0"
+    "@earendil-works/pi-durable": ">=1.0.4 <1.4.0",
+    "@earendil-works/chord": ">=1.0.4 <1.4.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-agent-core": {
       "optional": true
     },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },