bareloop 0.40.0 → 0.42.0

package/types/providerrows.d.ts

@@ -7,26 +7,26 @@
  */
 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.
+ * The model lines of a row, pure (no I/O, no rewrite of the file). A row WITH `models.<ENV>` uses
+ * that list and ignores `keys.<ENV>.{name,priceInPerM,priceOutPerM}`. A row WITHOUT it whose
+ * `keys.<ENV>.name` is a non-empty saved string reads as ONE line: ticked when BOTH older prices
+ * are finite numbers >= 0 (the line carries them), else UNTICKED with no price (a ticked line
+ * needs both prices). A row with no saved name reads as no lines — nothing is carried from a
+ * built-in table.
  * @param {string} envName
- * @returns {{ name: string, shape: string, baseUrl: string }}
+ * @param {Record<string, any>} config
+ * @returns {ModelLine[]}
  */
-export function defaultsFor(envName: string): {
-    name: string;
-    shape: string;
-    baseUrl: string;
-};
+export function effectiveModels(envName: string, config: Record<string, any>): ModelLine[];
 /**
- * @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)
- * @property {unknown} [priceInPerM] the customer's own price, USD per 1M input tokens — carried RAW
- *   (present only when the config row names it); {@link ratesFor} is the one place that validates it
- * @property {unknown} [priceOutPerM] the same, for output tokens
+ * Every ticked-and-priced line of the rows, in keys-file order.
+ * @param {readonly KeyRow[]} rows
+ * @returns {{ row: KeyRow, line: ModelLine }[]}
  */
+export function tickedLines(rows: readonly KeyRow[]): {
+    row: KeyRow;
+    line: ModelLine;
+}[];
 /**
  * The rows: one per name in `filled`, saved entry over defaults.
  * @param {{ filled: readonly string[], config: Record<string, any> }} src
@@ -37,20 +37,33 @@ export function keyRows({ filled, config }: {
     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.
+ * The key names that make rows: every key in the keys file with a value (file order), plus — when `env` is given — a key only the
+ * SHELL holds that config already names (`keys.<ENV>` or `models.<ENV>`), sorted after them. The page shows such a row as
+ * "found in shell"; the run path must resolve it the same way.
+ * @param {readonly string[]} filled the keys file's filled names
+ * @param {Record<string, any>} config
+ * @param {Record<string, string|undefined>} [env] the shell side
+ * @returns {string[]}
+ */
+export function rowNamesOf(filled: readonly string[], config: Record<string, any>, env?: Record<string, string | undefined>): string[];
+/**
+ * The rows for a keys home. `undefined` home (a door that skipped the keys file) = no rows. With `env`, a shell-only key that
+ * config names is a row too ({@link rowNamesOf}).
  * @param {string|undefined} home
+ * @param {Record<string, string|undefined>} [env]
  * @returns {KeyRow[]}
  */
-export function rowsForHome(home: string | undefined): KeyRow[];
+export function rowsForHome(home: string | undefined, env?: Record<string, string | undefined>): KeyRow[];
 /**
- * @param {string} provider
- * @returns {string} the shape's default host ('' = the vendor's own)
+ * EVERY row a config home names, keyed or not: the keys file's filled names plus every name `keys.<ENV>` / `models.<ENV>` carries. For
+ * a readout that must say which variable a model line WOULD read ("KEY is not set in this shell") before any key exists. Never for a run.
+ * @param {string|undefined} home
+ * @returns {KeyRow[]}
  */
-export function defaultUrlOf(provider: string): string;
+export function namedRowsForHome(home: string | undefined): KeyRow[];
 /**
- * An endpoint in comparable form: blank = the shape's default host; scheme + host lower-cased,
- * trailing slashes dropped.
+ * An endpoint in comparable form: scheme + host lower-cased, trailing slashes dropped. A blank
+ * Base URL is blank — there is no default host.
  * @param {string} provider
  * @param {string|null|undefined} baseUrl
  * @returns {string}
@@ -58,8 +71,7 @@ export function defaultUrlOf(provider: string): string;
 export function endpointOf(provider: string, baseUrl: string | null | undefined): string;
 /**
  * A job's provider in plain words for a refusal line: the host its Base URL points at (else the
- * shape's own default host, else the shape's label), plus the model when the spec names one.
- * Never a key, a path or a status code.
+ * shape's label), plus the model when the spec names one. Never a key, a path or a status code.
  * @param {{provider?: string, baseUrl?: string|null, model?: string|null}} spec
  * @returns {string}
  */
@@ -68,15 +80,10 @@ export function providerInWords(spec: {
     baseUrl?: string | null;
     model?: string | null;
 }): 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.
+ * endpoint; when several share it, the one that HAS a ticked-and-priced line for `model`, else
+ * the first.
  * @param {readonly KeyRow[]} rows
  * @param {{ provider?: string|null, baseUrl?: string|null, model?: string|null }} id
  * @returns {KeyRow|null}
@@ -87,56 +94,97 @@ export function findRow(rows: readonly KeyRow[], { provider, baseUrl, model }: {
     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.
+ * How a Model-menu pick resolves: the row named by `provider` (its key's env name) with a ticked-and-priced line for `model`.
+ * With no `provider` (an older caller) the first row ticking the model. `baseUrl` is absent when blank, exactly as a spec omits it.
+ * A model no row ticks, or a row that does not tick it, is `null` — never offered, never run.
  * @param {readonly KeyRow[]} rows
- * @param {string} model
- * @returns {{ provider: string, baseUrl?: string, envName: string, name: string }|null}
+ * @param {{ provider?: string|null, model?: string|null }} pick `provider` is the KEY's env name
+ * @returns {{ provider: string, baseUrl?: string, envName: string, name: string, legacyMaxTokens: boolean }|null}
  */
-export function modelChoiceFor(rows: readonly KeyRow[], model: string): {
+export function modelChoiceFor(rows: readonly KeyRow[], { provider, model }: {
+    provider?: string | null;
+    model?: string | null;
+}): {
     provider: string;
     baseUrl?: string;
     envName: string;
     name: string;
+    legacyMaxTokens: boolean;
 } | null;
 /**
- * The models Chat offers, in keys-file order.
+ * The lines Chat's Model menu offers: every ticked-and-priced line of the rows, in keys-file order, labelled `<KEY> · <model>`.
  * @param {readonly KeyRow[]} rows
- * @returns {{ id: string, envName: string, shape: string }[]}
+ * @returns {{ slot: string, model: string, label: string }[]}
  */
-export function chatModels(rows: readonly KeyRow[]): {
-    id: string;
-    envName: string;
-    shape: string;
+export function chatLines(rows: readonly KeyRow[]): {
+    slot: string;
+    model: string;
+    label: 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).
+ * Judge a Model-menu pick `{provider, model}` against the rows, for the doors that start a session. `ok:true` carries the choice;
+ * otherwise the plain refusal (one of the three sentences).
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider?: string|null, model?: string|null }} pick
+ * @returns {{ ok: true, choice: NonNullable<ReturnType<typeof modelChoiceFor>> } | { ok: false, say: string }}
+ */
+export function judgePick(rows: readonly KeyRow[], pick: {
+    provider?: string | null;
+    model?: string | null;
+}): {
+    ok: true;
+    choice: NonNullable<ReturnType<typeof modelChoiceFor>>;
+} | {
+    ok: false;
+    say: string;
+};
+/**
+ * Which Settings line a RUN works on. A spec's own `model` wins; a spec that names none (signed before models were required)
+ * takes `--model <id>`; a spec with no `baseUrl` (the same era) matches a row on any endpoint of its shape. `--provider <KEY>`
+ * narrows to one key when two keys tick the same id. Pure; the signed spec is never changed, so its hash is untouched.
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider?: string|null, baseUrl?: string|null, model?: string|null }} spec the signed spec's worker fields
+ * @param {{ model?: string|null, provider?: string|null }} [flags] the operator's `--model` / `--provider`
+ * @returns {{ ok: true, row: KeyRow, line: ModelLine, model: string, baseUrl: string|undefined } | { ok: false, say: string }}
+ */
+export function resolveWorker(rows: readonly KeyRow[], spec: {
+    provider?: string | null;
+    baseUrl?: string | null;
+    model?: string | null;
+}, flags?: {
+    model?: string | null;
+    provider?: string | null;
+}): {
+    ok: true;
+    row: KeyRow;
+    line: ModelLine;
+    model: string;
+    baseUrl: string | undefined;
+} | {
+    ok: false;
+    say: string;
+};
+/**
+ * The key variable NAME a job on `(provider, baseUrl[, model])` reads: the matching row's own env name. There is NO built-in
+ * name: no matching row = no key (`name: null`).
  * @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 }}
+ * @returns {{ name: string|null, chosen: boolean }}
  */
 export function keyNameFor(provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): {
-    name: string;
-    builtIn: string;
+    name: string | null;
     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.
+ * The key VALUE for a row's env name out of an env (the `null` no-key marker becomes {@link NO_KEY_PLACEHOLDER}); `undefined`
+ * when the row's variable is unset or empty.
  * @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>}
+ * @param {string|null|undefined} envName
+ * @returns {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>;
+export function keyValueOf(env: Record<string, string | undefined>, envName: string | null | undefined): string | undefined;
 /**
  * The one readout line for a resolved customer price, preview and run tail alike:
  * `yours: in $0.006 / out $1.20 per 1M tokens (DEEPSEEK_API_KEY row)`. A 0 / 0 price is accepted (the price
@@ -150,12 +198,12 @@ export function priceReadout(price: {
     envName: string;
 }): string;
 /**
- * The customer's own price for the row a `(provider, baseUrl[, model])` identity belongs to —
- * the SAME row match {@link keyNameFor} uses (`findRow`), so the price and the key always come
- * from one row. `null` = no price set (the run keeps bare-agent's built-in guess, byte-identical
- * to before). Both fields or neither, each a finite number >= 0, USD per 1M tokens; anything
- * else throws `ConfigError` naming the row and field — a bad price never silently falls back to
- * the guess. `rates` is bare-agent's `Loop({ rates })` shape (USD per 1K); `inPerM`/`outPerM`
+ * The customer's own price for the model LINE of the row a `(provider, baseUrl[, model])` identity
+ * belongs to — the SAME row match {@link keyNameFor} uses (`findRow`), so the price and the key
+ * always come from one row. With a `model`, the row's line of that name; without one, the row's
+ * first ticked line. `null` = no price set (the run keeps bare-agent's built-in guess). A line's
+ * price is a pair or nothing ({@link modelsProblem} guards the file), so a half price never
+ * reaches here. `rates` is bare-agent's `Loop({ rates })` shape (USD per 1K); `inPerM`/`outPerM`
  * are what a readout prints.
  * @param {string|null|undefined} provider
  * @param {string|null|undefined} baseUrl
@@ -173,13 +221,38 @@ export function ratesFor(provider: string | null | undefined, baseUrl: string |
     envName: string;
 } | null;
 /**
- * The price a judge's rounds are booked at. A price belongs to the MODEL's row: when the judge is
- * the worker's own provider it calls the worker's endpoint, so a row on that endpoint NAMED for the
- * judge's model prices it ({@link ratesFor}); a judge model that is absent or names no row there
- * keeps the worker's price (the worker's row, or none = the guess). A different provider resolves
- * on its own default endpoint, as before. A bad price on the resolved row throws like `ratesFor`.
- * The judge's KEY is chosen elsewhere (`applyConfiguredKey`, by the worker's model), so the two
- * can come from different rows — same provider + endpoint, judge model naming another row.
+ * A model line's own price in bare-agent's shape, or `null` when the line carries none (a price is a pair or nothing).
+ * @param {ModelLine} line
+ * @returns {{ rates: { in: number, out: number }, inPerM: number, outPerM: number }|null}
+ */
+export function ratesOfLine(line: ModelLine): {
+    rates: {
+        in: number;
+        out: number;
+    };
+    inPerM: number;
+    outPerM: number;
+} | null;
+/**
+ * The row a judge's key and endpoint come from: the worker's own row when the judge shares the worker's API shape, else the judge
+ * shape's row that ticks the judge's model (else the first row of that shape). `null` when no row is on that shape.
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider: string, model?: string|null }} judge
+ * @param {string|null|undefined} workerProvider
+ * @param {KeyRow|null} workerRow
+ * @returns {KeyRow|null}
+ */
+export function judgeRowFor(rows: readonly KeyRow[], judge: {
+    provider: string;
+    model?: string | null;
+}, workerProvider: string | null | undefined, workerRow: KeyRow | null): KeyRow | null;
+/**
+ * The price a judge's rounds are booked at. A price belongs to the MODEL's line: when the judge is
+ * the worker's own provider it calls the worker's endpoint, so a row on that endpoint with a line
+ * NAMED for the judge's model prices it ({@link ratesFor}); a judge model that is absent or names
+ * no line there keeps the worker's price (the worker's row, or none = the guess). A different
+ * provider resolves with no endpoint. The judge's KEY is chosen elsewhere (`applyConfiguredKey`,
+ * by the worker's model), so the two can come from different rows.
  * @param {{ provider: string, model?: string|null }} judge
  * @param {string|null|undefined} workerProvider
  * @param {string|null|undefined} workerBaseUrl
@@ -191,52 +264,72 @@ export function judgeRatesFor(judge: {
     provider: string;
     model?: string | null;
 }, workerProvider: string | null | undefined, workerBaseUrl: string | null | undefined, workerPrice: ReturnType<typeof ratesFor>, rows: readonly KeyRow[]): ReturnType<typeof ratesFor>;
-/** 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";
+export { SHAPES };
 /**
  * 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 = {
+export function isTickedLine(l: ModelLine): boolean;
+/** The plain sentence when a stale Chat pick names a key and a model no row ticks (fwd's wording, bareloop's seam). */
+export const REFUSE_NO_TICK: "Tick a model in Settings > Providers. Nothing was spent.";
+export const REFUSE_NO_PICK: "Pick a model. Nothing was spent.";
+export function refuseNotSetUp(key: string): string;
+/**
+ * The CLI sentence when a run names no model and the spec carries none (fwd's `pickTicked` sentence).
+ */
+export const REFUSE_NAME_MODEL: "Name the model with --model <id>: one ticked in Settings > Providers with both prices.";
+/**
+ * one model line of a row (`models.<ENV>` in config.json)
+ */
+export type ModelLine = {
     /**
-     * the key variable NAME (read-only label; never a value)
+     * the model id
+     */
+    model: string;
+    /**
+     * ticked = offered in Chat (needs both prices)
      */
+    use: boolean;
+    /**
+     * the customer's own price, USD per 1M input tokens
+     */
+    inPerM?: number | undefined;
+    /**
+     * the same, for output tokens
+     */
+    outPerM?: number | undefined;
+};
+export type PriceResult = {
+    rates: {
+        in: number;
+        out: number;
+    };
+    inPerM: number;
+    outPerM: number;
     envName: string;
+} | null;
+export type KeyRow = {
     /**
-     * the model id Chat uses ('' = not offered in Chat)
+     * the key variable NAME (read-only label; never a value)
      */
-    name: string;
+    envName: string;
     /**
      * the `src/providers.js` table entry (the API shape's id)
      */
     provider: string;
     /**
-     * the saved Base URL ('' = the shape's default host)
+     * the saved Base URL ('' = none typed yet)
      */
     baseUrl: string;
     /**
-     * the customer's own price, USD per 1M input tokens — carried RAW
-     * (present only when the config row names it); {@link ratesFor} is the one place that validates it
+     * the "old max_tokens" tick (only meaningful on `openai-api`)
      */
-    priceInPerM?: unknown;
+    legacyMaxTokens: boolean;
     /**
-     * the same, for output tokens
+     * the row's model lines
      */
-    priceOutPerM?: unknown;
+    models: ModelLine[];
 };
+import { SHAPES } from './providershapes.js';