@clemrig/flow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clément CHESNEAU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @clemrig/flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write agent workflows in TypeScript and run them with [Claude Code](https://code.claude.com) or [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
+
+A workflow is an explicit graph of **CODE** stages (your code), **AGENT** stages (an agent run by Claude Code or Pi) and **GATE** stages that accept a result or send it back for correction, a bounded number of times. This package is the engine: the API to write workflows, their execution, the agent runtimes and the runs. [`@clemrig/factory`](https://www.npmjs.com/package/@clemrig/factory) builds a command and per-repository workflows on it; [`@clemrig/flow-ui`](https://www.npmjs.com/package/@clemrig/flow-ui) shows the runs in a local dashboard.
+
+## Requirements
+
+macOS or Linux, Node.js 24 or later. For agent stages, the `claude` CLI (2.1.296 or later) or the `pi` CLI (1.1.0 or later) in the `PATH`, connected to its provider. The engine never reads or stores credentials.
+
+## Run a workflow
+
+```sh
+npm install @clemrig/flow
+```
+
+```ts
+import { defineWorkflow, END, node, startRun, step, z } from "@clemrig/flow";
+
+const hello = defineWorkflow({
+  name: "hello",
+  input: z.object({ name: z.string().min(1) }),
+  initial: "greet",
+  nodes: {
+    greet: node(
+      step(async ({ state }) => ({ greeting: `Hello ${String(state.input.name)}` })),
+      { ok: END },
+    ),
+  },
+});
+
+const run = await startRun(
+  {
+    workflow: hello,
+    input: { name: "flow" },
+    prompts: async () => ({}), // prompt texts by name, for agent stages
+    dir: process.cwd(), // where stages and agents work; given to stages as `dir`
+    configDir: process.cwd(), // where relative skill, extension and MCP paths of profiles resolve
+  },
+  { onEvent: (event) => console.log(event.type, event.stage) },
+);
+const state = await run.done;
+console.log(state.status, state.data);
+```
+
+Before it creates the run, `startRun` checks, in this order, `dir` (an existing directory), the budget (`maxCostUsd`, in USD, replaces the workflow's), the input against the workflow's `input` (an `InvalidInputError` lists every problem), the prompts (a non-empty text for each agent stage's prompt) and each runtime the workflow uses, its version and connection checked in `dir`; the first failing check rejects it with its reasons. It then returns the run, its end (`done`) and `stop(reason)`, which fails the run before its next stage. Runs are kept in `runsDir` when it is given. The engine never changes the process's current directory: stage code reaches the working directory through `dir`. While child processes run (agents, commands), a SIGINT or SIGTERM to the program interrupts them, so that none outlives it, and stops each run before its next stage, even if a stage catches the interruption. A program about to quit at once can call `killChildProcesses()`, which kills the child processes of every run.
+
+The stages, gates, corrections, agent profiles, sessions and prompts are described in the "Write a workflow" section of [`@clemrig/factory`'s README](https://www.npmjs.com/package/@clemrig/factory); import them from `@clemrig/flow` here. What it says of `.factory/`, prompt files and `factory run` options belongs to the factory: with the engine alone, the program gives the input, the prompt texts and the directories to `startRun`.
+
+## Runs
+
+Each run keeps `state.json` and `events.jsonl` in its own folder of `runsDir`, by default `.flow/runs/` of `dir`. When the engine creates `.flow/`, it writes a `.gitignore` that ignores everything in it: runs hold inputs, agent outputs and the journal, and stay private. `listRuns(runsDir)`, `loadRun(runsDir, id)`, `loadRunEvents(runsDir, id)`, `summarizeRun(state)` and `presentResult(workflow, state)` read them; `flow-ui` shows them.
+
+## License
+
+MIT

package/dist/app/run.d.ts

@@ -0,0 +1,38 @@
+import type { RunEvent, RunState, Workflow } from "../engine/types.js";
+import { type RuntimeStatus } from "../system/runtimes/inspect.js";
+/** What a run needs: its workflow, its options, its prompts and its directories. */
+export interface RunSetup {
+    workflow: Workflow;
+    /** The run's input, validated by the workflow's input object; none by default. */
+    input?: Record<string, unknown>;
+    /** The run's budget in USD instead of the workflow's. */
+    maxCostUsd?: number;
+    /** Prompt texts by name, read once the input is valid. */
+    prompts(): Promise<Record<string, string>>;
+    /** The directory stages and agents work in. */
+    dir: string;
+    /** Relative skill, extension and MCP command paths of profiles belong to it. */
+    configDir: string;
+    /** Where runs are kept, one directory per run; `.flow/runs/` of `dir` by default. */
+    runsDir?: string;
+}
+export interface RunHooks {
+    /** Each stage, journal and agent event, once recorded. */
+    onEvent(event: RunEvent): void;
+}
+/** A created run, executing in the foreground. */
+export interface StartedRun {
+    state: Readonly<RunState>;
+    /** Each runtime the run uses: version, executable and connection. */
+    runtimes: RuntimeStatus[];
+    /** Settles with the run once it completed or failed. */
+    done: Promise<RunState>;
+    /** Fails the run with `reason` before its next stage. */
+    stop(reason: Error): void;
+}
+/**
+ * Checks input, budget, prompts and runtimes before creating the run, then runs
+ * it: stages and agents work in `dir`; the process's current directory is left
+ * as it is.
+ */
+export declare function startRun(setup: RunSetup, hooks: RunHooks): Promise<StartedRun>;

package/dist/app/run.js

@@ -0,0 +1,104 @@
+import { budgetProblem, emptyMetrics, recordUsage } from "../engine/metrics.js";
+import { executeWorkflow } from "../engine/runner.js";
+import { parseInput } from "../engine/workflow.js";
+import { whenInterrupted } from "../system/process.js";
+import { AgentRuntime } from "../system/runtimes/agent-runtime.js";
+import { inspectRuntimes, } from "../system/runtimes/inspect.js";
+import { createFlowDirectory, defaultRunsDir, FileRunStore, isDirectory, newRunId, } from "../system/store.js";
+/**
+ * Checks input, budget, prompts and runtimes before creating the run, then runs
+ * it: stages and agents work in `dir`; the process's current directory is left
+ * as it is.
+ */
+export async function startRun(setup, hooks) {
+    const { workflow, dir, configDir } = setup;
+    if (!(await isDirectory(dir)))
+        throw new Error(`dir is not an existing directory: ${dir}`);
+    const maxCostUsd = setup.maxCostUsd ?? workflow.maxCostUsd;
+    if (setup.maxCostUsd !== undefined &&
+        !(Number.isFinite(setup.maxCostUsd) && setup.maxCostUsd > 0))
+        throw new Error(`maxCostUsd must be a positive number of USD, got ${typeof setup.maxCostUsd === "string" ? JSON.stringify(setup.maxCostUsd) : String(setup.maxCostUsd)}`);
+    const input = parseInput(workflow, setup.input ?? {});
+    const prompts = await setup.prompts();
+    const unprompted = [
+        ...new Set(Object.values(workflow.agents).map(({ prompt }) => prompt)),
+    ].filter((name) => !(Object.hasOwn(prompts, name) && prompts[name]?.trim()));
+    if (unprompted.length)
+        throw new Error(unprompted.map((name) => `Missing or empty prompt: ${name}`).join("; "));
+    const { runtimes, problems, executables } = await inspectRuntimes(workflow.agents, dir);
+    if (problems.length)
+        throw new Error(`Missing prerequisites: ${problems.map(({ stage, runtime, reason }) => `stage ${stage} (${runtime}): ${reason}`).join("; ")}`);
+    const now = new Date().toISOString();
+    const state = {
+        version: 4,
+        id: newRunId(),
+        workflow: workflow.name,
+        input,
+        stage: workflow.initial,
+        status: "running",
+        data: {},
+        createdAt: now,
+        updatedAt: now,
+        metrics: emptyMetrics(),
+        runtimes: Object.fromEntries(Object.entries(runtimes).map(([runtime, { detail }]) => [
+            runtime,
+            detail,
+        ])),
+    };
+    if (setup.runsDir === undefined)
+        await createFlowDirectory(dir);
+    else if ((await isDirectory(setup.runsDir)) === false)
+        throw new Error(`runsDir is not a directory: ${setup.runsDir}`);
+    const store = new FileRunStore(setup.runsDir ?? defaultRunsDir(dir), state.id);
+    const agent = new AgentRuntime({
+        dir,
+        configDir,
+        prompts,
+        onUsage: async (report) => {
+            if (state.metrics)
+                recordUsage(state.metrics, report);
+            await store.save(state);
+        },
+        run: { id: state.id, directory: store.directory },
+        executables,
+    });
+    await store.save(state);
+    const controller = new AbortController();
+    /**
+     * Past its budget, the run stops: the abort fails it at its next stage
+     * boundary even if workflow code catches the error, and no call starts.
+     */
+    const overBudget = () => {
+        const problem = maxCostUsd === undefined || !state.metrics
+            ? undefined
+            : budgetProblem(state.metrics, maxCostUsd);
+        if (problem)
+            controller.abort(new Error(problem));
+        return problem;
+    };
+    // Checked before each agent call and after it, failed or not, on the figures its runtime announced.
+    const budgeted = {
+        async execute(request, record) {
+            const refused = overBudget();
+            if (refused)
+                throw new Error(refused);
+            const value = await agent
+                .execute(request, record)
+                .finally(() => overBudget());
+            const exceeded = overBudget();
+            if (exceeded)
+                throw new Error(exceeded);
+            return value;
+        },
+    };
+    // The signal that interrupts its processes also stops the run, even if a stage catches the interruption.
+    const release = whenInterrupted((signal) => controller.abort(new Error(`Run interrupted by ${signal}`)));
+    const done = executeWorkflow(workflow, state, { agent: budgeted, dir }, store, { onEvent: hooks.onEvent, signal: controller.signal }).finally(release);
+    return {
+        state,
+        runtimes: Object.values(runtimes),
+        done,
+        stop: (reason) => controller.abort(reason),
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/app/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/app/run.ts"],"names":[],"mappings":"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"}

package/dist/app/runs.d.ts

@@ -0,0 +1,32 @@
+import type { RunEvent, RunState, Workflow } from "../engine/types.js";
+/** A run, or why it cannot be read. */
+export type RunEntry = {
+    id: string;
+    state: RunState;
+} | {
+    id: string;
+    error: string;
+};
+/** The runs kept in `runsDir`, in creation order; an unreadable run comes with its error. */
+export declare function listRuns(runsDir: string): Promise<RunEntry[]>;
+/** A run as a list shows it; a cost no agent announced is unknown (`null`), not zero. */
+export declare function summarizeRun(state: RunState): {
+    id: string;
+    workflow: string;
+    status: "completed" | "failed" | "running";
+    stage: string;
+    durationMs: number | null;
+    costUsd: number | null;
+    /** Some agent call announced no usage. */
+    partial: boolean;
+    updatedAt: string;
+};
+/** One run's state; an unknown ID is refused. */
+export declare function loadRun(runsDir: string, id: string): Promise<RunState>;
+/** One run's stage and journal events, in order. */
+export declare function loadRunEvents(runsDir: string, id: string): Promise<RunEvent[]>;
+/**
+ * A run's result lines: its workflow's rendering, or its validated data without
+ * its workflow. A failing rendering becomes the explanation.
+ */
+export declare function presentResult(workflow: Workflow | undefined, state: Readonly<RunState>): string[];

package/dist/app/runs.js

@@ -0,0 +1,55 @@
+import { elapsedMs } from "../engine/metrics.js";
+import { presentData } from "../engine/workflow.js";
+import { FileRunStore } from "../system/store.js";
+const message = (error) => error instanceof Error ? error.message : String(error);
+/** The runs kept in `runsDir`, in creation order; an unreadable run comes with its error. */
+export async function listRuns(runsDir) {
+    const entries = [];
+    for (const id of await FileRunStore.list(runsDir))
+        try {
+            entries.push({
+                id,
+                state: await new FileRunStore(runsDir, id).load(),
+            });
+        }
+        catch (error) {
+            entries.push({ id, error: message(error) });
+        }
+    return entries;
+}
+/** A run as a list shows it; a cost no agent announced is unknown (`null`), not zero. */
+export function summarizeRun(state) {
+    const usage = state.metrics?.usage;
+    return {
+        id: state.id,
+        workflow: state.workflow,
+        status: state.status,
+        stage: state.stage,
+        durationMs: elapsedMs(state),
+        costUsd: usage?.responses ? usage.costUsd : null,
+        /** Some agent call announced no usage. */
+        partial: Boolean(usage?.missing),
+        updatedAt: state.updatedAt,
+    };
+}
+/** One run's state; an unknown ID is refused. */
+export async function loadRun(runsDir, id) {
+    return new FileRunStore(runsDir, id).load();
+}
+/** One run's stage and journal events, in order. */
+export async function loadRunEvents(runsDir, id) {
+    return new FileRunStore(runsDir, id).events();
+}
+/**
+ * A run's result lines: its workflow's rendering, or its validated data without
+ * its workflow. A failing rendering becomes the explanation.
+ */
+export function presentResult(workflow, state) {
+    try {
+        return workflow ? workflow.presentResult(state) : presentData(state);
+    }
+    catch (error) {
+        return [`Result unavailable: ${message(error)}`];
+    }
+}
+//# sourceMappingURL=runs.js.map

package/dist/app/runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.js","sourceRoot":"","sources":["../../src/app/runs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOlD,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE,CACjC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEzD,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAe;IAC5C,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,MAAM,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE;gBACF,KAAK,EAAE,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;aAClD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9C,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,YAAY,CAAC,KAAe;IAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC;IACnC,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC;QAC5B,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;QAChD,0CAA0C;QAC1C,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;QAChC,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAe,EAAE,EAAU;IACvD,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,EAAU;IAEV,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA8B,EAC9B,KAAyB;IAEzB,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,uBAAuB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC"}

package/dist/engine/metrics.d.ts

@@ -0,0 +1,45 @@
+import type { RunState } from "./types.js";
+/** Tokens of a model response or of an agent call. */
+export interface TokenCounts {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** Tokens and the runtime's estimated cost. */
+export interface AgentUsage extends TokenCounts {
+    costUsd: number;
+}
+export interface RunMetrics {
+    /** The run's total, the sum of its sessions; `responses` counts measured reports, `missing` unmeasured ones. */
+    usage: AgentUsage & {
+        responses: number;
+        missing: number;
+    };
+    /**
+     * Per agent session, `<runtime>:<session>`: the latest total its runtime
+     * announced (Claude Code), or the sum of its responses (Pi). Absent from runs
+     * recorded before it existed.
+     */
+    sessions?: Record<string, AgentUsage>;
+}
+/** A measure as the runtime reports it: one response (Pi), or its session's total so far (Claude Code). */
+export interface UsageReport {
+    session: string;
+    scope: "response" | "session";
+    /** `undefined` when the runtime reported nothing measurable. */
+    usage: AgentUsage | undefined;
+}
+/** Tokens and cost of several measures together. */
+export declare function sumUsage(measures: AgentUsage[]): AgentUsage;
+export declare function emptyMetrics(): RunMetrics;
+/**
+ * Records a measure as its runtime reports it: a session total replaces the
+ * previous one, a response adds to its session. The run's total is the sum of
+ * its sessions; nothing else is computed.
+ */
+export declare function recordUsage(metrics: RunMetrics, report: UsageReport): void;
+/** Why a run past its budget must stop: its announced cost exceeds it, or a call announced none. */
+export declare function budgetProblem(metrics: RunMetrics, maxCostUsd: number): string | undefined;
+/** From creation to now while running, to the last update once completed or failed. */
+export declare function elapsedMs(state: RunState, now?: number): number | null;

package/dist/engine/metrics.js

@@ -0,0 +1,60 @@
+const fields = [
+    "input",
+    "output",
+    "cacheRead",
+    "cacheWrite",
+    "costUsd",
+];
+const noUsage = () => ({
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    costUsd: 0,
+});
+/** Tokens and cost of several measures together. */
+export function sumUsage(measures) {
+    const total = noUsage();
+    for (const measure of measures)
+        for (const field of fields)
+            total[field] += measure[field];
+    return total;
+}
+export function emptyMetrics() {
+    return { usage: { ...noUsage(), responses: 0, missing: 0 }, sessions: {} };
+}
+/**
+ * Records a measure as its runtime reports it: a session total replaces the
+ * previous one, a response adds to its session. The run's total is the sum of
+ * its sessions; nothing else is computed.
+ */
+export function recordUsage(metrics, report) {
+    if (!report.usage) {
+        metrics.usage.missing++;
+        return;
+    }
+    metrics.usage.responses++;
+    metrics.sessions ??= {};
+    const { sessions } = metrics;
+    const previous = sessions[report.session];
+    sessions[report.session] =
+        report.scope === "session" || !previous
+            ? report.usage
+            : sumUsage([previous, report.usage]);
+    Object.assign(metrics.usage, sumUsage(Object.values(sessions)));
+}
+/** Why a run past its budget must stop: its announced cost exceeds it, or a call announced none. */
+export function budgetProblem(metrics, maxCostUsd) {
+    if (metrics.usage.missing)
+        return `Budget of ${maxCostUsd} USD cannot be checked: an agent call announced no cost`;
+    if (metrics.usage.costUsd > maxCostUsd)
+        return `Budget exceeded: ${metrics.usage.costUsd.toFixed(6)} USD spent, maximum ${maxCostUsd.toFixed(6)} USD`;
+    return undefined;
+}
+/** From creation to now while running, to the last update once completed or failed. */
+export function elapsedMs(state, now = Date.now()) {
+    const end = state.status === "running" ? now : Date.parse(state.updatedAt);
+    const elapsed = end - Date.parse(state.createdAt);
+    return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : null;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/engine/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/engine/metrics.ts"],"names":[],"mappings":"AAqCA,MAAM,MAAM,GAAG;IACb,OAAO;IACP,QAAQ;IACR,WAAW;IACX,YAAY;IACZ,SAAS;CACD,CAAC;AAEX,MAAM,OAAO,GAAG,GAAe,EAAE,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,CAAC;CACX,CAAC,CAAC;AAEH,oDAAoD;AACpD,MAAM,UAAU,QAAQ,CAAC,QAAsB;IAC7C,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC;IACxB,KAAK,MAAM,OAAO,IAAI,QAAQ;QAC5B,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,KAAK,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAmB,EAAE,MAAmB;IAClE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACxB,OAAO;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;IAC1B,OAAO,CAAC,QAAQ,KAAK,EAAE,CAAC;IACxB,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;QACtB,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,QAAQ;YACrC,CAAC,CAAC,MAAM,CAAC,KAAK;YACd,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,aAAa,CAC3B,OAAmB,EACnB,UAAkB;IAElB,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO;QACvB,OAAO,aAAa,UAAU,yDAAyD,CAAC;IAC1F,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,UAAU;QACpC,OAAO,oBAAoB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAChH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,SAAS,CAAC,KAAe,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACzD,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,CAAC"}

package/dist/engine/primitives.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { AgentDeclaration, Edge, RetryEdge, Stage, StageContext, StageResult, WorkflowNode } from "./types.js";
+type Awaitable<T> = T | Promise<T>;
+export declare const END: null;
+/** A correction route, taken at most `max` times per run. */
+export declare function retry(to: string, max: number): RetryEdge;
+/** Binds a stage to its routes; every declared outcome must be routed. */
+export declare function node<O extends string>(stage: Stage<O>, on: Record<O, Edge>): WorkflowNode;
+/** Selects explicit agent context from the run input and workflow data. */
+export declare function pick(...keys: string[]): (context: StageContext) => Record<string, unknown>;
+/** AGENT primitive: one structured request; its untrusted output waits for a gate. */
+export declare function agent(options: AgentDeclaration & {
+    schema: z.ZodType;
+    context: (context: StageContext) => Awaitable<Record<string, unknown>>;
+}): Stage<"ok">;
+/** CODE primitive: deterministic work with named outcomes. */
+export declare function code<O extends string = "ok">(outcomes: readonly O[], run: (context: StageContext) => Promise<StageResult<O>>): Stage<O>;
+/** What a step records: data, or nothing. */
+type StepData = Record<string, unknown> | void;
+/** CODE primitive with a single successful outcome. */
+export declare function step(run: (context: StageContext) => Promise<StepData>): Stage<"ok">;
+/** GATE primitive: decides acceptance or correction from saved facts. */
+export declare function gate<O extends string>(outcomes: readonly O[], run: (context: StageContext) => Promise<StageResult<O>>): Stage<O>;
+export type Check<T> = (value: T, context: StageContext) => Awaitable<string | undefined | {
+    data: Record<string, unknown>;
+}>;
+/** GATE over the last agent output: schema, then business invariants; failures are corrections. */
+export declare function schemaGate<S extends z.ZodType>(options: {
+    schema: S;
+    /** Data key of the validated output. */
+    into: string;
+    check?: Check<z.output<S>>;
+}): Stage<"ok" | "invalid">;
+export {};

package/dist/engine/primitives.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export const END = null;
+/** A correction route, taken at most `max` times per run. */
+export function retry(to, max) {
+    return { to, max };
+}
+/** Binds a stage to its routes; every declared outcome must be routed. */
+export function node(stage, on) {
+    return { stage, on };
+}
+/** Selects explicit agent context from the run input and workflow data. */
+export function pick(...keys) {
+    return ({ state }) => Object.fromEntries(keys.flatMap((key) => {
+        const value = key === "input" ? state.input : state.data[key];
+        return value === undefined ? [] : [[key, value]];
+    }));
+}
+/** AGENT primitive: one structured request; its untrusted output waits for a gate. */
+export function agent(options) {
+    const { profile, prompt, session } = options;
+    return {
+        kind: "AGENT",
+        outcomes: ["ok"],
+        agent: {
+            profile,
+            ...(prompt === undefined ? {} : { prompt }),
+            ...(session === undefined ? {} : { session }),
+        },
+        async run(context) {
+            const { state } = context;
+            const output = await context.agent.execute({
+                profile,
+                prompt: prompt ?? state.stage,
+                session: typeof session === "function"
+                    ? session(state)
+                    : (session ?? state.stage),
+                context: {
+                    ...(await options.context(context)),
+                    ...(state.feedback === undefined ? {} : { feedback: state.feedback }),
+                },
+                schema: z.toJSONSchema(options.schema),
+            });
+            return { outcome: "ok", output };
+        },
+    };
+}
+/** CODE primitive: deterministic work with named outcomes. */
+export function code(outcomes, run) {
+    return { kind: "CODE", outcomes, run };
+}
+/** CODE primitive with a single successful outcome. */
+export function step(run) {
+    return code(["ok"], async (context) => {
+        const data = await run(context);
+        return { outcome: "ok", ...(data ? { data } : {}) };
+    });
+}
+/** GATE primitive: decides acceptance or correction from saved facts. */
+export function gate(outcomes, run) {
+    return { kind: "GATE", outcomes, run };
+}
+/** GATE over the last agent output: schema, then business invariants; failures are corrections. */
+export function schemaGate(options) {
+    return gate(["ok", "invalid"], async (context) => {
+        const parsed = options.schema.safeParse(context.state.output);
+        if (!parsed.success)
+            return {
+                outcome: "invalid",
+                reason: `Invalid structured output:\n${z.prettifyError(parsed.error)}`,
+            };
+        const checked = await options.check?.(parsed.data, context);
+        if (typeof checked === "string")
+            return { outcome: "invalid", reason: checked };
+        return {
+            outcome: "ok",
+            reason: `Structured output and invariants valid: ${options.into}`,
+            data: { ...(checked?.data ?? {}), [options.into]: parsed.data },
+        };
+    });
+}
+//# sourceMappingURL=primitives.js.map

package/dist/engine/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/engine/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC;AAExB,6DAA6D;AAC7D,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,GAAW;IAC3C,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC;AACrB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,IAAI,CAClB,KAAe,EACf,EAAmB;IAEnB,OAAO,EAAE,KAAK,EAAE,EAAE,EAAkB,CAAC;AACvC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,IAAI,CAClB,GAAG,IAAc;IAEjB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CACnB,MAAM,CAAC,WAAW,CAChB,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,MAAM,KAAK,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9D,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CACH,CAAC;AACN,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,KAAK,CACnB,OAGC;IAED,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC7C,OAAO;QACL,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,CAAC,IAAI,CAAC;QAChB,KAAK,EAAE;YACL,OAAO;YACP,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3C,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;SAC9C;QACD,KAAK,CAAC,GAAG,CAAC,OAAO;YACf,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;YAC1B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;gBACzC,OAAO;gBACP,MAAM,EAAE,MAAM,IAAI,KAAK,CAAC,KAAK;gBAC7B,OAAO,EACL,OAAO,OAAO,KAAK,UAAU;oBAC3B,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;oBAChB,CAAC,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC;gBAC9B,OAAO,EAAE;oBACP,GAAG,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;oBACnC,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;iBACtE;gBACD,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC;aACvC,CAAC,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,IAAI,CAClB,QAAsB,EACtB,GAAuD;IAEvD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AACzC,CAAC;AAMD,uDAAuD;AACvD,MAAM,UAAU,IAAI,CAClB,GAAiD;IAEjD,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACpC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,EAAE,OAAO,EAAE,IAAa,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,IAAI,CAClB,QAAsB,EACtB,GAAuD;IAEvD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AACzC,CAAC;AAOD,mGAAmG;AACnG,MAAM,UAAU,UAAU,CAAsB,OAK/C;IACC,OAAO,IAAI,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,OAAO;YACjB,OAAO;gBACL,OAAO,EAAE,SAAkB;gBAC3B,MAAM,EAAE,+BAA+B,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;aACvE,CAAC;QACJ,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC5D,IAAI,OAAO,OAAO,KAAK,QAAQ;YAC7B,OAAO,EAAE,OAAO,EAAE,SAAkB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC1D,OAAO;YACL,OAAO,EAAE,IAAa;YACtB,MAAM,EAAE,2CAA2C,OAAO,CAAC,IAAI,EAAE;YACjE,IAAI,EAAE,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE;SAChE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/profiles.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/** An agent stage's runtime, settings and access, declared in full by its workflow. */
+export declare const profileSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    runtime: z.ZodLiteral<"pi">;
+    access: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>>;
+    provider: z.ZodString;
+    model: z.ZodString;
+    thinking: z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        minimal: "minimal";
+        off: "off";
+        xhigh: "xhigh";
+    }>;
+    tools: z.ZodArray<z.ZodString>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    extensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    runtime: z.ZodLiteral<"claude-code">;
+    access: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>>;
+    model: z.ZodString;
+    thinking: z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        xhigh: "xhigh";
+    }>;
+    tools: z.ZodArray<z.ZodString>;
+    mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>], "runtime">;
+/** A profile as a workflow declares it. */
+export type AgentProfile = z.input<typeof profileSchema>;
+/** A profile with its defaults applied. */
+export type ResolvedProfile = z.output<typeof profileSchema>;
+export type Runtime = ResolvedProfile["runtime"];
+/** Each runtime's name as the operator reads it. */
+export declare const runtimeLabels: Record<Runtime, string>;
+/** The profile with its defaults applied; an invalid profile is refused with its problems. */
+export declare function resolveProfile(profile: AgentProfile): ResolvedProfile;