@crewhaus/tool-flow 0.7.0

package/README.md

@@ -0,0 +1,178 @@
+# @crewhaus/tool-flow
+
+Deterministic control flow: the decisions a harness makes constantly and
+should almost never pay a model to make.
+
+Which arm to take. Whether an error is worth retrying. Whether the loop is
+still moving. Whether there is time left for the thorough path. Which band a
+score falls in. Whether N answers actually agreed. Which rep this lead
+belongs to. What the flow can do next. None of these are judgement calls —
+they all have right answers — and routing each one through a model costs
+tokens, adds latency, and risks getting it wrong.
+
+| Tool | Answers |
+|---|---|
+| `Branch` | which arm of an if/switch a value takes |
+| `DecisionTable` | what an operator's policy table says, and which rows said it |
+| `ErrorClassify` | what kind of error this is and what to do next |
+| `DeadlineCheck` | how much of the time budget is left, and whether one more step fits |
+| `ConsensusVote` | what N answers settled on, and how much they agreed |
+| `StallDetect` | whether the loop is progressing, repeating, or oscillating |
+| `RuleScore` | what this record scores, which band it lands in, and why |
+| `LeadAssign` | which owner a record routes to, and why it was not one of the others |
+| `SequenceRun` | which steps of a declared flow can run now, and what the rest are waiting on |
+
+## One condition grammar
+
+`Branch`, `DecisionTable`, `RuleScore`, `LeadAssign` and `SequenceRun` all
+evaluate the same `checks` that `@crewhaus/tool-schema`'s `Assert` tool does,
+through the same evaluator:
+
+```yaml
+when:
+  - { path: "order.total", op: greaterThan, expected: 1000 }
+  - { path: "customer.tier", op: oneOf, expected: [enterprise, strategic] }
+```
+
+There is deliberately no second vocabulary. An operator who learns
+`startsWith` from `Assert` gets the same operator, with the same semantics,
+in a branch and in a scoring rule.
+
+## Determinism
+
+Every library under `src/lib` is pure: the clock is a parameter, never a
+call, and nothing here touches the filesystem, the network or a random
+source. The same inputs give the same answer in a test, in a replay, and in
+production.
+
+Three tool wrappers read the real clock, because knowing the time is part of
+their job:
+
+- **`DeadlineCheck`** always — a model does not know what time it is, which
+  is the whole reason the tool exists.
+- **`ErrorClassify`** only to resolve a `Retry-After` given as an HTTP-date.
+- **`SequenceRun`** only to decide whether a step's `after` gate has passed.
+
+All three take an explicit `now` that overrides it. That is the only impurity
+in the package, and passing `now` removes it.
+
+Timestamps must carry a UTC offset. `2026-01-01T00:00:00` is rejected with an
+explanation rather than guessed at, because per ECMAScript an offset-less
+date-time string is *local* time while the date-only form is UTC — so the
+same spec would mean different instants on two machines.
+
+An epoch outside the ±8.64e15 ms a `Date` can represent is rejected by name
+for the same reason: the field that parsed it is the only place that still
+knows which of a spec's several instants was the bad one, and left to reach a
+consumer it surfaces as a bare `RangeError: Invalid Date`.
+
+## What it refuses
+
+Three shapes are errors rather than conveniences, because each one reads as
+working and does not:
+
+- **An arm, row or owner with no conditions.** Under `all`, an empty
+  condition list is vacuously true, so it silently swallows everything after
+  it while looking like a rule. A catch-all is spelled `otherwise`, or
+  `fallback` in `LeadAssign`. A `SequenceRun` step may omit `when` entirely —
+  steps are not alternatives, so an unconditional one swallows nothing — but
+  an explicitly empty list is still rejected, because it says "gated" and is
+  not.
+- **Two arms, rows, owners or steps sharing a name.** The name is the thing
+  the caller routes on and the thing that appears in the audit trail.
+- **A custom `ErrorClassify` rule with no conditions**, which would match
+  every error and mask every builtin pack behind it.
+
+`DecisionTable`'s `unique` and `priority` policies report an ambiguity as a
+conflict rather than picking a winner — that ambiguity is the policy bug the
+strict policy exists to find. `LeadAssign` does the same with two equally
+specific territories, and with a roster that is missing a fact its strategy
+needs: an owner with a capacity but no load has not been shown to have room,
+and one with no load at all is not on zero. Neither of those falls through to
+`fallback`, because "nobody is eligible" and "I cannot work out who is" are
+different answers, and only the first one has a right owner to route to. The
+per-owner report says the same thing one level down: such an owner comes back
+`eligible: null` with the missing fact as the reason, never `eligible: true`.
+
+`specific` ranks a territory by the conditions it *requires*, not by the ones
+a particular record happened to satisfy — an owner with `match: any` insists
+on exactly one however many hold, so counting the holders would send two leads
+in the same territory to two different reps over a field neither territory
+asked for.
+
+## What it does not do
+
+- **It does not invoke anything.** These tools decide; they do not act on the
+  decision. `Branch` hands back the arm's declared `result`, and the caller
+  acts. `SequenceRun` is the same promise at flow scale: it returns the steps
+  that can run now, each with the parameters to run it with, and runs none of
+  them — invoking a tool needs the executor, which no tool package has.
+  Chaining tool calls without a model turn needs the `kind: tool` step, which
+  does not exist yet.
+- **It does not persist anything.** `StallDetect` takes the history as an
+  argument rather than keeping one, `SequenceRun` takes `completed` and
+  `failed`, and `LeadAssign` takes the loads and hands the advanced rotation
+  cursor back. Durable cursors and counters are `@crewhaus/tool-state`.
+- **It does not wait.** Nothing here sleeps, polls, or blocks. `ErrorClassify`
+  reports the wait a server asked for, and `SequenceRun` reports how long a
+  step has left before it is due; honouring either is the caller's job. There
+  is deliberately no `WaitForEvent`: blocking needs an event source to block
+  on and an abort signal to stop on, and a tool named for a wait that returned
+  immediately would be believed.
+- **It does not ask a human.** Approvals and questions need a channel and a
+  resumable id, which belong to the harness runtime.
+- **It does not validate against JSON Schema.** That is `JsonSchemaValidate`,
+  and the path-assertion gate is `Assert`, both in `@crewhaus/tool-schema`.
+
+## Error classification
+
+`ErrorClassify` maps any combination of status, exit code, signal, errno or
+provider code, message text and `Retry-After` onto one of 19 stable classes
+and one of 9 next actions. Precedence is: caller rules, then status, then
+signal, then exit code, then code, then message text.
+
+Two details worth knowing:
+
+- **`retryable` follows the action, not the class.** An OOM kill is class
+  `capacity`, which is retryable in general — but that particular one
+  resolves to `escalate`, and a caller reading the boolean would otherwise
+  re-run the identical command and be killed identically.
+- **Message matching uses substrings, not regular expressions.** That text
+  comes from a remote server, and a pattern with nested quantifiers there is
+  a denial of service waiting to happen. Caller-supplied rules may use a
+  regex; the builtin packs never do.
+
+Exit code `1` is deliberately unclassified. It is the generic "it failed" and
+says nothing about why, so claiming a class for it would be inventing
+information.
+
+## A known limitation: regex denial of service
+
+The `matches` and `notMatches` ops compile a caller-supplied pattern and run
+it against caller-supplied text. JavaScript's regex engine backtracks, so a
+pattern with nested quantifiers against text that *nearly* matches can take
+seconds of CPU:
+
+```
+^(([a-z])+.)+[A-Z]([a-z])+$   against 60 lowercase letters   ~2.7s
+```
+
+This is a property of the shared check grammar in `@crewhaus/tool-schema`,
+not of this package — the `Assert` tool has the same exposure, and both are
+reachable with operator-written or model-written patterns matched against
+text a harness fetched from somewhere else.
+
+Two things reduce it, neither of which is a fix:
+
+- `ErrorClassify` matches `message` and `code` **separately** rather than
+  joining them. A pattern anchored with `$` against a joined string can never
+  match, and a pattern that can never match is precisely the worst case for a
+  backtracking engine — joining the fields manufactured that for free.
+- `ErrorClassify`'s builtin packs use substrings, never patterns, so the
+  default path compiles no regex at all.
+
+A real fix has to live in the shared evaluator: reject nested-quantifier
+patterns before compiling them, or match with an engine that does not
+backtrack. Until then, treat `matches` as trusted-pattern-only, and prefer
+`contains`, `startsWith` and `endsWith` — which are linear — where they will
+do.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { type Check } from "@crewhaus/tool-schema";
+export declare const branch: RegisteredTool;
+export declare const decisionTable: RegisteredTool;
+export declare const errorClassify: RegisteredTool;
+export declare const deadlineCheck: RegisteredTool;
+export declare const consensusVote: RegisteredTool;
+export declare const stallDetect: RegisteredTool;
+export declare const ruleScore: RegisteredTool;
+export declare const leadAssign: RegisteredTool;
+export declare const sequenceRun: RegisteredTool;
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const FLOW_TOOLS: ReadonlyArray<RegisteredTool>;
+export type { Check };

package/dist/index.js

@@ -0,0 +1,461 @@
+/**
+ * @crewhaus/tool-flow — deterministic control flow.
+ *
+ * These are the decisions a harness makes constantly and should almost never
+ * pay a model to make: which arm to take, whether an error is worth
+ * retrying, whether the loop is still moving, whether there is time left,
+ * which band a score falls in, whether N answers actually agreed.
+ *
+ * Every library under `./lib` is pure — the clock is a parameter, never a
+ * call — so the same inputs give the same answer in a test, in a replay and
+ * in production. Three of the tool wrappers do read the real clock, because
+ * knowing the time is part of their job: `DeadlineCheck` always,
+ * `ErrorClassify` only to resolve a `Retry-After` given as a date, and
+ * `SequenceRun` only to decide whether a step's `after` gate has passed. All
+ * three take an explicit `now` that overrides it, and that is the only
+ * impurity in the package.
+ *
+ * The condition vocabulary is `@crewhaus/tool-schema`'s: `Branch`,
+ * `DecisionTable`, `RuleScore`, `LeadAssign` and `SequenceRun` all evaluate
+ * the same `checks` the `Assert` tool does, through the same evaluator. An
+ * operator learns one grammar.
+ */
+import { buildTool } from "@crewhaus/tool-builder";
+import { ASSERT_OPS } from "@crewhaus/tool-schema";
+import { z } from "zod";
+import { ASSIGN_STRATEGIES, assignOwner } from "./lib/assign";
+import { evaluateBranches } from "./lib/branch";
+import { VOTE_MODES, tallyVotes } from "./lib/consensus";
+import { checkDeadline } from "./lib/deadline";
+import { HIT_POLICIES, evaluateTable } from "./lib/decision";
+import { ERROR_CLASSES, NEXT_ACTIONS, classifyError } from "./lib/errors";
+import { scoreValue } from "./lib/score";
+import { planSequence } from "./lib/sequence";
+import { detectStall } from "./lib/stall";
+/** Compact JSON — the reader is a model, and every byte is context. */
+const json = (value) => JSON.stringify(value);
+/** Ceilings that keep one pathological table from becoming a hang. */
+const LIMITS = {
+    checks: 64,
+    arms: 64,
+    rows: 512,
+    rules: 256,
+    votes: 512,
+    history: 512,
+    signals: 64,
+    owners: 256,
+    steps: 256,
+};
+const checkSchema = z.object({
+    path: z
+        .string()
+        .optional()
+        .describe("dotted path into the value, e.g. 'order.items[0].sku'; omit for the value itself"),
+    op: z.enum(ASSERT_OPS),
+    expected: z.unknown().describe("the operand; its meaning depends on the op"),
+    flags: z.string().optional().describe("regex flags for matches/notMatches"),
+    message: z.string().optional().describe("replaces the generated reason when this check fails"),
+});
+const checksField = z.array(checkSchema).min(1).max(LIMITS.checks);
+const matchField = z
+    .enum(["all", "any"])
+    .optional()
+    .describe("whether every check must hold, or any one of them; default all");
+/**
+ * The largest epoch millisecond value a `Date` represents, per ECMAScript.
+ * Beyond it every `Date` is invalid, and `toISOString` throws.
+ */
+const MAX_TIME_VALUE = 8.64e15;
+/**
+ * An instant, as epoch milliseconds or an ISO-8601 string.
+ *
+ * A string without an offset is rejected rather than guessed at. Per
+ * ECMAScript, `Date.parse("2026-01-01T00:00:00")` is *local* time while the
+ * date-only form is UTC, so the same spec would mean different instants on
+ * two machines — the exact class of bug this package exists to remove.
+ *
+ * This is the one place an instant is turned into a number, so it is also
+ * the one place that has the field name to put in the message. An epoch
+ * outside the representable range used to pass straight through and surface
+ * later as a bare `RangeError: Invalid Date` from whichever consumer
+ * rendered it — `DeadlineCheck`'s `deadline`, `SequenceRun`'s
+ * `not due until …` — naming neither the field nor the value, in a spec that
+ * may carry a dozen instants. The string form was already caught, because
+ * `Date.parse` returns NaN out there; only the numeric form got this far.
+ */
+function parseInstant(value, field) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${field} is not a finite epoch-millisecond value`);
+        if (Math.abs(value) > MAX_TIME_VALUE) {
+            throw new Error(`${field} (${value}) is outside the range a date can represent (±8.64e15 epoch milliseconds)`);
+        }
+        return value;
+    }
+    const text = value.trim();
+    if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(text)) {
+        throw new Error(`${field} ("${text}") has no UTC offset — write it as e.g. 2026-01-01T00:00:00Z, because an offset-less string means local time and would differ between machines`);
+    }
+    const parsed = Date.parse(text);
+    if (Number.isNaN(parsed))
+        throw new Error(`${field} ("${text}") is not a valid ISO-8601 instant`);
+    return parsed;
+}
+const instantField = z.union([z.string(), z.number()]);
+// ---------------------------------------------------------------------------
+export const branch = buildTool({
+    name: "Branch",
+    description: "Take the first arm whose conditions hold, and hand back that arm's name and its declared result. Use it to route on a tool result — exit code, status, a field of a JSON response — without spending a model turn deciding which way to go. Conditions use the same vocabulary as Assert. An arm with no conditions is rejected, because it would silently swallow every later arm; a catch-all is spelled 'otherwise'.",
+    inputSchema: z.object({
+        value: z.unknown().describe("the value the arms are tested against"),
+        arms: z
+            .array(z.object({
+            name: z.string().min(1).describe("what the caller routes on; must be unique"),
+            when: checksField,
+            match: matchField,
+            result: z.unknown().describe("returned verbatim when this arm wins"),
+        }))
+            .min(1)
+            .max(LIMITS.arms),
+        otherwise: z
+            .object({ name: z.string().min(1), result: z.unknown() })
+            .optional()
+            .describe("used when no arm matches; without it a miss returns matched:false"),
+        verbose: z
+            .boolean()
+            .optional()
+            .describe("include the per-arm report of why earlier arms did not match"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const outcome = evaluateBranches(input.value, input.arms, {
+            otherwise: input.otherwise,
+        });
+        const body = {
+            matched: outcome.matched,
+            name: outcome.name,
+            index: outcome.index,
+            fallback: outcome.fallback,
+            result: outcome.result,
+            ...(input.verbose ? { evaluated: outcome.evaluated } : {}),
+        };
+        return json(body);
+    },
+});
+export const decisionTable = buildTool({
+    name: "DecisionTable",
+    description: "Answer an operator's policy table — severity by tier to priority and owner, error class by attempt to action — returning the matched row ids, the outputs, and a digest of the table that produced them. Four hit policies: first match, exactly one match, highest priority, or collect them all. Use it to keep a policy in versioned data instead of in a prompt, and to get an audit trail for free.",
+    inputSchema: z.object({
+        value: z.unknown().describe("the value the rows are tested against"),
+        policy: z.enum(HIT_POLICIES).describe("first | unique | priority | collect"),
+        version: z.string().optional().describe("echoed into the answer, so it is attributable"),
+        rows: z
+            .array(z.object({
+            id: z.string().min(1).describe("the audit trail; must be unique"),
+            when: checksField,
+            match: matchField,
+            priority: z.number().optional().describe("used by the priority policy; higher wins"),
+            outputs: z.record(z.unknown()).describe("what this row decides"),
+        }))
+            .min(1)
+            .max(LIMITS.rows),
+        otherwise: z.record(z.unknown()).optional().describe("outputs when no row matches"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => json(evaluateTable(input.value, input)),
+});
+export const errorClassify = buildTool({
+    name: "ErrorClassify",
+    description: `Turn an error's signals — HTTP status, exit code, signal, errno or provider code, message text, Retry-After — into one of ${ERROR_CLASSES.length} stable classes and one of ${NEXT_ACTIONS.length} next actions, with the wait the server itself asked for. Use it instead of asking a model whether something is worth retrying: a 429 with Retry-After is not a judgement call, and neither is exit 127. Attempt and maxAttempts downgrade a retry to an escalation once the attempts run out.`,
+    inputSchema: z.object({
+        status: z.number().int().optional().describe("HTTP status code"),
+        exitCode: z.number().int().optional().describe("process exit code; 128+N is read as signal N"),
+        signal: z.string().optional().describe("POSIX signal name, e.g. SIGKILL"),
+        code: z
+            .string()
+            .optional()
+            .describe("errno (ECONNRESET) or provider code (insufficient_quota)"),
+        message: z.string().optional().describe("the error message, or the tail of stderr"),
+        retryAfter: z
+            .string()
+            .optional()
+            .describe("the raw Retry-After header: seconds or an HTTP-date"),
+        attempt: z.number().int().positive().optional().describe("1-based attempt number"),
+        maxAttempts: z.number().int().positive().optional(),
+        now: instantField
+            .optional()
+            .describe("reference instant for a date-form Retry-After; defaults to the real clock"),
+        rules: z
+            .array(z.object({
+            id: z.string().min(1),
+            contains: z.string().optional().describe("case-insensitive substring of message or code"),
+            matches: z.string().optional().describe("regex source, matched case-insensitively"),
+            status: z.number().int().optional(),
+            exitCode: z.number().int().optional(),
+            class: z.enum(ERROR_CLASSES),
+            action: z.enum(NEXT_ACTIONS),
+            waitMs: z.number().int().nonnegative().optional(),
+        }))
+            .max(LIMITS.rules)
+            .optional()
+            .describe("caller rules, tried in order before every builtin pack"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const nowMs = input.now === undefined ? Date.now() : parseInstant(input.now, "now");
+        return json(classifyError(input, { rules: input.rules, nowMs }));
+    },
+});
+export const deadlineCheck = buildTool({
+    name: "DeadlineCheck",
+    description: "Report how much of a time budget is left, as milliseconds, a fraction, and a phase (ample, tight, critical, expired) a branch can switch on — and, given the cost of one more step, whether that step still fits. Use it because a model does not know what time it is: this is the authoritative clock for 'stop polling', 'skip the optional enrichment', 'take the fast path'.",
+    inputSchema: z
+        .object({
+        deadline: instantField.optional().describe("absolute end, ISO-8601 with offset or epoch ms"),
+        budgetMs: z.number().int().nonnegative().optional().describe("duration from startedAt"),
+        startedAt: instantField.optional().describe("when the budget started; defaults to now"),
+        now: instantField.optional().describe("overrides the real clock, for tests and replays"),
+        stepCostMs: z.number().int().positive().optional().describe("cost of one more unit of work"),
+        tightAt: z.number().min(0).max(1).optional().describe("fraction at or below which: tight"),
+        criticalAt: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("...and critical; must be <= tightAt"),
+    })
+        .refine((v) => v.deadline !== undefined || v.budgetMs !== undefined, {
+        message: "give either deadline or budgetMs",
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const nowMs = input.now === undefined ? Date.now() : parseInstant(input.now, "now");
+        return json(checkDeadline({
+            nowMs,
+            deadlineMs: input.deadline === undefined ? undefined : parseInstant(input.deadline, "deadline"),
+            budgetMs: input.budgetMs,
+            startedAtMs: input.startedAt === undefined ? undefined : parseInstant(input.startedAt, "startedAt"),
+            stepCostMs: input.stepCostMs,
+            tightAt: input.tightAt,
+            criticalAt: input.criticalAt,
+        }));
+    },
+});
+export const consensusVote = buildTool({
+    name: "ConsensusVote",
+    description: "Settle several answers into one by weighted plurality, and report how much they actually agreed. Compares exactly, numerically within a tolerance, or as sets by Jaccard overlap, after optional normalization. Use it to decide when N crew members or N samples agree enough to act, and when the disagreement means a judge or a human should look — the agreement fraction and the dissenters are the output that matters, not just the winner.",
+    inputSchema: z.object({
+        votes: z
+            .array(z.object({
+            value: z.unknown().describe("the answer cast"),
+            weight: z.number().nonnegative().optional().describe("default 1"),
+            voter: z.string().optional().describe("named in the dissent report"),
+        }))
+            .min(1)
+            .max(LIMITS.votes),
+        mode: z.enum(VOTE_MODES).optional().describe("exact | numeric | set; default exact"),
+        tolerance: z.number().nonnegative().optional().describe("numeric mode: absolute distance"),
+        overlap: z.number().min(0).max(1).optional().describe("set mode: minimum Jaccard similarity"),
+        threshold: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("support needed to be decided; default 0.5"),
+        normalize: z
+            .object({
+            trim: z.boolean().optional().describe("default true"),
+            lowercase: z.boolean().optional(),
+            collapseWhitespace: z.boolean().optional(),
+            stripPunctuation: z.boolean().optional(),
+        })
+            .optional(),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => json(tallyVotes(input.votes, input)),
+});
+export const stallDetect = buildTool({
+    name: "StallDetect",
+    description: "Given the last N turns of named progress signals — a failing-test fingerprint, a workspace diff hash, the last error, the tool call being made — say whether the loop is still moving, repeating itself, or oscillating between states. Use it to stop a fix-test-fail loop that has stopped making progress, which from inside any single turn is indistinguishable from one about to succeed. Also names the signals that have never changed.",
+    inputSchema: z.object({
+        history: z
+            .array(z.record(z.string()))
+            .min(1)
+            .max(LIMITS.history)
+            .describe("oldest first; each entry maps signal name to an opaque fingerprint"),
+        window: z
+            .number()
+            .int()
+            .min(2)
+            .optional()
+            .describe("identical snapshots to call it stalled; default 3"),
+        maxCycle: z
+            .number()
+            .int()
+            .positive()
+            .max(16)
+            .optional()
+            .describe("longest cycle to look for; default 3"),
+        signals: z
+            .array(z.string())
+            .max(LIMITS.signals)
+            .optional()
+            .describe("consider only these signals"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => json(detectStall(input.history, {
+        window: input.window,
+        maxCycle: input.maxCycle,
+        signals: input.signals,
+    })),
+});
+export const ruleScore = buildTool({
+    name: "RuleScore",
+    description: "Score a record against versioned additive rules and report the band it lands in, together with every rule that fired and what it contributed. Use it for lead qualification, risk, or triage priority: unlike a score a model produced, this one can be explained to the person it affects, re-run identically next quarter, and attributed to a rule version.",
+    inputSchema: z.object({
+        value: z.unknown().describe("the record being scored"),
+        version: z.string().optional().describe("echoed into the result, so a change is attributable"),
+        rules: z
+            .array(z.object({
+            id: z.string().min(1),
+            when: checksField,
+            points: z.number().describe("may be negative"),
+            label: z.string().optional().describe("the reason that goes on the record"),
+        }))
+            .min(1)
+            .max(LIMITS.rules),
+        bands: z
+            .array(z.object({ name: z.string().min(1), min: z.number() }))
+            .max(LIMITS.rules)
+            .optional()
+            .describe("highest band whose min is met wins, whatever order they are declared in"),
+        min: z.number().optional().describe("clamp the total"),
+        max: z.number().optional(),
+        includeMissed: z.boolean().optional().describe("also list the rules that did not fire"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const result = scoreValue(input.value, input);
+        if (input.includeMissed)
+            return json(result);
+        const { missed: _missed, ...rest } = result;
+        return json(rest);
+    },
+});
+export const leadAssign = buildTool({
+    name: "LeadAssign",
+    description: "Route a record to an owner from a declared roster: territory and segment as the same conditions Assert and RuleScore use, plus capacity, an out-of-office flag, and a strategy — declaration order, most specific territory, least loaded, or round robin. Use it to keep lead routing in versioned rules instead of in a prompt, and to be able to tell a rep exactly why a lead went elsewhere. It decides only: the load figures come in and the advanced rotation cursor goes back out, because this package does not persist anything.",
+    inputSchema: z.object({
+        value: z.unknown().describe("the record being routed"),
+        strategy: z.enum(ASSIGN_STRATEGIES).describe("first | specific | least_loaded | round_robin"),
+        version: z.string().optional().describe("echoed into the answer, so it is attributable"),
+        owners: z
+            .array(z.object({
+            id: z.string().min(1).describe("what gets written on the record; must be unique"),
+            when: checksField,
+            match: matchField,
+            load: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe("assignments already held; required by least_loaded and by capacity"),
+            capacity: z.number().nonnegative().optional().describe("skip this owner at or above it"),
+            available: z
+                .boolean()
+                .optional()
+                .describe("false takes the owner out; absent means no out-of-office record"),
+        }))
+            .min(1)
+            .max(LIMITS.owners),
+        cursor: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("round_robin: where the last call left off; the answer carries the next one, or null when nothing was picked from the roster and the old cursor still stands"),
+        fallback: z
+            .object({ id: z.string().min(1) })
+            .optional()
+            .describe("owner of last resort when nobody is eligible; never used for an undecidable roster"),
+        verbose: z
+            .boolean()
+            .optional()
+            .describe("include the per-owner report of why each was in, out, or undetermined (eligible: null)"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const { considered, ...rest } = assignOwner(input.value, input);
+        return json(input.verbose ? { ...rest, considered } : rest);
+    },
+});
+export const sequenceRun = buildTool({
+    name: "SequenceRun",
+    description: "Work out what a declared multi-step sequence should do next — the steps whose prerequisites are complete, whose scheduled time has arrived and whose conditions hold, each with the parameters to run it with — plus what is still waiting, what can no longer happen because a step it needs failed or was ruled out, and what its own conditions ruled out. The flow's state is one of ready, blocked, finished or halted, so a flow that died is never reported as one that completed. It returns a plan and runs nothing: invoking a tool needs the executor, which no tool package has. Use it to drive a cadence or a fix-up flow from versioned data, with the caller executing each step the plan hands back.",
+    inputSchema: z.object({
+        value: z.unknown().describe("the context the step conditions are tested against"),
+        version: z.string().optional().describe("echoed into the plan, so a change is attributable"),
+        steps: z
+            .array(z.object({
+            id: z.string().min(1).describe("must be unique; what needs and progress refer to"),
+            when: checksField
+                .optional()
+                .describe("the step's own gate; omit it for a step that is always due"),
+            match: matchField,
+            needs: z
+                .array(z.string().min(1))
+                .max(LIMITS.steps)
+                .optional()
+                .describe("ids that must be completed first"),
+            params: z.unknown().describe("returned verbatim in the plan, for the caller to act on"),
+            after: instantField.optional().describe("not due before this instant"),
+        }))
+            .min(1)
+            .max(LIMITS.steps),
+        completed: z
+            .array(z.string().min(1))
+            .max(LIMITS.steps)
+            .optional()
+            .describe("ids already done; the caller keeps this, the tool does not"),
+        failed: z
+            .array(z.string().min(1))
+            .max(LIMITS.steps)
+            .optional()
+            .describe("ids that failed; their dependents are reported unreachable, not waiting"),
+        now: instantField.optional().describe("overrides the real clock, for tests and replays"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const nowMs = input.now === undefined ? Date.now() : parseInstant(input.now, "now");
+        // Each `after` is parsed here and dropped, so the planner can only read
+        // the parsed number: a step can never end up gated on an offset-less
+        // string that means one instant on the operator's laptop and another in
+        // CI, because the string does not reach it.
+        const steps = input.steps.map(({ after, ...step }) => ({
+            ...step,
+            afterMs: after === undefined ? undefined : parseInstant(after, `step "${step.id}" after`),
+            when: step.when,
+        }));
+        return json(planSequence(input.value, { version: input.version, steps }, { nowMs, completed: input.completed, failed: input.failed }));
+    },
+});
+/** Every tool this package registers, in the order a catalog should list them. */
+export const FLOW_TOOLS = Object.freeze([
+    branch,
+    consensusVote,
+    deadlineCheck,
+    decisionTable,
+    errorClassify,
+    leadAssign,
+    ruleScore,
+    sequenceRun,
+    stallDetect,
+]);