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

package/dist/durable/task.js

@@ -0,0 +1,395 @@
+// A workflow run as one pi-durable task: `agentrun.workflow`, version 1, one phase `run`. The phase opens the recovery
+// driver on the document store, runs the interpreter to its end inside one invocation, and makes one terminal commit;
+// every journal commit in between leaves the task's own state unchanged. The journal is what resumes: a process that
+// dies leaves the task pending, and the next process's `resume()` runs the phase again, which answers what committed
+// from the journal. Three rules from the task spike hold here:
+//   - a typed failure is a committed outcome (`failed`, with the code in `error.detail`), never a throw, so pi records
+//     it whole instead of faulting the task with a message;
+//   - a pause is taken at a seam: the driver stops admitting, an effect in flight completes and commits, the journal
+//     commits `paused`, and the task stays pending until the host closes the Harness; reopening continues it;
+//   - a cancel is pi's `abortTask`, which returns once the task is marked, before it is terminal: pi ends the run
+//     invocation and the conversations the task owns first, then the abort handler commits `cancelled` in the journal
+//     and an `aborted` outcome. A cancelled run never resumes.
+// A host that continues an escalated run (its ladder) does so inside the same invocation, through `escalated`, so the
+// continuation it opens is a conversation the task owns: the run's stops reach it the way they reach the run's steps.
+import { defineDocFamily, defineExtension, defineTask } from "@earendil-works/pi-durable";
+import { runWorkflow } from "@parcha/agentrun-dsl";
+import { bindingDigests, bindingMismatch, canonicalHash, isRecoveryError, openRecovery, recoveryBound, RecoveryError, withRecovery } from "@parcha/agentrun-dsl/recovery";
+import { storageError } from "./pi-versions.js";
+import { documentStore } from "./store.js";
+const RunDoc = defineDocFamily({ kind: "agentrun.task", version: 1, scope: "session", family: true, initial: () => ({ task: null, stop: null }) });
+/** Records a stop on a run's entry. A recorded cancel stands, so the first cancel names the run's source; a recorded
+ *  pause is replaced by the stop that follows it. */
+const recordStop = (run, stop) => { if (run.stop?.action !== "cancel")
+    run.stop = stop; };
+/** The source of the cancel a run's entry records. */
+const cancelSource = (run) => (run?.stop?.action === "cancel" ? run.stop.source ?? undefined : undefined);
+const cancelled = (source) => ({ status: "aborted", reason: source ? `cancelled by ${source}` : "cancelled" });
+const json = (value) => (value === undefined ? null : JSON.parse(JSON.stringify(value)));
+/** Why a request is not the run a task holds, or undefined when it is: the same binding (the workflow as authored and
+ *  what the host binds beside it, as the driver binds its journal) and the same input, each by its canonical digest, so
+ *  key order does not matter. The refusal is the driver's binding mismatch and names what moved: the workflow's parts,
+ *  what the host binds, or the input's fields (`input.<field>`). Each part is compared over its own digests, so a bound
+ *  key named like the input (`input`) hides neither; when both moved, the refusal holds both parts' messages and names. */
+const requestMoved = (held, asked) => {
+    const was = recoveryBound(held.workflow, held.bind), is = recoveryBound(asked.workflow, asked.bind);
+    const parts = [
+        was.binding !== is.binding && bindingMismatch(JSON.stringify(was.inputs), is.inputs),
+        canonicalHash(held.input) !== canonicalHash(asked.input) && bindingMismatch(JSON.stringify(bindingDigests({ input: held.input })), bindingDigests({ input: asked.input })),
+    ].filter((part) => Boolean(part));
+    if (parts.length < 2)
+        return parts[0];
+    return Object.assign(new RecoveryError(parts.map((part) => part.message).join("; "), "RUN_STORE_BINDING_MISMATCH"), { moved: parts.flatMap((part) => part.moved ?? []) });
+};
+const codeOf = (error) => {
+    const code = error?.code;
+    return typeof code === "string" && code ? code : "WORKFLOW_FAILED";
+};
+const messageOf = (error) => String(error?.message ?? error);
+/** A failure's own fields that are plain JSON (a host's typed failure: its stage, its node, its cost), so the host can
+ *  read back the failure it raised. The stack and the cause stay out. */
+const ownFields = (error) => {
+    const out = {};
+    if (!error || typeof error !== "object")
+        return out;
+    for (const [key, value] of Object.entries(error)) {
+        if (key === "stack" || key === "cause" || value === undefined)
+            continue;
+        try {
+            out[key] = json(value);
+        }
+        catch { /* not plain JSON: left out */ }
+    }
+    return out;
+};
+/** The document store over one invocation's commits: a commit after the task was aborted or the Harness closed is
+ *  refused by pi, so the driver can never write past its run's end. The task is the journal's one owner across its
+ *  invocations: its abort handler takes the journal over from a run invocation that never closed it. */
+function invocationStore(runtime, context, key) {
+    const host = {
+        commit: async (change) => {
+            let result;
+            await runtime.commit(async (tx) => { result = await change(tx); return undefined; }, context);
+            return result;
+        },
+    };
+    return documentStore(host, key, { owner: `agentrun.workflow:${runtime.taskId}`, context });
+}
+const uncommitted = new Map();
+const uncommittedId = (key, taskId) => JSON.stringify([key, taskId]);
+const uncommittedOf = (key, taskId) => {
+    const id = uncommittedId(key, taskId);
+    let entry = uncommitted.get(id);
+    if (!entry) {
+        let reject;
+        const promise = new Promise((_, fail) => { reject = fail; });
+        promise.catch(() => undefined);
+        const made = { promise, failed: false, waits: 0, fail: (error) => { made.failed = true; reject(error); } };
+        entry = made;
+        uncommitted.set(id, entry);
+    }
+    return entry;
+};
+/** Runs where this process holds them, by key: the driver a pause is handed to, and when the run ended. */
+const live = new Map();
+/** The task definition, the extension that carries it, and the host's three operations on a run. */
+export function createWorkflowExtension(host) {
+    /** The run's driver over its journal, with the host's options. */
+    const openDriver = async (task, runtime, context, phase) => {
+        const { key, workflow, bind } = task.input;
+        const options = await host.options?.({ key, taskId: task.id, runtime, context, phase });
+        return openRecovery(invocationStore(runtime, context, key), workflow, { ...options, key, ...(bind ? { bind } : {}) });
+    };
+    /** The driver, then what the interpreter runs with: a host that fails to give it lets the driver go. */
+    const open = async (task, runtime, context) => {
+        const driver = await openDriver(task, runtime, context, "run");
+        try {
+            const parts = await host.run({ key: task.input.key, taskId: task.id, runtime, context, driver });
+            const deps = "deps" in parts
+                ? { ...parts.deps, signal: AbortSignal.any([driver.signal, runtime.signal, ...(parts.deps.signal ? [parts.deps.signal] : [])]) }
+                : withRecovery(driver, { ...parts.adapters, signal: runtime.signal }, { durableNodes: parts.durableNodes });
+            return { deps, driver, interpret: ("deps" in parts && parts.interpret) || runWorkflow };
+        }
+        catch (error) {
+            await driver.close().catch(() => undefined);
+            throw error;
+        }
+    };
+    const failed = (error) => ({ status: "failed", error: { message: messageOf(error), detail: { ...ownFields(error), code: codeOf(error) } } });
+    const Workflow = defineTask({
+        name: "agentrun.workflow", version: 1, initial: () => ({ phase: "run" }),
+        phases: {
+            run: async (task, runtime, context) => {
+                const { key, workflow, input } = task.input;
+                /** The run's one terminal commit. One the Session refuses (not an abort's) hands this process's waiters the run's
+                 *  own failure, or the refusal. */
+                const commitEnd = async (outcome, cause) => {
+                    try {
+                        await runtime.commit(() => ({ status: "terminal", outcome }), context);
+                    }
+                    catch (error) {
+                        if (!runtime.signal.aborted)
+                            uncommittedOf(key, task.id).fail(cause ?? error);
+                        throw error;
+                    }
+                };
+                let opened;
+                try {
+                    opened = await open(task, runtime, context);
+                }
+                catch (error) {
+                    if (runtime.signal.aborted)
+                        throw error;
+                    await commitEnd(failed(error), error);
+                    return;
+                }
+                const { deps, driver, interpret } = opened;
+                // A stop the run's entry records is the driver's before anything runs. The entry lets go of a pause once the
+                // journal holds it, so the next start runs again. A failure here lets the driver go and is the run's failure,
+                // as a failure to open is.
+                let early;
+                try {
+                    early = (await runtime.snapshot(RunDoc, key, context))?.stop ?? null;
+                    if (early?.action === "pause") {
+                        driver.stop({ action: "pause", ...(early.source ? { source: early.source } : {}) });
+                        await driver.flush().catch(() => undefined);
+                        await runtime.commit(async (tx) => { const run = await tx.doc(RunDoc, key, null); if (run.stop?.action === "pause")
+                            run.stop = null; return undefined; }, context);
+                    }
+                }
+                catch (error) {
+                    await driver.close().catch(() => undefined);
+                    if (runtime.signal.aborted)
+                        throw error;
+                    await commitEnd(failed(error), error);
+                    return;
+                }
+                let end;
+                live.set(key, { driver, ended: new Promise((resolve) => { end = resolve; }) });
+                let outcome;
+                let cause;
+                const ladder = host.escalated;
+                /** The run continues on the host's ladder; the row the host committed rides on the outcome. */
+                const handOff = async (ending) => {
+                    const continuation = await ladder(ending, { key, taskId: task.id, runtime, context, driver, signal: AbortSignal.any([runtime.signal, driver.signal]) });
+                    await driver.flush();
+                    const row = driver.escalation();
+                    if (!row)
+                        throw Object.assign(new Error("The host continued the run without committing its escalation"), { code: "ESCALATION_NOT_COMMITTED" });
+                    return { status: "completed", result: { status: "escalated", escalation: json(row), state: json(ending.state), continuation: json(continuation) } };
+                };
+                /** A pause the driver took: the task stays pending until the host closes the Harness. */
+                const paused = () => driver.signal.aborted && driver.signal.reason?.code === "FROZEN_PAUSED";
+                try {
+                    const prior = ladder ? driver.escalation() : undefined;
+                    if (early?.action === "cancel") {
+                        // A cancel recorded before pi marked the task (the process died between the two) is taken before any step
+                        // and before the host's ladder on a run reopened after its escalation: this invocation ends the run as the
+                        // abort handler would have.
+                        driver.stop({ action: "cancel", ...(early.source ? { source: early.source } : {}) });
+                        await driver.flush();
+                        outcome = cancelled(early.source ?? undefined);
+                    }
+                    else if (prior) {
+                        driver.checkStop();
+                        outcome = await handOff({ row: prior, state: prior.state });
+                    }
+                    else if (driver.preStepRefusal) {
+                        // A refusal found before any step: nothing runs. With a ladder, the host continues the run from it.
+                        if (!ladder)
+                            throw driver.preStepRefusal;
+                        outcome = await handOff({ refusal: driver.preStepRefusal, state: { ...input } });
+                    }
+                    else {
+                        let run;
+                        try {
+                            run = await interpret(workflow, input, deps);
+                        }
+                        catch (error) {
+                            // A refusal, a stop or an abort never ladders.
+                            if (!ladder || runtime.signal.aborted || driver.signal.aborted || isRecoveryError(error))
+                                throw error;
+                            outcome = await handOff({ error, state: driver.lastState() });
+                        }
+                        if (run)
+                            outcome = run.status === "complete"
+                                ? { status: "completed", result: { status: "complete", output: json(run.output), state: json(run.state) } }
+                                : ladder ? await handOff({ escalation: run.escalation, state: run.state })
+                                    : { status: "completed", result: { status: "escalated", escalation: json(run.escalation), state: json(run.state) } };
+                    }
+                }
+                catch (error) {
+                    // An abort or a close: this invocation may not decide the outcome (its commits are refused), so it only ends.
+                    if (runtime.signal.aborted)
+                        throw error;
+                    if (!paused()) {
+                        outcome = failed(error);
+                        cause = error;
+                    }
+                }
+                finally {
+                    // A paused run stays live here until its invocation ends, so a pause handed over meanwhile is answered.
+                    if (!paused())
+                        live.delete(key);
+                    await driver.close().catch(() => undefined);
+                    end();
+                }
+                if (paused() || !outcome) {
+                    // The pause is in the journal once the driver's commits have landed; the task stays pending, and its
+                    // invocation ends when the host closes the Harness.
+                    await new Promise((resolve) => { if (runtime.signal.aborted)
+                        resolve();
+                    else
+                        runtime.signal.addEventListener("abort", () => resolve(), { once: true }); });
+                    if (live.get(key)?.driver === driver)
+                        live.delete(key);
+                    throw runtime.signal.reason;
+                }
+                await commitEnd(outcome, cause);
+            },
+        },
+        abort: async (task, runtime, context) => {
+            const { key } = task.input;
+            const source = cancelSource(await runtime.snapshot(RunDoc, key, context).catch(() => undefined));
+            // The journal records the cancel, so no later open of it resumes. A journal the driver refuses (a binding that
+            // moved, a checkpoint it cannot read) is left as it is; the task still ends aborted.
+            try {
+                const driver = await openDriver(task, runtime, context, "abort");
+                driver.stop({ action: "cancel", ...(source ? { source } : {}) });
+                await driver.close();
+            }
+            catch { /* the outcome below is committed whatever the journal said */ }
+            await runtime.commit(() => ({ status: "terminal", outcome: cancelled(source) }), context);
+        },
+    });
+    const outcomeOf = async (harness, settled, key, context) => {
+        if (settled.state.status !== "terminal")
+            return undefined;
+        const outcome = settled.state.outcome;
+        if (outcome.status === "completed")
+            return outcome.result;
+        if (outcome.status === "aborted") {
+            const source = cancelSource(await harness.snapshot(RunDoc, key, context));
+            return { status: "stopped", stop: "cancelled", ...(source ? { source } : {}) };
+        }
+        const error = outcome.error;
+        return { status: "refused", code: error?.detail?.code ?? String(outcome.status).toUpperCase(), message: error?.message ?? String(outcome.reason ?? outcome.status), ...(error?.detail ? { detail: error.detail } : {}) };
+    };
+    const handle = (harness, key, taskId, started) => ({
+        key, taskId, started,
+        wait: async (context) => {
+            const failure = uncommittedOf(key, taskId);
+            failure.waits += 1;
+            try {
+                const settled = await Promise.race([harness.waitForTask(taskId, context), failure.promise]);
+                return (await outcomeOf(harness, settled, key, context));
+            }
+            catch (error) {
+                // A Session that failed at a storage error rejects its waits with `SessionFailed` (pi-durable 1.2): the
+                // waiters get the storage's error, as 1.1 gave it.
+                throw storageError(error);
+            }
+            finally {
+                // The last wait to end releases the entry, whether the task ended or the wait did; a failure keeps it.
+                failure.waits -= 1;
+                const id = uncommittedId(key, taskId);
+                if (failure.waits === 0 && !failure.failed && uncommitted.get(id) === failure)
+                    uncommitted.delete(id);
+            }
+        },
+    });
+    return {
+        extension: defineExtension({ name: "agentrun.workflow", tasks: [Workflow] }),
+        /** Start the run `request.key` names, or reach the task that already runs it. The run's entry and its task are
+         *  created in one commit, so two starts of one key make one task. A start that reaches a task asks for the run it
+         *  holds: its workflow, what the host binds and its input are the task's, by canonical digest, so key order does not
+         *  matter. One that asks for another run is refused with the driver's binding mismatch (`RUN_STORE_BINDING_MISMATCH`,
+         *  its `moved` naming the workflow's parts, what the host binds, or the input's fields as `input.<field>`) and
+         *  commits nothing: no task, no stop, no cancel. Another run takes another key. A live task is attached to; a task
+         *  that ended complete, escalated or cancelled is returned as it is; one that ended refused, failed or faulted is
+         *  replaced by a new task over the same journal, which refuses again until the host reconciles it. A journal an
+         *  older build started, with no task, gets one here, and its driver checks the binding as it opens. A stop the host
+         *  gave before the run started (`options.stop`) is recorded in the commit that creates or reaches the task, and is
+         *  taken before anything runs. A cancel aborts the task before the scheduler runs it, so its abort handler commits
+         *  it; one a process recorded and died before pi marked the task is taken by the run's next invocation, before any
+         *  step and before the host's ladder. A pause is handed to the driver by the run's phase as it opens, before any
+         *  step. So a pause given with a start that attaches to a run already running in this process is not taken now: it
+         *  is recorded, and taken when the run's next invocation opens. `stop` pauses a run that is running here. */
+        async start(harness, request, context, options = {}) {
+            const conversationId = options.conversationId ?? (await harness.root(context)).id;
+            const stop = options.stop ? { action: options.stop.action, source: options.stop.source ?? null } : null;
+            const asked = json(request);
+            const [taskId, started] = await harness.commit(async (tx) => {
+                const run = await tx.doc(RunDoc, request.key, null);
+                if (run.task !== null) {
+                    const prior = await tx.task(run.task);
+                    // A request for another run than the task holds is refused, and the throw discards this commit.
+                    const moved = prior && requestMoved(prior.input, asked);
+                    if (moved)
+                        throw moved;
+                    if (prior && prior.state.status !== "terminal") {
+                        if (stop)
+                            recordStop(run, stop);
+                        return [run.task, "attached"];
+                    }
+                    const kept = prior?.state.status === "terminal" && (prior.state.outcome.status === "completed" || prior.state.outcome.status === "aborted");
+                    if (kept)
+                        return [run.task, "settled"];
+                }
+                const id = await tx.createTask(Workflow, asked, { ownership: { kind: "conversation" }, conversationId: conversationId, ...(options.background ? { background: true } : {}) });
+                run.task = id;
+                run.stop = stop;
+                return [id, "created"];
+            }, context);
+            // A failure an earlier invocation of this task left in this process is not this one's; one still awaited is kept,
+            // so the waiters it has and the invocation that may yet fail share it.
+            const earlier = uncommittedId(request.key, taskId);
+            if (uncommitted.get(earlier)?.failed)
+                uncommitted.delete(earlier);
+            if (stop?.action === "cancel" && started !== "settled")
+                await harness.abortTask(taskId, context);
+            harness.resume();
+            return handle(harness, request.key, taskId, started);
+        },
+        /** The run's task and, once it is terminal, its outcome; undefined when no start named the key. */
+        async read(harness, key, context) {
+            const run = await harness.snapshot(RunDoc, key, context);
+            if (!run || run.task === null)
+                return undefined;
+            const record = await harness.getTask(run.task, context);
+            if (!record)
+                return undefined;
+            const outcome = await outcomeOf(harness, record, key, context);
+            return { taskId: record.id, status: record.state.status, ...(outcome ? { outcome } : {}) };
+        },
+        /** Pause or cancel the run. A pause resolves once the journal holds it (an effect in flight completes and commits
+         *  first) or the run ended; the host then closes the Harness, and the task stays pending. A cancel resolves when pi
+         *  has marked the task, before it is terminal; `wait` gives the aborted outcome. */
+        async stop(harness, key, action, context, source) {
+            if (action === "pause") {
+                const running = live.get(key);
+                if (!running)
+                    return "not-live";
+                running.driver.stop({ action: "pause", ...(source ? { source } : {}) });
+                // The run is paused once its work has stopped, not when the journal first holds the pause: a continuation the
+                // host's ladder runs stops through the run's signal and may take a while, and the host lets go of the run only
+                // after it has. Its driver's commits have landed by then.
+                await running.ended;
+                await running.driver.flush().catch(() => undefined);
+                return running.driver.signal.aborted ? "paused" : "ended";
+            }
+            const taskId = await harness.commit(async (tx) => {
+                const run = await tx.doc(RunDoc, key, null);
+                if (run.task === null)
+                    return null;
+                // A finished run keeps what ended it, and the first cancel of a live one names its source.
+                if ((await tx.task(run.task))?.state.status !== "terminal")
+                    recordStop(run, { action: "cancel", source: source ?? null });
+                return run.task;
+            }, context);
+            if (taskId === null)
+                return "not-live";
+            return harness.abortTask(taskId, context);
+        },
+    };
+}

package/dist/extension-service.js

@@ -1,6 +1,7 @@
 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, candidatePolicyErrors, EffectOutcomeUnknownError, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, EffectDeadlineExceededError, } from '@parcha/agentrun-dsl';
 export class ExtensionServiceError extends Error {
@@ -93,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)
@@ -444,6 +456,7 @@ export class WorkflowExtensionService {
             ...(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 } : {}),
             // 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) } : {}),

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;