@clemrig/flow 0.0.0-stage → 0.2.0

package/dist/engine/profiles.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+/** Pi native tools; any other tool name must come from an explicitly trusted extension. */
+const piBuiltinTools = new Set([
+    "read",
+    "bash",
+    "powershell",
+    "edit",
+    "write",
+    "grep",
+    "find",
+    "ls",
+]);
+/** Pi native tools that can change files or run commands. */
+const piWriteTools = new Set(["bash", "powershell", "edit", "write"]);
+/**
+ * The only Claude Code tools a read-only profile may use. Its native set grows with
+ * each version (worktrees, monitors, schedules…), so anything else is refused.
+ */
+const claudeCodeReadTools = new Set([
+    "Read",
+    "Grep",
+    "Glob",
+    "WebFetch",
+    "WebSearch",
+]);
+const timeoutMs = z.number().int().min(1000).max(7_200_000).default(900_000);
+/** `read` by default; `write` allows tools that change files or run commands. */
+const access = z.enum(["read", "write"]).default("read");
+const piProfileSchema = z
+    .strictObject({
+    runtime: z.literal("pi"),
+    access,
+    // No default: a profile names the provider whose connection it uses.
+    provider: z.string().min(1),
+    model: z.string().min(1),
+    thinking: z.enum([
+        "off",
+        "minimal",
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+    ]),
+    // Exact names only: Pi allowlist patterns could accidentally grant mutation tools.
+    tools: z.array(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/)),
+    skills: z.array(z.string().min(1)).default([]),
+    extensions: z.array(z.string().min(1)).default([]),
+    timeoutMs,
+})
+    .refine((profile) => profile.extensions.length > 0 ||
+    profile.tools.every((tool) => piBuiltinTools.has(tool)), {
+    path: ["tools"],
+    message: "Custom tools require explicitly trusted extensions",
+});
+const mcpTool = /^mcp__([a-zA-Z0-9][a-zA-Z0-9-]*)__[a-zA-Z0-9_-]+$/;
+/** The server a Claude Code MCP tool name (`mcp__<server>__<tool>`) belongs to. */
+function mcpToolServer(tool) {
+    return mcpTool.exec(tool)?.[1];
+}
+const claudeCodeProfileSchema = z
+    .strictObject({
+    runtime: z.literal("claude-code"),
+    access,
+    model: z.string().min(1),
+    /** Claude Code effort levels. */
+    thinking: z.enum(["low", "medium", "high", "xhigh", "max"]),
+    // Exact names only: rules such as Bash(git *) or "default" would change the tool set.
+    tools: z.array(z
+        .string()
+        .refine((tool) => /^[A-Z][a-zA-Z0-9]*$/.test(tool) || mcpTool.test(tool))),
+    // Without "_": `mcp__<server>__<tool>` names must split one way only.
+    mcpServers: z
+        .record(z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9-]*$/), 
+    // No env: servers inherit the run's environment, so secrets stay out of workflows.
+    z.strictObject({
+        command: z.string().min(1),
+        args: z.array(z.string()).default([]),
+    }))
+        .default({}),
+    timeoutMs,
+})
+    .refine((profile) => profile.tools.every((tool) => {
+    const server = mcpToolServer(tool);
+    return (server === undefined || Object.hasOwn(profile.mcpServers, server));
+}), { path: ["tools"], message: "MCP tools require a declared server" });
+/** Tools a read-only profile must not have; tools of a declared MCP server are trusted like Pi extension tools. */
+function writeTools(profile) {
+    return profile.tools.filter((tool) => profile.runtime === "pi"
+        ? piWriteTools.has(tool)
+        : !claudeCodeReadTools.has(tool) && mcpToolServer(tool) === undefined);
+}
+/** An agent stage's runtime, settings and access, declared in full by its workflow. */
+export const profileSchema = z
+    .discriminatedUnion("runtime", [piProfileSchema, claudeCodeProfileSchema])
+    .superRefine((profile, context) => {
+    const refused = profile.access === "read" ? writeTools(profile) : [];
+    if (refused.length)
+        context.addIssue({
+            code: "custom",
+            path: ["tools"],
+            message: `read-only profile must not include ${refused.join(", ")}; set access: "write" to allow it`,
+        });
+});
+/** Each runtime's name as the operator reads it. */
+export const runtimeLabels = {
+    "claude-code": "Claude Code",
+    pi: "Pi",
+};
+/** The profile with its defaults applied; an invalid profile is refused with its problems. */
+export function resolveProfile(profile) {
+    const parsed = profileSchema.safeParse(profile);
+    if (!parsed.success)
+        throw new Error(`Invalid agent profile:\n${z.prettifyError(parsed.error)}`);
+    return parsed.data;
+}
+//# sourceMappingURL=profiles.js.map

package/dist/engine/profiles.js.map

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

package/dist/engine/runner.d.ts

@@ -0,0 +1,13 @@
+import type { AgentPort, RunEvent, RunState, RunStore, Workflow } from "./types.js";
+/**
+ * Deterministic graph runner. Stages report outcomes; the graph routes them.
+ * Each retry edge is taken at most its maximum; an aborted run stops before its
+ * next stage, or fails instead of completing.
+ */
+export declare function executeWorkflow(workflow: Pick<Workflow, "nodes">, state: RunState, runtime: {
+    agent: AgentPort;
+    dir: string;
+}, store: RunStore, options?: {
+    onEvent?: (event: RunEvent) => void;
+    signal?: AbortSignal;
+}): Promise<RunState>;

package/dist/engine/runner.js

@@ -0,0 +1,157 @@
+/**
+ * The journal of one stage run: its messages and its agent's activity. Writes
+ * keep their call order and are awaited before the stage is routed; the first
+ * write failure fails the stage.
+ */
+function stageJournal(write, stage, kind) {
+    let pending = Promise.resolve();
+    let failure;
+    let closed = false;
+    const append = (event) => {
+        if (closed)
+            throw new Error(`Stage ${stage} logged after it ended`);
+        pending = pending
+            .then(() => write(event))
+            .catch((error) => {
+            failure ??= { error };
+        });
+    };
+    return {
+        log(message, data) {
+            append({ type: "log", stage, kind, message, ...(data ? { data } : {}) });
+        },
+        activity(activity) {
+            append({ type: "agent", stage, kind, activity });
+        },
+        async flush() {
+            closed = true;
+            await pending;
+            if (failure)
+                throw failure.error;
+        },
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Deterministic graph runner. Stages report outcomes; the graph routes them.
+ * Each retry edge is taken at most its maximum; an aborted run stops before its
+ * next stage, or fails instead of completing.
+ */
+export async function executeWorkflow(workflow, state, runtime, store, options = {}) {
+    const emit = async (event) => {
+        const full = {
+            ...event,
+            runId: state.id,
+            at: new Date().toISOString(),
+        };
+        await store.event(full);
+        options.onEvent?.(full);
+    };
+    while (state.status === "running") {
+        const node = workflow.nodes[state.stage];
+        if (!node)
+            throw new Error(`Unknown stage: ${state.stage}`);
+        const current = state.stage;
+        const kind = node.stage.kind;
+        let outcome = {};
+        const journal = stageJournal(emit, current, kind);
+        try {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? new Error("Run aborted");
+            await emit({ type: "stage", stage: current, kind, status: "started" });
+            const context = {
+                state,
+                dir: runtime.dir,
+                agent: {
+                    execute: (request) => runtime.agent.execute(request, journal.activity),
+                },
+                log: journal.log,
+            };
+            const result = await node.stage.run(context);
+            await journal.flush();
+            if (!node.stage.outcomes.includes(result.outcome) ||
+                !Object.hasOwn(node.on, result.outcome))
+                throw new Error(`Stage ${current} returned unrouted outcome ${result.outcome}`);
+            const edge = node.on[result.outcome] ?? null;
+            const correction = typeof edge === "object" && edge !== null ? edge : undefined;
+            const next = correction ? correction.to : edge;
+            if (next !== null && !workflow.nodes[next])
+                throw new Error(`Unknown route: ${next}`);
+            const decision = kind === "GATE" || correction || result.reason
+                ? {
+                    verdict: correction ? "correction" : "accepted",
+                    reason: result.reason ?? result.outcome,
+                    destination: next,
+                }
+                : undefined;
+            outcome = {
+                ...(decision ? { decision } : {}),
+                ...(result.detail ? { detail: result.detail } : {}),
+            };
+            let retry;
+            if (correction) {
+                const key = `${current}.${result.outcome}`;
+                state.retries ??= {};
+                const count = (state.retries[key] ?? 0) + 1;
+                state.retries[key] = count;
+                retry = { key, count, max: correction.max };
+                outcome.retry = retry;
+            }
+            Object.assign(state.data, result.data);
+            if (Object.hasOwn(result, "output"))
+                state.output = result.output;
+            if (correction)
+                state.feedback = result.feedback ?? result.reason;
+            else if (kind === "GATE") {
+                delete state.feedback;
+                delete state.output;
+            }
+            if (retry && retry.count > retry.max)
+                throw new Error(`Retry ${retry.key} → ${next} exceeded its maximum of ${retry.max}`);
+            // The end of the run is a stage boundary too: an interrupted run never completes.
+            if (next === null && options.signal?.aborted)
+                throw options.signal.reason ?? new Error("Run aborted");
+            if (next === null)
+                state.status = "completed";
+            else
+                state.stage = next;
+            state.updatedAt = new Date().toISOString();
+            // The event first: a reader that sees the run ended has every event.
+            await emit({
+                type: "stage",
+                stage: current,
+                kind,
+                status: state.status === "running" ? "passed" : state.status,
+                ...outcome,
+            });
+            await store.save(state);
+        }
+        catch (error) {
+            // The stage's own failure takes precedence over a journal write failure.
+            await journal.flush().catch(() => undefined);
+            state.status = "failed";
+            state.error = errorMessage(error);
+            state.updatedAt = new Date().toISOString();
+            try {
+                await emit({
+                    type: "stage",
+                    stage: current,
+                    kind,
+                    status: "failed",
+                    ...outcome,
+                    detail: outcome.detail
+                        ? `${outcome.detail}\n${state.error}`
+                        : state.error,
+                });
+            }
+            finally {
+                // The failed state is kept even if its event cannot be written.
+                await store.save(state);
+            }
+        }
+    }
+    return state;
+}
+//# sourceMappingURL=runner.js.map

package/dist/engine/runner.js.map

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

package/dist/engine/types.d.ts

@@ -0,0 +1,194 @@
+import type { z } from "zod";
+import type { AgentUsage, RunMetrics, TokenCounts } from "./metrics.js";
+import type { AgentProfile, ResolvedProfile, Runtime } from "./profiles.js";
+export type StageKind = "AGENT" | "CODE" | "GATE";
+/** What an agent stage asks of the agent runtime. */
+export interface AgentRequest {
+    /** The stage's profile as declared; the runtime validates it and applies its defaults. */
+    profile: AgentProfile;
+    /** Name of the prompt file the runtime appends to its system prompt. */
+    prompt: string;
+    /** The run-local conversation the request continues. */
+    session: string;
+    context: unknown;
+    schema: Record<string, unknown>;
+}
+/** Adds a message to the run journal (`events.jsonl`), with optional data. */
+export type Log = (message: string, data?: Record<string, unknown>) => void;
+/** What an agent call does, as its runtime reports it; never the messages themselves. */
+export type AgentActivity = {
+    kind: "call";
+    status: "started";
+    runtime: Runtime;
+    model: string;
+    session: string;
+} | {
+    kind: "call";
+    status: "completed" | "failed";
+    runtime: Runtime;
+    /** As the runtime announced it at the end of the call: the call's own, or its session's total. */
+    usage?: AgentUsage;
+    scope?: "call" | "session";
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    status: "started";
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    status: "completed" | "failed";
+    durationMs: number;
+} | {
+    kind: "response";
+    tokens: TokenCounts;
+    costUsd?: number;
+    /** Reported while the call runs and replaced by the figures announced at its end. */
+    provisional: boolean;
+} | {
+    kind: "warning";
+    message: string;
+};
+/** Records an agent call's activity under the calling stage. */
+export type RecordActivity = (activity: AgentActivity) => void;
+/** Agent execution managed by the core runtime; `record` journals its activity under the calling stage. */
+export interface AgentPort {
+    execute(request: AgentRequest, record?: RecordActivity): Promise<unknown>;
+}
+export interface RunState {
+    /** 4 since workflows declare their inputs, agent profiles and retry maximums. */
+    version: 4;
+    id: string;
+    workflow: string;
+    /** Options validated by the workflow's input object. */
+    input: Record<string, unknown>;
+    stage: string;
+    status: "running" | "completed" | "failed";
+    /** Validated values written by the workflow's stages. */
+    data: Record<string, unknown>;
+    /** Owned by the engine: untrusted output of the last agent, cleared when a gate accepts. */
+    output?: unknown;
+    /** Owned by the engine: correction routed by the last retry edge, cleared when a gate accepts. */
+    feedback?: unknown;
+    /** Corrections taken per retry edge, keyed `<stage>.<outcome>`. */
+    retries?: Record<string, number>;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+    metrics?: RunMetrics;
+    /** Each runtime the run used, with its version and connection, as checked before it started. */
+    runtimes?: Partial<Record<Runtime, string>>;
+}
+export interface WorkflowDecision {
+    verdict: "accepted" | "correction";
+    reason: string;
+    destination: string | null;
+}
+/** What a stage receives: its run, the agent runtime, the run journal and the working directory. */
+export interface StageContext {
+    state: Readonly<RunState>;
+    agent: AgentPort;
+    log: Log;
+    /** The directory the workflow works in. */
+    dir: string;
+}
+/** A stage reports a named outcome; the workflow graph decides where it leads. */
+export interface StageResult<O extends string = string> {
+    outcome: O;
+    /** Why this outcome was chosen; becomes the decision reason. */
+    reason?: string;
+    /** Correction carried by a retry edge to the next stage; defaults to the reason. */
+    feedback?: unknown;
+    /** Validated values merged into the run's data. */
+    data?: Record<string, unknown>;
+    /** Untrusted agent output, kept for the next gate. */
+    output?: unknown;
+    detail?: string;
+}
+/** What an agent stage declares, checked by `defineWorkflow`. */
+export interface AgentDeclaration {
+    profile: AgentProfile;
+    /** Name of the prompt text the run supplies; defaults to the stage name. Letters, digits, - or _, so that a caller can keep each prompt in a file of that name. */
+    prompt?: string;
+    /** Conversation name; defaults to the stage name. */
+    session?: string | ((state: Readonly<RunState>) => string);
+}
+export interface Stage<O extends string = string> {
+    kind: StageKind;
+    outcomes: readonly O[];
+    agent?: AgentDeclaration;
+    run: (context: StageContext) => Promise<StageResult<O>>;
+}
+/** A correction route, taken at most `max` times per run. */
+export interface RetryEdge {
+    to: string;
+    max: number;
+}
+/** Next stage name, END (null) or a bounded correction route. */
+export type Edge = string | null | RetryEdge;
+export interface WorkflowNode<O extends string = string> {
+    stage: Stage<O>;
+    on: Record<O, Edge>;
+}
+/** What a workflow author writes: inputs, graph and an optional rendering. */
+export interface WorkflowDefinition {
+    /** Letters, digits, - or _, so that a caller can name a folder after it. */
+    name: string;
+    /** Validates each run's input, strictly. */
+    input?: z.ZodObject;
+    initial: string;
+    nodes: Record<string, WorkflowNode>;
+    /** Fails a run once its agents' announced cost exceeds it, in USD; a run's own budget replaces it. */
+    maxCostUsd?: number;
+    /** Result lines; by default the run's validated data as JSON. */
+    presentResult?(state: Readonly<RunState>): string[];
+}
+/** An agent stage as `defineWorkflow` resolves it. */
+export interface AgentStage {
+    profile: ResolvedProfile;
+    prompt: string;
+}
+/** A workflow validated by `defineWorkflow`. */
+export interface Workflow extends WorkflowDefinition {
+    /** Agent stages by stage name. */
+    agents: Record<string, AgentStage>;
+    presentResult(state: Readonly<RunState>): string[];
+}
+export interface RetryContext {
+    /** The retry edge, `<stage>.<outcome>`. */
+    key: string;
+    count: number;
+    max: number;
+}
+interface EventBase {
+    runId: string;
+    stage: string;
+    kind: StageKind;
+    at: string;
+}
+/** Recorded by the engine when a stage starts and when it ends. */
+export interface StageEvent extends EventBase {
+    type: "stage";
+    status: "started" | "passed" | "failed" | "completed";
+    retry?: RetryContext;
+    decision?: WorkflowDecision;
+    detail?: string;
+}
+/** Recorded by a stage, or by the agent runtime on its behalf, while it runs. */
+export interface LogEvent extends EventBase {
+    type: "log";
+    message: string;
+    data?: Record<string, unknown>;
+}
+/** Recorded by the agent runtime for the calling stage while it runs. */
+export interface AgentEvent extends EventBase {
+    type: "agent";
+    activity: AgentActivity;
+}
+export type RunEvent = StageEvent | LogEvent | AgentEvent;
+export interface RunStore {
+    save(state: RunState): Promise<void>;
+    event(event: RunEvent): Promise<void>;
+}
+export {};

package/dist/engine/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":""}

package/dist/engine/workflow.d.ts

@@ -0,0 +1,24 @@
+import type { RunState, Workflow, WorkflowDefinition } from "./types.js";
+/** True for a workflow returned by `defineWorkflow`. */
+export declare function isWorkflow(value: unknown): value is Workflow;
+/** By default a run shows its validated data, never raw agent output. */
+export declare function presentData(state: Readonly<RunState>): string[];
+/**
+ * Validates a workflow when it is declared: graph, retry maximums, loops, agent
+ * stages and inputs. Agent profiles are returned with their defaults applied.
+ */
+export declare function defineWorkflow(definition: WorkflowDefinition): Workflow;
+/** A problem of a run's input: an unknown field, or an invalid or missing one, by its path. */
+export interface InputProblem {
+    kind: "unknown" | "invalid";
+    /** The field's path, its names joined by `.`. */
+    field: string;
+    message: string;
+}
+/** A run's input refused by its workflow's input object, with every problem. */
+export declare class InvalidInputError extends Error {
+    readonly problems: InputProblem[];
+    constructor(workflow: string, problems: InputProblem[]);
+}
+/** Validates a run's input against the workflow's input object, strictly; every problem is listed. */
+export declare function parseInput(workflow: Pick<Workflow, "name" | "input">, input: Record<string, unknown>): Record<string, unknown>;