segreant 0.1.0 → 0.2.0

package/dist/cost/declarations.js

@@ -0,0 +1,37 @@
+import { isDemo } from '../config.js';
+import { modelNameError, PriceOverridesError, setPriceOverride } from './overrides.js';
+import { loadPricing, rateFor } from './pricing.js';
+export function declarePrice(model, input) {
+    if (isDemo())
+        throw new PriceOverridesError('Demo mode only shows sample data; run without --demo to declare a price.');
+    if (input.kind === 'like') {
+        const error = modelNameError(input.like);
+        if (error)
+            throw new PriceOverridesError(`--like: ${error}`);
+        // A declaration or family guess is insufficient: point directly at a named card entry.
+        if (!Object.values(loadPricing().providers).some((p) => Object.hasOwn(p.models, input.like))) {
+            throw new PriceOverridesError(`${input.like} is not an exact rate-card match; segreant pricing --coverage lists models seen.`);
+        }
+    }
+    return setPriceOverride(model, input);
+}
+/** Recorded guesses that are still guesses under today's card and declarations. */
+export function unknownModels(store) {
+    const recorded = store.unresolvedModels();
+    const models = new Map();
+    for (const row of recorded) {
+        const match = rateFor(row.provider, row.model).pricing.rateMatchKind;
+        if (match === 'exact_provider' || match === 'exact_cross_provider' || match === 'user_declared' || match === 'user_declared_free')
+            continue;
+        const key = JSON.stringify([row.provider, row.model]);
+        const prior = models.get(key);
+        if (prior) {
+            prior.requests += row.requests;
+            prior.costUsd += row.costUsd;
+        }
+        else {
+            models.set(key, { ...row, rateMatchKind: match });
+        }
+    }
+    return [...models.values()].sort((a, b) => b.costUsd - a.costUsd || a.provider.localeCompare(b.provider) || a.model.localeCompare(b.model));
+}

package/dist/cost/exactPricing.js

@@ -11,7 +11,7 @@
 import { addMoney, formatMoneyAmount, money } from '../economics/money.js';
 import { applyExactRate, exactRate } from '../economics/rate.js';
 const RATE_KEYS = new Set(['input', 'output', 'cache_write_5m', 'cache_write_1h', 'cache_read']);
-const USAGE_KEYS = new Set(['inputTokens', 'outputTokens', 'cacheWriteTokens', 'cacheReadTokens', 'cacheWriteTtl', 'reasoningTokens']);
+const USAGE_KEYS = new Set(['inputTokens', 'outputTokens', 'cacheWriteTokens', 'cacheReadTokens', 'cacheWriteTtl', 'cacheWriteTtlObserved', 'reasoningTokens']);
 function assertObject(value, label) {
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         throw new Error(`${label} must be an object`);
@@ -78,6 +78,9 @@ function canonicalUsage(value) {
     }
     if (value.reasoningTokens !== undefined)
         tokenCount(value.reasoningTokens, 'exact normalized usage reasoningTokens');
+    if (value.cacheWriteTtlObserved !== undefined && typeof value.cacheWriteTtlObserved !== 'boolean') {
+        throw new Error('exact normalized usage cacheWriteTtlObserved must be a boolean');
+    }
     return Object.freeze({
         inputTokens,
         outputTokens,

package/dist/cost/firstSight.js

@@ -0,0 +1,98 @@
+/**
+ * The checkpoint, not the clock: the first time Segreant prices a request by a
+ * guess (a family match or the generic fallback), it asks the public price list
+ * whether the model is known yet. A 30-day refresh left a new model at a guessed
+ * price for up to a month; claude-haiku-5-5 was in the public list while
+ * Segreant priced it at $3/$15 instead of $0.10/$0.50.
+ *
+ * The lookup never sits in a request's path: the request is recorded at its
+ * provisional price at once, and the lookup runs afterwards. When the list does
+ * know the model, recorded rows are NOT rewritten here; the user is told, and
+ * `segreant reprice` previews the correction (preview-then-commit).
+ *
+ * One lookup at a time, and none when the card was checked within the last hour
+ * (the check is a conditional GET; the list does not change faster than that).
+ */
+import { pricingStatus, rateFor } from './pricing.js';
+export const FIRST_SIGHT_MIN_INTERVAL_MS = 60 * 60 * 1000;
+const GUESSED = new Set(['family_provider', 'family_cross_provider', 'fallback']);
+/** What the refreshed card itself answers; a price the user declared meanwhile is not the list's answer (PR #146 review). */
+const CARD_EXACT = new Set(['exact_provider', 'exact_cross_provider']);
+/** Whether the card's last check of the price list is older than the interval (or never happened). */
+export function priceCheckDue(status, now = Date.now()) {
+    const when = status.lastCheckedAt ?? status.fetchedAt;
+    const ms = when === null ? NaN : Date.parse(when);
+    return !Number.isFinite(ms) || now - ms >= FIRST_SIGHT_MIN_INTERVAL_MS;
+}
+function defaultLastChecked() {
+    const st = pricingStatus();
+    const when = st.lastCheckedAt ?? st.fetchedAt;
+    const ms = when === null ? NaN : Date.parse(when);
+    return Number.isFinite(ms) ? ms : null;
+}
+export function createFirstSightWatcher(options) {
+    const now = options.now ?? Date.now;
+    const lastChecked = options.lastCheckedMs ?? defaultLastChecked;
+    const minInterval = options.minIntervalMs ?? FIRST_SIGHT_MIN_INTERVAL_MS;
+    // Models priced by a guess that no lookup has answered yet, by tuple key.
+    const pending = new Map();
+    let running = null;
+    let lastAttemptMs = null;
+    const due = () => {
+        const t = now();
+        if (lastAttemptMs !== null && t - lastAttemptMs < minInterval)
+            return false;
+        const checked = lastChecked();
+        return checked === null || t - checked >= minInterval;
+    };
+    const run = () => {
+        if (running || pending.size === 0 || !due())
+            return;
+        lastAttemptMs = now();
+        running = (async () => {
+            try {
+                const result = await options.refresh();
+                if (!result.ok) {
+                    options.onFailed?.(result.error ?? 'the price list could not be read');
+                    return;
+                }
+                // Every pending model is checked against the refreshed card, including
+                // one first seen while this lookup was running: a snapshot taken at the
+                // start left it pending for good once the card priced it exactly, since
+                // exact requests never call note() again (PR #146 review). Known or not,
+                // each has had its answer; one the list does not know is not asked about
+                // again until the next interval.
+                const answered = [...pending.values()];
+                pending.clear();
+                const learned = answered.filter(({ provider, model }) => CARD_EXACT.has(rateFor(provider, model).pricing.rateMatchKind));
+                if (learned.length > 0)
+                    options.onLearned?.(learned);
+            }
+            catch (error) {
+                options.onFailed?.(error instanceof Error ? error.message : String(error));
+            }
+            finally {
+                running = null;
+            }
+        })();
+    };
+    return {
+        note(provider, model, rateMatchKind) {
+            try {
+                if (!GUESSED.has(rateMatchKind) || !options.enabled())
+                    return;
+                const key = JSON.stringify([provider, model]);
+                if (!pending.has(key))
+                    pending.set(key, { provider, model });
+                run();
+            }
+            catch {
+                // A sighting must never break the request that caused it.
+            }
+        },
+        async idle() {
+            while (running)
+                await running;
+        },
+    };
+}

package/dist/cost/overrides.js

@@ -0,0 +1,230 @@
+/**
+ * Prices the user declared for models no rate card knows: a private or
+ * fine-tuned model, a local model that costs nothing, or a new model the public
+ * price list has not caught up with yet. A declaration is the user's claim, not
+ * a published list price, so it is recorded under its own basis
+ * (`user_declared_price`) and never mixed into "list cost".
+ *
+ * Three forms:
+ * - `rate`: decimal USD per 1M tokens, the same units as the rate card;
+ * - `like`: price this model at another model's rate on the current card;
+ * - `free`: a local model; every request costs zero.
+ *
+ * The file is written only by `setPriceOverride` (validated, atomic). A hand
+ * edit that breaks it is refused with the reason, never half-read: a price that
+ * silently disappeared would change what a cap counts.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { acquireConfigMutationLock, DemoReadOnlyError, isDemo, segreantHome } from '../config.js';
+export class PriceOverridesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PriceOverridesError';
+    }
+}
+/** A plain non-negative decimal with at most 12 places, e.g. "0.1" or "15". */
+const DECIMAL = /^(0|[1-9]\d{0,6})(\.\d{1,12})?$/;
+const MODEL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,199}$/;
+const MAX_MODELS = 500;
+export function overridesPath() {
+    return join(segreantHome(), 'pricing', 'overrides.json');
+}
+function validDecimal(value, positive) {
+    if (typeof value !== 'string' || !DECIMAL.test(value))
+        return false;
+    return !positive || Number(value) > 0;
+}
+/** The reason a model name cannot carry a declared price, or null. */
+export function modelNameError(model) {
+    if (typeof model !== 'string' || !MODEL_NAME.test(model)) {
+        return 'model names are 1-200 characters: letters, digits and . _ : @ / + -, starting with a letter or digit';
+    }
+    if (model === '__proto__' || model === 'constructor' || model === 'prototype')
+        return 'that model name is reserved';
+    return null;
+}
+function overrideError(model, raw, requireDeclaredAt) {
+    const nameError = modelNameError(model);
+    if (nameError)
+        return `${JSON.stringify(model)}: ${nameError}`;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return `${model}: must be an object`;
+    const o = raw;
+    if (requireDeclaredAt && (typeof o['declaredAt'] !== 'string' || Number.isNaN(Date.parse(o['declaredAt'])))) {
+        return `${model}: declaredAt must be a timestamp`;
+    }
+    const allowed = new Set(['kind', 'declaredAt']);
+    switch (o['kind']) {
+        case 'rate':
+            for (const k of ['input', 'output', 'cacheRead', 'cacheWrite', 'cacheWrite1h'])
+                allowed.add(k);
+            // Input and output must be positive: a zero there is what `free` is for,
+            // and a typo'd zero would silently stop a cap from counting this model.
+            if (!validDecimal(o['input'], true))
+                return `${model}: input must be a positive decimal (USD per 1M tokens)`;
+            if (!validDecimal(o['output'], true))
+                return `${model}: output must be a positive decimal (USD per 1M tokens)`;
+            if (o['cacheRead'] !== undefined && !validDecimal(o['cacheRead'], true))
+                return `${model}: cacheRead must be a positive decimal`;
+            if (o['cacheWrite'] !== undefined && !validDecimal(o['cacheWrite'], true))
+                return `${model}: cacheWrite must be a positive decimal`;
+            if (o['cacheWrite1h'] !== undefined && !validDecimal(o['cacheWrite1h'], true))
+                return `${model}: cacheWrite1h must be a positive decimal`;
+            break;
+        case 'like':
+            allowed.add('like');
+            if (modelNameError(o['like']) !== null)
+                return `${model}: like must name another model`;
+            if (o['like'] === model)
+                return `${model}: cannot be priced like itself`;
+            break;
+        case 'free':
+            break;
+        default:
+            return `${model}: kind must be rate, like or free`;
+    }
+    for (const k of Object.keys(o))
+        if (!allowed.has(k))
+            return `${model}: unknown field ${k}`;
+    return null;
+}
+/** The first problem with a parsed overrides file, or null when it is valid. */
+export function validatePriceOverrides(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return 'the file is not a JSON object';
+    const o = raw;
+    if (o['version'] !== 1)
+        return 'version must be 1';
+    const models = o['models'];
+    if (!models || typeof models !== 'object' || Array.isArray(models))
+        return 'models must be an object';
+    const entries = Object.entries(models);
+    if (entries.length > MAX_MODELS)
+        return `at most ${MAX_MODELS} declared prices`;
+    for (const [model, entry] of entries) {
+        const error = overrideError(model, entry, true);
+        if (error)
+            return error;
+    }
+    return null;
+}
+let cache = null;
+/**
+ * The declared prices, re-read when the file's content changes. Throws
+ * PriceOverridesError when the file is broken or cannot be read.
+ *
+ * Only a missing file means "no declarations". A path the process cannot
+ * reach (a directory that lost search permission, an I/O error) used to read
+ * as absent, so a negotiated price silently dropped out of accounting and the
+ * cap (PR #146 review). The cache is keyed on the text itself, not on mtime and
+ * size: an edit that keeps both, such as a restored backup, is still seen.
+ */
+export function loadPriceOverrides() {
+    const path = overridesPath();
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            cache = null;
+            return { version: 1, models: {} };
+        }
+        throw new PriceOverridesError(`${path} could not be read (${error?.code ?? String(error)}); check its permissions, or remove it`);
+    }
+    if (cache && cache.path === path && cache.text === text)
+        return cache.file;
+    let parsed;
+    try {
+        parsed = JSON.parse(text.replace(/^/, ''));
+    }
+    catch {
+        throw new PriceOverridesError(`${path} is not valid JSON; fix it or remove it (segreant pricing unset <model> rewrites it)`);
+    }
+    const error = validatePriceOverrides(parsed);
+    if (error)
+        throw new PriceOverridesError(`${path}: ${error}`);
+    const file = parsed;
+    // A null-prototype copy: a model named like an Object method can never resolve to one.
+    const models = Object.create(null);
+    for (const [model, entry] of Object.entries(file.models))
+        models[model] = entry;
+    const safe = { version: 1, models };
+    cache = { path, text, file: safe };
+    return safe;
+}
+/**
+ * The declarations that price requests: none while showing sample data. The
+ * demo is advertised as isolated, so a real negotiated rate or private model
+ * name must never change or appear in it (PR #146 review).
+ */
+export function activePriceOverrides() {
+    return isDemo() ? Object.create(null) : loadPriceOverrides().models;
+}
+export function priceOverrideFor(model) {
+    return activePriceOverrides()[model] ?? null;
+}
+function writeOverrides(file) {
+    const path = overridesPath();
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    const sorted = {};
+    for (const model of Object.keys(file.models).sort())
+        sorted[model] = file.models[model];
+    // Private like the config and backups: model names and negotiated rates are
+    // not for other local users (PR #146 review). chmod covers a leftover temp
+    // file, which writeFileSync's mode would not narrow.
+    writeFileSync(tmp, `${JSON.stringify({ version: 1, models: sorted }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    cache = null;
+}
+/** Validate and store one declaration. Throws PriceOverridesError with the reason when it is not valid. */
+/**
+ * One read-modify-write at a time, across processes: two writers that each
+ * loaded the same file would otherwise both succeed while the later rename
+ * dropped the other's declaration (PR #146 review). The configuration lock is
+ * shared, so a price edit also never interleaves with a config edit; a second
+ * writer is refused with the reason rather than waiting or losing data.
+ */
+function withOverridesLock(mutate) {
+    if (isDemo())
+        throw new DemoReadOnlyError();
+    const lock = acquireConfigMutationLock();
+    try {
+        cache = null;
+        return mutate();
+    }
+    finally {
+        lock.release();
+    }
+}
+export function setPriceOverride(model, input, now = new Date()) {
+    const declared = { ...input, declaredAt: now.toISOString() };
+    const error = overrideError(model, declared, true);
+    if (error)
+        throw new PriceOverridesError(error);
+    return withOverridesLock(() => {
+        const file = loadPriceOverrides();
+        const models = { ...file.models, [model]: declared };
+        if (Object.keys(models).length > MAX_MODELS)
+            throw new PriceOverridesError(`at most ${MAX_MODELS} declared prices`);
+        writeOverrides({ version: 1, models });
+        return declared;
+    });
+}
+/** Remove a declaration. Returns false when there was none. */
+export function removePriceOverride(model) {
+    return withOverridesLock(() => {
+        const file = loadPriceOverrides();
+        if (!(model in file.models))
+            return false;
+        const models = {};
+        for (const [name, entry] of Object.entries(file.models))
+            if (name !== model)
+                models[name] = entry;
+        writeOverrides({ version: 1, models });
+        return true;
+    });
+}