import type { AccountConfig, AccountRef, Config, RunnerName } from "./config.js"; import type { Secrets } from "./env.js"; import type { FailureKind } from "./runners/failure.js"; import type { Skill } from "./skills.js"; export type AccountRunner = AccountConfig["runner"]; export type AccountKind = AccountConfig["kind"]; /** Where each CLI keeps its login when nothing says otherwise. */ export declare function defaultLoginDir(runner: AccountRunner, home?: string): string; export interface ResolvedAccount { name: string; runner: AccountRunner; kind: AccountKind; label?: string; disabled: boolean; /** The configuration directory runs use (absolute). */ dir: string; /** `dir` is the CLI's own default (`~/.claude`, `~/.codex`): the machine's own login, so no variable is set for it. */ defaultDir: boolean; /** `dir` is under `/accounts/` (skillhook made it; `accounts remove --purge` may delete it). */ managed: boolean; /** The `.env` name of a `token` / `api_key` account's credential. */ secretEnv?: string; /** The directory whose settings are linked into `dir` (`share_from`). */ shareFrom?: string; } /** `SKILLHOOK_ACCOUNT__TOKEN` / `_API_KEY`: never forwarded to a run except through the account itself. */ export declare function defaultAccountSecretEnv(name: string, kind: AccountKind): string; export declare function accountsDir(skillhookHome: string): string; export declare function resolveAccount(name: string, spec: AccountConfig, skillhookHome: string, home?: string): ResolvedAccount; export interface PreparedDir { dir: string; created: boolean; linked: string[]; /** Entries the account already has as its own file or directory, so they are not linked. */ kept: string[]; } /** * Makes the account's directory (mode 700) and, with `share_from`, links the shared settings into it: for Codex every * top-level entry of the shared home except the private ones, for Claude Code the settings files. Idempotent: run again * (`skillhook accounts login`, `accounts sync`) it links what the shared directory gained meanwhile and never replaces * a file the account has of its own. Written only by commands a person runs, never by the server. */ export declare function prepareAccountDir(account: ResolvedAccount): PreparedDir; export declare function listAccounts(config: Config, skillhookHome: string): ResolvedAccount[]; export declare function getAccount(config: Config, skillhookHome: string, name: string): ResolvedAccount | undefined; export declare function refNames(ref: AccountRef | undefined): string[]; /** * The pool for a run on `runner`: the explicit account, else the skill's `account:` when it is for that runner (a * fallback runner does not inherit the other runner's accounts), else `defaults.accounts.`. */ export declare function poolFor(skill: Pick, config: Config, runner: RunnerName, explicit?: string): string[]; /** The runner the skill's own `account:` implies, when it does not set `runner:` (all accounts of a pool share one). */ export declare function runnerOfAccounts(config: Config, names: string[]): AccountRunner | undefined; /** What is wrong with an account reference, for validation and the health report; empty when it is usable. */ export declare function accountRefProblems(config: Config, names: string[], runner: RunnerName): string[]; /** * `env` pointed at the account: its configuration directory (unless it is the CLI's default, which needs no variable, * and on macOS must not get one: Claude Code names its keychain entry after a non-default directory), and only its * credential. Every other way of authenticating that `env` carried is removed, so the run is billed to this account. */ export declare function withAccountEnv(env: Record, account: ResolvedAccount, secrets: Secrets): Record; export interface UsageWindow { /** `five_hour`, `seven_day`, `seven_day_opus`, `primary`, `secondary`, … as the provider names it. */ id: string; /** For people: "5h", "weekly", "weekly (Opus)". */ label: string; /** 0–100. */ used_percent: number; resets_at?: string; /** The window's length, when the provider says. */ window_minutes?: number; } export interface AccountUsage { fetched_at: string; windows: UsageWindow[]; /** Extra usage / credits beyond the plan, when the provider reports them. */ credits?: { enabled?: boolean; used?: number; limit?: number; balance?: number; currency?: string; unlimited?: boolean; }; plan?: string; error?: string; } export interface AccountIdentity { email?: string; org?: string; /** `max`, `pro`, `team`, `plus`, `business`, … */ plan?: string; /** A ChatGPT subscription's paid-until date. */ subscription_until?: string; checked_at: string; } export interface AccountState { /** When the pool last gave the account a job (before it ran): the round robin's clock. */ last_picked_at?: string; last_used_at?: string; last_job?: string; last_success_at?: string; last_failure?: { kind: FailureKind; at: string; job?: string; message?: string; }; /** Skipped by pools until then: a usage limit was hit (reset time from the CLI's message, the usage API or the cooldown). */ limited_until?: string; limited_reason?: string; identity?: AccountIdentity; usage?: AccountUsage; } export type AccountStates = Record; /** `jobs/.accounts.json`, read and written whole (small; one entry per account). */ export declare class AccountStateStore { readonly file: string; constructor(jobsDir: string); all(): AccountStates; get(name: string): AccountState; /** Merges `patch` into the account's entry (`undefined` removes a field) and returns the new entry. */ update(name: string, patch: Partial>): AccountState; remove(name: string): void; } /** Is the account skipped for now because it hit a limit? */ export declare function isLimited(state: AccountState | undefined, now?: number): boolean; /** * How much of the window is used now: a window whose reset has passed (or, with no reset time, whose whole length * has gone by since it was read) is empty again, whatever the last reading said. */ export declare function windowUsed(window: UsageWindow, fetchedAt: string | undefined, now?: number): number; /** The fullest usage window as of `now`, 0–100 (undefined when no usage is known). */ export declare function peakUsage(state: AccountState | undefined, now?: number): number | undefined; export interface PoolOrderOptions { now?: number; /** Jobs running on each account right now. */ inFlight?: Record; /** `account_policy.usage_avoid_percent`: a window at or above it puts the account behind those with more left. */ avoidPercent?: number; } /** * The order in which a pool's accounts are tried, in tiers: accounts with usage left first, then those with a window * at or above `avoidPercent` (about to hit a limit, so a long run would likely be cut off mid-session; the one with * the most left first), then limited ones (used only when nothing else is left, and then only once their limit may be * over). Within the first tier, `ordered` keeps the order listed; `balanced` takes the account running the fewest jobs, * then the least used (in bands of 25 points), then the one picked least recently: with no usage known that is a * round robin, and an account a person also uses by hand gets fewer jobs as its windows fill. */ export declare function orderPool(names: string[], states: AccountStates, strategy: Config["account_policy"]["strategy"], options?: PoolOrderOptions): string[]; /** * When a usage limit the CLI reported ends, from its message: Claude Code's `Claude AI usage limit reached|`, * "resets at 3pm" / "resets 7:30am (Europe/Paris)" style times (today or tomorrow, in the machine's zone when none * is named), Codex's "try again in 2 days 3 hours" / "in 45 minutes". Undefined when it does not say. */ export declare function parseLimitReset(message: string | undefined, now?: Date): string | undefined; /** Claude Code's `rate_limit_event` notices of one run, by window type (`five_hour`, `seven_day`, `seven_day_opus`, …). */ export type RunRateLimits = Record; /** The windows a run reported, merged over what was known (a run only mentions the windows it touched). */ export declare function usageFromRun(before: AccountState, rateLimits: RunRateLimits | undefined, at?: string): Partial>; /** What `jobs/.accounts.json` should say after a run of this account ended. */ export declare function stateAfterRun(input: { jobId: string; ok: boolean; failure?: { kind: FailureKind; message?: string; }; at?: string; cooldownMinutes: number; rateLimits?: RunRateLimits; }): Partial>;