@prohost/cli 0.5.0 → 0.7.0

package/dist/agent/runtime_status.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Runtime, model and remaining capacity — what `agent run` tells ProhostAI about itself.
+ *
+ * ProhostAI shows every paired AI employee with its runtime ("Claude Code"),
+ * model ("Opus 5.5"), machine and how much of the operator's Claude or Codex
+ * subscription is left. Only this machine can see those things, so the harness
+ * reports them in a `runtime_status` frame on the socket it already holds.
+ *
+ * **Credentials never leave this machine, and this module never reads them.**
+ * Every number comes from the agent CLI answering with its own login:
+ *
+ * - Claude Code: the `rate_limit_event` and `system/init` lines of a run's own
+ *   `stream-json` output, and — when idle — the `get_usage` control request to
+ *   an unmodified `claude -p --input-format stream-json` (no model turn).
+ * - Codex: the rollout file Codex writes for each run under
+ *   `$CODEX_HOME/sessions`, and — when idle — `account/rateLimits/read` on
+ *   `codex app-server`.
+ *
+ * Nothing here opens the Claude Code keychain item or `~/.codex/auth.json`, and
+ * nothing forwards an account id, email or org. Only labels, percentages and
+ * reset times go on the wire. Unknown or missing data is omitted, never sent as
+ * zero.
+ *
+ * Every parser here fails soft, in the same spirit as `readClaudeStream`: the
+ * shapes belong to other tools and grow without asking us.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { AccountBlock } from './accounts.js';
+/** Feature name the server lists in `auth_ok.features` when it accepts the frame. */
+export declare const RUNTIME_STATUS_FEATURE = "runtime_status";
+/** Routine report cadence while connected. */
+export declare const STATUS_INTERVAL_MS: number;
+/**
+ * Minimum spacing between frames. The server accepts one per 30 s per socket
+ * and drops the rest; a second of margin keeps clock jitter from costing us
+ * the frame that carried a change.
+ */
+export declare const MIN_FRAME_SPACING_MS = 31000;
+/** Ask the agent CLI for fresh numbers when the last ones are this old. */
+export declare const QUOTA_REFRESH_AFTER_MS: number;
+/** Ceiling on one idle quota probe. */
+export declare const PROVIDER_TIMEOUT_MS = 10000;
+export type QuotaKind = 'session' | 'weekly' | 'weekly_model';
+export interface QuotaWindow {
+    kind: QuotaKind;
+    /** 0–100. */
+    used_percent: number;
+    /**
+     * ISO-8601, or `null` for a window whose usage is known but which has not
+     * started — Claude's 5-hour window after five idle hours. Reported as such
+     * rather than dropped: "0%, starts on next use" is an answer, a missing
+     * window is not.
+     */
+    resets_at: string | null;
+    /** The model a `weekly_model` window is scoped to, e.g. `Fable`. */
+    model_label?: string;
+}
+/** What one source managed to learn. Every field is optional; absent means "didn't learn it". */
+export interface RuntimeObservation {
+    runtime_version?: string;
+    model?: string;
+    plan_label?: string;
+    quota_windows?: QuotaWindow[];
+}
+/** A percentage on a 0–``scale`` scale, as 0–100 rounded to one decimal. */
+export declare function percent(value: unknown, scale: 1 | 100): number | undefined;
+/** Epoch seconds or an ISO string, as ISO-8601; anything else is `undefined`. */
+export declare function isoTime(value: unknown): string | undefined;
+/** First `X.Y.Z…` in a `--version` line, e.g. `2.1.282 (Claude Code)` or `codex-cli 0.146.0`. */
+export declare function parseVersion(stdout: string): string | undefined;
+/**
+ * Windows from a stream `rate_limit_event.rate_limit_info`.
+ *
+ * `unifiedWindows.*.utilization` is a FRACTION (0–1, and it can exceed 1) with
+ * epoch-second resets — unlike `get_usage`, which is 0–100 with ISO strings.
+ * The field is marked internal upstream, so an unexpected shape yields nothing.
+ */
+export declare function fromClaudeRateLimitInfo(info: unknown): QuotaWindow[];
+/**
+ * Windows from a `get_usage` control response (0–100, ISO strings).
+ *
+ * A window with a usage but a `null` reset is kept, with `resets_at: null` —
+ * that is how an idle account's 5-hour window reads, and dropping it is what
+ * left paired agents showing a weekly window and nothing else (B3).
+ *
+ * Per-model weekly windows come from `rate_limits.limits[]` rows of kind
+ * `weekly_scoped` (classified on `kind`, as the schema asks, never on a
+ * label), falling back to `model_scoped[]`.
+ */
+export declare function fromClaudeGetUsage(usage: unknown): QuotaWindow[];
+/** `get_usage.subscription_type` → display label; `undefined` for anything else. */
+export declare function claudePlanLabel(subscriptionType: unknown): string | undefined;
+/**
+ * Windows from Codex `rate_limits` (rollout, snake_case) or `rateLimits`
+ * (app-server, camelCase).
+ *
+ * Classified by window LENGTH, never by slot: on some plans `primary` is the
+ * weekly window and there is no 5-hour one at all.
+ */
+export declare function fromCodexRateLimits(rateLimits: unknown, lineTimestamp?: string): QuotaWindow[];
+/** `plan_type` / `planType` → `ChatGPT Pro`; `undefined` when there is no plan. */
+export declare function codexPlanLabel(planType: unknown): string | undefined;
+/** Model named in the exec string itself (`-m gpt-5` / `--model gpt-5` / `--model=gpt-5`). */
+export declare function modelFromExec(exec: string): string | undefined;
+/** `$CODEX_HOME`, defaulting to `~/.codex` exactly as Codex does. */
+export declare function codexHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * The top-level `model = "…"` in `$CODEX_HOME/config.toml` — Codex's default.
+ *
+ * Only the top level, before the first `[table]`: a `model` inside a profile
+ * table is not the default. A first guess only; the rollout's `turn_context`
+ * replaces it after the first run.
+ */
+export declare function codexConfiguredModel(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Locate the rollout for one thread: `sessions/YYYY/MM/DD/rollout-*-<thread_id>.jsonl`.
+ *
+ * The date directory is local time and a resumed thread lives under the day it
+ * started, so the date is never guessed — days are scanned newest first.
+ */
+export declare function findCodexRollout(threadId: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * What a Codex rollout says: the model the turn really used (after `-m`,
+ * profiles and `-c`), the CLI version, and the last rate-limit snapshot.
+ */
+export declare function parseCodexRollout(content: string): RuntimeObservation;
+/** Read the rollout for a finished Codex thread, if it can be found. */
+export declare function readCodexObservation(threadId: string | undefined, env?: NodeJS.ProcessEnv): RuntimeObservation | undefined;
+/**
+ * Where fresh numbers come from when no run has produced any lately.
+ *
+ * Implementations ask the unmodified agent CLI through its own protocol, so
+ * the CLI answers with its own login and this process never holds a
+ * credential. Resolve `undefined` on any failure — the reporter keeps what it
+ * had and omits what it doesn't know.
+ */
+export interface QuotaProvider {
+    refresh(): Promise<RuntimeObservation | undefined>;
+}
+type SpawnFn = typeof nodeSpawn;
+/**
+ * Claude Code's `get_usage` control request. No model turn is made, so no
+ * quota is spent. The `initialize` response carries account identity; it is
+ * never read.
+ */
+export declare function claudeQuotaProvider(options: {
+    binary: string;
+    spawnImpl?: SpawnFn;
+    timeoutMs?: number;
+    /** Account environment, read at each probe so a switch applies to the next one. */
+    env?: () => NodeJS.ProcessEnv;
+}): QuotaProvider;
+/** Codex's `account/rateLimits/read` over `codex app-server` stdio JSON-RPC. */
+export declare function codexQuotaProvider(options: {
+    binary: string;
+    clientVersion: string;
+    spawnImpl?: SpawnFn;
+    timeoutMs?: number;
+    /** Account environment, read at each probe so a switch applies to the next one. */
+    env?: () => NodeJS.ProcessEnv;
+}): QuotaProvider;
+/**
+ * Fold new windows into the ones already known, one KIND at a time.
+ *
+ * Sources see different slices: a run's `rate_limit_event` carries only the
+ * 5-hour and weekly windows (and omits one whose reset has passed), while the
+ * idle `get_usage` probe also carries the per-model weekly ones. Replacing the
+ * whole list with whatever arrived last is how a stream event used to erase
+ * the windows it simply didn't mention. A kind the observation names replaces
+ * every window of that kind; a kind it doesn't name is kept.
+ */
+export declare function mergeWindows(known: QuotaWindow[] | undefined, observed: QuotaWindow[]): QuotaWindow[];
+/** What the harness knows about accounts on this machine, for the frame. */
+export interface AccountsSnapshot {
+    /** The account this agent runs on. */
+    current?: AccountBlock;
+    /**
+     * Every account on the machine, identity and sign-in state only. Omitted
+     * when the list would be partial: the server treats it as authoritative
+     * and would forget whatever it doesn't name.
+     */
+    all?: AccountBlock[];
+}
+export interface RuntimeStatusReporterOptions {
+    /** `claude_code` | `codex` | `goose` | `custom`. */
+    runtime: string;
+    /** Idle quota source; omit for a runtime that has none. */
+    provider?: QuotaProvider;
+    /**
+     * Accounts on this machine and which one this agent uses. Re-read on the
+     * same cadence as the idle quota probe (it asks each login whether it is
+     * signed in), and straight away after {@link RuntimeStatusReporter.accountsChanged}.
+     */
+    accounts?: () => Promise<AccountsSnapshot | undefined>;
+    /** A run is executing — it will bring fresh numbers, so don't probe beside it. */
+    isBusy?: () => boolean;
+    now?: () => number;
+    /** Timer seam for tests. Returns a cancel function. */
+    schedule?: (fn: () => void, ms: number) => () => void;
+    intervalMs?: number;
+    log?: (line: string) => void;
+}
+/**
+ * Holds the latest runtime snapshot and decides when to send it.
+ *
+ * Sends only while attached — i.e. only on a socket whose server advertised
+ * {@link RUNTIME_STATUS_FEATURE}. Cadence: once on attach, every
+ * {@link STATUS_INTERVAL_MS}, and promptly when the model, plan or runtime
+ * version changes or capacity crosses a band — but never closer together than
+ * {@link MIN_FRAME_SPACING_MS}.
+ */
+export declare class RuntimeStatusReporter {
+    private readonly options;
+    private readonly now;
+    private readonly schedule;
+    private state;
+    private quotaObservedAt;
+    private send;
+    private lastSentAt;
+    private cancelPending;
+    private cancelTick;
+    private refreshing;
+    private accountGeneration;
+    private accounts;
+    private accountsObservedAt;
+    constructor(options: RuntimeStatusReporterOptions);
+    /** Merge what a source learned. Absent fields keep their previous value. */
+    observe(observation: RuntimeObservation | undefined): void;
+    /**
+     * Record the accounts snapshot. Moving to another account drops what was
+     * known about the previous one's capacity and plan — they describe a
+     * different subscription — and asks for fresh numbers straight away.
+     */
+    setAccounts(snapshot: AccountsSnapshot | undefined, options?: {
+        quiet?: boolean;
+    }): void;
+    /**
+     * The account choice changed (an operator picked one in ProhostAI): re-read
+     * accounts and capacity on the next tick rather than in fifteen minutes.
+     */
+    accountsChanged(): void;
+    /** The model to report on a run's completion, when nothing more specific is known. */
+    model(): string | undefined;
+    /** Start reporting on a socket that advertised the feature. */
+    attach(send: (frame: Record<string, unknown>) => void): void;
+    /** Stop reporting — the socket is gone. */
+    detach(): void;
+    /** The frame as it would be sent now. */
+    frame(): Record<string, unknown>;
+    /** Routine tick: refresh idle quota if it is stale, send, and re-arm. */
+    private tick;
+    private refresh;
+    /** Send now if spacing allows, else once it does. Coalesces. */
+    private sendSoon;
+    private flush;
+}
+export {};