@crewhaus/tool-flow 0.7.0

package/dist/lib/consensus.js

@@ -0,0 +1,99 @@
+/**
+ * Settle N answers into one, and say how much they actually agreed.
+ *
+ * The agreement number is the point. A plurality winner with 40% support is
+ * not the same as a unanimous one, and a caller that only reads the winner
+ * cannot tell them apart — which is exactly when a judge or a human should
+ * be brought in.
+ */
+import { canonicalize } from "./canonical";
+export const VOTE_MODES = ["exact", "numeric", "set"];
+export function normalizeValue(value, options = {}) {
+    if (typeof value !== "string")
+        return value;
+    let text = value;
+    if (options.trim !== false)
+        text = text.trim();
+    if (options.lowercase)
+        text = text.toLowerCase();
+    if (options.stripPunctuation)
+        text = text.replace(/[^\p{L}\p{N}\s]/gu, "");
+    if (options.collapseWhitespace)
+        text = text.replace(/\s+/g, " ").trim();
+    return text;
+}
+/** Jaccard similarity of two arrays treated as sets of stringified members. */
+export function jaccard(a, b) {
+    const left = new Set(a.map(canonicalize));
+    const right = new Set(b.map(canonicalize));
+    if (left.size === 0 && right.size === 0)
+        return 1;
+    let shared = 0;
+    for (const item of left)
+        if (right.has(item))
+            shared += 1;
+    return shared / (left.size + right.size - shared);
+}
+/** Whether two already-normalized values count as the same answer. */
+function same(a, b, options) {
+    const mode = options.mode ?? "exact";
+    if (mode === "numeric") {
+        if (typeof a !== "number" || typeof b !== "number")
+            return false;
+        if (!Number.isFinite(a) || !Number.isFinite(b))
+            return false;
+        return Math.abs(a - b) <= (options.tolerance ?? 0);
+    }
+    if (mode === "set") {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        return jaccard(a, b) >= (options.overlap ?? 1);
+    }
+    return canonicalize(a) === canonicalize(b);
+}
+export function tallyVotes(votes, options = {}) {
+    if (votes.length === 0)
+        throw new Error("no votes were given");
+    const groups = [];
+    let total = 0;
+    for (const [index, vote] of votes.entries()) {
+        const weight = vote.weight ?? 1;
+        if (!Number.isFinite(weight) || weight < 0) {
+            throw new Error(`vote ${index} has weight ${vote.weight}, which must be a non-negative number`);
+        }
+        const value = normalizeValue(vote.value, options.normalize);
+        total += weight;
+        const voter = vote.voter ?? `#${index}`;
+        // Grouping is by first-match against existing groups, which is what makes
+        // `numeric` and `set` work at all: they are not transitive, so there is no
+        // canonical key to bucket by. Declared order therefore decides which
+        // group a borderline value joins, and that is why it is documented.
+        const existing = groups.find((g) => same(g.value, value, options));
+        if (existing) {
+            existing.weight += weight;
+            existing.voters.push(voter);
+        }
+        else {
+            groups.push({ value, weight, voters: [voter], order: index });
+        }
+    }
+    const ranked = [...groups].sort((a, b) => b.weight - a.weight || a.order - b.order);
+    const top = ranked[0];
+    const runnerUp = ranked[1];
+    const tie = runnerUp !== undefined && runnerUp.weight === top.weight;
+    const agreement = total === 0 ? 0 : top.weight / total;
+    const threshold = options.threshold ?? 0.5;
+    return {
+        // A tie is never decided, however high the fraction: two answers at 50%
+        // each would otherwise both clear a 0.5 threshold.
+        decided: !tie && agreement >= threshold,
+        winner: top.value,
+        support: top.weight,
+        total,
+        agreement,
+        unanimous: ranked.length === 1,
+        tie,
+        groups: ranked.map((g) => ({ value: g.value, weight: g.weight, voters: g.voters })),
+        dissenters: ranked.slice(1).flatMap((g) => g.voters),
+    };
+}

package/dist/lib/deadline.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Time budgets.
+ *
+ * A model does not know what time it is, and a harness that asks one to
+ * decide "do I still have time for the thorough path?" is paying a token
+ * price for arithmetic. This does the arithmetic.
+ *
+ * The clock is an input, not a call. Every function here takes `nowMs`, so
+ * the same inputs give the same answer in a test, in a replay and in a
+ * production run; the tool wrapper is the one place that reads the real
+ * clock, and even there the caller may override it.
+ */
+/** How much of the budget is left, as a label a branch can switch on. */
+export declare const BUDGET_PHASES: readonly ["ample", "tight", "critical", "expired"];
+export type BudgetPhase = (typeof BUDGET_PHASES)[number];
+export type DeadlineInput = {
+    readonly nowMs: number;
+    /** An absolute end, as epoch ms. Supply this or `budgetMs`. */
+    readonly deadlineMs?: number;
+    /** A duration, measured from `startedAtMs` (default: now). */
+    readonly budgetMs?: number;
+    readonly startedAtMs?: number;
+    /**
+     * What one more unit of work is expected to cost. When it does not fit in
+     * the remaining time, `fits` is false and the caller can skip it.
+     */
+    readonly stepCostMs?: number;
+    /** Fraction remaining at or below which the phase becomes `tight`. */
+    readonly tightAt?: number;
+    /** ...and `critical`. Must be below `tightAt`. */
+    readonly criticalAt?: number;
+};
+export type DeadlineReport = {
+    readonly nowMs: number;
+    readonly deadlineMs: number;
+    readonly remainingMs: number;
+    readonly elapsedMs: number;
+    readonly totalMs: number;
+    /** Remaining over total, clamped to 0..1. 0 when the budget was empty. */
+    readonly fractionRemaining: number;
+    readonly phase: BudgetPhase;
+    readonly expired: boolean;
+    /** Null when no `stepCostMs` was given. */
+    readonly fits: boolean | null;
+    /** How many more steps of `stepCostMs` fit. Null without a step cost. */
+    readonly stepsRemaining: number | null;
+    readonly deadline: string;
+};
+export declare function checkDeadline(input: DeadlineInput): DeadlineReport;

package/dist/lib/deadline.js

@@ -0,0 +1,68 @@
+/**
+ * Time budgets.
+ *
+ * A model does not know what time it is, and a harness that asks one to
+ * decide "do I still have time for the thorough path?" is paying a token
+ * price for arithmetic. This does the arithmetic.
+ *
+ * The clock is an input, not a call. Every function here takes `nowMs`, so
+ * the same inputs give the same answer in a test, in a replay and in a
+ * production run; the tool wrapper is the one place that reads the real
+ * clock, and even there the caller may override it.
+ */
+/** How much of the budget is left, as a label a branch can switch on. */
+export const BUDGET_PHASES = ["ample", "tight", "critical", "expired"];
+const DEFAULT_TIGHT = 0.5;
+const DEFAULT_CRITICAL = 0.2;
+export function checkDeadline(input) {
+    const tightAt = input.tightAt ?? DEFAULT_TIGHT;
+    const criticalAt = input.criticalAt ?? DEFAULT_CRITICAL;
+    if (criticalAt > tightAt) {
+        throw new Error(`criticalAt (${criticalAt}) must not be above tightAt (${tightAt})`);
+    }
+    const startedAtMs = input.startedAtMs ?? input.nowMs;
+    let deadlineMs;
+    let totalMs;
+    if (input.deadlineMs !== undefined) {
+        deadlineMs = input.deadlineMs;
+        totalMs = Math.max(0, deadlineMs - startedAtMs);
+    }
+    else if (input.budgetMs !== undefined) {
+        totalMs = Math.max(0, input.budgetMs);
+        deadlineMs = startedAtMs + totalMs;
+    }
+    else {
+        throw new Error("give either deadlineMs or budgetMs");
+    }
+    const remainingMs = deadlineMs - input.nowMs;
+    const elapsedMs = input.nowMs - startedAtMs;
+    const expired = remainingMs <= 0;
+    // A zero-length budget is spent by definition; dividing by it would give
+    // NaN, which would then compare false against every threshold and read as
+    // "ample" — the most dangerous possible answer.
+    const fractionRemaining = totalMs === 0 ? 0 : Math.min(1, Math.max(0, remainingMs / totalMs));
+    const phase = expired
+        ? "expired"
+        : fractionRemaining <= criticalAt
+            ? "critical"
+            : fractionRemaining <= tightAt
+                ? "tight"
+                : "ample";
+    const stepCost = input.stepCostMs;
+    const stepsRemaining = stepCost === undefined || stepCost <= 0
+        ? null
+        : Math.max(0, Math.floor(Math.max(0, remainingMs) / stepCost));
+    return {
+        nowMs: input.nowMs,
+        deadlineMs,
+        remainingMs,
+        elapsedMs,
+        totalMs,
+        fractionRemaining,
+        phase,
+        expired,
+        fits: stepCost === undefined ? null : !expired && remainingMs >= stepCost,
+        stepsRemaining,
+        deadline: new Date(deadlineMs).toISOString(),
+    };
+}

package/dist/lib/decision.d.ts

@@ -0,0 +1,38 @@
+import { type Check } from "@crewhaus/tool-schema";
+import type { MatchMode } from "./branch";
+export declare const HIT_POLICIES: readonly ["first", "unique", "priority", "collect"];
+export type HitPolicy = (typeof HIT_POLICIES)[number];
+export type DecisionRow = {
+    readonly id: string;
+    readonly when: ReadonlyArray<Check>;
+    readonly match?: MatchMode;
+    /** Used by the `priority` policy; higher wins. Defaults to 0. */
+    readonly priority?: number;
+    readonly outputs: Readonly<Record<string, unknown>>;
+};
+export type DecisionTable = {
+    /** Echoed into every answer, so a decision is attributable to a revision. */
+    readonly version?: string;
+    readonly policy: HitPolicy;
+    readonly rows: ReadonlyArray<DecisionRow>;
+    /** Used when no row matches. Without it, a miss is `matched: false`. */
+    readonly otherwise?: Readonly<Record<string, unknown>>;
+};
+export type DecisionResult = {
+    readonly ok: boolean;
+    readonly matched: boolean;
+    readonly policy: HitPolicy;
+    readonly version: string | null;
+    /** Ids of every row that matched, in declared order. */
+    readonly matchedIds: ReadonlyArray<string>;
+    /** One row's outputs; for `collect`, one entry per matched row. */
+    readonly outputs: Readonly<Record<string, unknown>> | ReadonlyArray<Record<string, unknown>> | null;
+    readonly fallback: boolean;
+    /** Set when the table could not answer: ambiguity under `unique`/`priority`. */
+    readonly conflict: string | null;
+    /** Stable digest of the table, so a changed policy is visible in a log. */
+    readonly tableHash: string;
+};
+/** Digest of the rows and policy — not the version string, which is a label. */
+export declare function hashTable(table: DecisionTable): string;
+export declare function evaluateTable(value: unknown, table: DecisionTable): DecisionResult;

package/dist/lib/decision.js

@@ -0,0 +1,107 @@
+/**
+ * Decision tables: an operator's policy written once, answered the same way
+ * every time, with the matched row ids as the audit trail.
+ *
+ * The difference from {@link ./branch} is the hit policy. A branch is always
+ * "first one wins". A table can also require exactly one row to match, rank
+ * by priority, or collect every match — and each of those catches a class of
+ * policy bug that "first wins" hides.
+ */
+import { createHash } from "node:crypto";
+import { runChecks } from "@crewhaus/tool-schema";
+import { canonicalize } from "./canonical";
+export const HIT_POLICIES = ["first", "unique", "priority", "collect"];
+/** Digest of the rows and policy — not the version string, which is a label. */
+export function hashTable(table) {
+    const material = canonicalize({ policy: table.policy, rows: table.rows });
+    return createHash("sha256").update(material).digest("hex").slice(0, 16);
+}
+export function evaluateTable(value, table) {
+    if (table.rows.length === 0)
+        throw new Error("the decision table has no rows");
+    const seen = new Set();
+    for (const row of table.rows) {
+        if (row.when.length === 0) {
+            throw new Error(`row "${row.id}" has no checks — a row with no checks matches everything; use "otherwise" for a default`);
+        }
+        if (seen.has(row.id))
+            throw new Error(`two rows share the id "${row.id}"`);
+        seen.add(row.id);
+    }
+    const tableHash = hashTable(table);
+    const version = table.version ?? null;
+    const base = { policy: table.policy, version, tableHash };
+    const matches = [];
+    for (const row of table.rows) {
+        const report = runChecks(value, row.when);
+        const ok = (row.match ?? "all") === "all" ? report.ok : report.passed > 0;
+        if (ok) {
+            matches.push(row);
+            // `first` needs no further rows; the others need to see them all.
+            if (table.policy === "first")
+                break;
+        }
+    }
+    const matchedIds = matches.map((r) => r.id);
+    if (matches.length === 0) {
+        if (table.otherwise) {
+            return {
+                ...base,
+                ok: true,
+                matched: true,
+                matchedIds: [],
+                outputs: table.otherwise,
+                fallback: true,
+                conflict: null,
+            };
+        }
+        return {
+            ...base,
+            ok: true,
+            matched: false,
+            matchedIds: [],
+            outputs: null,
+            fallback: false,
+            conflict: null,
+        };
+    }
+    const answer = (outputs, conflict) => ({
+        ...base,
+        ok: conflict === null,
+        matched: conflict === null,
+        matchedIds,
+        outputs: conflict === null ? outputs : null,
+        fallback: false,
+        conflict,
+    });
+    switch (table.policy) {
+        case "first":
+            return answer(matches[0]?.outputs ?? null, null);
+        case "collect":
+            return answer(matches.map((r) => r.outputs), null);
+        case "unique":
+            // Two rows matching under `unique` is the bug the policy exists to
+            // find: the table's conditions were meant to be disjoint and are not.
+            return matches.length === 1
+                ? answer(matches[0]?.outputs ?? null, null)
+                : answer(null, `rows ${matchedIds.map((id) => `"${id}"`).join(", ")} all matched`);
+        case "priority": {
+            let best = matches[0];
+            let tied = [best];
+            for (const row of matches.slice(1)) {
+                const a = row.priority ?? 0;
+                const b = best.priority ?? 0;
+                if (a > b) {
+                    best = row;
+                    tied = [row];
+                }
+                else if (a === b) {
+                    tied.push(row);
+                }
+            }
+            return tied.length === 1
+                ? answer(best.outputs, null)
+                : answer(null, `rows ${tied.map((r) => `"${r.id}"`).join(", ")} share the top priority ${best.priority ?? 0}`);
+        }
+    }
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Map an error to a stable class and a next action.
+ *
+ * Deciding "is this worth retrying?" is the single most common reason a
+ * harness spends a model turn on something that has a right answer. A 429
+ * with `Retry-After: 30` is not a judgement call, and neither is exit code
+ * 127. This turns the signals a failure actually carries — status, exit
+ * code, errno, the text — into one of a fixed set of classes and one of a
+ * fixed set of actions, so a loop can act on it directly.
+ *
+ * Nothing here reads the clock. `Retry-After` in its HTTP-date form is a
+ * point in time, and turning that into a wait needs a "now"; the caller
+ * supplies one or gets the date back unconverted. A classifier that quietly
+ * called `Date.now()` would return a different answer every second, which is
+ * exactly what this package promises not to do.
+ */
+export declare const ERROR_CLASSES: readonly ["ok", "transient", "timeout", "unavailable", "rate_limited", "quota", "auth", "permission", "not_found", "bad_request", "conflict", "too_large", "unsupported", "capacity", "integrity", "cancelled", "redirect", "bug", "unknown"];
+export type ErrorClass = (typeof ERROR_CLASSES)[number];
+export declare const NEXT_ACTIONS: readonly ["continue", "retry", "retry_after", "backoff", "reauth", "reduce_input", "escalate", "skip", "fail"];
+export type NextAction = (typeof NEXT_ACTIONS)[number];
+/** Everything a failure might carry. All optional; more is better. */
+export type ErrorSignal = {
+    readonly status?: number;
+    readonly exitCode?: number;
+    readonly signal?: string;
+    /** A Node errno (`ECONNRESET`) or a provider code (`insufficient_quota`). */
+    readonly code?: string;
+    /** The error message, or the tail of stderr. */
+    readonly message?: string;
+    /** The raw `Retry-After` header: delta-seconds or an HTTP-date. */
+    readonly retryAfter?: string;
+    /** 1-based attempt number and its ceiling, to decide when to stop. */
+    readonly attempt?: number;
+    readonly maxAttempts?: number;
+};
+/** A caller-supplied rule, tried before every builtin pack. */
+export type ErrorRule = {
+    readonly id: string;
+    /** Case-insensitive substring of the message, or of `code`. */
+    readonly contains?: string;
+    /** Regex source matched against the message. Anchored by the caller. */
+    readonly matches?: string;
+    readonly status?: number;
+    readonly exitCode?: number;
+    readonly class: ErrorClass;
+    readonly action: NextAction;
+    readonly waitMs?: number;
+};
+export type Classification = {
+    readonly class: ErrorClass;
+    readonly action: NextAction;
+    readonly retryable: boolean;
+    /** How long to wait, when the error itself said so. Never invented. */
+    readonly waitMs: number | null;
+    /** The `Retry-After` date, when it was a date and no `now` was given. */
+    readonly retryAt: string | null;
+    /** Which rule decided this: a pack entry's id, or a caller rule's id. */
+    readonly matched: string;
+    readonly source: "custom" | "status" | "exit" | "signal" | "code" | "message" | "default";
+    /** True when attempts ran out, which downgrades a retry to an escalation. */
+    readonly exhausted: boolean;
+};
+/**
+ * Parse `Retry-After`. Two forms are legal: delta-seconds, and an HTTP-date.
+ * The date form needs a reference point to become a duration, so without
+ * `nowMs` it is returned as a date and `waitMs` stays null.
+ */
+export declare function parseRetryAfter(raw: string, nowMs?: number): {
+    waitMs: number | null;
+    retryAt: string | null;
+};
+export type ClassifyOptions = {
+    readonly rules?: ReadonlyArray<ErrorRule>;
+    /** Epoch milliseconds, only used to turn an HTTP-date `Retry-After` into a wait. */
+    readonly nowMs?: number;
+};
+export declare function classifyError(signal: ErrorSignal, options?: ClassifyOptions): Classification;