toolroll 0.5.0

package/dist/phase-routing.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Explainable, risk-aware phase routing (v47).
+ *
+ * WHICH agent plans, builds, repairs, and reviews a task is decided here,
+ * once, from signed facts — never guessed from a model's name and never
+ * re-decided behind an approval's back. The policy is a small table over
+ * explicit inputs:
+ *
+ *   risk         — the task's declared risk (routine / elevated / high)
+ *   quality      — the evidence policy the scope signs (default / strict)
+ *   evidence     — what the acceptance rubric demands (screenshots, …)
+ *   publication  — how far the plane may carry the result unattended
+ *   candidates   — the operator's CONFIGURED routine and strong agents
+ *   overrides    — an approver's explicit per-phase choice, recorded
+ *   pins         — a routine firing's or plan request's pinned pair
+ *
+ * and its output is one canonical ROUTE: four legs, each with an exact
+ * provider AND an exact model id, which tier it came from, whether a
+ * person overrode it, and plain-English reasons. The same inputs always
+ * yield the same route and the same words — `recommendRoute` is pure, so
+ * the surfaces (CLI, task page, chat) render one projection rather than
+ * three.
+ *
+ * EXACTNESS is the law of this module: a candidate, an override, a pin,
+ * and every frozen leg name an exact model id — "the harness default"
+ * is not a term an approval can bind. A configuration that cannot make a
+ * leg exact (no model configured, a cross-provider repair row, gemini on
+ * the review phase) becomes a stated PROBLEM on that leg, and the scope
+ * files unresolved with those words; nothing is guessed or substituted.
+ *
+ * Strength is never inferred: "strong" means the operator named a strong
+ * candidate for that phase (`config set <phase> --tier strong …`). With
+ * none configured, a demanding task still routes to the configured
+ * default and SAYS so — and its posture reads as economical, because that
+ * is what actually runs. Provider readiness is a runner's observation,
+ * not a term — it rides beside the route (ready / unavailable / unknown),
+ * it is stated wherever the route is shown, and an unavailable provider
+ * is never substituted: admission halts with the reason, and only an
+ * already-approved explicit fallback entry may ever run instead.
+ *
+ * Approval seals the route (`approvedRouteJson`); its digest folds into
+ * the scope digest of EVERY route filed since v47 — routine-shaped routes
+ * included — so a task-level route edit stales the approval exactly as a
+ * goal edit does, while a global configuration change can never rewrite a
+ * sealed route. Only a row proven to predate v47 (no route era) reads as
+ * a legacy approval governed by its sealed profile alone.
+ */
+import type { Phase, ProviderId } from "./provider.js";
+import type { QualityMode } from "./quality.js";
+export declare const PROVIDER_ID_LIST: readonly ProviderId[];
+/** provider.ts's MODEL_ID, restated for the same reason and pinned by the
+ * same test: an exact model id is argv-safe — no leading dash, no
+ * whitespace or control bytes — or it is not a model id this policy can
+ * seal, stamp, or rehydrate. */
+export declare const MODEL_ID_SHAPE: RegExp;
+/** The same exactness for callers outside this policy (the profile
+ * rehydrator): one shape, one definition. */
+export declare function exactModelId(v: unknown): v is string;
+export declare const ROUTE_VERSION = 1;
+/** The durable route ERA a scope row carries once it was filed under this
+ * policy: NULL on a row proven to predate v47 (legacy — the sealed profile
+ * alone governs), this value on every row filed since. A row with an era
+ * and no readable route is corrupt and fails closed. */
+export declare const ROUTE_ERA = 1;
+export declare const PHASES: readonly Phase[];
+/** The review leg remains readable in signed history but is no longer scheduled. */
+export declare const ACTIVE_PHASES: readonly Phase[];
+export type RiskLevel = "routine" | "elevated" | "high";
+export declare const RISK_LEVELS: readonly RiskLevel[];
+export declare function isRiskLevel(value: unknown): value is RiskLevel;
+export declare function riskTitle(risk: RiskLevel): string;
+/**
+ * What declaring each risk level DOES, in one plain sentence — derived
+ * from the tiering table below, so the explanation a form or a chat gives
+ * can never drift from the policy that acts on it. The same words on
+ * every surface: the task page's risk control, the chat's answer, the CLI.
+ */
+export declare function riskConsequence(risk: RiskLevel): string;
+export declare const RISK_CHOICES: readonly {
+    risk: RiskLevel;
+    title: string;
+    consequence: string;
+}[];
+/** A runner's non-spending observation of one provider. `unknown` is a
+ * real answer (claude has no login probe that does not spend) and is never
+ * upgraded to ready. */
+export type ReadinessState = "ready" | "unavailable" | "unknown";
+export type ReadinessObservation = {
+    provider: ProviderId;
+    state: ReadinessState;
+    /** The probe's own words: "not logged in", "`codex` is not installed"… */
+    reason: string;
+    /** Which non-spending check produced this: version, identity, key, none. */
+    probe: string;
+    observedAt: string;
+    runner: string;
+};
+export type CandidateTier = "routine" | "strong";
+/** An exact agent: provider and model id, both required. */
+export type ExactSpec = {
+    provider: ProviderId;
+    model: string;
+};
+export type RouteCandidate = ExactSpec & {
+    /** Where the candidate was read from — provenance words, never a term. */
+    source: string;
+};
+export type PhaseCandidates = {
+    routine: RouteCandidate;
+    /** The operator's named strong agent for this phase, or null when none
+     * is configured. Never inferred. */
+    strong: RouteCandidate | null;
+};
+/** The repair phase's candidates: with no repair row configured the
+ * routine candidate is null and the leg INHERITS the build leg's exact
+ * pair (repairs resume the builder's session). */
+export type RepairCandidates = {
+    routine: RouteCandidate | null;
+    strong: RouteCandidate | null;
+};
+export type RouteCandidates = {
+    plan: PhaseCandidates;
+    build: PhaseCandidates;
+    repair: RepairCandidates;
+    review: PhaseCandidates;
+};
+/** An approver's explicit per-phase choice, recorded with attribution.
+ * Always an exact pair. */
+export type RouteOverride = ExactSpec & {
+    phase: Phase;
+    by: string;
+    at: string;
+};
+/** The evidence kinds an acceptance rubric demands — `scope.ts` owns the
+ * full type; the policy only needs the names. */
+export type RouteEvidenceKind = "check" | "screenshot" | "changed-path" | "manual-review";
+/** How far the plane may carry a result without a person: no publication
+ * grant at all, a grant whose merges wait for a human (notify), or a live
+ * mode that merges by itself (automerge). */
+export type PublicationAuthority = "none" | "notify" | "automerge";
+export type RouteInput = {
+    risk: RiskLevel;
+    qualityMode: QualityMode;
+    evidence: readonly RouteEvidenceKind[];
+    publication: PublicationAuthority;
+    candidates: RouteCandidates;
+    overrides: readonly RouteOverride[];
+    /** Pinned exact pairs beat everything: a routine firing's build pin, a
+     * plan request's plan pin, and — when an explicit approved profile files
+     * the scope — its repair model on the build provider. */
+    pins?: {
+        plan?: ExactSpec | null;
+        build?: ExactSpec | null;
+        repair?: ExactSpec | null;
+    };
+};
+export type RouteLeg = {
+    phase: Phase;
+    provider: ProviderId;
+    /** The exact model id this leg runs — never null on a frozen route. */
+    model: string;
+    /** The tier the recommendation drew from; an override or pin still
+     * records what tier the policy would have used. */
+    tier: CandidateTier;
+    chosen: "recommended" | "override" | "pinned";
+    /** What the policy recommended before any override or pin — shown so an
+     * overridden leg can say what it replaced. */
+    recommended: {
+        provider: ProviderId;
+        model: string;
+        tier: CandidateTier;
+    };
+    /** Plain-English, ordered, deterministic. */
+    reasons: string[];
+    /** A configuration that cannot run this leg at all (gemini on review,
+     * cross-provider repair) — stated, never repaired by substitution; a
+     * route with any problem files its scope unresolved. */
+    problem: string | null;
+};
+export type PhaseRoute = {
+    version: typeof ROUTE_VERSION;
+    risk: RiskLevel;
+    qualityMode: QualityMode;
+    publication: PublicationAuthority;
+    evidence: RouteEvidenceKind[];
+    /** The posture the route ACTUALLY runs under: "strong" only when at
+     * least one leg draws from a configured strong agent; "economy" when
+     * every selected agent is the routine one — however demanding the task,
+     * a route that keeps every default never claims stronger agents. */
+    posture: "economy" | "strong";
+    /** Why a stronger tier was wanted, in order (empty for a routine task). */
+    demands: string[];
+    legs: RouteLeg[];
+    overrides: RouteOverride[];
+};
+export declare function specWords(spec: {
+    provider: string;
+    model: string;
+}): string;
+/**
+ * The recommendation: pure, deterministic, table-driven. Same inputs,
+ * same route, same words. Every leg it returns is exact; a leg the
+ * configuration cannot make runnable carries a `problem` instead of a
+ * guess.
+ */
+export declare function recommendRoute(input: RouteInput): PhaseRoute;
+export declare function legOf(route: PhaseRoute, phase: Phase): RouteLeg;
+/** Every stated problem on the route, in phase order — a non-empty list
+ * means the scope files unresolved with these words. */
+export declare function routeProblems(route: PhaseRoute): string[];
+/** Whether two exact pairs are the same agent. */
+export declare function sameSpec(a: {
+    provider: string;
+    model: string | null;
+}, b: {
+    provider: string;
+    model: string | null;
+}): boolean;
+/** The stored snapshot bytes: the version rides IN the snapshot. */
+export declare function canonicalRouteJson(route: PhaseRoute): string;
+/** sha256 over a domain-separated canonical encoding, truncated to the
+ * same 128 bits every other safety digest here uses. Its own domain, so a
+ * route digest can never collide with a profile or chain digest. */
+export declare function routeDigestOf(route: PhaseRoute): string;
+/** Strict rehydration of a stored route — every field type-proved, every
+ * model an exact non-empty string; anything unexpected is null, never a
+ * guess. A null from a row that carries a route era is a corrupt seal. */
+export declare function routeFromJson(json: string | null): PhaseRoute | null;
+/** Strict parse of an override list: one per phase, every field proved,
+ * every model exact. */
+export declare function parseOverrides(raw: unknown): RouteOverride[] | null;
+/** The stored override list (a task-level column). Malformed reads as
+ * null — the caller files the scope unresolved rather than routing as if
+ * nobody had overridden anything. */
+export declare function overridesFromJson(json: string | null): RouteOverride[] | null;
+export declare function canonicalOverridesJson(overrides: readonly RouteOverride[]): string | null;
+export type ReadinessLookup = (provider: ProviderId) => Pick<ReadinessObservation, "state" | "reason" | "runner" | "observedAt"> | null;
+export type RouteLegProjection = RouteLeg & {
+    readiness: ReadinessState;
+    readinessReason: string | null;
+    readinessRunner: string | null;
+    observedAt: string | null;
+    /** One line every surface prints for this leg. */
+    words: string;
+};
+export type RouteProjection = {
+    digest: string;
+    risk: RiskLevel;
+    riskTitle: string;
+    posture: PhaseRoute["posture"];
+    postureWords: string;
+    demands: string[];
+    legs: RouteLegProjection[];
+    /** The compact plain-English line: who does what, and whether any of
+     * them is a stronger-than-default agent. */
+    summary: string;
+    /** True when any leg is known-unavailable — admission halts, nothing
+     * substitutes. */
+    halted: boolean;
+    /** Every stated leg problem, phase-prefixed. */
+    problems: string[];
+};
+/** What actually runs: stronger agents only when a leg draws from one. */
+export declare function postureWords(route: Pick<PhaseRoute, "legs">): string;
+export declare function readinessWords(state: ReadinessState, reason: string | null): string;
+export declare function chosenWords(leg: Pick<RouteLeg, "chosen" | "tier">): string;
+/**
+ * The one-line Agents summary every surface can show above the details:
+ * agents grouped by identical pair, in phase order — "claude · sonnet
+ * plans, builds, and repairs; claude · opus reviews" — with the posture
+ * said honestly (stronger agents only when one is actually selected).
+ */
+export declare function agentsSummary(route: Pick<PhaseRoute, "legs">): string;
+export declare function legLine(leg: RouteLegProjection): string;
+/** The one projection CLI, task page, and chat all render from. */
+export declare function projectRoute(route: PhaseRoute, readiness: ReadinessLookup): RouteProjection;
+/** The approval-card lines: one route header, one line per leg, then the
+ * reasons indented — identical bytes on every text surface. */
+export declare function routeWords(projection: RouteProjection, indent?: string): string[];
+/** The empty readiness lookup: every provider unknown. */
+export declare const NO_READINESS: ReadinessLookup;
+/** How a run's provenance names the leg it spent as: the frozen leg's own
+ * word, `legacy` for a run governed by a pre-routing approval, a contest
+ * lane, or an attended session, and `fallback` for an approved fallback
+ * entry (and every repair of one). */
+export type RouteChosen = RouteLeg["chosen"] | "legacy" | "fallback";
+export declare const ROUTE_CHOSEN: readonly RouteChosen[];
+/** One run's route provenance: the exact provider and model that ran,
+ * under which route (or legacy profile) digest, as which leg. */
+export type RouteStamp = {
+    routeDigest: string;
+    phase: Phase;
+    provider: string;
+    model: string | null;
+    chosen: RouteChosen;
+};
+/** A run's role, as the route phase it spends as: a scout runs the build
+ * leg's agent (the same sealed profile a build proves against). */
+export declare function phaseOfRole(role: "builder" | "repair" | "planner" | "scout" | "reviewer"): Phase;
+/**
+ * Strict proof of a route stamp's SHAPE, before anything about it is
+ * believed: a known phase and provenance word, a known provider, a
+ * non-empty digest, and an exact model on every stamp except a legacy
+ * one (a pre-routing profile may carry no model). Anything else is the
+ * words for why — admission refuses on them, never coerces.
+ */
+export declare function routeStampProblem(stamp: unknown): string | null;