@mostok/codexes 0.1.0

package/dist/runtime/runtime-contract.js

@@ -0,0 +1,79 @@
+import path from "node:path";
+export function createRuntimeContract(input) {
+    const contract = {
+        credentialStoreMode: input.credentialStoreMode,
+        sharedCodexHome: input.sharedCodexHome,
+        runtimeRoot: input.runtimeRoot,
+        perAccountRoot: input.accountRoot,
+        supported: input.credentialStoreMode === "file",
+        fileRules: [
+            createRule("config.toml", "shared", "never", "Shared CLI behavior and MCP config should remain common."),
+            createRule("mcp.json", "shared", "never", "MCP topology is shared across accounts."),
+            createRule("trust/**", "shared", "never", "Trust metadata should not be overwritten per account."),
+            createRule("auth.json", "account", "if-changed", "Windows probe evidence shows auth.json is sufficient for `codex login status`, so it belongs to the active account profile."),
+            createRule("sessions/**", "account", "if-changed", "Session refresh artifacts are still treated as account-scoped until a real token-refresh probe proves otherwise."),
+            createRule("cache/**", "ephemeral", "never", "Transient caches should be recreated instead of copied."),
+            createRule("logs/**", "ephemeral", "never", "Runtime logs are diagnostic and should not sync back."),
+            createRule("history.jsonl", "ephemeral", "never", "Conversation history should stay local to each runtime session."),
+            createRule("models_cache.json", "ephemeral", "never", "Model cache data can be rebuilt and should not drive account switching."),
+            createRule("tmp/**", "ephemeral", "never", "Temporary files should be discarded after each run."),
+            createRule("state_*.sqlite*", "protected", "never", "Observed SQLite runtime state exists in the live Codex home and remains unproven for cross-account merge or sync-back."),
+            createRule("logs_*.sqlite*", "protected", "never", "SQLite-backed log databases should stay isolated until a dedicated write-heavy probe proves they are safe to discard or share."),
+            createRule("keyring/**", "protected", "never", "External credential stores are explicitly unsupported for MVP."),
+        ],
+        syncBackStrategy: {
+            whenChildProcessSucceeds: "Compare allowed account-classified files and sync only changed files back to the owning account profile.",
+            whenChildProcessFails: "Restore pre-launch runtime state and avoid syncing ambiguous mutations unless the failure is known-safe.",
+            compareStrategy: "Use file existence, modified time, and content hash checks before any sync-back write.",
+        },
+    };
+    input.logger.info("runtime.contract_created", {
+        sharedCodexHome: contract.sharedCodexHome,
+        runtimeRoot: contract.runtimeRoot,
+        perAccountRoot: contract.perAccountRoot,
+        credentialStoreMode: contract.credentialStoreMode,
+        supported: contract.supported,
+    });
+    input.logger.debug("runtime.file_rules", {
+        fileRules: contract.fileRules,
+        syncBackStrategy: contract.syncBackStrategy,
+    });
+    return contract;
+}
+export function resolveAccountRuntimePaths(contract, accountId) {
+    const accountDirectory = path.join(contract.perAccountRoot, accountId);
+    return {
+        accountDirectory,
+        accountStateDirectory: path.join(accountDirectory, "state"),
+        accountMetadataFile: path.join(accountDirectory, "account.json"),
+        runtimeBackupDirectory: path.join(contract.runtimeRoot, "backups", accountId),
+        runtimeTempDirectory: path.join(contract.runtimeRoot, "tmp", accountId),
+    };
+}
+export function summarizeRuntimeContract(contract) {
+    return {
+        supported: contract.supported,
+        credentialStoreMode: contract.credentialStoreMode,
+        sharedCodexHome: contract.sharedCodexHome,
+        runtimeRoot: contract.runtimeRoot,
+        perAccountRoot: contract.perAccountRoot,
+        classifications: contract.fileRules.reduce((accumulator, rule) => {
+            accumulator[rule.classification] += 1;
+            return accumulator;
+        }, {
+            shared: 0,
+            account: 0,
+            ephemeral: 0,
+            protected: 0,
+        }),
+    };
+}
+function createRule(pathPattern, classification, syncBack, reason) {
+    return {
+        pathPattern,
+        classification,
+        syncBack,
+        reason,
+    };
+}
+//# sourceMappingURL=runtime-contract.js.map

package/dist/runtime/runtime-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-contract.js","sourceRoot":"","sources":["../../src/runtime/runtime-contract.ts"],"names":[],"mappings":"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"}

package/dist/selection/account-auth-state.d.ts

@@ -0,0 +1,23 @@
+import type { AccountRecord } from "../accounts/account-registry.js";
+import type { Logger } from "../logging/logger.js";
+export type AccountAuthStateFailureCategory = "missing-file" | "malformed-json" | "missing-access-token" | "unsupported-auth-shape";
+export interface AccountAuthState {
+    accessToken: string;
+    accountId: string | null;
+    authMode: string | null;
+    lastRefresh: string | null;
+}
+export type AccountAuthStateReadResult = {
+    ok: true;
+    filePath: string;
+    state: AccountAuthState;
+} | {
+    ok: false;
+    category: AccountAuthStateFailureCategory;
+    filePath: string;
+    message: string;
+};
+export declare function readAccountAuthState(input: {
+    account: AccountRecord;
+    logger: Logger;
+}): Promise<AccountAuthStateReadResult>;

package/dist/selection/account-auth-state.js

@@ -0,0 +1,132 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function readAccountAuthState(input) {
+    const filePath = path.join(input.account.authDirectory, "state", "auth.json");
+    input.logger.debug("selection.account_auth_state.read_start", {
+        accountId: input.account.id,
+        label: input.account.label,
+        filePath,
+    });
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            input.logger.warn("selection.account_auth_state.unsupported_shape", {
+                accountId: input.account.id,
+                label: input.account.label,
+                filePath,
+                topLevelType: typeof parsed,
+            });
+            return {
+                ok: false,
+                category: "unsupported-auth-shape",
+                filePath,
+                message: "auth.json is not a JSON object.",
+            };
+        }
+        const accessToken = resolveString(parsed.access_token, getNestedString(parsed, ["tokens", "access_token"]), getNestedString(parsed, ["tokens", "accessToken"]));
+        if (!accessToken) {
+            input.logger.warn("selection.account_auth_state.access_token_missing", {
+                accountId: input.account.id,
+                label: input.account.label,
+                filePath,
+                hasTokensObject: isRecord(parsed.tokens),
+            });
+            return {
+                ok: false,
+                category: "missing-access-token",
+                filePath,
+                message: "auth.json does not contain an access_token.",
+            };
+        }
+        const result = {
+            ok: true,
+            filePath,
+            state: {
+                accessToken,
+                accountId: resolveString(parsed.account_id, parsed.accountId, getNestedString(parsed, ["tokens", "account_id"]), getNestedString(parsed, ["tokens", "accountId"])),
+                authMode: resolveString(parsed.auth_mode, parsed.authMode, getNestedString(parsed, ["tokens", "auth_mode"]), getNestedString(parsed, ["tokens", "authMode"])),
+                lastRefresh: resolveString(parsed.last_refresh, parsed.lastRefresh, parsed.refresh_at, parsed.refreshAt),
+            },
+        };
+        input.logger.debug("selection.account_auth_state.read_complete", {
+            accountId: input.account.id,
+            label: input.account.label,
+            filePath,
+            hasAccessToken: true,
+            authAccountId: result.state.accountId,
+            authMode: result.state.authMode,
+            hasRefreshMetadata: result.state.lastRefresh !== null,
+        });
+        return result;
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT")) {
+            input.logger.warn("selection.account_auth_state.missing_file", {
+                accountId: input.account.id,
+                label: input.account.label,
+                filePath,
+            });
+            return {
+                ok: false,
+                category: "missing-file",
+                filePath,
+                message: "auth.json was not found for the account profile.",
+            };
+        }
+        if (error instanceof SyntaxError) {
+            input.logger.warn("selection.account_auth_state.malformed_json", {
+                accountId: input.account.id,
+                label: input.account.label,
+                filePath,
+                message: error.message,
+            });
+            return {
+                ok: false,
+                category: "malformed-json",
+                filePath,
+                message: error.message,
+            };
+        }
+        input.logger.warn("selection.account_auth_state.unsupported_shape", {
+            accountId: input.account.id,
+            label: input.account.label,
+            filePath,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return {
+            ok: false,
+            category: "unsupported-auth-shape",
+            filePath,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function getNestedString(value, pathParts) {
+    let current = value;
+    for (const part of pathParts) {
+        if (!isRecord(current) || typeof current[part] === "undefined") {
+            return null;
+        }
+        current = current[part];
+    }
+    return typeof current === "string" && current.trim().length > 0 ? current : null;
+}
+function resolveString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isNodeErrorWithCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+//# sourceMappingURL=account-auth-state.js.map

package/dist/selection/account-auth-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-auth-state.js","sourceRoot":"","sources":["../../src/selection/account-auth-state.ts"],"names":[],"mappings":"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"}

package/dist/selection/select-account.d.ts

@@ -0,0 +1,11 @@
+import type { AccountRegistry, AccountRecord } from "../accounts/account-registry.js";
+import type { AccountSelectionStrategy, ExperimentalSelectionConfig } from "../config/wrapper-config.js";
+import type { Logger } from "../logging/logger.js";
+export declare function selectAccountForExecution(input: {
+    experimentalSelection?: ExperimentalSelectionConfig;
+    fetchImpl?: typeof fetch;
+    logger: Logger;
+    registry: AccountRegistry;
+    selectionCacheFilePath?: string;
+    strategy: AccountSelectionStrategy;
+}): Promise<AccountRecord>;

package/dist/selection/select-account.js

@@ -0,0 +1,168 @@
+import { resolveAccountUsageSnapshots } from "./usage-probe-coordinator.js";
+export async function selectAccountForExecution(input) {
+    const accounts = await input.registry.listAccounts();
+    input.logger.info("selection.start", {
+        strategy: input.strategy,
+        accountCount: accounts.length,
+    });
+    if (accounts.length === 0) {
+        input.logger.warn("selection.none");
+        throw new Error("No accounts configured. Add one with `codexes account add <label>`.");
+    }
+    switch (input.strategy) {
+        case "manual-default":
+            return selectManualDefaultAccount(input.registry, input.logger, accounts);
+        case "single-account":
+            return selectSingleAccountOnly(input.registry, input.logger, accounts);
+        case "remaining-limit-experimental":
+            return selectExperimentalRemainingLimitAccount({
+                accounts,
+                experimentalSelection: input.experimentalSelection,
+                fetchImpl: input.fetchImpl,
+                logger: input.logger,
+                registry: input.registry,
+                selectionCacheFilePath: input.selectionCacheFilePath,
+            });
+    }
+}
+async function selectManualDefaultAccount(registry, logger, accounts) {
+    const defaultAccount = await registry.getDefaultAccount();
+    if (defaultAccount) {
+        logger.info("selection.manual_default", {
+            accountId: defaultAccount.id,
+            label: defaultAccount.label,
+        });
+        return defaultAccount;
+    }
+    if (accounts.length === 1) {
+        const [singleAccount] = accounts;
+        if (!singleAccount) {
+            throw new Error("No accounts configured.");
+        }
+        logger.info("selection.manual_default_fallback_single", {
+            accountId: singleAccount.id,
+            label: singleAccount.label,
+        });
+        return registry.selectAccount(singleAccount.id);
+    }
+    logger.warn("selection.manual_default_missing", {
+        accountCount: accounts.length,
+    });
+    throw new Error("Multiple accounts are configured but no default account is selected. Use `codexes account use <account-id-or-label>` first.");
+}
+async function selectSingleAccountOnly(registry, logger, accounts) {
+    if (accounts.length !== 1) {
+        logger.warn("selection.single_account_invalid", {
+            accountCount: accounts.length,
+        });
+        throw new Error("The single-account strategy requires exactly one configured account.");
+    }
+    const [singleAccount] = accounts;
+    if (!singleAccount) {
+        throw new Error("No accounts configured.");
+    }
+    logger.info("selection.single_account", {
+        accountId: singleAccount.id,
+        label: singleAccount.label,
+    });
+    const defaultAccount = await registry.getDefaultAccount();
+    if (defaultAccount?.id === singleAccount.id) {
+        return singleAccount;
+    }
+    return registry.selectAccount(singleAccount.id);
+}
+async function selectExperimentalRemainingLimitAccount(input) {
+    if (!input.experimentalSelection?.enabled || !input.selectionCacheFilePath) {
+        input.logger.warn("selection.experimental_config_missing", {
+            enabled: input.experimentalSelection?.enabled ?? false,
+            hasSelectionCacheFilePath: Boolean(input.selectionCacheFilePath),
+        });
+        return selectManualDefaultAccount(input.registry, input.logger, input.accounts);
+    }
+    const defaultAccount = await input.registry.getDefaultAccount();
+    const probeResults = await resolveAccountUsageSnapshots({
+        accounts: input.accounts,
+        cacheFilePath: input.selectionCacheFilePath,
+        fetchImpl: input.fetchImpl,
+        logger: input.logger,
+        probeConfig: input.experimentalSelection,
+    });
+    const failedProbes = probeResults.filter((entry) => !entry.ok);
+    if (failedProbes.length > 0) {
+        const eventName = failedProbes.length === probeResults.length
+            ? "selection.experimental_fallback_all_probes_failed"
+            : "selection.experimental_fallback_mixed_probe_outcomes";
+        input.logger.warn(eventName, {
+            failedAccountIds: failedProbes.map((entry) => entry.account.id),
+            failureCategories: failedProbes.map((entry) => entry.category),
+            successfulAccountIds: probeResults
+                .filter((entry) => entry.ok)
+                .map((entry) => entry.account.id),
+        });
+        return selectManualDefaultAccount(input.registry, input.logger, input.accounts);
+    }
+    const successfulProbes = probeResults.filter((entry) => entry.ok);
+    const candidates = successfulProbes
+        .filter((entry) => entry.snapshot.status === "usable")
+        .sort((left, right) => compareExperimentalCandidates({
+        defaultAccountId: defaultAccount?.id ?? null,
+        left,
+        right,
+        registryOrder: input.accounts,
+    }));
+    input.logger.info("selection.experimental_ranked", {
+        candidateOrder: candidates.map((entry) => ({
+            accountId: entry.account.id,
+            label: entry.account.label,
+            dailyRemaining: entry.snapshot.dailyRemaining,
+            weeklyRemaining: entry.snapshot.weeklyRemaining,
+            source: entry.source,
+        })),
+        defaultAccountId: defaultAccount?.id ?? null,
+    });
+    const selected = candidates[0];
+    if (!selected) {
+        const allExhausted = successfulProbes.every((entry) => entry.snapshot.limitReached || entry.snapshot.status === "limit-reached");
+        input.logger.warn(allExhausted
+            ? "selection.experimental_fallback_all_accounts_exhausted"
+            : "selection.experimental_fallback_ambiguous_usage", {
+            usableProbeCount: candidates.length,
+            probeStatuses: successfulProbes.map((entry) => ({
+                accountId: entry.account.id,
+                snapshotStatus: entry.snapshot.status,
+                limitReached: entry.snapshot.limitReached,
+                dailyRemaining: entry.snapshot.dailyRemaining,
+                weeklyRemaining: entry.snapshot.weeklyRemaining,
+            })),
+        });
+        return selectManualDefaultAccount(input.registry, input.logger, input.accounts);
+    }
+    input.logger.info("selection.experimental_selected", {
+        accountId: selected.account.id,
+        label: selected.account.label,
+        dailyRemaining: selected.snapshot.dailyRemaining,
+        weeklyRemaining: selected.snapshot.weeklyRemaining,
+        source: selected.source,
+    });
+    return selected.account;
+}
+function compareExperimentalCandidates(input) {
+    const dailyDelta = (input.right.snapshot.dailyRemaining ?? Number.NEGATIVE_INFINITY) -
+        (input.left.snapshot.dailyRemaining ?? Number.NEGATIVE_INFINITY);
+    if (dailyDelta !== 0) {
+        return dailyDelta;
+    }
+    const weeklyDelta = (input.right.snapshot.weeklyRemaining ?? Number.NEGATIVE_INFINITY) -
+        (input.left.snapshot.weeklyRemaining ?? Number.NEGATIVE_INFINITY);
+    if (weeklyDelta !== 0) {
+        return weeklyDelta;
+    }
+    const leftIsDefault = input.left.account.id === input.defaultAccountId;
+    const rightIsDefault = input.right.account.id === input.defaultAccountId;
+    if (leftIsDefault !== rightIsDefault) {
+        return leftIsDefault ? -1 : 1;
+    }
+    return (input.registryOrder.findIndex((account) => account.id === input.left.account.id) -
+        input.registryOrder.findIndex((account) => account.id === input.right.account.id));
+}
+//# sourceMappingURL=select-account.js.map

package/dist/selection/select-account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-account.js","sourceRoot":"","sources":["../../src/selection/select-account.ts"],"names":[],"mappings":"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"}

package/dist/selection/usage-cache.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "../logging/logger.js";
+import type { NormalizedUsageSnapshot } from "./usage-types.js";
+export interface UsageCacheEntry {
+    accountId: string;
+    accountLabel: string;
+    cachedAt: string;
+    snapshot: NormalizedUsageSnapshot;
+}
+export declare function loadUsageCache(input: {
+    cacheFilePath: string;
+    logger: Logger;
+}): Promise<UsageCacheEntry[]>;
+export declare function persistUsageCache(input: {
+    cacheFilePath: string;
+    entries: UsageCacheEntry[];
+    logger: Logger;
+}): Promise<void>;
+export declare function resolveFreshUsageCacheEntry(input: {
+    accountId: string;
+    entries: UsageCacheEntry[];
+    logger: Logger;
+    now: number;
+    ttlMs: number;
+}): UsageCacheEntry | null;

package/dist/selection/usage-cache.js

@@ -0,0 +1,106 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+const USAGE_CACHE_SCHEMA_VERSION = 1;
+export async function loadUsageCache(input) {
+    try {
+        const raw = await readFile(input.cacheFilePath, "utf8");
+        const parsed = JSON.parse(raw);
+        const normalized = normalizeUsageCacheDocument(parsed);
+        input.logger.debug("selection.usage_cache.load_success", {
+            cacheFilePath: input.cacheFilePath,
+            entryCount: normalized.entries.length,
+        });
+        return normalized.entries;
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT")) {
+            input.logger.debug("selection.usage_cache.missing", {
+                cacheFilePath: input.cacheFilePath,
+            });
+            return [];
+        }
+        const backupPath = `${input.cacheFilePath}.corrupt-${Date.now()}`;
+        await rename(input.cacheFilePath, backupPath).catch(() => undefined);
+        input.logger.warn("selection.usage_cache.corrupt", {
+            cacheFilePath: input.cacheFilePath,
+            backupPath,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+    }
+}
+export async function persistUsageCache(input) {
+    await mkdir(path.dirname(input.cacheFilePath), { recursive: true });
+    const document = {
+        schemaVersion: USAGE_CACHE_SCHEMA_VERSION,
+        entries: input.entries,
+    };
+    const tempFile = `${input.cacheFilePath}.tmp`;
+    const serialized = JSON.stringify(document, null, 2);
+    await writeFile(tempFile, serialized, "utf8");
+    await rename(tempFile, input.cacheFilePath);
+    input.logger.debug("selection.usage_cache.persisted", {
+        cacheFilePath: input.cacheFilePath,
+        entryCount: input.entries.length,
+    });
+}
+export function resolveFreshUsageCacheEntry(input) {
+    const entry = input.entries.find((candidate) => candidate.accountId === input.accountId) ?? null;
+    if (!entry) {
+        input.logger.debug("selection.usage_cache.miss", {
+            accountId: input.accountId,
+            ttlMs: input.ttlMs,
+        });
+        return null;
+    }
+    const ageMs = input.now - new Date(entry.cachedAt).valueOf();
+    if (!Number.isFinite(ageMs) || ageMs > input.ttlMs) {
+        input.logger.debug("selection.usage_cache.expired", {
+            accountId: input.accountId,
+            cachedAt: entry.cachedAt,
+            ageMs: Number.isFinite(ageMs) ? ageMs : null,
+            ttlMs: input.ttlMs,
+        });
+        return null;
+    }
+    input.logger.debug("selection.usage_cache.hit", {
+        accountId: input.accountId,
+        cachedAt: entry.cachedAt,
+        ageMs,
+        ttlMs: input.ttlMs,
+    });
+    return entry;
+}
+function normalizeUsageCacheDocument(value) {
+    if (!isRecord(value)) {
+        throw new Error("Usage cache document is not an object.");
+    }
+    const schemaVersion = typeof value.schemaVersion === "number" ? value.schemaVersion : USAGE_CACHE_SCHEMA_VERSION;
+    if (schemaVersion !== USAGE_CACHE_SCHEMA_VERSION) {
+        throw new Error(`Unsupported usage cache schema version ${schemaVersion}.`);
+    }
+    const entries = Array.isArray(value.entries)
+        ? value.entries.filter(isUsageCacheEntry)
+        : [];
+    return {
+        schemaVersion: USAGE_CACHE_SCHEMA_VERSION,
+        entries,
+    };
+}
+function isUsageCacheEntry(value) {
+    return (isRecord(value) &&
+        typeof value.accountId === "string" &&
+        typeof value.accountLabel === "string" &&
+        typeof value.cachedAt === "string" &&
+        isRecord(value.snapshot));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isNodeErrorWithCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+//# sourceMappingURL=usage-cache.js.map

package/dist/selection/usage-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-cache.js","sourceRoot":"","sources":["../../src/selection/usage-cache.ts"],"names":[],"mappings":"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"}

package/dist/selection/usage-client.d.ts

@@ -0,0 +1,23 @@
+import type { AccountRecord } from "../accounts/account-registry.js";
+import type { ExperimentalSelectionConfig } from "../config/wrapper-config.js";
+import type { Logger } from "../logging/logger.js";
+import type { NormalizedUsageSnapshot } from "./usage-types.js";
+export type UsageProbeFailureCategory = "auth-missing" | "timeout" | "http-error" | "invalid-response";
+export type AccountUsageProbeResult = {
+    ok: true;
+    account: AccountRecord;
+    snapshot: NormalizedUsageSnapshot;
+    source: "fresh";
+} | {
+    ok: false;
+    account: AccountRecord;
+    category: UsageProbeFailureCategory;
+    message: string;
+    source: "fresh";
+};
+export declare function probeAccountUsage(input: {
+    account: AccountRecord;
+    fetchImpl?: typeof fetch;
+    logger: Logger;
+    probeConfig: ExperimentalSelectionConfig;
+}): Promise<AccountUsageProbeResult>;