bareloop 0.31.0 → 0.32.0

package/types/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @param {string} [home] test seam; production never passes it
+ * @returns {string} `<home>/config.json`
+ */
+export function configPath(home?: string): string;
+/**
+ * @typedef {object} ConfigRead
+ * @property {Record<string, any>} config the parsed document ({} when missing/unreadable)
+ * @property {boolean} exists
+ * @property {string|null} problem plain words when the file is there but unreadable
+ */
+/**
+ * @param {{ home?: string }} [opts]
+ * @returns {ConfigRead}
+ */
+export function readConfig(opts?: {
+    home?: string;
+}): ConfigRead;
+/**
+ * Apply a patch and write. `null` deletes a field. Top-level fields shallow-merge;
+ * `keys` merges per key variable name, then per field. Validated before anything is
+ * written; nothing is written on a refusal.
+ *
+ * Patch fields understood: `monthlyLimitUsd` (finite > 0), `anthropicBalanceNote`
+ * (finite >= 0), `keys.<ENV NAME>.{name,shape,baseUrl}` (Name = a model id, shape = a provider table name, baseUrl = blank or http(s)). Any other
+ * field is passed through untouched (kept), but the whole document is swept for
+ * secret-shaped strings first.
+ * @param {Record<string, any>} patch
+ * @param {{ home?: string }} [opts]
+ * @returns {Record<string, any>} the document as written
+ */
+export function updateConfig(patch: Record<string, any>, opts?: {
+    home?: string;
+}): Record<string, any>;
+/** A plain-words config failure (bad value, secret-shaped string, unreadable file). */
+export class ConfigError extends Error {
+}
+export type ConfigRead = {
+    /**
+     * the parsed document ({} when missing/unreadable)
+     */
+    config: Record<string, any>;
+    exists: boolean;
+    /**
+     * plain words when the file is there but unreadable
+     */
+    problem: string | null;
+};

package/types/interviewrun.d.ts

@@ -1,6 +1,7 @@
 /**
  * @typedef {object} Deps
  * @property {Record<string,string|undefined>} [env]
+ * @property {string} [keysHome] P4a — test seam: load this home's `.env` keys file even when `env` is injected.
  * @property {NodeJS.ReadStream} [stdin]
  * @property {NodeJS.WritableStream} [stdout]
  * @property {NodeJS.WritableStream} [stderr]
@@ -25,6 +26,10 @@
 export function main(argv: string[], deps?: Deps): Promise<number>;
 export type Deps = {
     env?: Record<string, string | undefined> | undefined;
+    /**
+     * P4a — test seam: load this home's `.env` keys file even when `env` is injected.
+     */
+    keysHome?: string | undefined;
     stdin?: NodeJS.ReadStream | undefined;
     stdout?: NodeJS.WritableStream | undefined;
     stderr?: NodeJS.WritableStream | undefined;

package/types/keysfile.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `~/.config/bareloop` (or the injected override) — same home every other
+ * per-person file (runs.jsonl, config.json) lives in.
+ * @param {string} [home] test seam; production never passes it
+ * @returns {string}
+ */
+export function keysHome(home?: string): string;
+/**
+ * @param {string} [home]
+ * @returns {string} `<home>/.env`
+ */
+export function keysFilePath(home?: string): string;
+/**
+ * Parse the file's text. Lines that are not `NAME=value` are skipped silently
+ * (never echoed — a malformed line may hold a secret).
+ * @param {string} text
+ * @returns {Record<string,string>}
+ */
+export function parseKeysText(text: string): Record<string, string>;
+/**
+ * The NAMES in the file that carry a non-empty value, in file order — the Providers rows
+ * (an empty preset line is not a row). Names only; a missing/unreadable file = none.
+ * @param {string} [home]
+ * @returns {string[]}
+ */
+export function filledKeyNames(home?: string): string[];
+/**
+ * Create the keys file with the five empty preset lines when — and only when — it does not
+ * exist (mode 600). An existing file is never touched.
+ * @param {readonly string[]} presetNames the names to seed, in order
+ * @param {string} [home]
+ * @returns {boolean} true if it was created
+ */
+export function ensureKeysFile(presetNames: readonly string[], home?: string): boolean;
+/**
+ * @typedef {object} KeysLoad
+ * @property {boolean} exists the file is there
+ * @property {string[]} names the NAMES the file defines (sorted; never values)
+ * @property {string|null} warning a plain-words warning (file readable by others, or
+ *   unreadable), else null — a warning, never a refusal
+ * @property {Record<string,string|undefined>} env shell env with the file filling the
+ *   names the shell does not set. THE ONLY place values leave this module.
+ */
+/**
+ * Load the keys file over an env. Missing file is fine (no names, env unchanged).
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {KeysLoad}
+ */
+export function loadKeysEnv(opts?: {
+    env?: Record<string, string | undefined>;
+    home?: string;
+}): KeysLoad;
+/**
+ * The door helper the CLI and the panel call: load the file only when the caller is
+ * on the REAL environment (no injected env) or names a keys home explicitly — so a
+ * test that injects `env` alone never reads the real `~/.config/bareloop/.env`.
+ * @param {{ env?: Record<string,string|undefined>, keysHome?: string }} deps
+ * @returns {KeysLoad & { env: Record<string,string|undefined>, home: string|undefined }}
+ *   `home` = the home the file was loaded from (the real `~/.config/bareloop` when none was
+ *   injected) — or `undefined` when loading was skipped (injected env, no keysHome). The
+ *   door passes it on so config.json (src/config.js) is read from the SAME place, and never
+ *   from the real home in a test.
+ */
+export function keysForDoor(deps: {
+    env?: Record<string, string | undefined>;
+    keysHome?: string;
+}): KeysLoad & {
+    env: Record<string, string | undefined>;
+    home: string | undefined;
+};
+export type KeysLoad = {
+    /**
+     * the file is there
+     */
+    exists: boolean;
+    /**
+     * the NAMES the file defines (sorted; never values)
+     */
+    names: string[];
+    /**
+     * a plain-words warning (file readable by others, or
+     * unreadable), else null — a warning, never a refusal
+     */
+    warning: string | null;
+    /**
+     * shell env with the file filling the
+     * names the shell does not set. THE ONLY place values leave this module.
+     */
+    env: Record<string, string | undefined>;
+};

package/types/ledger.d.ts

@@ -81,6 +81,20 @@ export function spendProvenance(events: any[]): {
     unpriced: ProvenanceBucket;
     unknown: ProvenanceBucket;
 };
+/**
+ * The priced-rounds spend floor + first-record→last-record wall floor,
+ * derived straight off the spine's raw records — the same derivation a
+ * died run's "at least …" figures use, factored out so build item 6
+ * (2026-09-28) can hand a genuinely-still-running spine the identical
+ * floor instead of "unknown" on the Run tab, without a second copy of this
+ * math.
+ * @param {any[]} records raw parsed spine records
+ * @returns {{spendFloorUsd: number|null, wallFloorMs: number|null}}
+ */
+export function floorsFromRecords(records: any[]): {
+    spendFloorUsd: number | null;
+    wallFloorMs: number | null;
+};
 /** severity order, worst-first (the fold's display order; frequency ranks within) */
 export const LEDGER_CLASSES: readonly string[];
 /**

package/types/monthly.d.ts

@@ -0,0 +1,192 @@
+/**
+ * One run's own spend, off its spine records: this LEG's figure (never the chain fold),
+ * plus the drafting spend the run was signed with (counted once — on the first leg only).
+ * @param {any[]} records
+ * @returns {{ usd: number, complete: boolean }}
+ */
+export function legSpend(records: any[]): {
+    usd: number;
+    complete: boolean;
+};
+/**
+ * One run's wall time off its spine: job-start -> job-end when the run ended (exact), else the
+ * first -> last record floor (the SAME floor a died / still-running run's "at least" wall uses,
+ * `floorsFromRecords`). `ms` null = unknown — never 0.
+ * @param {any[]} records
+ * @returns {{ ms: number|null, complete: boolean }}
+ */
+export function legWall(records: any[]): {
+    ms: number | null;
+    complete: boolean;
+};
+/**
+ * Tokens a spine's rounds processed (input + output + cache read + cache write — all four,
+ * so a cache-heavy run is not under-reported), off the real `usage` field names.
+ * @param {any[]} records
+ * @returns {number}
+ */
+export function legTokens(records: any[]): number;
+/**
+ * Every listed run as one {@link Leg}. The ONE reader the month total, the all-time total
+ * and the per-provider figures share.
+ * @param {{ home?: string, now?: () => number, resumingSpine?: string|null }} [opts] `now` = the clock for the in-flight test; `resumingSpine` = the spine a resume continues: that leg reserves its spend only, never its unspent cap (the resume's own leg cap is that remainder)
+ * @returns {Leg[]}
+ */
+export function readLegs(opts?: {
+    home?: string;
+    now?: () => number;
+    resumingSpine?: string | null;
+}): Leg[];
+/**
+ * @param {{ home?: string, now?: () => number, resumingSpine?: string|null }} [opts] `resumingSpine`: see {@link readLegs}
+ * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's)
+ */
+export function monthSpend(opts?: {
+    home?: string;
+    now?: () => number;
+    resumingSpine?: string | null;
+}): {
+    usd: number;
+    atLeast: boolean;
+    runs: number;
+    reservedUsd: number;
+};
+/**
+ * The Money tab's figures: all-time and this-month spend, and per-provider breakdown
+ * (rows from `rowIdFor`; a run on no known row lands under its own provider name, never
+ * pooled into another row). Any leg with unknown spend makes the figure it belongs to
+ * an "at least".
+ * @param {{ home?: string, now?: () => number, rows?: readonly import('./providerrows.js').KeyRow[] }} [opts] `rows` = the Providers rows: when given, `tokensByRow` sums each row's tokens
+ * @returns {{ tokensByRow: Record<string, number>, total: {usd: number, atLeast: boolean, tokens: number}, month: {usd: number, atLeast: boolean, tokens: number},
+ *   byProvider: Record<string, {label: string, monthUsd: number, monthAtLeast: boolean, totalUsd: number, totalAtLeast: boolean, tokens: number, vouchedRounds: number, otherRounds: number, monthWallMs: number|null, monthWallAtLeast: boolean, totalWallMs: number|null, totalWallAtLeast: boolean}> }}
+ */
+export function spendSummary(opts?: {
+    home?: string;
+    now?: () => number;
+    rows?: readonly import("./providerrows.js").KeyRow[];
+}): {
+    tokensByRow: Record<string, number>;
+    total: {
+        usd: number;
+        atLeast: boolean;
+        tokens: number;
+    };
+    month: {
+        usd: number;
+        atLeast: boolean;
+        tokens: number;
+    };
+    byProvider: Record<string, {
+        label: string;
+        monthUsd: number;
+        monthAtLeast: boolean;
+        totalUsd: number;
+        totalAtLeast: boolean;
+        tokens: number;
+        vouchedRounds: number;
+        otherRounds: number;
+        monthWallMs: number | null;
+        monthWallAtLeast: boolean;
+        totalWallMs: number | null;
+        totalWallAtLeast: boolean;
+    }>;
+};
+/**
+ * @typedef {object} MonthlyRoom
+ * @property {boolean} ok
+ * @property {number|null} leftUsd what is left this month (null = no limit set)
+ * @property {number|null} limitUsd the person's monthly limit (null = none)
+ * @property {boolean} atLeast the month's spend is a floor, so `leftUsd` is a ceiling
+ */
+/**
+ * The person's monthly limit off a parsed config.json: key absent (or null) = no limit (null);
+ * a number above 0 = the limit; ANY other value present is a broken setting and throws
+ * `ConfigError` — a limit the file names but this code cannot read never reads as "no limit".
+ * @param {Record<string, any>} config
+ * @param {string} [home]
+ * @returns {number|null}
+ */
+export function monthlyLimitOf(config: Record<string, any>, home?: string): number | null;
+/**
+ * Does a run with this $ cap fit in what is left this month (running jobs counted at their full cap, except the spine a resume continues — `resumingSpine` — which counts its real spend)? No limit set (key absent or null) = ok, no check; a limit that is present but not a
+ * number above 0 throws `ConfigError`.
+ * Compared in whole cents. Also throws `ConfigError` when config.json is unreadable — a gate
+ * whose own instrument is broken refuses; it never silently runs with no limit.
+ * @param {{ capUsd: number, home?: string, now?: () => number, resumingSpine?: string|null }} args
+ * @returns {MonthlyRoom}
+ */
+export function checkMonthlyRoom({ capUsd, home, now, resumingSpine }: {
+    capUsd: number;
+    home?: string;
+    now?: () => number;
+    resumingSpine?: string | null;
+}): MonthlyRoom;
+/**
+ * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal).
+ * @param {MonthlyRoom} room
+ * @returns {string|null} null when the run fits
+ */
+export function monthlyRefusalText(room: MonthlyRoom): string | null;
+export type Leg = {
+    /**
+     * when the run was listed
+     */
+    at: Date;
+    /**
+     * job-start's provider (null = an older spine that carried none)
+     */
+    provider: string | null;
+    baseUrl: string | null;
+    /**
+     * this leg's spend (a floor when `!complete`)
+     */
+    usd: number;
+    /**
+     * every figure behind `usd` is known
+     */
+    complete: boolean;
+    tokens: number;
+    /**
+     * job-start's model (older spines carry a model but no provider)
+     */
+    model: string | null;
+    /**
+     * this leg's wall time (null = unknown; a floor when `!wallComplete`)
+     */
+    wallMs: number | null;
+    /**
+     * the wall is the exact job-start -> job-end span
+     */
+    wallComplete: boolean;
+    /**
+     * rounds priced by a rate somebody vouched for (`provider`/`caller`)
+     */
+    vouchedRounds: number;
+    /**
+     * every other round: a built-in guess, unpriced, or no provenance on record
+     */
+    otherRounds: number;
+    /**
+     * what the refusal check counts: `usd`, or the leg's cap when the run is in flight
+     */
+    reservedUsd: number;
+    /**
+     * the spine was missing/unreadable or the listed date was bad (spend unknown)
+     */
+    unreadable: boolean;
+};
+export type MonthlyRoom = {
+    ok: boolean;
+    /**
+     * what is left this month (null = no limit set)
+     */
+    leftUsd: number | null;
+    /**
+     * the person's monthly limit (null = none)
+     */
+    limitUsd: number | null;
+    /**
+     * the month's spend is a floor, so `leftUsd` is a ceiling
+     */
+    atLeast: boolean;
+};

package/types/panel/authorroutes.d.ts

@@ -25,7 +25,7 @@ export function checkHumanGuard(req: import("node:http").IncomingMessage, { toke
  * deliberately has none of).
  * @param {{ port: number, token: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: typeof realSpawn, bareloopBin?: string,
- *   jobsDir?: string, fetchImpl?: typeof fetch }} opts
+ *   jobsDir?: string, fetchImpl?: typeof fetch, home?: string }} opts
  */
 export function createAuthorRoutes(opts: {
     port: number;
@@ -36,6 +36,7 @@ export function createAuthorRoutes(opts: {
     bareloopBin?: string;
     jobsDir?: string;
     fetchImpl?: typeof fetch;
+    home?: string;
 }): {
     handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
     sessions: Map<string, any>;
@@ -48,7 +49,7 @@ export function createAuthorRoutes(opts: {
  * it to sign"), and this is where it is checked, not trusted.
  * @param {ReturnType<typeof createSession>} session
  * @param {string} claimedHash
- * @param {{env: any, spawnFn: typeof realSpawn, bareloopBin: string, sessionsRoot?: string}} o
+ * @param {{env: any, spawnFn: typeof realSpawn, bareloopBin: string, sessionsRoot?: string, home?: string}} o
  * @returns {{ok: boolean, error?: string, job?: string}}
  */
 export function signRun(session: ReturnType<typeof createSession>, claimedHash: string, o: {
@@ -56,6 +57,7 @@ export function signRun(session: ReturnType<typeof createSession>, claimedHash:
     spawnFn: typeof realSpawn;
     bareloopBin: string;
     sessionsRoot?: string;
+    home?: string;
 }): {
     ok: boolean;
     error?: string;

package/types/panel/authorsession.d.ts

@@ -16,9 +16,13 @@ export function jobNameTaken(name: string, opts?: {
  * creates a session or spends anything — never inside the async pipeline,
  * so a bad card refuses synchronously, in the same HTTP response.
  * @param {any} card
+ * @param {{jobsDir?: string, rows?: readonly import('../providerrows.js').KeyRow[]}} [opts] `rows` = the Settings rows (the Model menu); jobsDir is a server-side test seam — NEVER read off the client card
  * @returns {{ok: true}|{ok: false, error: string}}
  */
-export function validateJobCard(card: any): {
+export function validateJobCard(card: any, opts?: {
+    jobsDir?: string;
+    rows?: readonly import("../providerrows.js").KeyRow[];
+}): {
     ok: true;
 } | {
     ok: false;
@@ -30,7 +34,7 @@ export function validateJobCard(card: any): {
  * is the ONE thing a person answers next; `answer()`/`send()`/`revise()`/
  * `signPrepare()` are the only ways in.
  * @param {any} card the validated job card (see {@link validateJobCard})
- * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, timeoutMs?: number,
+ * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, home?: string, timeoutMs?: number,
  *   scout?: any, generate?: Function, confirmGenerate?: Function, authorFn?: Function,
  *   prepareSigningFn?: Function}} [deps] the last five are TEST SEAMS ONLY — see the note
  *   just above where each is read, below.
@@ -39,6 +43,7 @@ export function validateJobCard(card: any): {
 export function createSession(card: any, deps?: {
     env?: Record<string, string | undefined>;
     sessionsRoot?: string;
+    home?: string;
     timeoutMs?: number;
     scout?: any;
     generate?: Function;
@@ -46,16 +51,3 @@ export function createSession(card: any, deps?: {
     authorFn?: Function;
     prepareSigningFn?: Function;
 }): any;
-/**
- * The job card's "Model" select — a fixed, small, source-grounded mapping
- * from a display id to the `{provider, baseUrl?}` pair `src/interviewrun.js`
- * itself documents (that script's own `--provider openai-api --base-url
- * https://api.deepseek.com/v1` usage line for DeepSeek): the panel builds no
- * provider table of its own, this is a UI convenience over the SAME two
- * provider identities the CLI already resolves through `resolveProvider`.
- * @type {Readonly<Record<string, {provider: string, baseUrl?: string}>>}
- */
-export const MODEL_OPTIONS: Readonly<Record<string, {
-    provider: string;
-    baseUrl?: string;
-}>>;

package/types/panel/server.d.ts

@@ -211,13 +211,14 @@ export function getRunJob(runid: string, opts?: {
  * only `createPanelServer` below always supplies one.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
- * @param {{ home?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes> }} opts
+ * @param {{ home?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes> }} opts
  */
 export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
     home?: string;
     port: number;
     token?: string;
     authorRoutes?: ReturnType<typeof createAuthorRoutes>;
+    settingsRoutes?: ReturnType<typeof createSettingsRoutes>;
 }): void;
 /**
  * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
@@ -259,13 +260,17 @@ export function createPanelServer(opts?: {
  * Never picks a different port on collision (see file header): prints a
  * loud, named error to stderr and returns 1.
  * @param {string[]} argv
- * @param {{ out: (s: string) => void, err: (s: string) => void, runlistHome?: string }} ctx
+ * @param {{ out: (s: string) => void, err: (s: string) => void, runlistHome?: string, env?: Record<string,string|undefined> }} ctx
+ *   `env` is the RAW shell env (never the start-time merge with the keys file) — the routes
+ *   re-merge `~/.config/bareloop/.env` onto it per request so Reload keys is real;
+ *   undefined = the process env.
  * @returns {Promise<number>}
  */
 export function panelMain(argv: string[], ctx: {
     out: (s: string) => void;
     err: (s: string) => void;
     runlistHome?: string;
+    env?: Record<string, string | undefined>;
 }): Promise<number>;
 /**
  * A runid, as it appears in a URL path segment — never a raw filesystem
@@ -286,10 +291,12 @@ export const DEFAULT_PORT: 4700;
  * 2026-09-25).
  */
 export const SOFTGREEN_ADMITTED_ISO: "2026-08-18T00:00:00.000Z";
-export const DIED_MTIME_MS: number;
+export { DIED_MTIME_MS };
 /** The default/max page size for {@link getRunRounds} — tighten-only,
  * named so a future change is a deliberate, visible edit (item 5,
  * 2026-09-25). */
 export const ROUNDS_PAGE_DEFAULT: 50;
 export const ROUNDS_PAGE_MAX: 200;
 import { createAuthorRoutes } from './authorroutes.js';
+import { createSettingsRoutes } from './settingsroutes.js';
+import { DIED_MTIME_MS } from '../runlist.js';

package/types/panel/settingsroutes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @param {{ port: number, token: string, home?: string, env?: Record<string,string|undefined>,
+ *   fetchImpl?: typeof fetch, now?: () => number }} opts
+ */
+export function createSettingsRoutes(opts: {
+    port: number;
+    token: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): {
+    handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
+};

package/types/providerrows.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The key value to hand a provider: the `null` marker becomes the placeholder, anything else
+ * passes through unchanged.
+ * @template {string|undefined} T
+ * @param {T} raw
+ * @returns {T|string}
+ */
+export function usableKey<T extends string | undefined>(raw: T): T | string;
+/**
+ * What a key with no saved entry shows. Any name not listed is OpenAI-compatible with a
+ * blank URL and a blank Name.
+ * @param {string} envName
+ * @returns {{ name: string, shape: string, baseUrl: string }}
+ */
+export function defaultsFor(envName: string): {
+    name: string;
+    shape: string;
+    baseUrl: string;
+};
+/**
+ * @typedef {object} KeyRow
+ * @property {string} envName the key variable NAME (read-only label; never a value)
+ * @property {string} name the model id Chat uses ('' = not offered in Chat)
+ * @property {string} provider the `src/providers.js` table entry (the API shape's id)
+ * @property {string} baseUrl the saved Base URL ('' = the shape's default host)
+ */
+/**
+ * The rows: one per name in `filled`, saved entry over defaults.
+ * @param {{ filled: readonly string[], config: Record<string, any> }} src
+ * @returns {KeyRow[]}
+ */
+export function keyRows({ filled, config }: {
+    filled: readonly string[];
+    config: Record<string, any>;
+}): KeyRow[];
+/**
+ * The rows for a keys home. `undefined` home (a door that skipped the keys file) = no
+ * rows, so nothing resolves through the file and the provider's built-in variable stands.
+ * @param {string|undefined} home
+ * @returns {KeyRow[]}
+ */
+export function rowsForHome(home: string | undefined): KeyRow[];
+/**
+ * @param {string} provider
+ * @returns {string} the shape's default host ('' = the vendor's own)
+ */
+export function defaultUrlOf(provider: string): string;
+/**
+ * An endpoint in comparable form: blank = the shape's default host; scheme + host lower-cased,
+ * trailing slashes dropped.
+ * @param {string} provider
+ * @param {string|null|undefined} baseUrl
+ * @returns {string}
+ */
+export function endpointOf(provider: string, baseUrl: string | null | undefined): string;
+/**
+ * The URL a row talks to, for display ('' = the vendor's own host, which has no URL to show).
+ * @param {KeyRow} row
+ * @returns {string}
+ */
+export function shownUrl(row: KeyRow): string;
+/**
+ * Which row a `(provider, baseUrl[, model])` identity belongs to: the rows on that shape and
+ * endpoint; when several share it, the one whose Name is the model, else the first.
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider?: string|null, baseUrl?: string|null, model?: string|null }} id
+ * @returns {KeyRow|null}
+ */
+export function findRow(rows: readonly KeyRow[], { provider, baseUrl, model }: {
+    provider?: string | null;
+    baseUrl?: string | null;
+    model?: string | null;
+}): KeyRow | null;
+/**
+ * What Chat's Model menu offers and how a pick resolves: the row whose Name is the model
+ * (a blank Name is never offered). `baseUrl` is absent when blank, exactly as a spec omits it.
+ * @param {readonly KeyRow[]} rows
+ * @param {string} model
+ * @returns {{ provider: string, baseUrl?: string, envName: string, name: string }|null}
+ */
+export function modelChoiceFor(rows: readonly KeyRow[], model: string): {
+    provider: string;
+    baseUrl?: string;
+    envName: string;
+    name: string;
+} | null;
+/**
+ * The models Chat offers, in keys-file order.
+ * @param {readonly KeyRow[]} rows
+ * @returns {{ id: string, envName: string, shape: string }[]}
+ */
+export function chatModels(rows: readonly KeyRow[]): {
+    id: string;
+    envName: string;
+    shape: string;
+}[];
+/**
+ * The key variable NAME a job on `(provider, baseUrl[, model])` reads: the matching row's
+ * variable, else the provider's built-in one (byte-identical to before for anything no row
+ * claims).
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ name: string, builtIn: string, chosen: boolean }}
+ */
+export function keyNameFor(provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): {
+    name: string;
+    builtIn: string;
+    chosen: boolean;
+};
+/**
+ * The env a door hands to provider construction, with the matching row's key variable
+ * standing in for the provider's built-in one: `env[builtIn] = env[row.envName]` (the `null`
+ * no-key marker becomes {@link NO_KEY_PLACEHOLDER}). A copy — never mutates the input.
+ * No matching row and no marker = the env unchanged.
+ * @param {Record<string,string|undefined>} env
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {Record<string,string|undefined>}
+ */
+export function applyConfiguredKey(env: Record<string, string | undefined>, provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): Record<string, string | undefined>;
+/** DeepSeek's OpenAI-shaped endpoint (the same string the panel's Model menu used). */
+export const DEEPSEEK_BASE_URL: "https://api.deepseek.com/v1";
+/**
+ * The API shapes the dropdown offers. `id` is the `src/providers.js` table name;
+ * `defaultUrl` is the host a blank Base URL means ('' = the vendor's own, unshown).
+ * @type {readonly {id: string, label: string, defaultUrl: string}[]}
+ */
+export const SHAPES: readonly {
+    id: string;
+    label: string;
+    defaultUrl: string;
+}[];
+/** The five empty lines a fresh keys file is created with, in this order. */
+export const PRESET_KEY_NAMES: readonly string[];
+/** A local server's default endpoint: Ollama's OpenAI-compatible host (LM Studio / llama.cpp: change the URL). */
+export const LOCAL_BASE_URL: "http://127.0.0.1:11434/v1";
+/**
+ * A key line whose value is the word `null` is SET and means "no real key": the row exists and
+ * the provider is handed this harmless stand-in (local servers ignore auth). It is not a
+ * secret and is never shown or logged as a key.
+ */
+export const NO_KEY_PLACEHOLDER: "no-key-needed";
+export type KeyRow = {
+    /**
+     * the key variable NAME (read-only label; never a value)
+     */
+    envName: string;
+    /**
+     * the model id Chat uses ('' = not offered in Chat)
+     */
+    name: string;
+    /**
+     * the `src/providers.js` table entry (the API shape's id)
+     */
+    provider: string;
+    /**
+     * the saved Base URL ('' = the shape's default host)
+     */
+    baseUrl: string;
+};