lastlight-workflow-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Last Light Contributors
+
+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/dist/core/dag.d.ts

@@ -0,0 +1,37 @@
+import type { PhaseDefinition } from "./schema.js";
+export type NodeStatus = "pending" | "running" | "succeeded" | "failed" | "skipped";
+export type TriggerRule = "all_success" | "one_success" | "none_failed_min_one_success" | "all_done";
+export interface DagNode {
+    name: string;
+    depends_on: string[];
+    trigger_rule: TriggerRule;
+    status: NodeStatus;
+    output?: string;
+}
+export interface BuildDagOptions {
+    /**
+     * When set and **no** phase declares `depends_on`, synthesize a chain:
+     * each phase depends on the one declared before it (trigger rule
+     * `all_success`). This reproduces the old linear runner's semantics —
+     * sequential execution with a failure cascade — as a degenerate DAG, so
+     * the unified scheduler can treat every workflow uniformly. When any phase
+     * declares an explicit edge, the declared graph is used verbatim (no
+     * synthesis).
+     */
+    chainIfNoDeps?: boolean;
+}
+/** Build a DAG from phase definitions. Validates edges and detects cycles. */
+export declare function buildDag(phases: PhaseDefinition[], opts?: BuildDagOptions): DagNode[];
+/** Evaluate a trigger rule against upstream dependency statuses. */
+export declare function evaluateTriggerRule(rule: TriggerRule, depStatuses: NodeStatus[]): boolean;
+/** Return nodes that are ready to run: pending, all deps terminal, trigger rule satisfied. */
+export declare function getReadyNodes(dag: DagNode[]): DagNode[];
+/** Return nodes that should be skipped: pending, all deps terminal, trigger rule NOT satisfied. */
+export declare function getNodesToSkip(dag: DagNode[]): DagNode[];
+/** Check if all nodes are in a terminal state. */
+export declare function isComplete(dag: DagNode[]): boolean;
+/**
+ * Return layers of parallelizable phase names (topological sort).
+ * Each layer contains phases that can run concurrently.
+ */
+export declare function topoSort(dag: DagNode[]): string[][];

package/dist/core/dag.js

@@ -0,0 +1,118 @@
+const TERMINAL = ["succeeded", "failed", "skipped"];
+/** Build a DAG from phase definitions. Validates edges and detects cycles. */
+export function buildDag(phases, opts = {}) {
+    const names = new Set(phases.map((p) => p.name));
+    for (const phase of phases) {
+        if (!phase.depends_on?.length)
+            continue;
+        for (const dep of phase.depends_on) {
+            if (dep === phase.name)
+                throw new Error(`Phase "${phase.name}" depends on itself`);
+            if (!names.has(dep))
+                throw new Error(`Phase "${phase.name}" depends on unknown phase "${dep}"`);
+        }
+    }
+    const anyDeclared = phases.some((p) => p.depends_on && p.depends_on.length > 0);
+    const synthesizeChain = opts.chainIfNoDeps === true && !anyDeclared;
+    const nodes = phases.map((p, i) => ({
+        name: p.name,
+        depends_on: synthesizeChain
+            ? (i > 0 ? [phases[i - 1].name] : [])
+            : (p.depends_on ?? []),
+        trigger_rule: p.trigger_rule ?? "all_success",
+        status: "pending",
+    }));
+    // Detect cycles via DFS
+    const nodeMap = new Map(nodes.map((n) => [n.name, n]));
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map(nodes.map((n) => [n.name, WHITE]));
+    // NOTE: DFS follows depends_on edges (child → parent), the reverse of conventional
+    // execution-order direction. Cycle detection still works: a GRAY ancestor reachable
+    // from a descendant via depends_on edges indicates a cycle in this representation.
+    function dfs(name, path) {
+        color.set(name, GRAY);
+        for (const dep of nodeMap.get(name).depends_on) {
+            if (color.get(dep) === GRAY) {
+                throw new Error(`Cycle detected: ${[...path, name, dep].join(" -> ")}`);
+            }
+            if (color.get(dep) === WHITE) {
+                dfs(dep, [...path, name]);
+            }
+        }
+        color.set(name, BLACK);
+    }
+    for (const node of nodes) {
+        if (color.get(node.name) === WHITE)
+            dfs(node.name, []);
+    }
+    return nodes;
+}
+/** Evaluate a trigger rule against upstream dependency statuses. */
+export function evaluateTriggerRule(rule, depStatuses) {
+    if (depStatuses.length === 0)
+        return true;
+    switch (rule) {
+        case "all_success":
+            return depStatuses.every((s) => s === "succeeded");
+        case "one_success":
+            return depStatuses.some((s) => s === "succeeded");
+        case "none_failed_min_one_success":
+            return !depStatuses.some((s) => s === "failed") && depStatuses.some((s) => s === "succeeded");
+        case "all_done":
+            return depStatuses.every((s) => TERMINAL.includes(s));
+    }
+}
+/** Return nodes that are ready to run: pending, all deps terminal, trigger rule satisfied. */
+export function getReadyNodes(dag) {
+    const nodeMap = new Map(dag.map((n) => [n.name, n]));
+    return dag.filter((node) => {
+        if (node.status !== "pending")
+            return false;
+        const deps = node.depends_on.map((d) => nodeMap.get(d));
+        if (!deps.every((d) => TERMINAL.includes(d.status)))
+            return false;
+        return evaluateTriggerRule(node.trigger_rule, deps.map((d) => d.status));
+    });
+}
+/** Return nodes that should be skipped: pending, all deps terminal, trigger rule NOT satisfied. */
+export function getNodesToSkip(dag) {
+    const nodeMap = new Map(dag.map((n) => [n.name, n]));
+    return dag.filter((node) => {
+        if (node.status !== "pending")
+            return false;
+        const deps = node.depends_on.map((d) => nodeMap.get(d));
+        if (!deps.every((d) => TERMINAL.includes(d.status)))
+            return false;
+        return !evaluateTriggerRule(node.trigger_rule, deps.map((d) => d.status));
+    });
+}
+/** Check if all nodes are in a terminal state. */
+export function isComplete(dag) {
+    return dag.every((n) => TERMINAL.includes(n.status));
+}
+/**
+ * Return layers of parallelizable phase names (topological sort).
+ * Each layer contains phases that can run concurrently.
+ */
+export function topoSort(dag) {
+    const inDegree = new Map(dag.map((n) => [n.name, n.depends_on.length]));
+    const layers = [];
+    let current = dag.filter((n) => (inDegree.get(n.name) ?? 0) === 0).map((n) => n.name);
+    while (current.length > 0) {
+        layers.push([...current]);
+        const next = [];
+        for (const name of current) {
+            for (const node of dag) {
+                if (node.depends_on.includes(name)) {
+                    const deg = (inDegree.get(node.name) ?? 0) - 1;
+                    inDegree.set(node.name, deg);
+                    if (deg === 0)
+                        next.push(node.name);
+                }
+            }
+        }
+        current = next;
+    }
+    return layers;
+}
+//# sourceMappingURL=dag.js.map

package/dist/core/dag.js.map

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

package/dist/core/loop-eval.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal expression evaluator for generic loop `until` conditions.
+ *
+ * Supported forms:
+ *   output.contains('text')   — true if the output string contains 'text'
+ *   variable == 'value'       — equality check against the context map
+ *   variable != 'value'       — inequality check against the context map
+ *
+ * Deliberately limited to avoid eval() and expression-injection risk.
+ * Complex conditions should use until_bash instead.
+ */
+export interface LoopEvalContext {
+    output: string;
+    /**
+     * Flattened key/value store. Values are serialized to strings for the
+     * quoted-literal comparison; the `true`/`false` bare-literal path
+     * special-cases boolean-ish values ("true", "false", "1", "0").
+     * Dotted keys (e.g. `scratch.socratic.ready`) are resolved by reading
+     * the first segment from top level and walking the rest through nested
+     * objects.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Evaluate a single until expression against the given context.
+ * Returns false (safe default) for any unrecognised expression.
+ */
+export declare function evalUntilExpression(expr: string, ctx: LoopEvalContext): boolean;

package/dist/core/loop-eval.js

@@ -0,0 +1,74 @@
+/**
+ * Minimal expression evaluator for generic loop `until` conditions.
+ *
+ * Supported forms:
+ *   output.contains('text')   — true if the output string contains 'text'
+ *   variable == 'value'       — equality check against the context map
+ *   variable != 'value'       — inequality check against the context map
+ *
+ * Deliberately limited to avoid eval() and expression-injection risk.
+ * Complex conditions should use until_bash instead.
+ */
+/** Walk a dotted path through the eval context. */
+function readPath(ctx, path) {
+    const parts = path.split(".");
+    let cur = ctx[parts[0]];
+    for (let i = 1; i < parts.length; i++) {
+        if (cur === null || cur === undefined || typeof cur !== "object")
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(cur, parts[i]))
+            return undefined;
+        cur = cur[parts[i]];
+    }
+    return cur;
+}
+function coerceBool(v) {
+    if (typeof v === "boolean")
+        return v;
+    if (typeof v === "number")
+        return v !== 0;
+    if (typeof v === "string") {
+        const lower = v.toLowerCase();
+        return lower === "true" || lower === "1" || lower === "yes";
+    }
+    return false;
+}
+/**
+ * Evaluate a single until expression against the given context.
+ * Returns false (safe default) for any unrecognised expression.
+ */
+export function evalUntilExpression(expr, ctx) {
+    const trimmed = expr.trim();
+    // output.contains('text') or output.contains("text")
+    const containsMatch = trimmed.match(/^output\.contains\(['"](.+)['"]\)$/);
+    if (containsMatch) {
+        return String(ctx.output ?? "").includes(containsMatch[1]);
+    }
+    // dotted.path == true / == false / != true / != false (bare boolean literal)
+    const boolMatch = trimmed.match(/^([\w.]+)\s*(==|!=)\s*(true|false)$/);
+    if (boolMatch) {
+        const [, key, op, lit] = boolMatch;
+        const actual = coerceBool(readPath(ctx, key));
+        const expected = lit === "true";
+        return op === "==" ? actual === expected : actual !== expected;
+    }
+    // dotted.path == 'value' or dotted.path == "value"
+    const eqMatch = trimmed.match(/^([\w.]+)\s*==\s*['"](.+)['"]$/);
+    if (eqMatch) {
+        const [, key, value] = eqMatch;
+        const v = readPath(ctx, key);
+        return String(v ?? "") === value;
+    }
+    // dotted.path != 'value' or dotted.path != "value"
+    const neqMatch = trimmed.match(/^([\w.]+)\s*!=\s*['"](.+)['"]$/);
+    if (neqMatch) {
+        const [, key, value] = neqMatch;
+        const v = readPath(ctx, key);
+        if (v === undefined)
+            return false; // absent variable — safe default
+        return String(v) !== value;
+    }
+    // Unrecognised — safe default
+    return false;
+}
+//# sourceMappingURL=loop-eval.js.map

package/dist/core/loop-eval.js.map

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

package/dist/core/phase-executor.d.ts

@@ -0,0 +1,152 @@
+import type { ExecutorConfig, ExecutionResult, GitSandboxAccess, CommandSpec } from "./types.js";
+import type { AgentWorkflowDefinition, PhaseDefinition } from "./schema.js";
+import { type TemplateContext } from "./templates.js";
+import type { DagNode } from "./dag.js";
+import type { AgentPort, AssetLoader, EnginePorts, LivenessPort, ObservabilityPort, PhaseOutcome, PhaseReporter, PhaseResolver, WorkflowStateStore } from "../ports/ports.js";
+export type { PhaseReporter, PhaseResolver, PhaseOutcome, PhaseResult, ReportStepOpts, } from "../ports/ports.js";
+/**
+ * The single per-phase executor. Constructed once per workflow run, it owns
+ * every per-phase body — context / standard agent / reviewer-loop /
+ * generic-loop — behind one `execute(node, outputs)` entry point. The
+ * scheduler (`core/scheduler.ts`) owns the DAG, the `phases[]`/`outputs{}`
+ * accumulation, and the in-memory node status; `execute` reads the current
+ * outputs and returns its delta.
+ *
+ * Dependencies are grouped into cohesive collaborators:
+ *   - {@link PhaseRunContext}  run-scoped immutable data
+ *   - {@link PhaseReporter}    progress / notification surface
+ *   - {@link PhaseResolver}    model / variant / prompt / gate resolution
+ *   - {@link EnginePorts}      injected agent / asset / liveness / telemetry
+ *                              seams + app-registered phase-type handlers
+ *
+ * This makes the executor unit-testable with fakes and keeps the engine
+ * domain-agnostic (no imports of `../engine`, `../state`, `../config`, …).
+ */
+/** Run-scoped immutable data shared by every phase execution. */
+export interface PhaseRunContext {
+    definition: AgentWorkflowDefinition;
+    ctx: TemplateContext;
+    config: ExecutorConfig;
+    /** Single workspace shared by every phase + loop iteration of the run. */
+    taskId: string;
+    triggerId: string;
+    githubAccess: GitSandboxAccess;
+    /** Mutable scratch bag (generic-loop resume state). */
+    scratch: Record<string, unknown>;
+    /** Runs + dedup-ledger store (omitted ⇒ inert gates + no ledger resume). */
+    store?: WorkflowStateStore;
+    workflowId?: string;
+    /** Bot identity (was `getBotName()`), used in the generic-loop gate prompt. */
+    botName: string;
+}
+/**
+ * Build the agent prompt for a phase, handling both `prompt:` (template file)
+ * and `skill:`/`skills:` (skill references) phase definitions.
+ */
+export declare function buildPhasePrompt(phase: PhaseDefinition, ctx: TemplateContext, assets: AssetLoader, extraCtx?: Partial<TemplateContext>): string;
+/**
+ * Overlay per-phase executor config fields (`unrestricted_egress`,
+ * `web_search`, `sandbox_image`, resolved skill paths) onto the run-level
+ * config.
+ */
+export declare function phaseConfigFor(config: ExecutorConfig, phase: PhaseDefinition, assets: AssetLoader): ExecutorConfig;
+/** Check if an error was caused by manual termination (OOM/cancel/kill). */
+export declare function isTerminated(error?: string): boolean;
+/**
+ * Classify an execution outcome as *soft* — a clean exit that produced no
+ * usable output — versus *hard* (a real crash). Generic and phase-agnostic:
+ * it reads only the result fields, with no notion of reviewer/socratic. Both
+ * the reviewer loop and the generic loop consume it so their recovery logic
+ * stays in lockstep. A soft outcome is recoverable (retry / trust an on-disk
+ * artifact / advance); a hard one — terminated, fatal, tool error, non-zero
+ * exit — is not. See `mapStopReason` in the executors for the stop-reason
+ * vocabulary this keys off (`unknown` / `error_truncated` are the soft ones).
+ */
+export declare function isSoftOutcome(r: Pick<ExecutionResult, "success" | "error" | "stopReason">): boolean;
+/**
+ * The seams the dedup ledger needs: the runs+executions store, the agent
+ * runtime, container liveness, and telemetry. Threaded from the
+ * {@link PhaseExecutor}'s injected {@link EnginePorts}.
+ */
+interface LedgerDeps {
+    store?: WorkflowStateStore;
+    agent: AgentPort;
+    liveness: LivenessPort;
+    observability: ObservabilityPort;
+}
+type RunPhaseResult = {
+    result: ExecutionResult;
+    executionId: string;
+    skipped: false;
+} | {
+    result: ExecutionResult;
+    skipped: false;
+} | {
+    skipped: true;
+    reason: "running" | "done";
+};
+/**
+ * Run a single agent phase with DB-tracked deduplication. The dedup ledger
+ * (`shouldRunPhase`) is the single source of truth for resume, so re-running
+ * from the top skips completed phases here.
+ */
+export declare function runPhase(workflowName: string, phaseName: string, taskId: string, triggerId: string, prompt: string, config: ExecutorConfig, deps: LedgerDeps, modelOverride?: string, workflowRunId?: string, githubAccess?: GitSandboxAccess, variantOverride?: string): Promise<RunPhaseResult>;
+/**
+ * Run a single deterministic `bash`/`script` phase, sharing the agent phase's
+ * dedup ledger + executions row so it appears (and dedups on resume) exactly
+ * like an agent phase — just with `turns: 0` and no model cost.
+ */
+export declare function runCommandPhase(workflowName: string, phaseName: string, taskId: string, triggerId: string, spec: CommandSpec, config: ExecutorConfig, deps: LedgerDeps, workflowRunId?: string, githubAccess?: GitSandboxAccess, timeoutSeconds?: number, sandboxEnv?: Record<string, string>): Promise<RunPhaseResult>;
+export declare class PhaseExecutor {
+    private readonly run;
+    private readonly reporter;
+    private readonly resolver;
+    private readonly ports;
+    constructor(run: PhaseRunContext, reporter: PhaseReporter, resolver: PhaseResolver, ports: EnginePorts);
+    /** The dedup-ledger seams, bundled from the injected ports + run store. */
+    private get ledgerDeps();
+    /**
+     * Execute one DAG node and return its delta. The scheduler accumulates
+     * `results` into `phases[]`, merges `outputVars` into the shared outputs
+     * map, and maps `status`/`paused`/`aborted` onto node state + run control.
+     */
+    execute(node: DagNode, outputs: Readonly<Record<string, unknown>>): Promise<PhaseOutcome>;
+    private runContext;
+    /** Resolve model + variant for a phase/task, honouring YAML templates first. */
+    private resolveModelVariant;
+    private runPhaseCall;
+    private runStandard;
+    /**
+     * Body for `type: bash` / `type: script` phases. Runs a deterministic command
+     * in the sandbox (no LLM), then mirrors the agent-phase lifecycle: report
+     * progress, expose stdout downstream via `output_var` →
+     * `{{phaseOutputs.<name>.output}}`, fail the workflow on a non-zero exit, and
+     * honour an optional `approval_gate`.
+     */
+    private runCommandBody;
+    /** Render a command/script phase's template fields into a {@link CommandSpec}. */
+    private buildCommandSpec;
+    private runCommandPhaseCall;
+    /**
+     * Evaluate a `generic_loop.until_bash` condition INSIDE the sandbox (against
+     * the persisted workspace), replacing the old harness-host `execSync`. Exit 0
+     * ⇒ loop complete. The check inherits the phase's egress; no session log is
+     * written (it's an internal loop condition, not a user-facing phase).
+     */
+    private runUntilBash;
+    /**
+     * Evaluate the `contains_BLOCKED` rule. Returns "fail" when the workflow
+     * should fail, or "continue" when the marker is absent or bypassed.
+     */
+    private evaluateBlocked;
+    /**
+     * Persist + pause for an approval/reply gate, atomically. The approval
+     * insert, the `waiting_approval` phase marker, the optional scratch persist
+     * (loops record their iteration/cycle state here), and the run pause all
+     * happen in one transaction via `db.runs.pauseForApproval` — a partial
+     * failure can't leave the run paused without its gate, or vice versa.
+     */
+    private pauseForApproval;
+    private runReviewerLoop;
+    private runGenericLoop;
+}