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

package/dist/durable/workflow-tool.js

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

package/dist/extension-service.js

@@ -1,9 +1,9 @@
 import { types as utilTypes } from 'node:util';
 import { JevError, isJevResponseReason } from '@parcha/agentrun-jev';
-import { PiRunError } from './runner.js';
+import { RecoveryError } from '@parcha/agentrun-dsl/recovery';
+import { PiRunError } from './run-error.js';
 import { ToolInputValidationError } from './tool-input-error.js';
-import { inspectWorkflow, runWorkflow, validateWorkflow, EffectOutcomeUnknownError, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, EffectDeadlineExceededError, } from '@parcha/agentrun-dsl';
-import { workflowPolicyErrors } from './admission.js';
+import { inspectWorkflow, runWorkflow, validateWorkflow, candidatePolicyErrors, EffectOutcomeUnknownError, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, EffectDeadlineExceededError, } from '@parcha/agentrun-dsl';
 export class ExtensionServiceError extends Error {
     code;
     constructor(code, message) {
@@ -55,8 +55,10 @@ async function withAdapterDiagnostic(stage, run) {
                 if (error.code === 'http') {
                     if (Number.isInteger(error.status) && error.status >= 100 && error.status <= 599)
                         diagnostic.status = error.status;
-                    if (reason === 'max_tokens_exceeded')
+                    if (reason === 'max_tokens_exceeded') {
                         diagnostic.reason = reason;
+                        diagnostic.message = 'Jev refused the request: it exceeds the model\'s token budget. Send fewer or shorter items per request. No judgment was accepted; provider details are omitted.';
+                    }
                 }
             }
         }
@@ -92,7 +94,18 @@ async function withAdapterDiagnostic(stage, run) {
         throw error;
     }
 }
+/** The code of the first RecoveryError in an error's cause chain. */
+function recoveryCode(error) {
+    for (let current = error, depth = 0; current && depth < 16; current = current.cause, depth += 1) {
+        if (current instanceof RecoveryError)
+            return current.code;
+    }
+    return undefined;
+}
 function localDiagnostic(error) {
+    if (recoveryCode(error) === 'FROZEN_EFFECT_UNKNOWN')
+        return { code: 'FROZEN_EFFECT_UNKNOWN',
+            message: 'A tool call of this run has no recorded outcome. It is not repeated. Find out whether it happened, then start a new run (change the input) or reconcile it in the run journal.' };
     if (error instanceof AggregateError)
         return error.errors.slice(0, 100).map(localDiagnostic).find(Boolean);
     if (error instanceof AdapterDiagnosticError)
@@ -112,6 +125,9 @@ function localDiagnostic(error) {
             missing_map_result: 'A map body did not produce its resultPath. Select a path in the completed body state; a body with as is collected automatically when resultPath is omitted.',
             parallel_write_conflict: 'Parallel branches changed the same top-level state key. Give independent branches distinct output keys and combine them after the parallel node.',
             reserved_state_key: 'A node or host hook wrote an engine-owned "$"-prefixed state key such as $host. Choose another state key; host state is written only through decodeSubmission.',
+            route_missing: 'A route by valuePath found no value at that path and declares no otherwise. Make the earlier step always write a branch name, or add otherwise for the missing case.',
+            route_unknown: 'A route by valuePath found a value that names none of its branches and declares no otherwise. Write only declared branch names upstream, or add otherwise for the rest.',
+            route_type: 'A route by valuePath found a value that is not a string. It reads a branch name and never converts numbers, booleans or objects; map them to a branch name in a code step first.',
         };
         return { code: error.code, stage: error.stage.slice(0, 200),
             // Parallel patch keys may be computed from source values, unlike authored paths.
@@ -125,7 +141,7 @@ function localDiagnostic(error) {
             && stateBytes > maxStateBytes && maxStateBytes > 0)
             return {
                 code: 'jev_state_too_large', stage, stateBytes, maxStateBytes,
-                message: `Jev state at ${stage} is ${stateBytes} UTF-8 bytes; configured host limit is ${maxStateBytes}. No request was sent. A sift batches every item in one state; select original context explicitly or use per-item judgments without losing headers or qualifiers.`
+                message: `Jev state at ${stage} is ${stateBytes} UTF-8 bytes; configured host limit is ${maxStateBytes}. No request was sent. A sift splits its items across requests only when the host sets maxStateBytesPerRequest; otherwise send less of each item or use per-item judgments without losing headers or qualifiers.`
             };
         if (reason === 'invalid_state' || reason === 'invalid_questions')
             return { code: `jev_${reason}`, stage,
@@ -259,7 +275,7 @@ export class WorkflowExtensionService {
         const inspection = inspectWorkflow(workflow);
         if (inspection.nodes.length > extensionStructuralLimits.maxNodes)
             throw new ExtensionServiceError('bounds', 'A workflow may contain at most 200 nodes.');
-        const errors = workflowPolicyErrors(workflow, { allowExecutableCandidates: options.allowExecutableCandidates === true, rubricSections: this.rubricSections, allowedEffectTools: [...this.allowedTools] });
+        const errors = candidatePolicyErrors(workflow, { allowExecutableCandidates: options.allowExecutableCandidates === true, rubricSections: this.rubricSections, allowedEffectTools: [...this.allowedTools] });
         for (const entry of inspection.nodes) {
             const node = entry.path.split('/').slice(1).reduce((item, key) => item[key.replace(/~1/g, '/').replace(/~0/g, '~')], workflow);
             if (node.node === 'artifact')
@@ -362,11 +378,36 @@ export class WorkflowExtensionService {
                 queue.shift()?.();
             }
         };
+        const rejectTrace = (error) => {
+            rejectedEvents++;
+            traceTruncated = true;
+            if (!signal.aborted) {
+                // Snapshot rejects unsafe/non-JSON values separately from resource bounds.
+                // Keep fail-closed cancellation; never echo values or arbitrary error text.
+                const diagnostic = error instanceof ExtensionServiceError && error.code === 'data'
+                    ? new ExtensionServiceError('trace_invalid_data', 'Workflow trace contains non-JSON data. Numbers must be finite; objects and arrays must be plain, acyclic and free of accessors or symbols.')
+                    : error instanceof ExtensionServiceError && error.code === 'bounds'
+                        ? new ExtensionServiceError('limit', 'Workflow trace exceeded its JSON byte, depth or value-count limit.')
+                        : new ExtensionServiceError('trace_capture_failed', 'Workflow trace capture failed. Unsafe event details are omitted.');
+                controller.abort(diagnostic);
+            }
+        };
+        const prepareEvent = (event) => {
+            if (closed)
+                return { type: event.type, label: event.label };
+            try {
+                return snapshot(event, this.limits.maxEventBytes);
+            }
+            catch (error) {
+                rejectTrace(error);
+                return undefined;
+            }
+        };
         const onEvent = (event) => {
             if (closed)
                 return;
             try {
-                const clean = sanitize(snapshot(event, this.limits.maxEventBytes));
+                const clean = sanitize(event);
                 const size = Buffer.byteLength(JSON.stringify(clean));
                 if (size > this.limits.maxEventBytes)
                     throw new ExtensionServiceError('bounds', 'Workflow event exceeds its serialized byte limit.');
@@ -406,26 +447,18 @@ export class WorkflowExtensionService {
                 }
             }
             catch (error) {
-                rejectedEvents++;
-                traceTruncated = true;
-                if (!signal.aborted) {
-                    // Snapshot rejects unsafe/non-JSON values separately from resource bounds.
-                    // Keep fail-closed cancellation; never echo values or arbitrary error text.
-                    const diagnostic = error instanceof ExtensionServiceError && error.code === 'data'
-                        ? new ExtensionServiceError('trace_invalid_data', 'Workflow trace contains non-JSON data. Numbers must be finite; objects and arrays must be plain, acyclic and free of accessors or symbols.')
-                        : error instanceof ExtensionServiceError && error.code === 'bounds'
-                            ? new ExtensionServiceError('limit', 'Workflow trace exceeded its JSON byte, depth or value-count limit.')
-                            : new ExtensionServiceError('trace_capture_failed', 'Workflow trace capture failed. Unsafe event details are omitted.');
-                    controller.abort(diagnostic);
-                }
+                rejectTrace(error);
             }
         };
         const sections = Object.entries(this.rubricSections);
         const deps = {
-            signal, onEvent,
+            signal, onEvent, prepareEvent,
             ...(options.deps.skill ? { skill: options.deps.skill } : {}),
             ...(sections.length ? { sop: sections.map(([name, text]) => `## ${name}\n${text}`).join('\n\n') } : options.deps.sop ? { sop: options.deps.sop } : {}),
-            ...(options.deps.maxQuestionsPerRequest ? { maxQuestionsPerRequest: options.deps.maxQuestionsPerRequest } : {}),
+            // Forward any set limit, so the interpreter rejects an invalid one rather than running without it.
+            ...(options.deps.recovery ? { recovery: options.deps.recovery } : {}),
+            ...(options.deps.maxQuestionsPerRequest !== undefined ? { maxQuestionsPerRequest: options.deps.maxQuestionsPerRequest } : {}),
+            ...(options.deps.maxStateBytesPerRequest !== undefined ? { maxStateBytesPerRequest: options.deps.maxStateBytesPerRequest } : {}),
             ...(options.deps.runNode ? { runNode: params => dispatch('agent', params.signal, () => withAdapterDiagnostic(params.label, () => options.deps.runNode({ ...params, tools: params.tools ?? [...this.allowedTools] })), true) } : {}),
             ...(options.deps.runJudge ? { runJudge: params => dispatch('judge', params.signal, () => withAdapterDiagnostic(params.label, () => options.deps.runJudge(params)), true) } : {}),
             ...(options.deps.runEffect ? { runEffect: params => dispatch('tool', params.signal, () => {
@@ -456,9 +489,17 @@ export class WorkflowExtensionService {
                     failure.errors.slice(0, 100).forEach(collect);
             };
             collect(error);
+            const failedStep = events.findLast(event => event.type === 'node.end' && event.detail?.status === 'failed');
+            const failedPath = failedStep?.executionPath;
+            const toolFailed = failedStep && failedStep.detail?.kind === 'call'
+                && events.some(event => event.type === 'effect.failed' && event.executionPath === failedPath);
+            const observedStage = failedStep?.label.slice(0, 200);
             report = { digest: prepared.digest, status: code === 'cancelled' || code === 'deadline' ? 'interrupted' : 'failed', calls, events,
                 error: !owned && !signal.aborted && !invalidInput && localDiagnostic(error) || { code,
-                    ...(invalidInput ? { stage: 'input', problems: error.problems.slice(0, 8).map(problem => problem.slice(0, 500)) } : {}), message: owned ? reason.message : signal.aborted ? 'Workflow interrupted.' : invalidInput ? 'Input does not match this workflow. Pass input with action run, or inspect the workflow with its input before running.' : 'Workflow failed. Check the prepared graph, input contracts and host adapter access; provider error bodies are omitted.' },
+                    ...(invalidInput ? { stage: 'input', problems: error.problems.slice(0, 8).map(problem => problem.slice(0, 500)) } : observedStage ? { stage: observedStage } : {}),
+                    message: owned ? reason.message : signal.aborted ? 'Workflow interrupted.' : invalidInput ? 'Input does not match this workflow. Pass input with action run, or inspect the workflow with its input before running.'
+                        : toolFailed ? 'A registered tool call failed. Inspect the tool step and reconcile any effect before a new run. Underlying error text is omitted.'
+                            : 'Workflow failed. Inspect the affected step, input contracts and host adapters. Underlying error text is omitted.' },
                 ...(unknown.length ? { uncertainEffects: unknown } : {}), ...(traceTruncated ? { traceTruncated: true } : {}) };
         }
         finally {

package/dist/extension.d.ts

@@ -34,6 +34,8 @@ export interface AgentRunExtensionOptions {
     onWorkflowEvent?: (frame: AgentRunWorkflowEvent) => unknown;
     /** Explicit null disables an execution limit; omitted fields retain finite defaults. */
     runtimeLimits?: Partial<AgentRunRuntimeLimits>;
+    /** The host's SOP text for workflows that name `sopSection`s. It outranks a file the operator supplies with /agentrun sop. */
+    sop?: string;
 }
 /** Configure the native extension without granting configuration to workflow authors. */
 export declare function createAgentRunExtension(options?: AgentRunExtensionOptions): (pi: ExtensionAPI) => void;