@khorsheed/dsh-local-agent-codex 0.1.0-rc.6

package/lib/types/model-catalog.js

@@ -0,0 +1,220 @@
+/** Native app-server model/list discovery. Shared core cache owns refresh,
+ * stale data and subscriptions; this provider owns protocol and pagination. */
+import { dirname, join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { ModelDirectoryCache, modelDirectoryContextKey, delegationEnv } from '@khorsheed/dsh-local-agent';
+import { DEFAULT_DISPOSE_GRACE_MS } from './codex-cli-provider.js';
+/** Default overall bound for one catalog probe (spawn → model/list answer). */
+export const DEFAULT_CATALOG_PROBE_TIMEOUT_MS = 5_000;
+/** Default lifetime of a completed probe's cached answer, per scoped home. */
+export const DEFAULT_CATALOG_TTL_MS = 5 * 60_000;
+/** Grace between stdin EOF and terminate when the probe tears the process down. */
+const PROBE_EOF_GRACE_MS = 1_000;
+/** Preserve native metadata, including hidden candidates; reject malformed pages. */
+function catalogEntries(result) {
+    const page = result;
+    if (!Array.isArray(page?.data))
+        throw new Error('model/list returned no model array');
+    const entries = [];
+    let defaultModel;
+    for (const entry of page.data) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        const raw = typeof record['id'] === 'string' ? record['id'] : record['model'];
+        const value = typeof raw === 'string' ? raw.trim() : '';
+        if (value === '')
+            continue;
+        if (record['isDefault'] === true && defaultModel === undefined)
+            defaultModel = value;
+        const nativeEfforts = record['supportedReasoningEfforts'];
+        const options = Array.isArray(nativeEfforts) ? nativeEfforts.flatMap(option => {
+            if (typeof option !== 'object' || option === null)
+                return [];
+            const effort = option;
+            const choice = effort['reasoningEffort'];
+            if (typeof choice !== 'string' || choice === '')
+                return [];
+            return [{ value: choice, label: choice, ...typeof effort['description'] === 'string' ? { description: effort['description'] } : {} }];
+        }) : undefined;
+        const defaultEffort = record['defaultReasoningEffort'];
+        entries.push({
+            value, label: typeof record['displayName'] === 'string' ? record['displayName'] : value,
+            source: 'native', hidden: record['hidden'] === true,
+            ...typeof record['description'] === 'string' ? { description: record['description'] } : {},
+            ...options === undefined ? {} : { reasoning: { options, ...typeof defaultEffort === 'string' ? { default: defaultEffort } : {} } },
+        });
+    }
+    return {
+        entries, ...defaultModel === undefined ? {} : { defaultModel },
+        ...typeof page.nextCursor === 'string' && page.nextCursor !== '' ? { nextCursor: page.nextCursor } : {},
+    };
+}
+/** Synchronous compatibility reads plus a rich, subscribable directory. */
+export class CodexModelCatalog {
+    deps;
+    timeoutMs;
+    cache;
+    constructor(deps) {
+        this.deps = deps;
+        this.timeoutMs = deps.timeoutMs ?? DEFAULT_CATALOG_PROBE_TIMEOUT_MS;
+        this.cache = new ModelDirectoryCache({
+            load: (key, signal) => {
+                const context = JSON.parse(key);
+                return this.probe(context.homeDir, context.cwd, signal);
+            },
+            ttlMs: deps.ttlMs ?? DEFAULT_CATALOG_TTL_MS,
+            ...deps.now === undefined ? {} : { now: deps.now },
+            onError: error => deps.warn?.(`local-agent-codex: the model catalog probe degraded: ${error instanceof Error ? error.message : String(error)}`),
+        });
+    }
+    key(homeDir, cwd = homeDir) {
+        const files = [join(homeDir, 'config.toml'), join(homeDir, 'auth.json')];
+        for (let directory = cwd;; directory = dirname(directory)) {
+            files.push(join(directory, '.codex', 'config.toml'));
+            if (dirname(directory) === directory)
+                break;
+        }
+        return modelDirectoryContextKey({ provider: 'codex', homeDir, cwd, cli: ['codex'], files });
+    }
+    read(homeDir, cwd) {
+        return this.directory(homeDir, cwd).entries.filter(entry => !entry.hidden).map(entry => entry.value);
+    }
+    readDefault(homeDir, cwd) { return this.directory(homeDir, cwd).defaultModel; }
+    directory(homeDir, cwd) { return this.cache.read(this.key(homeDir, cwd)); }
+    follow(homeDir, signal, cwd) { return this.cache.follow(() => this.key(homeDir, cwd), signal); }
+    invalidate(homeDir, cwd) { this.cache.invalidate(this.key(homeDir, cwd)); }
+    dispose() { this.cache.dispose(); }
+    async refresh(homeDir, cwd) {
+        const snapshot = await this.cache.refresh(this.key(homeDir, cwd));
+        return snapshot.entries.filter(entry => !entry.hidden).map(entry => entry.value);
+    }
+    /**
+     * One bounded probe: spawn the app-server against the scoped home, answer
+     * the initialize handshake exactly as the live driver shapes it, ask
+     * `model/list`, then tear the process down (stdin EOF → grace →
+     * terminate). The overall timeout kills the process on expiry. Failures propagate to the shared cache, which preserves prior data.
+     */
+    async probe(homeDir, cwd, signal) {
+        const spec = {
+            argv: ['codex', 'app-server', '--stdio'],
+            cwd,
+            stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' },
+            graceMs: DEFAULT_DISPOSE_GRACE_MS,
+            env: delegationEnv({ CODEX_HOME: homeDir }),
+        };
+        const child = this.deps.spawn(spec);
+        const decoder = new StringDecoder('utf8');
+        let buffer = '';
+        const pending = new Map();
+        let nextId = 0;
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            for (const request of pending.values())
+                request.reject(new Error('the model catalog probe closed'));
+            pending.clear();
+        };
+        child.stdout?.on('data', (chunk) => {
+            buffer += decoder.write(chunk);
+            let index = buffer.indexOf('\n');
+            while (index >= 0) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                index = buffer.indexOf('\n');
+                if (line.trim() === '')
+                    continue;
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const id = typeof message.id === 'number' ? message.id : undefined;
+                if (id !== undefined && typeof message.method === 'string') {
+                    // A server→client request: the probe answers nothing but errors.
+                    child.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: 'unsupported' } }) + '\n');
+                    continue;
+                }
+                if (id === undefined)
+                    continue;
+                const request = pending.get(id);
+                if (request === undefined)
+                    continue;
+                pending.delete(id);
+                const wireError = message.error;
+                if (wireError !== undefined && wireError !== null) {
+                    request.reject(new Error(wireError.message ?? 'wire error'));
+                }
+                else {
+                    request.resolve(message.result);
+                }
+            }
+        });
+        void child.done.then(finish, finish);
+        const abort = () => { finish(); child.terminate(); };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        const request = (method, params) => {
+            if (done)
+                return Promise.reject(new Error('the model catalog probe closed'));
+            nextId += 1;
+            const id = nextId;
+            return new Promise((resolve, reject) => {
+                pending.set(id, { resolve: result => resolve(result), reject });
+                child.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+            });
+        };
+        const teardown = async () => {
+            finish();
+            child.stdin?.end();
+            await Promise.race([child.done.catch(() => { }), new Promise(resolve => setTimeout(resolve, PROBE_EOF_GRACE_MS))]);
+            child.terminate();
+            await child.waitForExit().catch(() => { });
+        };
+        let timer;
+        try {
+            return await Promise.race([
+                (async () => {
+                    await request('initialize', {
+                        clientInfo: { name: 'dsh-local-agent-codex', title: 'dsh local-agent codex model catalog probe', version: '0.1.0' },
+                        capabilities: { experimentalApi: false, requestAttestation: false },
+                    });
+                    child.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method: 'initialized' }) + '\n');
+                    const entries = new Map();
+                    const cursors = new Set();
+                    let cursor;
+                    let defaultModel;
+                    do {
+                        const page = catalogEntries(await request('model/list', { includeHidden: true, ...cursor === undefined ? {} : { cursor } }));
+                        for (const entry of page.entries)
+                            if (!entries.has(entry.value))
+                                entries.set(entry.value, entry);
+                        defaultModel ??= page.defaultModel;
+                        cursor = page.nextCursor;
+                        if (cursor !== undefined) {
+                            if (cursors.has(cursor))
+                                throw new Error('model/list repeated a pagination cursor');
+                            cursors.add(cursor);
+                        }
+                    } while (cursor !== undefined);
+                    return { entries: [...entries.values()], complete: true, customInput: true, ...defaultModel === undefined ? {} : { defaultModel } };
+                })(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('the model catalog probe timed out')), this.timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            await teardown();
+        }
+    }
+}

package/lib/types/provision.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Codex scoped-home provisioning: pin file-based credential storage so the
+ * device-code login writes `auth.json` inside the scoped home. Codex's
+ * `cli_auth_credentials_store` defaults to `auto` — on macOS that resolves
+ * to the keychain, which would both leak credentials outside the scoped
+ * home and defeat the `auth.json` presence check this package's records
+ * adapter uses for authentication. An existing config is respected
+ * untouched; sign-out removes the credential file.
+ * @module @khorsheed/dsh-local-agent-codex/provision
+ */
+/**
+ * Provision `<homeDir>/config.toml` unless one already exists. A present
+ * config is respected untouched (a person may have edited it); otherwise a
+ * minimal config pinning file-based credential storage is written so login
+ * lands in the scoped home's `auth.json`.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns true when a config was written, false when one already existed.
+ */
+export declare function provisionCodexConfig(homeDir: string): Promise<boolean>;
+/**
+ * Read the scoped config's effective custom endpoint: the base_url of the
+ * `model_providers` entry named by `model_provider`, or the first custom
+ * provider's base_url when no selection exists (a user manually editing the
+ * config to route through a custom endpoint typically sets both). Only used
+ * for diagnostics — the config is authoritative and a user-edited value is
+ * respected untouched.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the configured custom base URL, or undefined when none is set.
+ */
+export declare function readCodexBaseUrl(homeDir: string): Promise<string | undefined>;
+/**
+ * Read the scoped config's effective reasoning effort: the top-level
+ * `model_reasoning_effort` key (codex reads it for reasoning-capable models).
+ * A missing or malformed config, or no key, yields undefined — the honest
+ * "unknown", never a guessed default. Read-only: the config is authoritative
+ * and a user-edited value is reported as-is. The provider passes no effort
+ * override on the argv, so this IS the value every round runs with.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the configured effort, or undefined when none is set.
+ */
+export declare function readCodexReasoningEffort(homeDir: string): Promise<string | undefined>;
+/**
+ * Read the scoped config's configured model: the top-level `model` key — the
+ * selection a plain `codex exec` round runs with. A missing or malformed
+ * config, or no key, yields undefined — the honest "unknown", never a guessed
+ * default. Read-only: the config is authoritative and a user-edited value is
+ * reported as-is.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the configured model identifier, or undefined when none is set.
+ */
+export declare function readCodexModel(homeDir: string): Promise<string | undefined>;
+/**
+ * Every model identifier the scoped config.toml itself names, deduped in file
+ * order: the top-level `model` key plus each `[profiles.<name>]` table's own
+ * `model` (a profile is how a codex config names a second model at all).
+ * `[model_providers.*]` tables are deliberately NOT collected — their keys
+ * name providers (endpoint definitions), not models, so offering one as a
+ * model choice would be a wrong suggestion, not a discovered one. Absent file
+ * or no model keys yields an empty list, never a hardcoded catalog entry.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the model identifiers the file carries.
+ */
+export declare function listCodexConfigModels(homeDir: string): Promise<string[]>;
+/**
+ * The credential file's modification stamp (epoch ms), undefined when absent.
+ * A completed device-code login rewrites `auth.json`, so the stamp
+ * distinguishes a fresh login from a leftover (possibly revoked) credential.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the marker's mtime, or undefined when no credential exists.
+ */
+export declare function codexCredentialStamp(homeDir: string): Promise<number | undefined>;
+/**
+ * Sign out of the scoped account: remove the credential file, so `/<name>
+ * status` reports not authenticated and the next login authorizes a fresh
+ * account. With `cli_auth_credentials_store = "file"` the credentials live
+ * solely in `auth.json`, so removing it is the logout path.
+ * @param homeDir - the `codex` harness's scoped home.
+ */
+export declare function codexLogout(homeDir: string): Promise<void>;
+//# sourceMappingURL=provision.d.ts.map

package/lib/types/provision.js

@@ -0,0 +1,213 @@
+/**
+ * Codex scoped-home provisioning: pin file-based credential storage so the
+ * device-code login writes `auth.json` inside the scoped home. Codex's
+ * `cli_auth_credentials_store` defaults to `auto` — on macOS that resolves
+ * to the keychain, which would both leak credentials outside the scoped
+ * home and defeat the `auth.json` presence check this package's records
+ * adapter uses for authentication. An existing config is respected
+ * untouched; sign-out removes the credential file.
+ * @module @khorsheed/dsh-local-agent-codex/provision
+ */
+import { readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Credential file inside the scoped home; its presence marks auth. */
+const AUTH_FILE = 'auth.json';
+/** Minimal scoped config: keep credentials in the scoped home. */
+const SCOPED_CONFIG = `# Written by dsh-local-agent-codex: keep the device-code
+# credentials inside the scoped home (auth.json) instead of the OS keychain.
+cli_auth_credentials_store = "file"
+`;
+/**
+ * Provision `<homeDir>/config.toml` unless one already exists. A present
+ * config is respected untouched (a person may have edited it); otherwise a
+ * minimal config pinning file-based credential storage is written so login
+ * lands in the scoped home's `auth.json`.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns true when a config was written, false when one already existed.
+ */
+export async function provisionCodexConfig(homeDir) {
+    try {
+        await readFile(join(homeDir, 'config.toml'));
+        return false;
+    }
+    catch (error) {
+        // No config yet: fall through to provisioning.
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // `wx` refuses to overwrite a config that appeared since the read check.
+    await writeFile(join(homeDir, 'config.toml'), SCOPED_CONFIG, { flag: 'wx' });
+    return true;
+}
+/**
+ * Read the scoped config's effective custom endpoint: the base_url of the
+ * `model_providers` entry named by `model_provider`, or the first custom
+ * provider's base_url when no selection exists (a user manually editing the
+ * config to route through a custom endpoint typically sets both). Only used
+ * for diagnostics — the config is authoritative and a user-edited value is
+ * respected untouched.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the configured custom base URL, or undefined when none is set.
+ */
+export async function readCodexBaseUrl(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    // Section-aware line scan: key order inside a provider table is the
+    // writer's choice, so a base_url that does not immediately follow its
+    // header must still be found — a diagnostic that silently reports the
+    // default would mislead. model_provider is a top-level key, so it only
+    // counts before the first table header.
+    let section = '';
+    let selected;
+    const providers = new Map();
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        const key = /^(\w+)\s*=\s*"([^"]*)"$/.exec(line);
+        if (key === null)
+            continue;
+        if (section === '' && key[1] === 'model_provider')
+            selected = key[2];
+        const provider = /^model_providers\.(".*"|[\w-]+)$/.exec(section);
+        if (provider !== null && key[1] === 'base_url') {
+            providers.set(provider[1].replace(/^"(.*)"$/, '$1'), key[2]);
+        }
+    }
+    if (selected !== undefined && providers.has(selected))
+        return providers.get(selected);
+    // No selection: any single custom provider is the endpoint in effect.
+    if (providers.size === 1)
+        return [...providers.values()][0];
+    return undefined;
+}
+/**
+ * Read the scoped config's effective reasoning effort: the top-level
+ * `model_reasoning_effort` key (codex reads it for reasoning-capable models).
+ * A missing or malformed config, or no key, yields undefined — the honest
+ * "unknown", never a guessed default. Read-only: the config is authoritative
+ * and a user-edited value is reported as-is. The provider passes no effort
+ * override on the argv, so this IS the value every round runs with.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the configured effort, or undefined when none is set.
+ */
+export async function readCodexReasoningEffort(homeDir) {
+    return readTopLevelConfigString(homeDir, 'model_reasoning_effort');
+}
+/**
+ * Read the scoped config's configured model: the top-level `model` key — the
+ * selection a plain `codex exec` round runs with. A missing or malformed
+ * config, or no key, yields undefined — the honest "unknown", never a guessed
+ * default. Read-only: the config is authoritative and a user-edited value is
+ * reported as-is.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the configured model identifier, or undefined when none is set.
+ */
+export async function readCodexModel(homeDir) {
+    return readTopLevelConfigString(homeDir, 'model');
+}
+/**
+ * One top-level string key from the scoped config.toml: counts only before
+ * the first table header — the same rule the model_provider scan applies.
+ * Absent file or absent key yields undefined, never a guessed default.
+ */
+async function readTopLevelConfigString(homeDir, key) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let section = '';
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        if (section !== '')
+            continue;
+        const match = /^(\w+)\s*=\s*"([^"]*)"$/.exec(line);
+        if (match !== null && match[1] === key)
+            return match[2];
+    }
+    return undefined;
+}
+/**
+ * Every model identifier the scoped config.toml itself names, deduped in file
+ * order: the top-level `model` key plus each `[profiles.<name>]` table's own
+ * `model` (a profile is how a codex config names a second model at all).
+ * `[model_providers.*]` tables are deliberately NOT collected — their keys
+ * name providers (endpoint definitions), not models, so offering one as a
+ * model choice would be a wrong suggestion, not a discovered one. Absent file
+ * or no model keys yields an empty list, never a hardcoded catalog entry.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the model identifiers the file carries.
+ */
+export async function listCodexConfigModels(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    const seen = new Set();
+    const collect = (value) => {
+        if (value === undefined || value.trim() === '' || seen.has(value))
+            return;
+        seen.add(value);
+        found.push(value);
+    };
+    let section = '';
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        const match = /^(\w+)\s*=\s*"([^"]*)"$/.exec(line);
+        if (match === null || match[1] !== 'model')
+            continue;
+        if (section === '' || section.startsWith('profiles.'))
+            collect(match[2]);
+    }
+    return found;
+}
+/**
+ * The credential file's modification stamp (epoch ms), undefined when absent.
+ * A completed device-code login rewrites `auth.json`, so the stamp
+ * distinguishes a fresh login from a leftover (possibly revoked) credential.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the marker's mtime, or undefined when no credential exists.
+ */
+export async function codexCredentialStamp(homeDir) {
+    try {
+        return (await stat(join(homeDir, AUTH_FILE))).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Sign out of the scoped account: remove the credential file, so `/<name>
+ * status` reports not authenticated and the next login authorizes a fresh
+ * account. With `cli_auth_credentials_store = "file"` the credentials live
+ * solely in `auth.json`, so removing it is the logout path.
+ * @param homeDir - the `codex` harness's scoped home.
+ */
+export async function codexLogout(homeDir) {
+    await rm(join(homeDir, AUTH_FILE), { force: true });
+}

package/lib/types/records.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Codex session records adapter: scans the scoped home's `sessions/`
+ * rollout files (one JSONL per session under `sessions/YYYY/MM/DD/`).
+ * The LISTING reads only the head of each file — the first `session_meta`
+ * line carries the id, cwd, and started-at timestamp it needs. The READ-BACK
+ * path ({@link codexRolloutRoundFacts}) instead locates one run's file (by
+ * thread id, working directory, or a time window) and reads that round's
+ * usage, model, and codex build out of it — the facts the exec `--json` wire
+ * either omits entirely (the model) or drops on a non-completed round (the
+ * usage). Files are treated as append-only with torn-tail tolerance, and
+ * contents are always untrusted input.
+ * @module @khorsheed/dsh-local-agent-codex/records
+ */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { LocalAgentSessionRecord } from '@khorsheed/dsh-local-agent';
+/**
+ * Whether the scoped home holds usable Codex credentials: the `auth.json`
+ * file exists. Absent means the device-code flow has not completed.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns true when credentials are present.
+ */
+export declare function codexAuthenticated(homeDir: string): Promise<boolean>;
+/**
+ * Parse the first line of a rollout file for the listing fields. Unknown or
+ * malformed values yield an undefined record rather than failing the list.
+ * @param text - the raw rollout file content (only the head is read).
+ * @returns the record, or undefined when the head is not a session_meta line.
+ */
+export declare function rolloutRecord(text: string): LocalAgentSessionRecord | undefined;
+/**
+ * Read the scoped home's rollout files. The listing walks
+ * `sessions/YYYY/MM/DD/` and reads each `rollout-*.jsonl` head; a torn or
+ * malformed file is skipped rather than failing the whole list.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the parsed records, empty when no sessions exist yet.
+ */
+export declare function listCodexSessions(homeDir: string): Promise<readonly LocalAgentSessionRecord[]>;
+/**
+ * Map codex's token-count payload onto the shared usage contract — the
+ * SINGLE caliber for both the exec `turn.completed` usage and the rollout
+ * `token_count` recovery, so the two sources can never drift. Codex's
+ * `input_tokens` is the TOTAL input including cache hits (OpenAI-style
+ * accounting, confirmed against `total_tokens` in the rollout token_count),
+ * and `cached_input_tokens` is the cache-read subset — so the uncached
+ * bucket subtracts the cached portion to avoid double counting. There is no
+ * cache-write concept, so that bucket is omitted (the shared four-bucket
+ * contract: uncached input, output, cache read, cache write — codex fills
+ * the first three).
+ * @param usage - the raw codex usage object (`turn.completed`'s `usage` or a
+ *   rollout `token_count` `info.last_token_usage`/`total_token_usage`).
+ * @returns the shared usage record.
+ */
+export declare function usageFromCodex(usage: unknown): TokenUsage;
+/**
+ * Scan rollout-file text for the LAST `token_count` event and map its usage
+ * onto the shared contract. A token_count entry rides an
+ * `{"type":"event_msg","payload":{"type":"token_count","info":{…}}}` line
+ * (verified against codex-cli 0.144.0 rollout files); the per-turn
+ * `info.last_token_usage` is the same caliber as `turn.completed`'s usage,
+ * with the session-wide `total_token_usage` as fallback. Torn or malformed
+ * lines are skipped; an absent event yields undefined.
+ * @param text - raw rollout file content (the tail scan reads a bounded suffix).
+ * @returns the mapped usage of the last token_count event, or undefined.
+ */
+export declare function codexRolloutTokenUsage(text: string): TokenUsage | undefined;
+/**
+ * The codex build that wrote one rollout file, from its `session_meta` head
+ * (`payload.cli_version`, present since codex 0.14x). This is the AUTHORITY
+ * for the version a delegation round actually ran: it is codex's own record of
+ * itself, written by the process that served the round, so it cannot drift
+ * from the binary the way a later `--version` probe can.
+ * @param text - the raw rollout head.
+ * @returns the version, or undefined when the head names none.
+ */
+export declare function rolloutCliVersion(text: string): string | undefined;
+/** Locator for one run's rollout file, resolved by thread id, cwd, and a time window. */
+export interface CodexRolloutLocator {
+    /**
+     * The thread id observed from the run's NDJSON stream (`thread.started`);
+     * the primary locator — matches the session_meta head id.
+     */
+    readonly threadId?: string | undefined;
+    /**
+     * Epoch-ms run start (the spawn moment); the time-window fallback centers
+     * on it when no thread id matched (e.g. a kill truncated the stream before
+     * `thread.started`).
+     */
+    readonly windowStart?: number | undefined;
+    /**
+     * The directory the run's CLI process was spawned in. Only the time-window
+     * fallback uses it, and there it is decisive: concurrent delegations put
+     * several runs' files inside one window, and the head's `cwd` is what tells
+     * them apart (an orchestrator gives every cell its own directory).
+     */
+    readonly cwd?: string | undefined;
+}
+/** One delegation round's facts, read back from the run's own rollout file. */
+export interface CodexRoundFacts {
+    /** The round's last `token_count` usage, in the shared caliber. */
+    readonly usage?: TokenUsage;
+    /** The model the round's turn ran with (`turn_context.model`). */
+    readonly model?: string;
+    /** The codex build that served the round (`session_meta.cli_version`). */
+    readonly cliVersion?: string;
+}
+/**
+ * Read ONE run's facts back from its rollout file: the token usage a
+ * non-completed round never streamed, the model the exec `--json` wire does
+ * not carry at all (codex 0.144.0), and the codex build that served it. One
+ * locate and one file open serve all three.
+ *
+ * Every field is absent on a miss — no rollout file, an unreadable home, a
+ * hard kill before any turn boundary, a window with no turn_context. Absence
+ * is recorded, never guessed.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @param locator - the thread id, working directory, and/or start-time window.
+ * @returns the round's read-back facts.
+ */
+export declare function codexRolloutRoundFacts(homeDir: string, locator: CodexRolloutLocator): Promise<CodexRoundFacts>;
+//# sourceMappingURL=records.d.ts.map