@crewhaus/tool-flow 0.7.0

package/dist/lib/sequence.js

@@ -0,0 +1,244 @@
+/**
+ * Plan a declared sequence of steps. Nothing here runs one.
+ *
+ * A sequence is the other half of {@link ./branch}: a branch answers "which
+ * way", a sequence answers "what next, and what is it still waiting on". The
+ * answer is a plan — the steps whose prerequisites are met, whose gate time
+ * has passed and whose conditions hold, each carrying the parameters the
+ * caller should execute it with.
+ *
+ * It stops there on purpose. Invoking a tool needs the executor, which no
+ * tool package has, and a "runner" that quietly returned the steps it would
+ * have run is the shape of lie a caller only discovers in production. So
+ * this returns the plan and the caller — or the harness, which does have the
+ * executor — acts on it.
+ *
+ * Progress is an argument, not a memory. `completed` and `failed` come in
+ * the way {@link ./stall} takes its history, so the same inputs give the
+ * same plan in a test, in a replay and in production.
+ *
+ * Three distinctions carry the weight here, and each one is a different
+ * answer a caller has to be able to tell apart:
+ *
+ * - **waiting** — a prerequisite has not run yet, or the step is not due
+ *   yet. It can still happen.
+ * - **unreachable** — a prerequisite failed or was skipped, so this step can
+ *   never happen. Reporting that as "waiting" is how a flow hangs forever on
+ *   a step that died three turns ago.
+ * - **skipped** — the step's own conditions did not hold. A settled no.
+ */
+import { runChecks } from "@crewhaus/tool-schema";
+/**
+ * Where a flow stands.
+ *
+ * `finished` and `halted` are kept apart on purpose. Both mean there is
+ * nothing left to run, and a caller that reads one boolean for both reports
+ * a cadence that died on its second step as a cadence that completed.
+ */
+export const PLAN_STATES = ["ready", "blocked", "finished", "halted"];
+/**
+ * Work out what to run next.
+ *
+ * Structural problems throw rather than being reported, the way a duplicate
+ * row id does elsewhere in this package: a cycle, a `needs` naming a step
+ * that does not exist, or progress naming a step that does not exist are all
+ * bugs in the spec or in the caller's bookkeeping, not answers about this
+ * particular record. In particular an unknown id in `completed` — a typo, or
+ * a leftover from an older revision of the flow — would silently re-run a
+ * step the caller believes is finished.
+ */
+export function planSequence(value, spec, state) {
+    const steps = spec.steps;
+    if (steps.length === 0)
+        throw new Error("the sequence has no steps");
+    const byId = new Map();
+    for (const step of steps) {
+        if (step.when && step.when.length === 0) {
+            throw new Error(`step "${step.id}" has an empty condition list — omit "when" for a step that is always due`);
+        }
+        if (byId.has(step.id))
+            throw new Error(`two steps share the id "${step.id}"`);
+        byId.set(step.id, step);
+    }
+    for (const step of steps) {
+        for (const need of step.needs ?? []) {
+            if (need === step.id)
+                throw new Error(`step "${step.id}" needs itself`);
+            if (!byId.has(need)) {
+                throw new Error(`step "${step.id}" needs "${need}", which is not a step in this sequence`);
+            }
+        }
+    }
+    const completed = new Set(state.completed ?? []);
+    const failed = new Set(state.failed ?? []);
+    for (const [label, ids] of [
+        ["completed", completed],
+        ["failed", failed],
+    ]) {
+        for (const id of ids) {
+            if (!byId.has(id)) {
+                throw new Error(`${label} names "${id}", which is not a step in this sequence`);
+            }
+        }
+    }
+    for (const id of completed) {
+        if (failed.has(id))
+            throw new Error(`step "${id}" is listed as both completed and failed`);
+    }
+    // Kahn's algorithm, which both orders the walk and finds the cycle. Every
+    // step's prerequisites are decided before the step itself, so a chain of
+    // unreachability propagates in one pass instead of needing a fixpoint.
+    const order = topologicalOrder(steps, byId);
+    const states = new Map();
+    const reasons = new Map();
+    for (const step of order) {
+        if (failed.has(step.id)) {
+            states.set(step.id, "failed");
+            continue;
+        }
+        if (completed.has(step.id)) {
+            states.set(step.id, "done");
+            continue;
+        }
+        const dead = (step.needs ?? []).find((need) => {
+            const s = states.get(need);
+            return s === "failed" || s === "skipped" || s === "unreachable";
+        });
+        if (dead !== undefined) {
+            states.set(step.id, "unreachable");
+            reasons.set(step.id, {
+                id: step.id,
+                reason: `needs "${dead}", which is ${states.get(dead)}`,
+            });
+            continue;
+        }
+        const pending = (step.needs ?? []).find((need) => states.get(need) !== "done");
+        if (pending !== undefined) {
+            states.set(step.id, "waiting");
+            reasons.set(step.id, { id: step.id, reason: `needs "${pending}", which has not run` });
+            continue;
+        }
+        // The `after` gate is read before the step's own conditions, and the
+        // conditions are read only once the prerequisites are done. Both orders
+        // are deliberate: a gate usually reads something an earlier step
+        // produced, so evaluating it out of turn would report a settled `skipped`
+        // about a context that does not exist yet.
+        if (step.afterMs !== undefined && step.afterMs > state.nowMs) {
+            states.set(step.id, "waiting");
+            reasons.set(step.id, {
+                id: step.id,
+                reason: `not due until ${new Date(step.afterMs).toISOString()}`,
+                dueInMs: step.afterMs - state.nowMs,
+            });
+            continue;
+        }
+        // The shared evaluator reports a check it could not evaluate — a regex
+        // that will not compile, a malformed path — as a check that did not hold,
+        // with the reason as its text and no flag to tell the two apart. That is
+        // `Branch` and `RuleScore`'s behaviour too, and inventing a different one
+        // here would mean two answers to the same question. It bites harder in a
+        // sequence, because the skip cascades into `unreachable` dependents, so
+        // the reason travels with every one of them.
+        if (step.when && step.when.length > 0) {
+            const report = runChecks(value, step.when);
+            const holds = (step.match ?? "all") === "all" ? report.ok : report.passed > 0;
+            if (!holds) {
+                states.set(step.id, "skipped");
+                reasons.set(step.id, {
+                    id: step.id,
+                    reason: report.failures[0]?.reason ?? "no condition held",
+                });
+                continue;
+            }
+        }
+        states.set(step.id, "ready");
+    }
+    // Emitted in declared order, not in the topological order the walk used:
+    // the caller wrote the sequence down in the order they think about it, and
+    // a plan that came back reshuffled would read as a reordering.
+    const ready = [];
+    const waiting = [];
+    const unreachable = [];
+    const skipped = [];
+    const doneIds = [];
+    const failedIds = [];
+    for (const [index, step] of steps.entries()) {
+        const held = reasons.get(step.id) ?? { id: step.id, reason: "" };
+        switch (states.get(step.id)) {
+            case "ready":
+                ready.push(step.params === undefined
+                    ? { id: step.id, index }
+                    : { id: step.id, index, params: step.params });
+                break;
+            case "waiting":
+                waiting.push(held);
+                break;
+            case "unreachable":
+                unreachable.push(held);
+                break;
+            case "skipped":
+                skipped.push(held);
+                break;
+            case "done":
+                doneIds.push(step.id);
+                break;
+            case "failed":
+                failedIds.push(step.id);
+                break;
+        }
+    }
+    const planState = ready.length > 0
+        ? "ready"
+        : waiting.length > 0
+            ? "blocked"
+            : failedIds.length > 0 || unreachable.length > 0
+                ? "halted"
+                : "finished";
+    return {
+        state: planState,
+        ready,
+        next: ready[0] ?? null,
+        waiting,
+        unreachable,
+        skipped,
+        completed: doneIds,
+        failed: failedIds,
+        version: spec.version ?? null,
+        total: steps.length,
+    };
+}
+/** Steps ordered so that every step follows the steps it needs. */
+function topologicalOrder(steps, byId) {
+    const remaining = new Map();
+    const dependents = new Map();
+    for (const step of steps) {
+        const needs = new Set(step.needs ?? []);
+        remaining.set(step.id, needs.size);
+        for (const need of needs) {
+            const list = dependents.get(need);
+            if (list)
+                list.push(step.id);
+            else
+                dependents.set(need, [step.id]);
+        }
+    }
+    // Seeded in declared order so the walk is stable, though only the
+    // dependency order it guarantees is relied on downstream.
+    const queue = steps.filter((s) => remaining.get(s.id) === 0).map((s) => s.id);
+    const ordered = [];
+    for (let head = 0; head < queue.length; head++) {
+        const id = queue[head];
+        ordered.push(byId.get(id));
+        for (const dependent of dependents.get(id) ?? []) {
+            const left = remaining.get(dependent) - 1;
+            remaining.set(dependent, left);
+            if (left === 0)
+                queue.push(dependent);
+        }
+    }
+    if (ordered.length !== steps.length) {
+        const stuck = steps.filter((s) => !ordered.includes(s)).map((s) => `"${s.id}"`);
+        throw new Error(`steps ${stuck.join(", ")} depend on each other in a cycle`);
+    }
+    return ordered;
+}

package/dist/lib/stall.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Decide whether a loop is still making progress.
+ *
+ * A fix-test-fail loop that has stopped moving looks, from inside one turn,
+ * exactly like a loop that is about to succeed. The difference is only
+ * visible across turns, in whether the signals change — the failing-test
+ * fingerprint, the workspace diff hash, the last error, the tool call being
+ * made. This takes that history and answers the question.
+ *
+ * The history is an input. Nothing here persists anything, so the same
+ * history always gives the same verdict.
+ */
+export declare const STALL_REASONS: readonly ["progressing", "unchanged", "oscillating", "insufficient"];
+export type StallReason = (typeof STALL_REASONS)[number];
+/** One turn's observation: named signals, each an opaque fingerprint. */
+export type Snapshot = Readonly<Record<string, string>>;
+export type StallOptions = {
+    /** Identical snapshots needed in a row before calling it stalled. */
+    readonly window?: number;
+    /**
+     * Longest repeating cycle to look for. A loop that alternates between two
+     * states is not "unchanged", but it is just as stuck.
+     */
+    readonly maxCycle?: number;
+    /** Only these signals are considered, when given. */
+    readonly signals?: ReadonlyArray<string>;
+};
+export type StallReport = {
+    readonly stalled: boolean;
+    readonly reason: StallReason;
+    /** Consecutive identical snapshots at the end of the history. */
+    readonly repeats: number;
+    /** Length of the detected cycle; 1 means "unchanged". Null when progressing. */
+    readonly cycleLength: number | null;
+    /** Signals that changed between the last two snapshots. */
+    readonly changed: ReadonlyArray<string>;
+    /** Signals that have not changed anywhere in the history. */
+    readonly frozen: ReadonlyArray<string>;
+    readonly observed: number;
+};
+export declare function detectStall(history: ReadonlyArray<Snapshot>, options?: StallOptions): StallReport;

package/dist/lib/stall.js

@@ -0,0 +1,124 @@
+/**
+ * Decide whether a loop is still making progress.
+ *
+ * A fix-test-fail loop that has stopped moving looks, from inside one turn,
+ * exactly like a loop that is about to succeed. The difference is only
+ * visible across turns, in whether the signals change — the failing-test
+ * fingerprint, the workspace diff hash, the last error, the tool call being
+ * made. This takes that history and answers the question.
+ *
+ * The history is an input. Nothing here persists anything, so the same
+ * history always gives the same verdict.
+ */
+export const STALL_REASONS = ["progressing", "unchanged", "oscillating", "insufficient"];
+const DEFAULT_WINDOW = 3;
+const DEFAULT_MAX_CYCLE = 3;
+/**
+ * A snapshot reduced to a comparable string.
+ *
+ * Keys are sorted so that two snapshots with the same content compare equal
+ * whatever order they were built in, and the pairs are JSON rather than
+ * joined with a separator: a fingerprint is opaque caller-supplied text, and
+ * any separator could occur inside one, making two different snapshots
+ * collide.
+ */
+function fingerprint(snapshot, only) {
+    const keys = (only ?? Object.keys(snapshot)).slice().sort();
+    return JSON.stringify(keys.map((k) => [k, snapshot[k] ?? ""]));
+}
+export function detectStall(history, options = {}) {
+    const window = options.window ?? DEFAULT_WINDOW;
+    const maxCycle = options.maxCycle ?? DEFAULT_MAX_CYCLE;
+    if (window < 2)
+        throw new Error("window must be at least 2 — one snapshot cannot show a trend");
+    if (maxCycle < 1)
+        throw new Error("maxCycle must be at least 1");
+    const prints = history.map((s) => fingerprint(s, options.signals));
+    const observed = prints.length;
+    const changed = [];
+    if (observed >= 2) {
+        const a = history[observed - 2];
+        const b = history[observed - 1];
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+        for (const key of [...keys].sort()) {
+            if (options.signals && !options.signals.includes(key))
+                continue;
+            if (a[key] !== b[key])
+                changed.push(key);
+        }
+    }
+    const frozen = [];
+    if (observed >= 2) {
+        const keys = new Set(history.flatMap((s) => Object.keys(s)));
+        for (const key of [...keys].sort()) {
+            if (options.signals && !options.signals.includes(key))
+                continue;
+            const first = history[0]?.[key];
+            if (history.every((s) => s[key] === first))
+                frozen.push(key);
+        }
+    }
+    // Not enough history to say anything. Reporting "progressing" here would be
+    // a claim the data does not support, so it gets its own reason.
+    if (observed < window) {
+        return {
+            stalled: false,
+            reason: "insufficient",
+            repeats: 0,
+            cycleLength: null,
+            changed,
+            frozen,
+            observed,
+        };
+    }
+    let repeats = 1;
+    for (let i = observed - 1; i > 0; i--) {
+        if (prints[i] === prints[i - 1])
+            repeats += 1;
+        else
+            break;
+    }
+    if (repeats >= window) {
+        return {
+            stalled: true,
+            reason: "unchanged",
+            repeats,
+            cycleLength: 1,
+            changed,
+            frozen,
+            observed,
+        };
+    }
+    // Oscillation: the tail repeats a cycle of length k, at least twice, and
+    // the cycle itself is not constant (that is "unchanged", already handled).
+    for (let k = 2; k <= maxCycle; k++) {
+        const needed = k * 2;
+        if (observed < needed || needed < window)
+            continue;
+        const tail = prints.slice(observed - needed);
+        const first = tail.slice(0, k);
+        const second = tail.slice(k);
+        const cycles = first.every((p, i) => p === second[i]);
+        const varied = new Set(first).size > 1;
+        if (cycles && varied) {
+            return {
+                stalled: true,
+                reason: "oscillating",
+                repeats,
+                cycleLength: k,
+                changed,
+                frozen,
+                observed,
+            };
+        }
+    }
+    return {
+        stalled: false,
+        reason: "progressing",
+        repeats,
+        cycleLength: null,
+        changed,
+        frozen,
+        observed,
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crewhaus/tool-flow",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic control-flow tools: branching, decision tables, error classification, deadlines, consensus, stall detection, rule scoring, record routing and sequence planning",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "@crewhaus/tool-schema": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-flow"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-flow#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}