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

package/dist/extension.js

@@ -24,6 +24,7 @@ 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,
@@ -155,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);
     };
@@ -166,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 });
@@ -208,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();
         };
@@ -226,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 });
                 },
             },
@@ -249,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));
@@ -294,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();
@@ -427,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();
@@ -454,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 })
@@ -489,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);
@@ -585,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);
@@ -641,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.') ?? '';
@@ -671,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))}`);
                     }
@@ -740,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

@@ -2,16 +2,17 @@ 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;
 }

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/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.js

@@ -4,6 +4,7 @@ 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))),
@@ -29,7 +30,7 @@ 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 {
@@ -38,7 +39,7 @@ export function inspectCandidate(checker, candidate, input) {
     catch (error) {
         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 Error(message, { cause: error });
+        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.26",
+  "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.26",
+    "@parcha/pi-durable-disk": "0.1.0-beta.27",
     "typebox": "1.3.7"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.26",
-    "@parcha/agentrun-jev": "0.1.0-beta.26"
+    "@parcha/agentrun-dsl": "0.1.0-beta.27",
+    "@parcha/agentrun-jev": "0.1.0-beta.27"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",