toolroll 0.9.93 → 0.9.95

package/dist/fallback.d.ts

@@ -0,0 +1,138 @@
+import { type ChainEntry, type ExecutionProfile, type Scope } from "./scope.js";
+import type { Store } from "./store.js";
+export declare const MAX_FALLBACK_ENTRIES = 3;
+/** What a project's setting names: the rest of each entry's terms resolve at filing and seal with the approval. */
+export type FallbackEntry = {
+    provider: string;
+    model: string;
+    authMode: "subscription" | "api-key";
+};
+export type FallbackSetting = {
+    repo: string;
+    entries: FallbackEntry[];
+    paidGrant: {
+        by: string;
+        at: string;
+    } | null;
+    updatedBy: string;
+    updatedAt: string;
+};
+export declare function entryDigestOf(entry: ChainEntry): string;
+/** An entry in the words every surface uses. */
+export declare function entryWords(entry: FallbackEntry): string;
+/** Whether Toolroll can see this entry run out, in plain words: an entry it can't recognise ends the chain there. */
+export declare function entryMovesOnWords(entry: Pick<FallbackEntry, "provider" | "authMode">): string;
+/** Whether this entry spends money, by what it was pinned to: an API key, or a provider that only bills by use. A plan
+ * entry is never paid: where its login can't be proved to be that plan, it doesn't run (invoke.ts), it is never
+ * reinterpreted as a paid agent. */
+export declare function entryPaid(_store: Store, entry: Pick<FallbackEntry, "provider" | "authMode">): boolean;
+/** Parse `provider:model:plan|api-key`. The model is everything between the first and last colon, so ":free" ids work. */
+export declare function parseEntry(text: string): FallbackEntry | string;
+export declare function entriesProblem(entries: readonly FallbackEntry[]): string | null;
+export declare function fallbackSettingOf(store: Store, repo: string): FallbackSetting | null;
+export declare function setFallbackChain(store: Store, repo: string, entries: readonly FallbackEntry[], by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function clearFallbackChain(store: Store, repo: string, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/** The paid grant: the one explicit yes a paid entry spends under, read again at every money moment. */
+export declare function setPaidGrant(store: Store, repo: string, allowed: boolean, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * The chain a new scope files with: its base agent, then the project's entries. Null means no chain. A setting that can't
+ * resolve is a stated problem: the scope files unresolved in those words, and nothing runs on half a chain.
+ */
+export declare function chainForFiling(store: Store, repo: string | null, base: ExecutionProfile, baseAuth: string, lower: (profile: ExecutionProfile) => ExecutionProfile): {
+    ok: true;
+    chain: ChainEntry[] | null;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare const chainJsonOf: (chain: readonly ChainEntry[]) => string;
+/**
+ * Why this chain can't seal on this yes, or null. A paid entry takes a person's own yes: the ceremony or their chat tap,
+ * never a mode, grant, schedule, lead or automatic seal, and no machine's credential. A chat tap is bound to the scope's
+ * digest, which covers the chain, and the card shows the chain in full (chainTermsLines).
+ */
+export declare function chainSealProblem(store: Store, scope: Scope, basis: {
+    kind: string;
+} | undefined): string | null;
+/** Each tick, before any dispatch: settle every open walk. */
+export declare function reconcileWalks(store: Store, now: Date): void;
+export type FallbackDispatch = {
+    index: number;
+    entry: ChainEntry;
+    paid: boolean;
+} | {
+    problem: string;
+} | null;
+/**
+ * Which entry the next build of this task runs as, read by the tick before anything is claimed: null is the ordinary
+ * road (no chain, or the base agent). A move whose paid grant has since gone closes here and says so: nothing runs on it.
+ */
+export declare function dispatchEntryOf(store: Store, taskRef: number, taskId: string, now: Date): FallbackDispatch;
+/** A route stamp for a fallback entry, checked against the sealed chain: the admission's proof of `fallback` provenance. */
+export declare function fallbackStampProblem(store: Store, taskRef: number, taskId: string, stamp: {
+    routeDigest: string;
+    phase: string;
+    provider: string;
+    model: string | null;
+}, parentRun: number | null): string | null;
+/**
+ * Inside the run's admission transaction: bind it to its walk, or say why not (the caller rolls the row back). A base run
+ * opens a walk; a pending entry consumes its edge exactly once, with the paid grant re-read; a parked tail hands custody to
+ * its resumption; a repair inherits its parent's binding verbatim. Nothing else opens on a chain approval.
+ */
+export declare function bindRunToWalk(store: Store, runId: number, now: Date): string | null;
+/** The pinned entry a bound run spends as, or null for a run with no binding. */
+export declare function pinnedEntryOf(store: Store, runId: number): {
+    index: number;
+    entry: ChainEntry;
+} | {
+    problem: string;
+} | null;
+/**
+ * THE LAST LOOK AT THE SPAWN: one read of every authority a chain run spends under. A builder or repair on a chain
+ * approval with no binding spends nothing; a bound run must hold the walk's current place, under the live approval, as its
+ * exact entry; a paid entry must still hold the live grant. Null means go.
+ */
+export declare function chainCustodyProblem(store: Store, runId: number): string | null;
+/** Whether this finished attempt is about to move on: it holds a walk's place and the gateway classed it exhausted. */
+export declare function ranOutOnChain(store: Store, runId: number): boolean;
+/** The gateway refused this bound run: its plan login isn't proved. The walk closes, a person is told, no strike. */
+export declare function closeWalkSignedOut(store: Store, runId: number, now: Date): void;
+/**
+ * After the dispatch road finished a refused run: when it was a fallback agent refused for not being signed in to its
+ * plan, the task stops and waits for a person (task state failed, the run's reason saying why), until they retry it.
+ * Nothing expires it. True when it did.
+ */
+export declare function blockAfterSignedOut(store: Store, runId: number, now: Date): boolean;
+export type MoveResult = {
+    moved: true;
+    to: FallbackEntry;
+    paid: boolean;
+} | null;
+/**
+ * THE MOVE, inside sealFailure's transaction (the claim is already released, the run still open): only the walk's own tail,
+ * started and classed exhausted by the gateway, on the exact entry it was pinned to. Null means the ordinary failure road
+ * runs, with the walk closed in words when it can't go on. The caller finishes the run either way; a walk that moved leaves
+ * no strike.
+ */
+export declare function moveOnIfExhausted(store: Store, runId: number, taskId: string, now: Date): MoveResult;
+/**
+ * What the next agent is told about the move, for its brief. The one place the handover note plugs in: once it merges, a
+ * fallback run gets that note here. Null for any run that isn't continuing another agent's work.
+ */
+export declare function fallbackBriefFor(store: Store, runId: number): string | null;