@parcha/agentrun-pi 0.1.0-beta.23 → 0.1.0-beta.27

package/dist/durable/index.d.ts

@@ -1,6 +1,6 @@
 export type { RecoveryBinding, RecoveryEffect, RecoveryJournal, RecoveryNote, RecoveryStore } from "@parcha/agentrun-dsl/recovery";
 export { documentStore, type DocumentStoreHost, type DocumentStoreOptions } from "./store.js";
-export { committedRoutes, durableDecisions, durableDoc, readJournal, type JournalView } from "./readers.js";
+export { committedRoutes, durableDecisions, durableDoc, readJournal, type DurableReadOptions, type JournalView } from "./readers.js";
 export { recordCommits, recordingLines, snapshotLines, type RecordingLine, type RecordingSource } from "./recording.js";
 export { reuseReceipts, seedReceipts, ReceiptIndex, type ReceiptReuse, type ReuseReceiptsOptions, type ReusableTool } from "./receipts.js";
 export { effectResultOf } from "../effect-result.js";

package/dist/durable/node-runner.js

@@ -12,6 +12,7 @@
 import { randomUUID } from "node:crypto";
 import { configure, defineDoc, defineExtension, GenerationTask, hook, section, } from "@earendil-works/pi-durable";
 import { canonicalSha256, runStopOf } from "@parcha/agentrun-dsl/recovery";
+import { SUBMIT_TOOL } from "../host-tools.js";
 import { nodeThinking } from "../thinking.js";
 import { closeNodeAttempt, runNodeAttempt } from "./node.js";
 import { DELIVERY_ATTEMPTS, lintRecordRoot, submitFooter } from "./record.js";
@@ -78,7 +79,7 @@ async function underStop(signal, work) {
     }
 }
 const listed = (value) => Array.isArray(value);
-const isSubmit = (tool) => tool.name === "submit";
+const isSubmit = (tool) => tool.name === SUBMIT_TOOL;
 /** The node runner over a host. Install `extension` in the registry before the Harness opens; `on` binds the runner
  *  to where its conversations live (`taskScope`, `hostScope`). */
 export function nodeRunner(host, options = {}) {
@@ -177,7 +178,7 @@ export function nodeRunner(host, options = {}) {
                 const { agent, record } = await underStop(signal, async () => ({ agent: leveled(await host.agent(node), node), record: await host.record?.(node) ?? {} }));
                 const label = record.label ?? `the ${node.label} record`;
                 const offered = (listed(agent.tools) ? agent.tools : listed(agent.extensions) ? agent.extensions.flatMap((selected) => selected.tools ?? []) : [])
-                    .map((offer) => offer.name).filter((name) => name !== "submit");
+                    .map((offer) => offer.name).filter((name) => name !== SUBMIT_TOOL);
                 const system = [...node.system, host.stance?.(node, { tools: offered })].filter(Boolean).join("\n\n");
                 const input = inputOf(node.user);
                 const reviewers = [

package/dist/durable/readers.d.ts

@@ -11,11 +11,16 @@ export type JournalView = {
     notes: RecoveryNote[];
     effects: RecoveryEffect[];
 };
+/** How a reader opens the store file. `immutable` opens it as SQLite's immutable file, for a store no process writes any
+ *  more and with no write-ahead log beside it (an ended run's): nothing beside it is read or made. */
+export type DurableReadOptions = {
+    immutable?: boolean;
+};
 /** The run's store `file`, opened read-only for `read`; null when there is no such file. Every query of one `read` runs
  *  in one read transaction, so what it returns is one commit's view, whatever a writer commits meanwhile. */
-export declare function withDurableFile<T>(file: string, read: (db: Database) => T): T | null;
+export declare function withDurableFile<T>(file: string, read: (db: Database) => T, options?: DurableReadOptions): T | null;
 /** A Session document of the run's store `file`, read-only; undefined when the file or the document is absent. */
-export declare function durableDoc<T = Record<string, unknown>>(file: string, kind: string, key?: string): T | undefined;
+export declare function durableDoc<T = Record<string, unknown>>(file: string, kind: string, key?: string, options?: DurableReadOptions): T | undefined;
 /** The decision rows (`agentrun.decisions`) of the run's store `file`, in commit order, in whichever form the store holds: the single
  *  document's `receipts` list, or the keyed documents (one row each, in the order of their keys). A reader that folds decisions from the
  *  store uses this and not `durableDoc(file, "agentrun.decisions").receipts`, which is nothing in the keyed form. */
@@ -25,7 +30,7 @@ export declare function durableDecisions(file: string): Array<Record<string, unk
  *  admitted, in either layout: in the keyed one (`agentrun.frozen_run.v4`) the effects a map item owns, nested maps
  *  included, are listed by that item's record, not the driver's, and are read from there. `state` is the driver's own
  *  record: in the keyed layout what lies in each map item stays in the item's record. */
-export declare function readJournal(file: string, key: string): JournalView | undefined;
+export declare function readJournal(file: string, key: string, options?: DurableReadOptions): JournalView | undefined;
 /** Every committed route decision a frozen snapshot holds (each judge's answer, whole), by execution path. Empty for a
  *  state that is no snapshot. */
 export declare function committedRoutes(state: unknown): Record<string, Json>;

package/dist/durable/readers.js

@@ -4,16 +4,17 @@
 // readers take the store file itself (pi-durable's SQLite file, wherever the host keeps it), never a directory.
 import fs from "node:fs";
 import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 import { apply } from "@earendil-works/chord/delta";
 import { decisionKey } from "./decisions.js";
 import { effectKey } from "./store.js";
 /** The run's store `file`, opened read-only for `read`; null when there is no such file. Every query of one `read` runs
  *  in one read transaction, so what it returns is one commit's view, whatever a writer commits meanwhile. */
-export function withDurableFile(file, read) {
+export function withDurableFile(file, read, options = {}) {
     if (!fs.existsSync(file))
         return null;
     const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
-    const db = new DatabaseSync(file, { readOnly: true, timeout: 5000 });
+    const db = new DatabaseSync(options.immutable ? `${pathToFileURL(file).href}?immutable=1` : file, { readOnly: true, timeout: 5000 });
     try {
         db.exec("BEGIN");
         return read(db);
@@ -67,8 +68,8 @@ function itemEffects(db, key, table, into) {
     }
 }
 /** A Session document of the run's store `file`, read-only; undefined when the file or the document is absent. */
-export function durableDoc(file, kind, key) {
-    return (withDurableFile(file, (db) => sessionDoc(db, kind, key)) ?? undefined);
+export function durableDoc(file, kind, key, options = {}) {
+    return (withDurableFile(file, (db) => sessionDoc(db, kind, key), options) ?? undefined);
 }
 /** The decision rows (`agentrun.decisions`) of the run's store `file`, in commit order, in whichever form the store holds: the single
  *  document's `receipts` list, or the keyed documents (one row each, in the order of their keys). A reader that folds decisions from the
@@ -94,7 +95,7 @@ export function durableDecisions(file) {
  *  admitted, in either layout: in the keyed one (`agentrun.frozen_run.v4`) the effects a map item owns, nested maps
  *  included, are listed by that item's record, not the driver's, and are read from there. `state` is the driver's own
  *  record: in the keyed layout what lies in each map item stays in the item's record. */
-export function readJournal(file, key) {
+export function readJournal(file, key, options = {}) {
     return withDurableFile(file, (db) => {
         const doc = sessionDoc(db, "agentrun.driver", key);
         if (!doc || doc.binding === null)
@@ -113,7 +114,7 @@ export function readJournal(file, key) {
             return { id, name: e?.name ?? "", argsHash: e?.argsHash ?? "", status: e?.status ?? "unknown", session: e?.session ?? null, result: e?.result ?? null, ...(e?.intent ? { intent: e.intent } : {}), ...(e?.args !== undefined ? { args: e.args } : {}), ...(Array.isArray(e?.calls) ? { calls: e.calls } : {}) };
         });
         return { binding: doc.binding, inputs: doc.inputs, generation: doc.generation, revision: doc.revision, state: doc.state, notes: doc.notes, effects };
-    }) ?? undefined;
+    }, options) ?? undefined;
 }
 /** Every committed route decision a frozen snapshot holds (each judge's answer, whole), by execution path. Empty for a
  *  state that is no snapshot. */

package/dist/durable/record-tool.js

@@ -1,5 +1,6 @@
 import { defineDoc, defineTool, GenerationTask, hook, } from "@earendil-works/pi-durable";
 import { DELIVERY_ATTEMPTS, deliver, deliveryTerminates, deliveryText, fileSubmission, mixedFileSubmission, nudgeText, repairRecord, VIOLATIONS_SHOWN, } from "./record.js";
+import { SUBMIT_TOOL } from "../host-tools.js";
 import { toolResult } from "./pi-versions.js";
 /** The record a conversation delivered, or null while it has not, and the delivery attempts it has spent. */
 export const RecordDoc = defineDoc({
@@ -76,7 +77,7 @@ export function recordTool(options) {
         ...(deliveryTerminates(delivery) ? { control: { terminate: true } } : {}),
     });
     return defineTool({
-        name: "submit",
+        name: SUBMIT_TOOL,
         description: shown.description,
         parameters: shown.parameters,
         // Every call's arguments are carried to `execute`; one record's are repaired here, before the Harness validates.

package/dist/durable/workflow-tool.js

@@ -8,7 +8,7 @@ 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 { checkHostTools } from "../host-tools.js";
+import { assertHostTools, SUBMIT_TOOL } from "../host-tools.js";
 import { modelJson } from "../presentation.js";
 import { WorkflowStore } from "../workflow-store.js";
 import { progressLines, WorkflowObservation } from "../workflow-view.js";
@@ -38,7 +38,8 @@ const answer = (value) => toolResult([{ type: "text", text: modelJson(value) }],
  *  agent definition. `workflow` reads and stops runs from the host's side. */
 export function createWorkflowTool(host) {
     // The host's tools pass the check the coding-agent extension's do; the tool's own name and the node runner's submit are reserved.
-    checkHostTools(host.tools ?? [], { reserved: [host.name ?? "agentrun", "submit"], executable: false });
+    const name = host.name ?? "agentrun";
+    assertHostTools(host.tools ?? [], { reserved: [name, SUBMIT_TOOL], executable: false });
     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
@@ -86,7 +87,7 @@ export function createWorkflowTool(host) {
         },
     });
     const tool = defineTool({
-        name: host.name ?? "agentrun",
+        name,
         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",

package/dist/extension.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { Compile } from 'typebox/compile';
-import { checkHostTools } from './host-tools.js';
+import { assertHostTools, SUBMIT_TOOL } from './host-tools.js';
 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 } from '@parcha/agentrun-dsl';
@@ -24,11 +24,14 @@ 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';
+import { OperatorError } from './operator-error.js';
 const constructors = {
     read: createReadToolDefinition, bash: createBashToolDefinition, edit: createEditToolDefinition,
     write: createWriteToolDefinition, grep: createGrepToolDefinition, find: createFindToolDefinition, ls: createLsToolDefinition,
 };
 const mutatingTools = new Set(['bash', 'edit', 'write']);
+/** The extension's own tool's name, which a host tool may not take. */
+const toolName = 'agentrun';
 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) {
@@ -79,7 +82,7 @@ function registerExtension(pi, configuration) {
     const toolSet = (ctx, trusted = false) => {
         if (configuration.hostTools) {
             const supplied = configuration.hostTools(ctx);
-            checkHostTools(supplied, { reserved: ['agentrun', 'submit'], executable: true });
+            assertHostTools(supplied, { reserved: [toolName, SUBMIT_TOOL], executable: true });
             return supplied.map(tool => ({ ...tool, parameters: structuredClone(tool.parameters), ...(tool.resultSchema ? { resultSchema: structuredClone(tool.resultSchema) } : {}) }));
         }
         const active = new Set(pi.getActiveTools());
@@ -153,7 +156,8 @@ function registerExtension(pi, configuration) {
         pi.sendMessage({ customType: 'agentrun', content: safe(content), display: true, details });
     };
     const commandError = (s, error) => {
-        const message = error instanceof Error && (error instanceof WorkflowStoreError || error.name === 'ExtensionServiceError' || /^(No workflow|Inspect a workflow|A workflow|Cannot inspect|Workflow|Code|Executable|Unsupported|Invalid workflow|AgentRun requires|AgentRun authoring|The active Pi|Saved workflow|SOP|The SOP|Use \/agentrun sop)/.test(error.message))
+        // What may reach the operator is decided by the error's type, never by its text.
+        const message = error instanceof Error && (error instanceof WorkflowStoreError || error.name === 'ExtensionServiceError' || error instanceof OperatorError)
             ? 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);
     };
@@ -164,10 +168,10 @@ function registerExtension(pi, configuration) {
     };
     const inspect = (ctx, s, workflow, input) => {
         if (s.busy && (workflow !== undefined || input !== undefined))
-            throw new Error('A workflow is running. Stop it before changing its definition or input.');
+            throw new OperatorError('A workflow is running. Stop it before changing its definition or input.');
         const candidate = workflow === undefined ? s.draft : workflow;
         if (candidate === undefined)
-            throw new Error('No workflow yet. Describe a task with /agentrun <task>.');
+            throw new OperatorError('No workflow yet. Describe a task with /agentrun <task>.');
         // 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 });
@@ -206,7 +210,7 @@ function registerExtension(pi, configuration) {
             signal.throwIfAborted();
             toolCalls++;
             if (limits.toolAttempts !== null && toolCalls > limits.toolAttempts)
-                throw new Error('Workflow tool-call limit reached');
+                throw new OperatorError('Workflow tool-call limit reached');
             configuration.onToolAttempt?.();
             signal.throwIfAborted();
         };
@@ -224,7 +228,7 @@ function registerExtension(pi, configuration) {
                     signal.throwIfAborted();
                     modelCalls++;
                     if (limits.modelRequests !== null && modelCalls > limits.modelRequests)
-                        throw new Error('Workflow model-request limit reached');
+                        throw new OperatorError('Workflow model-request limit reached');
                     return ctx.modelRegistry.streamSimple(model, transcript, { ...options, reasoning: options?.reasoning === 'off' ? undefined : options?.reasoning, signal: options?.signal ? AbortSignal.any([signal, options.signal]) : signal });
                 },
             },
@@ -247,26 +251,26 @@ function registerExtension(pi, configuration) {
                     judge = createJevRunner({ signal, maxAttempts: 1 });
                 }
                 catch {
-                    throw new Error('AgentRun requires TypeSafe configuration for this workflow. Set TYPESAFE_API_KEY and, for a gateway, TYPESAFE_BASE_URL before running.');
+                    throw new OperatorError('AgentRun requires TypeSafe configuration for this workflow. Set TYPESAFE_API_KEY and, for a gateway, TYPESAFE_BASE_URL before running.');
                 }
             }
         }
         return {
             runNode: request => {
                 if (!runner)
-                    throw new Error('Workflow agent adapter was not admitted');
+                    throw new OperatorError('Workflow agent adapter was not admitted');
                 return runner(request);
             },
             runJudge: request => {
                 if (!judge)
-                    throw new Error('Workflow Jev adapter was not admitted');
+                    throw new OperatorError('Workflow Jev adapter was not admitted');
                 return judge(request);
             },
             runEffect: async ({ node, input, signal: effectSignal }) => {
                 countTool();
                 const tool = tools.find(tool => tool.name === node.tool);
                 if (!tool || node.via !== 'tool')
-                    throw new Error('Workflow requested an unavailable tool');
+                    throw new OperatorError('Workflow requested an unavailable tool');
                 let result;
                 try {
                     result = await tool.execute('agentrun-effect', input, effectSignal, undefined, workflowToolContext(ctx));
@@ -292,21 +296,21 @@ function registerExtension(pi, configuration) {
         else if (s.sop) {
             const read = await readSopFile(ctx.cwd, s.sop.file);
             if (read.sha256 !== s.sop.sha256)
-                throw new Error(`SOP file ${s.sop.file} changed since it was supplied. Run /agentrun sop ${s.sop.file} again to use the new text.`);
+                throw new OperatorError(`SOP file ${s.sop.file} changed since it was supplied. Run /agentrun sop ${s.sop.file} again to use the new text.`);
             sop = read;
         }
         else
-            throw new Error(`Workflow requires SOP text for ${needed.map(name => `"${name}"`).join(', ')}. Supply it with /agentrun sop <file>.`);
+            throw new OperatorError(`Workflow requires SOP text for ${needed.map(name => `"${name}"`).join(', ')}. Supply it with /agentrun sop <file>.`);
         const missing = missingSopSections(sop.text, needed);
         if (missing.length)
-            throw new Error(`SOP text has no "## <section>" heading for ${missing.map(name => `"${name}"`).join(', ')}.`);
+            throw new OperatorError(`SOP text has no "## <section>" heading for ${missing.map(name => `"${name}"`).join(', ')}.`);
         return sop;
     };
     const execute = async (ctx, s, input, options = {}) => {
         if (s.busy)
-            throw new Error('A workflow is already running. Use /agentrun stop first.');
+            throw new OperatorError('A workflow is already running. Use /agentrun stop first.');
         if (!s.draft)
-            throw new Error('Inspect a workflow first. Try /agentrun demo, or describe a task with /agentrun <task>.');
+            throw new OperatorError('Inspect a workflow first. Try /agentrun demo, or describe a task with /agentrun <task>.');
         const scripted = s.demo !== undefined;
         s.busy = true;
         s.controller = new AbortController();
@@ -425,7 +429,7 @@ function registerExtension(pi, configuration) {
      *  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>.');
+            throw new OperatorError('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();
@@ -452,7 +456,7 @@ function registerExtension(pi, configuration) {
     };
     const launch = async (ctx, s, input, trusted = false) => {
         if (s.busy)
-            throw new Error('A workflow is already running. Use /agentrun stop first.');
+            throw new OperatorError('A workflow is already running. Use /agentrun stop first.');
         // Capture host selection and permission before yielding the interactive command loop.
         const runContext = { ...ctx, model: ctx.model, thinkingLevel: ctx.thinkingLevel ?? pi.getThinkingLevel() };
         const pending = execute(runContext, s, structuredClone(input), { trusted })
@@ -467,10 +471,10 @@ function registerExtension(pi, configuration) {
             await pending;
     };
     pi.registerTool({
-        name: 'agentrun', label: 'AgentRun workflow',
+        name: toolName, 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. 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.',
+            : '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. A run this session left interrupted or failed resumes from its journal when its draft, input, SOP and tools are unchanged; any other run starts new. Scripted demos stay scripted on rerun.',
         parameters: workflowToolParameters(),
         executionMode: 'sequential',
         renderResult(result, options) {
@@ -487,9 +491,9 @@ function registerExtension(pi, configuration) {
             const store = new WorkflowStore(ctx.cwd);
             if (args.action === 'save') {
                 if (s.busy)
-                    throw new Error('A workflow is running. Save after it stops.');
+                    throw new OperatorError('A workflow is running. Save after it stops.');
                 if (!s.draft)
-                    throw new Error('No workflow to save. Inspect a workflow first.');
+                    throw new OperatorError('No workflow to save. Inspect a workflow first.');
                 const saved = await store.save(args.name ?? '', s.draft);
                 s.savedName = saved.name;
                 persist(s);
@@ -583,9 +587,9 @@ function registerExtension(pi, configuration) {
                 }
                 else if (/^save(?:\s|$)/.test(command)) {
                     if (s.busy)
-                        throw new Error('A workflow is running. Save after it stops.');
+                        throw new OperatorError('A workflow is running. Save after it stops.');
                     if (!s.draft)
-                        throw new Error('No workflow to save. Inspect a workflow first.');
+                        throw new OperatorError('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);
@@ -639,23 +643,23 @@ function registerExtension(pi, configuration) {
                         return;
                     }
                     if (s.busy)
-                        throw new Error('A workflow is running. Stop it before changing its SOP.');
+                        throw new OperatorError('A workflow is running. Stop it before changing its SOP.');
                     if (configuration.sop)
-                        throw new Error('SOP text comes from the host; /agentrun sop is not used.');
+                        throw new OperatorError('SOP text comes from the host; /agentrun sop is not used.');
                     const read = await readSopFile(ctx.cwd, file);
                     const needed = s.draft ? inspectWorkflow(s.draft).requires.sopSections : [];
                     const missing = missingSopSections(read.text, needed);
                     if (missing.length)
-                        throw new Error(`SOP text has no "## <section>" heading for ${missing.map(name => `"${name}"`).join(', ')}. Nothing was changed.`);
+                        throw new OperatorError(`SOP text has no "## <section>" heading for ${missing.map(name => `"${name}"`).join(', ')}. Nothing was changed.`);
                     s.sop = { file: read.file, sha256: read.sha256 };
                     persist(s);
                     show(s, `SOP set: ${read.file} (${read.text.length} characters). ${needed.length ? `Covers ${needed.map(name => `"${name}"`).join(', ')}.` : 'The current workflow names no section.'}`);
                 }
                 else if (/^input(?:\s|$)/.test(command)) {
                     if (!s.draft)
-                        throw new Error('No workflow yet. Load or describe a procedure first.');
+                        throw new OperatorError('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.');
+                        throw new OperatorError('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.') ?? '';
@@ -669,10 +673,10 @@ function registerExtension(pi, configuration) {
                             input = JSON.parse(supplied);
                         }
                         catch {
-                            throw new Error('Workflow input must be valid JSON, or describe it in plain language.');
+                            throw new OperatorError('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.');
+                            throw new OperatorError('Workflow input must be an object.');
                         inspect(ctx, s, undefined, input);
                         show(s, `Input updated. Nothing was run.\n\n${formatWorkflowView(view(ctx, s))}`);
                     }
@@ -738,12 +742,12 @@ function registerExtension(pi, configuration) {
                 }
                 else {
                     if (s.busy)
-                        throw new Error('A workflow is running. Stop it before starting another.');
+                        throw new OperatorError('A workflow is running. Stop it before starting another.');
                     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.');
+                        throw new OperatorError('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);
+                        throw new OperatorError(PI_MODEL_SETUP_MESSAGE);
                     pi.sendUserMessage(`/skill:${AUTHOR_SKILL_NAME} ${raw}`, { expandPromptTemplates: true });
                 }
             }

package/dist/host-session.js

@@ -1,16 +1,18 @@
 import { Agent } from '@earendil-works/pi-agent-core';
+import { SUBMIT_TOOL } from './host-tools.js';
 import { createPiRunner } from './runner.js';
 import { workflowToolContext } from './tool-context.js';
+import { OperatorError } from './operator-error.js';
 export const PI_MODEL_SETUP_MESSAGE = 'AgentRun requires an active Pi model. Use /login to connect a provider, then /model to select it. Try /agentrun demo without model access.';
 function selectedModel(context) {
     const model = context.model;
     if (!model)
-        throw new Error(PI_MODEL_SETUP_MESSAGE);
+        throw new OperatorError(PI_MODEL_SETUP_MESSAGE);
     if (!context.modelRegistry || typeof context.modelRegistry.streamSimple !== 'function' || typeof context.modelRegistry.getAll !== 'function') {
-        throw new Error('AgentRun requires the host public model registry');
+        throw new OperatorError('AgentRun requires the host public model registry');
     }
     if (!context.modelRegistry.getAll().some(known => known.id === model.id && known.provider === model.provider && known.api === model.api)) {
-        throw new Error(PI_MODEL_SETUP_MESSAGE);
+        throw new OperatorError(PI_MODEL_SETUP_MESSAGE);
     }
     return model;
 }
@@ -28,7 +30,7 @@ export function createPiHostSessionFactory(context) {
             parameters: tool.parameters,
             async execute(id, args, signal, onUpdate) {
                 const result = await tool.execute(id, args, signal, onUpdate, toolContext);
-                if (tool.name === 'submit' && result.details?.accepted === true)
+                if (tool.name === SUBMIT_TOOL && result.details?.accepted === true)
                     delivered = true;
                 return result;
             },

package/dist/host-tools.d.ts

@@ -1,9 +1,12 @@
+/** The tool a workflow node delivers its result with (the runner's and the durable record tool's), so no host tool may
+ *  take its name. */
+export declare const SUBMIT_TOOL = "submit";
 /**
  * Refuses a host's tool list unless it is an array of at most 100 tools, each with a name of 1 to 200 characters that
  * is not blank, not in `reserved` and not repeated, and an object parameter schema (and result schema, when given) the
  * compiler takes. With `executable`, each tool also needs an `execute` function. Throws on the first problem.
  */
-export declare function checkHostTools(tools: unknown, options: {
+export declare function assertHostTools(tools: unknown, options: {
     reserved: readonly string[];
     executable: boolean;
 }): void;

package/dist/host-tools.js

@@ -3,12 +3,15 @@
 import { Compile } from 'typebox/compile';
 /** The most tools a host may register. */
 const MAX_HOST_TOOLS = 100;
+/** The tool a workflow node delivers its result with (the runner's and the durable record tool's), so no host tool may
+ *  take its name. */
+export const SUBMIT_TOOL = 'submit';
 /**
  * Refuses a host's tool list unless it is an array of at most 100 tools, each with a name of 1 to 200 characters that
  * is not blank, not in `reserved` and not repeated, and an object parameter schema (and result schema, when given) the
  * compiler takes. With `executable`, each tool also needs an `execute` function. Throws on the first problem.
  */
-export function checkHostTools(tools, options) {
+export function assertHostTools(tools, options) {
     if (!Array.isArray(tools) || tools.length > MAX_HOST_TOOLS)
         throw new Error(`Host must supply at most ${MAX_HOST_TOOLS} explicit tool definitions`);
     const names = new Set();

package/dist/operator-error.d.ts

@@ -0,0 +1,4 @@
+/** An error whose message is written for the operator, so the extension shows it as it is. Any other error reaches the
+ *  operator as a generic message, since its text may carry what an operator should not see. Its name stays `Error`. */
+export declare class OperatorError extends Error {
+}

package/dist/operator-error.js

@@ -0,0 +1,4 @@
+/** An error whose message is written for the operator, so the extension shows it as it is. Any other error reaches the
+ *  operator as a generic message, since its text may carry what an operator should not see. Its name stays `Error`. */
+export class OperatorError extends Error {
+}

package/dist/runner.js

@@ -1,5 +1,6 @@
 import { Compile } from "typebox/compile";
 import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, ModelRuntime, } from "@earendil-works/pi-coding-agent";
+import { SUBMIT_TOOL } from "./host-tools.js";
 import { PiRunError } from "./run-error.js";
 import { nodeThinking } from "./thinking.js";
 export { PiRunError } from "./run-error.js";
@@ -49,7 +50,7 @@ export function createPiRunner(options) {
     const timeoutMs = options.timeoutMs === null ? null : positive(options.timeoutMs ?? 120_000, "timeoutMs");
     const names = new Set();
     for (const tool of options.tools ?? []) {
-        if (tool.name === "submit" || names.has(tool.name))
+        if (tool.name === SUBMIT_TOOL || names.has(tool.name))
             throw new Error(`Reserved or duplicate Pi tool: ${tool.name}`);
         names.add(tool.name);
     }
@@ -96,7 +97,7 @@ export function createPiRunner(options) {
         let unsubscribe;
         const result = (text, ok) => ({ content: [{ type: "text", text }], details: { accepted: ok } });
         const submit = {
-            name: "submit", label: "Submit result", description: "Deliver a result matching the required JSON Schema. Rejection feedback must be corrected in this session.",
+            name: SUBMIT_TOOL, label: "Submit result", description: "Deliver a result matching the required JSON Schema. Rejection feedback must be corrected in this session.",
             parameters,
             executionMode: "sequential",
             async execute(id, args) {
@@ -162,7 +163,7 @@ export function createPiRunner(options) {
                 cwd, model: options.model, modelRuntime: options.modelRuntime,
                 thinkingLevel: nodeThinking(request.thinking, options.thinkingLevel), maxTurns: maxTurns ?? undefined, resourceLoader, settingsManager,
                 sessionManager,
-                tools: [...requested, "submit"],
+                tools: [...requested, SUBMIT_TOOL],
                 customTools: [...(options.tools ?? []).filter(tool => requested.includes(tool.name)).map(tool => ({
                         ...tool,
                         executionMode: "sequential",
@@ -192,7 +193,7 @@ export function createPiRunner(options) {
             unsubscribe = session.subscribe(event => {
                 // Native events carry correlation IDs, including SDK-rejected calls. Custom
                 // sessions without IDs use execute's counter so one attempt is not counted twice.
-                if (event.type === "tool_execution_start" && event.toolName === "submit" && event.toolCallId !== undefined && !accepted && !stopped && !fatal) {
+                if (event.type === "tool_execution_start" && event.toolName === SUBMIT_TOOL && event.toolCallId !== undefined && !accepted && !stopped && !fatal) {
                     submissions++;
                     pendingSubmissions.set(event.toolCallId, {
                         ...(Object.hasOwn(event, "args") ? { args: structuredClone(event.args) } : {}), executed: false,
@@ -200,7 +201,7 @@ export function createPiRunner(options) {
                     if (maxSubmissions !== null && submissions > maxSubmissions)
                         stop("submission_limit");
                 }
-                if (event.type === "tool_execution_end" && event.toolName === "submit") {
+                if (event.type === "tool_execution_end" && event.toolName === SUBMIT_TOOL) {
                     if (event.toolCallId !== undefined)
                         pendingSubmissions.delete(event.toolCallId);
                     if (!accepted && !stopped && !fatal && maxSubmissions !== null && submissions >= maxSubmissions)
@@ -228,7 +229,8 @@ export function createPiRunner(options) {
                 throw new PiRunError(stopped, turns, submissions);
             if (accepted)
                 return submission;
-            throw new PiRunError(maxTurns !== null && turns >= maxTurns ? "turn_limit" : "no_submission", turns, submissions);
+            // The loop ends only on one of the three above or at the turn cap, so what is left is the cap.
+            throw new PiRunError("turn_limit", turns, submissions);
         }
         catch (error) {
             if (fatal)

package/dist/sop.js

@@ -1,25 +1,26 @@
 import { createHash } from 'node:crypto';
 import { lstat, readFile, realpath } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { OperatorError } from './operator-error.js';
 export const MAX_SOP_BYTES = 512 * 1024;
 export const sopDigest = (text) => createHash('sha256').update(text).digest('hex');
 /** The SOP text of a regular file inside `cwd`; a path that resolves outside it, or a file over the bound, is refused. */
 export async function readSopFile(cwd, file) {
     if (!file.trim() || file.includes('\0'))
-        throw new Error('Use /agentrun sop <file>, a path inside this project.');
+        throw new OperatorError('Use /agentrun sop <file>, a path inside this project.');
     const root = await realpath(cwd);
-    const target = await realpath(resolve(cwd, file)).catch(() => { throw new Error(`SOP file not found: ${file}`); });
+    const target = await realpath(resolve(cwd, file)).catch(() => { throw new OperatorError(`SOP file not found: ${file}`); });
     const inside = relative(root, target);
     if (!inside || inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside))
-        throw new Error('The SOP file must be inside this project.');
+        throw new OperatorError('The SOP file must be inside this project.');
     const info = await lstat(target);
     if (!info.isFile())
-        throw new Error('The SOP must be a regular file.');
+        throw new OperatorError('The SOP must be a regular file.');
     if (info.size > MAX_SOP_BYTES)
-        throw new Error(`The SOP file is larger than ${MAX_SOP_BYTES / 1024} KiB.`);
+        throw new OperatorError(`The SOP file is larger than ${MAX_SOP_BYTES / 1024} KiB.`);
     const text = (await readFile(target, 'utf8')).replace(/^/, '');
     if (!text.trim())
-        throw new Error('The SOP file is empty.');
+        throw new OperatorError('The SOP file is empty.');
     return { file: inside.split(sep).join('/'), text, sha256: sopDigest(text) };
 }
 /** The sections a workflow names that the SOP has no `## <section>` heading line for. */

package/dist/workflow-tool.d.ts

@@ -1,6 +1,6 @@
 import { Type } from 'typebox';
 import { type AuthorHostAddendum, type DryRunResult, type WorkflowDeps } from '@parcha/agentrun-dsl';
-import type { WorkflowExtensionService } from './extension-service.js';
+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: () => {

package/dist/workflow-tool.js

@@ -2,7 +2,9 @@
 // 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 { ExtensionServiceError } from './extension-service.js';
 import { PI_HOST_ADDENDUM } from './host-addendum.js';
+import { OperatorError } from './operator-error.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))),
@@ -28,14 +30,16 @@ export const authoringReferences = (host = PI_HOST_ADDENDUM) => ({
  *  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.');
+        throw new OperatorError('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'}`);
+        const message = `Cannot inspect workflow: ${error instanceof Error ? error.message : 'Invalid workflow'}`;
+        // The service's refusal keeps its type and code, so a host branches on it as it does for a run; either keeps its cause.
+        throw error instanceof ExtensionServiceError ? Object.assign(new ExtensionServiceError(error.code, message), { cause: error }) : new OperatorError(message, { cause: error });
     }
     return { inspection, tree: formatWorkflowTree(inspection) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-pi",
-  "version": "0.1.0-beta.23",
+  "version": "0.1.0-beta.27",
   "description": "Pi extension for building, running and evaluating AgentRun workflows",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,12 +50,12 @@
     "@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.23",
+    "@parcha/pi-durable-disk": "0.1.0-beta.27",
     "typebox": "1.3.7"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.23",
-    "@parcha/agentrun-jev": "0.1.0-beta.23"
+    "@parcha/agentrun-dsl": "0.1.0-beta.27",
+    "@parcha/agentrun-jev": "0.1.0-beta.27"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",