toolroll 0.9.103 → 0.9.105

package/dist/route-rules.d.ts

@@ -1,324 +0,0 @@
-import { type NotCountedReason } from "./contracts/route-results.js";
-import { type PhaseRoute } from "./phase-routing.js";
-import { type RuleDoor, type RuleRefusalReason } from "./route-store.js";
-import { type Store } from "./store.js";
-/** The policy version a grant is sealed under: a grant sealed under another version pauses its rule. */
-export declare const ROUTING_POLICY_VERSION = 1;
-/** When to suggest (Suggest and trigger terms): records of the last 90 days, the newest 20 decided. */
-export declare const SUGGEST_TERMS: Readonly<{
-    windowDays: 90;
-    newest: 20;
-    minDecided: 10;
-    minMature: 0.9;
-    lastClean: 3;
-    configuredGap: 0.05;
-    maxNotCounted: number;
-}>;
-/** How long a grant lasts, how long Not now keeps a suggestion quiet, and when Needs you says a grant ends soon. */
-export declare const GRANT_DAYS = 90;
-export declare const NOT_NOW_DAYS = 30;
-export declare const EXPIRY_WARNING_DAYS = 7;
-/** A rule's switch-back terms, sealed at acceptance (route_rule.grant_json) and read only from there. */
-export type Grant = {
-    policyVersion: number;
-    cutoff: string;
-    expires: string;
-    /** Switch off when more than `max` of the latest `window` decided records are rejected. */
-    reject: {
-        window: number;
-        max: number;
-    };
-    /** Once `window` decided records exist: switch off when fewer than `min` of the latest `window` are mature. */
-    mature: {
-        window: number;
-        min: number;
-    };
-    /** Switch off when more than `max` of the latest `window` closed exposures were approved with another model. */
-    declined: {
-        window: number;
-        max: number;
-    };
-};
-export declare function grantFor(now: Date): Grant;
-/** The switch-back terms in words, as the review shows them before acceptance and Settings after. */
-export declare function grantWords(grant: Grant): string[];
-export type RuleState = "active" | "trialling" | "paused" | "switched-off" | "turned-off" | "expired" | "dropped" | "finished";
-export type RuleRow = {
-    id: number;
-    repo: string;
-    cohortSize: "small" | "medium";
-    kind: "rule" | "trial";
-    provider: string;
-    model: string;
-    configured: {
-        provider: string;
-        model: string | null;
-    };
-    state: RuleState;
-    generation: number;
-    grant: Grant | null;
-    prices: Prices | null;
-    depends: Record<string, number> | null;
-    acceptedBy: string;
-    acceptedAt: string;
-    endedAt: string | null;
-    endedBy: string | null;
-    endReason: string | null;
-    /** A trial's number of places (slice 3); null for a rule. */
-    limit: number | null;
-};
-/** Listed prices, in dollars per million tokens, as snapshotted. */
-export type Prices = {
-    model: {
-        in: number;
-        out: number;
-    };
-    configured: {
-        in: number;
-        out: number;
-    };
-};
-export declare function ruleById(store: Store, id: number): RuleRow | null;
-/** A project's rules a person sees: the live ones (active, paused) and, for 30 days, the ones that ended (a Not now
- * offer is not a rule and is left out). */
-export declare function rulesOf(store: Store, repo: string, now: Date): RuleRow[];
-/** Whether a project offers suggestions (its "Suggest cheaper models" switch; a project not saved here reads on). */
-export declare function suggestModelsOn(store: Store, repo: string): boolean;
-/** The configuration generations a rule for this project depends on: the installation's and the project's build and
- * repair rows. */
-export declare function dependsOf(store: Store, repo: string): Record<string, number>;
-export type Evidence = {
-    /** The newest decided records counted (at most SUGGEST_TERMS.newest), how many of them were accepted and checked. */
-    decided: number;
-    mature: number;
-    rejected: number;
-    /** Records in the window not counted, and their reasons with how many each. */
-    notCounted: number;
-    notCountedReasons: {
-        reason: NotCountedReason;
-        count: number;
-    }[];
-    total: number;
-    /** The newest decided tasks, by id, newest first. */
-    tasks: string[];
-    /** Observed median API dollars a task, over mature records priced in dollars; null below 5 such records. */
-    medianMicrousd: number | null;
-};
-/** The model's own name when the catalog knows it ("Claude Haiku 5.5"), else its id. */
-export declare function modelName(store: Store, model: string): string;
-export type Suggestion = {
-    /** `<size>:<model>:<offer>` — what the person reviews, and what accept and Not now name. */
-    id: string;
-    repo: string;
-    cohortSize: "small" | "medium";
-    provider: "claude";
-    model: string;
-    name: string;
-    configured: {
-        provider: string;
-        model: string;
-        name: string;
-    };
-    evidence: Evidence;
-    configuredEvidence: Evidence;
-    prices: Prices;
-    depends: Record<string, number>;
-    /** Three digests the offer binds: the evidence, the prices, and the configuration generations. */
-    offer: {
-        evidence: string;
-        prices: string;
-        depends: string;
-    };
-    grant: Grant;
-};
-/** What an offer for this cohort and model would say now, whether or not it qualifies: the parts its digests bind,
- * and why it doesn't qualify (null: it does). */
-export declare function offerNow(store: Store, repo: string, size: "small" | "medium", model: string, now: Date): {
-    suggestion: Suggestion | null;
-    why: string | null;
-    parts: Suggestion["offer"] | null;
-};
-/** A suggestion id read back: its cohort, model and the three digest prefixes it was offered under. */
-export declare function readSuggestionId(id: string): {
-    size: "small" | "medium";
-    model: string;
-    evidence: string;
-    prices: string;
-    depends: string;
-} | null;
-/**
- * The suggestions a project offers now: per size (small, routine), the cheapest Claude model whose records here earn
- * it, unless a rule for that size is live, the project's switch is off, or a person said Not now within 30 days.
- */
-export declare function suggestionsFor(store: Store, repo: string, now: Date): Suggestion[];
-/** A suggestion in plain words, the evidence first. */
-export declare function suggestionWords(suggestion: Suggestion): string;
-export type RuleRefusal = {
-    ok: false;
-    reason: RuleRefusalReason | "stale-suggestion" | "price-changed" | "config-changed" | "invalid" | "taken" | "not-found" | "unknown-project";
-    problem: string;
-};
-/**
- * Accept a suggestion as a rule, in one transaction: the person re-proved; the offer still earned, at the same
- * prices and on the same configuration generations it was offered under; the configuration valid with the rule
- * added (checkScope); and the size's one winner free. A refusal names which: `stale-suggestion`, `price-changed`,
- * `config-changed`, `invalid` or `taken`.
- */
-export declare function acceptSuggestion(store: Store, input: {
-    repo: string;
-    id: string;
-}, door: RuleDoor, now: Date): {
-    ok: true;
-    rule: number;
-    suggestion: Suggestion;
-} | RuleRefusal;
-/** Turn a live rule off, or drop a paused one. Tasks already approved keep the model they were approved with. */
-export declare function turnOffRule(store: Store, ruleId: number, door: RuleDoor, now: Date): {
-    ok: true;
-    rule: RuleRow;
-} | RuleRefusal;
-/** Keep a paused rule: live again on the configuration as it stands, if that configuration can run it. */
-export declare function keepRule(store: Store, ruleId: number, door: RuleDoor, now: Date): {
-    ok: true;
-    rule: RuleRow;
-} | RuleRefusal;
-/** Not now: the suggestion stays quiet for 30 days. */
-export declare function dismissSuggestion(store: Store, input: {
-    repo: string;
-    id: string;
-}, door: RuleDoor, now: Date): {
-    ok: true;
-} | RuleRefusal;
-/** A project's "Suggest cheaper models" switch: on takes a person's step-up, off also the local owner. */
-export declare function setSuggestModels(store: Store, repo: string, on: boolean, door: RuleDoor): {
-    ok: true;
-} | RuleRefusal;
-export type TripResult = {
-    trips: false;
-} | {
-    trips: true;
-    why: string;
-};
-/** Whether a grant's sealed terms trip on these decided records (newest first) and closed exposures (newest first,
- * true = approved with another model). Pure. Pending and provisional records are never passed in. */
-export declare function tripOf(grant: Grant, decided: readonly ("mature" | "rejected")[], exposures: readonly boolean[]): TripResult;
-export type SwitchOffOutcome = "kept" | "switched-off" | "paused" | "expired" | "moved";
-/**
- * One rule's check, as ONE transaction: re-read the rule and its generation; any configuration generation it depends
- * on that moved pauses it (never a switch-off on terms it no longer has); an ended grant ends it, a grant sealed under
- * another policy or by an account that's gone pauses it; then the trigger, recomputed from records with the sealed
- * terms, switches it off by compare-and-swap on its generation — and the configuration is checked without it, or the
- * switch-off rolls back and the rule pauses instead.
- */
-export declare function switchOffIfTripped(store: Store, ruleId: number, now: Date): {
-    outcome: SwitchOffOutcome;
-    why: string | null;
-};
-/** Hold a task approved under a rule that switched itself off: nothing starts on it (no strike: nothing ran) until a
- * person approves it again — the hold goes with that yes (store.ts sealScopeApproval). */
-export declare function holdRuleOff(store: Store, taskRef: number, taskId: string, model: string, now: Date): void;
-/**
- * The reconcile pass's routing step (operate.ts, after the records are evaluated again): each live rule checked
- * against its sealed terms; Needs you told about a rule that switched off, paused or ends soon; tasks approved under a
- * switched-off rule held, with their plans re-filed on the configured builder so a person can approve them again; and
- * plans still waiting for approval under a rule that is no longer live re-filed the same way. Each task is its own
- * transaction; one that can't be re-filed now (a live claim) is tried again next pass.
- */
-export declare function routeRulesPass(store: Store, repo: string, now: Date): {
-    switchedOff: number;
-    paused: number;
-    held: number;
-    refiled: number;
-};
-/**
- * The evidence line beside a route whose build leg an earned rule selected (approval sheet, approval step, chat side
- * panel, text card), or null for any other route. The selection is sealed; the counts read "so far", from the
- * records as they stand.
- */
-export declare function selectionEvidenceWords(store: Store, route: PhaseRoute | null, now: Date): string | null;
-/** The evidence line for a task's proposed (or, once approved, sealed) route. */
-export declare function taskEvidenceWords(store: Store, taskId: string, now: Date): string | null;
-/** A rule in words for Settings and the command line. */
-export declare function ruleWords(store: Store, rule: RuleRow): string;
-/** When to offer a trial (docs/plans/results-routing.md, "Trials"): the configured Claude builder of a cohort has at
- * least 10 decided records here at ≥ 90% accepted with checks passing, and a cheaper Claude model has too few results
- * here to be suggested on its own. A trial tries it on the next 10 eligible tasks, each approved by a person. */
-export declare const TRIAL_TERMS: Readonly<{
-    places: 10;
-    configuredMinDecided: 10;
-    configuredMinMature: 0.9;
-    days: 90;
-}>;
-export type TrialOffer = {
-    /** `trial:<size>:<model>:<offer>` — what the person starts, and what Not now names. */
-    id: string;
-    repo: string;
-    cohortSize: "small" | "medium";
-    provider: "claude";
-    model: string;
-    name: string;
-    configured: {
-        provider: string;
-        model: string;
-        name: string;
-    };
-    evidence: Evidence;
-    configuredEvidence: Evidence;
-    prices: Prices;
-    depends: Record<string, number>;
-    places: number;
-    offer: {
-        evidence: string;
-        prices: string;
-        depends: string;
-    };
-};
-/** A trial offer's id read back: its cohort, model and the three digest prefixes it was offered under. */
-export declare function readTrialOfferId(id: string): {
-    size: "small" | "medium";
-    model: string;
-    evidence: string;
-    prices: string;
-    depends: string;
-} | null;
-/** What a trial offer for this cohort and model would say now, whether or not it qualifies: the parts its digests
- * bind, and why it doesn't qualify (null: it does). */
-export declare function trialOfferNow(store: Store, repo: string, size: "small" | "medium", model: string, now: Date): {
-    offer: TrialOffer | null;
-    why: string | null;
-    parts: TrialOffer["offer"] | null;
-};
-/**
- * The trials a project offers now: per size, where nothing is suggested (a suggestion has enough evidence to stand on
- * its own) and no rule or trial is live, the closest cheaper Claude model the catalog lists now (the dearest of those
- * cheaper on both prices, then the newest), unless the project's switch is off or a person said Not now to it.
- */
-export declare function trialOffersFor(store: Store, repo: string, now: Date): TrialOffer[];
-/** A trial offer in plain words, the evidence first. */
-export declare function trialOfferWords(offer: TrialOffer): string;
-/** A project's trials a person sees: live (trialling, paused) and, for 30 days, the ones that ended. */
-export declare function trialsOf(store: Store, repo: string, now: Date): RuleRow[];
-/**
- * Start a trial, in one transaction: the person re-proved (a step-up); the offer still standing, at the same prices
- * and on the same configuration generations it was offered under, with its eligibility re-checked now (a stale
- * offer refuses); the configuration valid with the trial's builder added (checkScope: repairs resume its session);
- * and the size's one winner free (concurrent starts: one wins). A refusal names which.
- */
-export declare function startTrial(store: Store, input: {
-    repo: string;
-    id: string;
-}, door: RuleDoor, now: Date): {
-    ok: true;
-    trial: number;
-    offer: TrialOffer;
-} | RuleRefusal;
-/** Stop a live or paused trial. Plans waiting on it are re-filed on the configured builder; tasks a person already
- * approved on it keep that model. */
-export declare function stopTrial(store: Store, trialId: number, door: RuleDoor, now: Date): {
-    ok: true;
-    trial: RuleRow;
-} | RuleRefusal;
-/** A trial's progress in words, as Settings, the command line and chat say it. */
-export declare function trialWords(store: Store, trial: RuleRow): string;
-/** The project's live trial for a size, as Settings reads it (null when none). */
-export declare function liveTrialOf(store: Store, repo: string, size: "small" | "medium"): RuleRow | null;

package/dist/route-savings.d.ts

@@ -1,136 +0,0 @@
-/**
- * What earned rules and trials observed (docs/plans/results-routing.md, slice 4): the Spend page's "Suggestions and
- * rules" block and the matching lines of `toolroll spend [--json]`. Read-only: it reads saved result records and rules,
- * and never suggests, accepts, routes or switches anything.
- *
- * For each project and size, each live or recently ended rule or trial (and each standing suggestion) compares two
- * sides over matched 90-day windows:
- * - a rule or trial: the configured model's results in the 90 days before it was accepted, against the results built
- *   under that rule or trial (their sealed selection names it) in the 90 days from acceptance, to its end or now;
- * - a suggestion: the configured model's results and the cheaper model's, over the same last 90 days.
- *
- * Cost rules (item 10): API dollars, plan usage and unknown cost are kept apart and never added together. The median is
- * of API dollars a task over results priced wholly in API dollars, with "API-priced N of M" beside it; it is hidden
- * (null, shown "—") unless each side has at least 5 such results. A result's spending includes its revision and repair
- * runs (remediation). Prices are the snapshot sealed at acceptance (a suggestion's are the listed prices now). Unknown
- * is never $0. The label is "observed, not a promise".
- */
-import { type Prices } from "./route-rules.js";
-import type { Store } from "./store.js";
-/** The window on each side, the priced results each side needs before a median shows, and when an open result's
- * last evaluation reads as stale. */
-export declare const SAVINGS_TERMS: Readonly<{
-    windowDays: 90;
-    minPriced: 5;
-    staleAfterHours: 24;
-}>;
-export declare const SAVINGS_LABEL = "observed, not a promise";
-/** One result record as this view reads it. */
-export type SavingsRecord = {
-    state: string;
-    firstStartedAt: string;
-    apiMicrousd: number;
-    subscriptionRuns: number;
-    subscriptionTokens: number;
-    unknownRuns: number;
-    remediationRuns: number;
-    closed: boolean;
-    evaluatedAt: string;
-};
-/** One side of a comparison. Every amount kind is counted on its own. */
-export type SavingsSide = {
-    provider: string;
-    model: string | null;
-    name: string;
-    /** The window, [from, to). */
-    from: string;
-    to: string;
-    /** Results with an answer (accepted and waiting, counted, counted against); pending and not counted ones apart. */
-    results: number;
-    mature: number;
-    rejected: number;
-    provisional: number;
-    pending: number;
-    notCounted: number;
-    /** Results whose every run was priced in API dollars, and their median API dollars a task (null: hidden). */
-    apiPriced: number;
-    medianApiMicrousd: number | null;
-    /** Results with work on a plan (usage, not billed), with their runs and tokens. */
-    planResults: number;
-    planRuns: number;
-    planTokens: number;
-    /** Results with a run whose cost is unknown, and how many runs. Never $0. */
-    unknownResults: number;
-    unknownRuns: number;
-    /** Revision and repair runs, whose spending is included in their results'. */
-    remediationRuns: number;
-};
-export type SavingsKind = "rule" | "trial" | "suggestion";
-export type SavingsRow = {
-    kind: SavingsKind;
-    id: string;
-    repo: string;
-    project: string;
-    size: "small" | "medium";
-    state: string;
-    status: string;
-    /** The configured model's side (before, for a rule or trial) and the cheaper model's (after). */
-    configured: SavingsSide;
-    cheaper: SavingsSide;
-    /** Both sides have at least SAVINGS_TERMS.minPriced API-priced results, so the medians show. */
-    enough: boolean;
-    prices: Prices | null;
-    pricesFrom: "accepted" | "listed-now";
-    words: string[];
-};
-export type SavingsReport = {
-    label: typeof SAVINGS_LABEL;
-    windowDays: number;
-    minPriced: number;
-    rows: SavingsRow[];
-    /** The oldest last evaluation of an open result shown, when it is older than SAVINGS_TERMS.staleAfterHours. */
-    staleSince: string | null;
-};
-/** Whether a result was priced wholly in API dollars: no plan run, no unknown run, and a recorded charge. */
-export declare const apiPriced: (one: Pick<SavingsRecord, "apiMicrousd" | "subscriptionRuns" | "unknownRuns">) => boolean;
-/** The median of whole micro-dollars, rounded; null for none. */
-export declare function medianOf(values: readonly number[]): number | null;
-/** One side's figures from its records. The median is computed here, and hidden by `compare` when either side is short. */
-export declare function sideOf(who: {
-    provider: string;
-    model: string | null;
-    name: string;
-}, window: {
-    from: string;
-    to: string;
-}, records: readonly SavingsRecord[]): SavingsSide;
-/** Two sides compared: both medians show only when each side has enough API-priced results; otherwise neither does. */
-export declare function compare(configured: SavingsSide, cheaper: SavingsSide): {
-    configured: SavingsSide;
-    cheaper: SavingsSide;
-    enough: boolean;
-};
-/** Dollars a task: under a cent reads "<$0.01", never a false $0. */
-export declare const dollars: (microusd: number) => string;
-/** A side's figures in words: the median (or —), then API-priced, plan usage and unknown cost, each apart. */
-export declare function sideWords(side: SavingsSide): {
-    median: string;
-    parts: string[];
-};
-/** The listed prices in words, per million tokens. */
-export declare function pricesWords(row: Pick<SavingsRow, "prices" | "pricesFrom" | "configured" | "cheaper">): string;
-/** What not having enough priced results means, in words. */
-export declare function notEnoughWords(row: Pick<SavingsRow, "configured" | "cheaper">): string;
-export declare const statusWords: (state: string) => string;
-/** The row's own lines, as the command line prints them. */
-export declare function rowLines(row: SavingsRow): string[];
-/** The spend report's lines for this block: a heading and each row, or one line when there is nothing yet. */
-export declare function savingsLines(report: SavingsReport | {
-    error: string;
-}): string[];
-/** The block for these projects, by project then size. */
-export declare function savingsReport(store: Store, repos: readonly string[], now: Date): SavingsReport;
-/** The block, or that it can't be read: an unreadable block never fails the Spend page or `toolroll spend`. */
-export declare function savingsReportOrError(store: Store, repos: readonly string[], now: Date): SavingsReport | {
-    error: string;
-};