@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/driver/fake.js

@@ -0,0 +1,73 @@
+import { makeEmit } from './session-support.js';
+function asTurn(value) {
+    return typeof value === 'string' ? { text: value } : value;
+}
+/**
+ * An in-memory {@link Driver} for tests and `FRAMEWORK_FAKE` runs: it never spawns a
+ * process, replays scripted turns deterministically, and emits the same
+ * {@link DriverEvent} shape a real driver does. Mirrors `AiFake` /
+ * `FakeRunner`, so the whole flow runs offline with no CLI and no model.
+ */
+export class FakeDriver {
+    opts;
+    id = 'fake';
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    // Narrowed to the concrete session so callers can read `prompts` for assertions.
+    start(opts) {
+        return Promise.resolve(new FakeDriverSession(this.opts, opts));
+    }
+}
+/** A single {@link FakeDriver} session. Records every prompt for assertions. */
+export class FakeDriverSession {
+    config;
+    startOpts;
+    id;
+    cwd;
+    /** Every prompt this session received, in order. */
+    prompts = [];
+    index = 0;
+    constructor(config, startOpts) {
+        this.config = config;
+        this.startOpts = startOpts;
+        this.id = config.sessionId ?? 'fake-session';
+        this.cwd = startOpts.cwd;
+    }
+    prompt(text, opts = {}) {
+        if (this.startOpts.signal?.aborted || opts.signal?.aborted) {
+            return Promise.reject(new Error('[framework] fake prompt aborted'));
+        }
+        const i = this.index++;
+        this.prompts.push(text);
+        const turn = this.resolveTurn(text, i);
+        this.emit({ type: 'start', prompt: text });
+        for (const label of turn.actions ?? [])
+            this.emit({ type: 'action', label });
+        if (turn.text)
+            this.emit({ type: 'text', text: turn.text });
+        this.emit({ type: 'result', text: turn.text, sessionId: this.id, ...(turn.usage ? { usage: turn.usage } : {}) });
+        return Promise.resolve({ text: turn.text, sessionId: this.id, ...(turn.usage ? { usage: turn.usage } : {}) });
+    }
+    readCode(path) {
+        const contents = this.config.files?.[path];
+        if (contents === undefined)
+            return Promise.reject(new Error(`[framework] fake driver has no file ${path}`));
+        return Promise.resolve(contents);
+    }
+    dispose() {
+        return Promise.resolve();
+    }
+    resolveTurn(text, i) {
+        if (this.config.respond)
+            return asTurn(this.config.respond(text, i));
+        const turns = this.config.turns ?? [];
+        if (turns.length === 0)
+            return { text: '' };
+        return turns[Math.min(i, turns.length - 1)];
+    }
+    emit(event) {
+        makeEmit(this.startOpts.onEvent, 'fake driver')(event);
+    }
+}
+//# sourceMappingURL=fake.js.map

package/dist/driver/fake.js.map

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

package/dist/driver/index.d.ts

@@ -0,0 +1,10 @@
+export type { Driver, DriverSession, DriverStartOptions, DriverPromptOptions, DriverTurn, DriverEvent, DriverUsage, DriverRateLimit, DriverQuota, DriverQuotaWindow, DriverQuotaUnavailableReason, } from './types.js';
+export { isTransientQuotaReason } from './types.js';
+export { readClaudeQuota, parseQuotaReadout, type ReadClaudeQuotaOptions } from './claude-code-quota.js';
+export { FakeDriver, FakeDriverSession, type FakeTurn, type FakeDriverOptions } from './fake.js';
+export { CodexDriver, CodexSession, CodexJsonParser, type CodexDriverOptions, type CodexSandbox } from './codex.js';
+export { ClaudeCodeDriver, ClaudeCodeSession, StreamJsonParser, runClaude, type ClaudeCodeDriverOptions, type McpServerSpec, type PermissionMode, } from './claude-code.js';
+export { ActionsDriver, ActionsSession, replayTranscript, type ActionsDriverOptions, type FetchLike } from './actions.js';
+export { CloudDriver, CloudSession, type CloudDriverOptions, type ExtensionStart } from './cloud.js';
+export { runCliSession, type AgentCliParser, type RunCliSessionOptions, type SpawnLike, type SpawnedProcess, } from './cli-session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/driver/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/driver/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,MAAM,EACN,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,WAAW,EACX,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AACxG,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,QAAQ,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAChG,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AACnH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AACzH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAMpG,OAAO,EACL,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAA"}

package/dist/driver/index.js

@@ -0,0 +1,14 @@
+export { isTransientQuotaReason } from './types.js';
+export { readClaudeQuota, parseQuotaReadout } from './claude-code-quota.js';
+export { FakeDriver, FakeDriverSession } from './fake.js';
+export { CodexDriver, CodexSession, CodexJsonParser } from './codex.js';
+export { ClaudeCodeDriver, ClaudeCodeSession, StreamJsonParser, runClaude, } from './claude-code.js';
+export { ActionsDriver, ActionsSession, replayTranscript } from './actions.js';
+export { CloudDriver, CloudSession } from './cloud.js';
+// `readZip`/`ZipEntry` are deliberately absent (#947): the Actions driver's internal zip reader
+// rode this barrel onto the published surface via `src/index.ts`'s `export *`, with no importer
+// outside the driver and its own test — both of which take the module by path. An accidental
+// export is a one-way door once released, and this package has never been published, so the
+// removal costs nobody anything.
+export { runCliSession, } from './cli-session.js';
+//# sourceMappingURL=index.js.map

package/dist/driver/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/driver/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAA+B,MAAM,wBAAwB,CAAA;AACxG,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAyC,MAAM,WAAW,CAAA;AAChG,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAA8C,MAAM,YAAY,CAAA;AACnH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,GAIV,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAA6C,MAAM,cAAc,CAAA;AACzH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAgD,MAAM,YAAY,CAAA;AACpG,gGAAgG;AAChG,gGAAgG;AAChG,6FAA6F;AAC7F,4FAA4F;AAC5F,iCAAiC;AACjC,OAAO,EACL,aAAa,GAKd,MAAM,kBAAkB,CAAA"}

package/dist/driver/session-support.d.ts

@@ -0,0 +1,14 @@
+import type { DriverEvent } from './types.js';
+/**
+ * A {@link DriverStartOptions.onEvent} caller that never lets a listener throw into the
+ * driver — a throwing dashboard handler must not abort the agent. An absent `onEvent`
+ * is a no-op. `driver` names it in the swallow log so a thrown handler stays traceable.
+ */
+export declare function makeEmit(onEvent: ((event: DriverEvent) => void) | undefined, driver: string): (event: DriverEvent) => void;
+/** The live AbortSignals for a prompt — the session's and the per-call one, minus the absent. */
+export declare function combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal[];
+/** Fold a session's framing and a per-call system prompt into one blank-line-separated block. */
+export declare function combineFraming(...parts: (string | undefined)[]): string;
+/** Read a workspace file relative to the session cwd — the driver's `readCode`. */
+export declare function readWorkspaceFile(cwd: string, path: string): Promise<string>;
+//# sourceMappingURL=session-support.d.ts.map

package/dist/driver/session-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-support.d.ts","sourceRoot":"","sources":["../../src/driver/session-support.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAQ7C;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAS1H;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,GAAG,OAAO,EAAE,CAAC,WAAW,GAAG,SAAS,CAAC,EAAE,GAAG,WAAW,EAAE,CAErF;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,CAEvE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5E"}

package/dist/driver/session-support.js

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+// The pieces every driver session needs but that are not agent-specific: emitting events
+// without letting a listener throw into the agent, folding the session + per-call signals and
+// framing, and reading a workspace file. The agent-specific parts (argv, the output parser,
+// how framing is delivered) stay in each driver; these do not, so a second driver reuses
+// them rather than copying them.
+/**
+ * A {@link DriverStartOptions.onEvent} caller that never lets a listener throw into the
+ * driver — a throwing dashboard handler must not abort the agent. An absent `onEvent`
+ * is a no-op. `driver` names it in the swallow log so a thrown handler stays traceable.
+ */
+export function makeEmit(onEvent, driver) {
+    if (!onEvent)
+        return () => { };
+    return event => {
+        try {
+            onEvent(event);
+        }
+        catch (err) {
+            console.error(`[framework] ${driver} onEvent threw; ignoring:`, err);
+        }
+    };
+}
+/** The live AbortSignals for a prompt — the session's and the per-call one, minus the absent. */
+export function combineSignals(...signals) {
+    return signals.filter((s) => s != null);
+}
+/** Fold a session's framing and a per-call system prompt into one blank-line-separated block. */
+export function combineFraming(...parts) {
+    return parts.filter(Boolean).join('\n\n');
+}
+/** Read a workspace file relative to the session cwd — the driver's `readCode`. */
+export function readWorkspaceFile(cwd, path) {
+    return readFile(resolve(cwd, path), 'utf8');
+}
+//# sourceMappingURL=session-support.js.map

package/dist/driver/session-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-support.js","sourceRoot":"","sources":["../../src/driver/session-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,yFAAyF;AACzF,8FAA8F;AAC9F,4FAA4F;AAC5F,yFAAyF;AACzF,iCAAiC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAmD,EAAE,MAAc;IAC1F,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IAC7B,OAAO,KAAK,CAAC,EAAE;QACb,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,CAAC,CAAA;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,eAAe,MAAM,2BAA2B,EAAE,GAAG,CAAC,CAAA;QACtE,CAAC;IACH,CAAC,CAAA;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,cAAc,CAAC,GAAG,OAAoC;IACpE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAA;AAC3D,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,cAAc,CAAC,GAAG,KAA6B;IAC7D,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC3C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAAY;IACzD,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;AAC7C,CAAC"}

package/dist/driver/types.d.ts

@@ -0,0 +1,310 @@
+import type { DriverImplId } from '../driver-names.js';
+/**
+ * The **driver** seam: the one abstraction The Framework wraps a coding-agent
+ * CLI behind. A driver treats the agent (Claude Code today, Codex / opencode
+ * later) as a **black box**: we hand it a prompt, let its *own* loop run to
+ * completion, then read the code it produced and gate on the outcome ourselves.
+ *
+ * The seam is deliberately the **code and the outcome**, never the agent's
+ * individual tool calls (guardrail from #165). We drive by prompting and verify
+ * by result (builds / serves / review-passes), so the wrapped agent keeps its
+ * subscription-based auth and its internal loop stays untouched and swappable.
+ *
+ * Decision (#166, option A): a single execution path. Everything runs *through*
+ * the driver; personas become prompt-framing ({@link DriverStartOptions.system}),
+ * and each loop pass (review / security / QA / UX) is a **fresh** {@link
+ * DriverSession.prompt} call, so `prompt` is the fresh-context unit.
+ *
+ * `Driver` is intentionally tiny: `start` a session, `prompt` it, read the code,
+ * `dispose`. It mirrors the runner seam's shape so a second agent slots in behind
+ * the same three methods.
+ */
+/** A wrapped coding-agent CLI. Boots {@link DriverSession}s bound to a workspace. */
+export interface Driver {
+    /**
+     * Stable id for this concrete implementation, e.g. `"claude-code"`. Not the driver's *name*
+     * (`claude`), which is the user's choice: one driver has an implementation per place it can run
+     * (D5). {@link driverFromImpl} maps this back to the choice.
+     */
+    readonly id: DriverImplId;
+    /** Boot a session bound to a workspace directory. */
+    start(opts: DriverStartOptions): Promise<DriverSession>;
+    /**
+     * Ask the agent where the account's subscription quota stands (#521), for the
+     * consumption limits in #519. Account-wide and independent of any session, so
+     * it hangs off the driver rather than off {@link DriverSession}.
+     *
+     * Optional: an agent that can't report it omits the method entirely, the same
+     * way {@link DriverRateLimit} is omitted by drivers that can't emit it.
+     */
+    readQuota?(opts?: {
+        signal?: AbortSignal;
+    }): Promise<DriverQuota>;
+}
+/** How to boot a {@link DriverSession}. */
+export interface DriverStartOptions {
+    /** Absolute path to the workspace the agent reads and edits. */
+    cwd: string;
+    /**
+     * Role framing prepended to every prompt in this session (option A: personas
+     * are prompt-framing, not a separate agent). Maps to the agent's system prompt.
+     */
+    system?: string;
+    /** Model id to pass through when the wrapped agent supports selecting one. */
+    model?: string;
+    /** Abort the whole session; disposing kills the underlying process. */
+    signal?: AbortSignal;
+    /**
+     * Resume a prior agent session id (#720): seed the session so its very first
+     * prompt (with `resume`) continues that conversation instead of starting fresh.
+     * This is how a finished agent is revived from the dashboard — its captured session
+     * id is threaded here so the opening message lands with the full prior context.
+     * A driver that can't resume ignores it and runs fresh (the best-effort contract).
+     */
+    resumeSessionId?: string;
+    /**
+     * Observe the agent's *own* progress as it works. Black-box granularity: we
+     * forward these for visibility (the dashboard) but never branch control flow
+     * on them. Isolated: a throwing callback must not break the agent.
+     */
+    onEvent?: (event: DriverEvent) => void;
+}
+/** A booted agent session, bound to one workspace. */
+export interface DriverSession {
+    /** Stable id (the agent's own session id when it exposes one). */
+    readonly id: string;
+    /** Absolute workspace path the agent is bound to. */
+    readonly cwd: string;
+    /**
+     * Send one prompt, let the agent's built-in loop run to completion, and
+     * resolve with its final turn. Each call is a **fresh** invocation (fresh
+     * context per loop pass) unless a driver documents otherwise.
+     */
+    prompt(text: string, opts?: DriverPromptOptions): Promise<DriverTurn>;
+    /**
+     * Read a file the agent produced (the seam is the code). Optional: a driver
+     * whose workspace is not host-readable may omit it and rely on a runner.
+     */
+    readCode?(path: string): Promise<string>;
+    /** Tear the session down (kill the process, free resources). Idempotent. */
+    dispose(): Promise<void>;
+}
+/** Per-prompt overrides. */
+export interface DriverPromptOptions {
+    /** Extra framing for just this prompt, appended after the session `system`. */
+    system?: string;
+    /** Abort just this prompt (the in-flight invocation). */
+    signal?: AbortSignal;
+    /**
+     * Continue the agent's *previous* turn instead of starting fresh (#714): the
+     * live-chat path resumes the same session so the message lands in the ongoing
+     * conversation with full context. Best-effort — a driver that can't resume
+     * (or has no prior turn yet) runs a fresh invocation, the normal case. Honored
+     * by the Claude Code driver via `--resume <sessionId>`.
+     */
+    resume?: boolean;
+}
+/** The outcome of one {@link DriverSession.prompt} turn. */
+export interface DriverTurn {
+    /** The agent's final assistant text for this prompt. */
+    text: string;
+    /**
+     * The agent's session id for this turn, when it exposes one. The MVP
+     * persistence shortcut is to forward the agent's own transcript rather than
+     * keep our own store (#165), so this is the handle a UI links to.
+     */
+    sessionId?: string;
+    /** Token + cost accounting for this turn, when the agent reports it (#322). */
+    usage?: DriverUsage;
+}
+/**
+ * Token and cost accounting for one turn, as reported by the wrapped agent (#322).
+ * Claude Code emits this on its final `result` line; drivers that cannot report
+ * it simply omit it. Costs are whatever the agent computed, in USD.
+ *
+ * Tokens are the part every agent reports; the price is the part only some do
+ * (#540). So `costUsd` is optional and the tokens are not: Codex reports counts
+ * and no price, and an agent that can't price a turn reports the tokens it does
+ * know rather than nothing at all.
+ */
+export interface DriverUsage {
+    /**
+     * Cost of the turn in USD, when the agent prices its own turns. Omitted when it
+     * doesn't — never `0`, which would read as free rather than as unknown.
+     *
+     * Note this is a notional price under a subscription: the user pays a flat fee,
+     * and the agent reports what the turn would have cost on metered API pricing.
+     * What a subscription actually spends is quota, which {@link DriverQuota}
+     * carries and the consumption limits (#519) gate on.
+     */
+    costUsd?: number;
+    /** Non-cached input tokens. */
+    inputTokens: number;
+    /** Output tokens. */
+    outputTokens: number;
+    /** Tokens read from the prompt cache. */
+    cacheReadTokens: number;
+    /** Tokens written to the prompt cache. */
+    cacheCreationTokens: number;
+}
+/**
+ * Where the account's subscription quota stands, as reported by the wrapped
+ * agent (#517). Claude Code emits one of these per turn on its `stream-json`
+ * output; drivers that cannot report it simply omit it. This is the account
+ * limit, not this agent's spend — {@link DriverUsage} covers the latter.
+ */
+export interface DriverRateLimit {
+    /**
+     * Whether the account may still spend against this window: `allowed`,
+     * `allowed_warning`, or `rejected`. Left open rather than a union — only
+     * `allowed` has been observed, and a status we don't know is the signal we're
+     * capturing for, so it must surface rather than be dropped.
+     */
+    status: string;
+    /**
+     * Which quota window this reports on (`five_hour`, `seven_day`,
+     * `seven_day_opus`, `seven_day_sonnet`, `weekly`). Left open for the same
+     * reason: the agent adds windows as plans change.
+     */
+    window: string;
+    /** When the window resets, epoch **milliseconds** (the agent reports seconds). */
+    resetsAt: number;
+}
+/**
+ * One quota window and how much of it the account has burned (#521).
+ *
+ * The three concepts here are easy to confuse. {@link DriverUsage} is what *this
+ * run* spent. {@link DriverRateLimit} is a per-turn traffic light (are we still
+ * allowed to spend, and when does the window reset). This is the missing middle:
+ * the *proportion* of a window consumed, which is the only one of the three that
+ * can fill a progress bar.
+ */
+export interface DriverQuotaWindow {
+    /** The window's name exactly as the agent phrased it, e.g. `"Current session"`. */
+    label: string;
+    /**
+     * Normalized window, so callers can gate without matching on prose.
+     * `session` is Claude's 5-hour window, `week` its all-models week, and
+     * `week-model` a single model's week (Opus/Sonnet get their own).
+     *
+     * Note there is deliberately no `day`: Claude measures a 5-hour session and a
+     * week, and nothing per day (#519 was specced against a daily limit that does
+     * not exist).
+     */
+    kind: 'session' | 'week' | 'week-model' | 'unknown';
+    /** How much of the window is gone, 0-100. */
+    percentUsed: number;
+    /**
+     * When the window resets, as the agent worded it (`"Jul 18 at 7am
+     * (Asia/Jerusalem)"`). Prose, not a timestamp: the agent prints no year, so
+     * parsing it to an epoch would be guesswork. {@link DriverRateLimit.resetsAt}
+     * carries the exact epoch for the window it reports on.
+     */
+    resetsAtText?: string;
+}
+/**
+ * Why a quota read came back empty.
+ *
+ * The split that matters is transient vs authoritative. `fetch-failed`,
+ * `timeout` and `unrecognized` describe *this attempt* (the agent's own usage
+ * fetch can be refused upstream, with a penalty window), so a recent reading is
+ * still worth showing and asking again may work. The remaining reasons describe
+ * the account or the install and are a statement about the setup, so a retained
+ * reading must not outlive them.
+ */
+export type DriverQuotaUnavailableReason = 
+/** The agent's own usage fetch failed, e.g. refused upstream. Transient. */
+'fetch-failed'
+/** The agent did not answer in time. Transient. */
+ | 'timeout'
+/** The agent binary isn't installed or isn't on `PATH`. */
+ | 'agent-not-found'
+/** The account has no subscription quota to report (e.g. API-key auth). */
+ | 'no-subscription'
+/**
+ * The agent answered, but not in a shape we recognize (it reworded the readout).
+ *
+ * Transient, because it describes one answer rather than the install: an
+ * update notice printed ahead of the JSON, or empty stdout while the CLI
+ * swaps itself under a long-lived daemon, both land here and both are gone by
+ * the next read (#960).
+ */
+ | 'unrecognized';
+/** Whether a {@link DriverQuotaUnavailableReason} describes this attempt rather than the setup. */
+export declare function isTransientQuotaReason(reason: DriverQuotaUnavailableReason): boolean;
+/**
+ * Where the account's subscription quota stands (#521), as a whole reading.
+ *
+ * Modelled as available-or-not rather than as an empty window list, so a caller
+ * can't mistake "we couldn't ask" for "nothing is used".
+ */
+export type DriverQuota = {
+    available: true;
+    windows: DriverQuotaWindow[];
+} | {
+    available: false;
+    reason: DriverQuotaUnavailableReason;
+};
+/**
+ * A black-box progress event from the wrapped agent. We forward these to the
+ * dashboard for visibility but never gate on them: the loop gates on the code /
+ * outcome, not on which tool the agent reached for.
+ */
+export type DriverEvent = 
+/** A prompt was sent; the agent's loop is starting. */
+{
+    type: 'start';
+    prompt: string;
+}
+/**
+ * The agent announced its session id, at the start of the turn (#1322). `result` repeats it,
+ * but a turn that never settles — a manual Stop, an error, a kill — used to take the id down
+ * with it, and with it the agent's `claude --resume` handle. Telemetry consumes this one rather
+ * than forwarding it: the id is plumbing, not conversation.
+ */
+ | {
+    type: 'session';
+    sessionId: string;
+}
+/** An assistant text chunk streamed out. */
+ | {
+    type: 'text';
+    text: string;
+}
+/** The agent used a tool. We surface the name only, not the arguments. */
+ | {
+    type: 'action';
+    label: string;
+}
+/**
+ * The turn settled with this final text. `sessionLink` is the real URL of the session,
+ * for a driver whose session has one of its own (#1317) — the cloud hand-off — so the
+ * meta can link there instead of the generic entry point; drivers without one omit it.
+ * `anchorSha` is the hand-off anchor commit (#1601), for a driver whose session does its
+ * work on a branch of its own naming that this machine can only recognize later by
+ * ancestry; drivers whose work stays on the designated branch omit it.
+ */
+ | {
+    type: 'result';
+    text: string;
+    sessionId?: string;
+    sessionLink?: string;
+    anchorSha?: string;
+    usage?: DriverUsage;
+}
+/** Where the account's subscription quota stands (#517). */
+ | {
+    type: 'rate-limit';
+    limit: DriverRateLimit;
+}
+/** The agent (or its transport) errored. */
+ | {
+    type: 'error';
+    message: string;
+}
+/** Something the driver worked around, worth telling the user about (#778). */
+ | {
+    type: 'notice';
+    message: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/driver/types.d.ts.map

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

package/dist/driver/types.js

@@ -0,0 +1,5 @@
+/** Whether a {@link DriverQuotaUnavailableReason} describes this attempt rather than the setup. */
+export function isTransientQuotaReason(reason) {
+    return reason === 'fetch-failed' || reason === 'timeout' || reason === 'unrecognized';
+}
+//# sourceMappingURL=types.js.map

package/dist/driver/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/driver/types.ts"],"names":[],"mappings":"AAgPA,mGAAmG;AACnG,MAAM,UAAU,sBAAsB,CAAC,MAAoC;IACzE,OAAO,MAAM,KAAK,cAAc,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,cAAc,CAAA;AACvF,CAAC"}

package/dist/driver-cli.d.ts

@@ -0,0 +1,61 @@
+import { type ClaudeCodeDriverOptions, type Driver } from 'agent-driver';
+import { type DriverName } from './driver-names.js';
+/**
+ * Which agent drives an agent (#542). Each is a whole coding-agent CLI the user
+ * already pays for, driven on their own subscription with no API key (#495).
+ *
+ * The names live in the node-free `agent-names.ts` so the dashboard and the registry read
+ * the same list without touching the driver layer; this module adds what only the node side
+ * needs (binaries, drivers). Historical import sites keep working via these re-exports.
+ */
+export { DRIVERS, isDriverName, driverFromImpl, DRIVER_LABELS, type DriverName } from './driver-names.js';
+/**
+ * How an agent CLI answers "am I logged in?", and what fixes it when the answer is no (#1326).
+ *
+ * The exit code cannot decide this on its own: `claude auth status` prints its answer as JSON
+ * and exits 0 either way. So each agent reads its own answer, and anything unrecognised comes
+ * back `undefined` (could not say) rather than `false`. That asymmetry is deliberate. A wrong
+ * "you are logged out" blocks a setup that works, which is worse than the silent dead agent this
+ * exists to prevent, so only a CLI that says no out loud fails preflight.
+ */
+export interface AgentAuthSpec {
+    /** The args that make the CLI report its login state, e.g. `auth status`. */
+    args: readonly string[];
+    /** Reads the CLI's answer out of its output. `undefined` when it could not say. */
+    loggedIn: (result: {
+        ok: boolean;
+        output: string;
+    }) => boolean | undefined;
+    /** The one command that fixes a logged-out CLI. */
+    fix: string;
+}
+/** What we know about an agent before we run it. */
+export interface DriverSpec {
+    /** How to say it in a sentence, e.g. "Claude Code". */
+    label: string;
+    /** The CLI binary, resolved on PATH. */
+    bin: string;
+    /** Shown when preflight cannot find {@link bin}. */
+    installHint: string;
+    /** How preflight asks the CLI whether it is logged in (#1326). */
+    auth: AgentAuthSpec;
+}
+/** The agents we can drive, and what each can tell us about itself. */
+export declare const DRIVER_SPECS: Record<DriverName, DriverSpec>;
+/** Options for {@link createDriver}. */
+export interface CreateDriverOptions {
+    driver: DriverName;
+    /** Claude Code driver options. Ignored by any other agent, which has its own. */
+    claudeOpts?: ClaudeCodeDriverOptions;
+}
+/**
+ * Build the {@link Driver} for the picked driver name — the one place a session turns
+ * the choice into a live implementation.
+ *
+ * Codex takes none of the Claude options: its sandbox is its own flag rather
+ * than a permission mode, and it has no MCP config for `--browser`. Those are
+ * dropped here and reported at the call site, so a flag that cannot apply says
+ * so rather than looking honored.
+ */
+export declare function createDriver(opts: CreateDriverOptions): Driver;
+//# sourceMappingURL=driver-cli.d.ts.map

package/dist/driver-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-cli.d.ts","sourceRoot":"","sources":["../src/driver-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,uBAAuB,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAA;AACvG,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAElE;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEzG;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,mFAAmF;IACnF,QAAQ,EAAE,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,GAAG,SAAS,CAAA;IAC1E,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,IAAI,EAAE,aAAa,CAAA;CACpB;AAED,uEAAuE;AACvE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,CAkCvD,CAAA;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAA;IAClB,iFAAiF;IACjF,UAAU,CAAC,EAAE,uBAAuB,CAAA;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAO9D"}

package/dist/driver-cli.js

@@ -0,0 +1,66 @@
+import { ClaudeCodeDriver, CodexDriver } from 'agent-driver';
+import { DRIVER_LABELS } from './driver-names.js';
+/**
+ * Which agent drives an agent (#542). Each is a whole coding-agent CLI the user
+ * already pays for, driven on their own subscription with no API key (#495).
+ *
+ * The names live in the node-free `agent-names.ts` so the dashboard and the registry read
+ * the same list without touching the driver layer; this module adds what only the node side
+ * needs (binaries, drivers). Historical import sites keep working via these re-exports.
+ */
+export { DRIVERS, isDriverName, driverFromImpl, DRIVER_LABELS } from './driver-names.js';
+/** The agents we can drive, and what each can tell us about itself. */
+export const DRIVER_SPECS = {
+    claude: {
+        label: DRIVER_LABELS.claude,
+        bin: 'claude',
+        installHint: 'install Claude Code and make sure `claude` is on your PATH: https://claude.com/claude-code',
+        auth: {
+            args: ['auth', 'status'],
+            // Prints JSON (`{"loggedIn": true, "authMethod": ...}`) and exits 0 either way, so the
+            // flag is the answer and the exit code is not. A version too old to know the subcommand
+            // prints usage instead, which parses as nothing and correctly reads as "could not say".
+            loggedIn: ({ output }) => {
+                try {
+                    const parsed = JSON.parse(output);
+                    const value = parsed?.loggedIn;
+                    return typeof value === 'boolean' ? value : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            fix: 'claude auth login',
+        },
+    },
+    codex: {
+        label: DRIVER_LABELS.codex,
+        bin: 'codex',
+        installHint: 'install the Codex CLI and make sure `codex` is on your PATH: https://developers.openai.com/codex/cli',
+        auth: {
+            args: ['login', 'status'],
+            // Answers in a sentence rather than JSON: "Logged in using ChatGPT", or a "Not logged in".
+            // The negative is tested first, since it contains the positive as a substring.
+            loggedIn: ({ output }) => (/not logged in/i.test(output) ? false : /logged in/i.test(output) ? true : undefined),
+            fix: 'codex login',
+        },
+    },
+};
+/**
+ * Build the {@link Driver} for the picked driver name — the one place a session turns
+ * the choice into a live implementation.
+ *
+ * Codex takes none of the Claude options: its sandbox is its own flag rather
+ * than a permission mode, and it has no MCP config for `--browser`. Those are
+ * dropped here and reported at the call site, so a flag that cannot apply says
+ * so rather than looking honored.
+ */
+export function createDriver(opts) {
+    switch (opts.driver) {
+        case 'codex':
+            return new CodexDriver();
+        case 'claude':
+            return new ClaudeCodeDriver(opts.claudeOpts ?? {});
+    }
+}
+//# sourceMappingURL=driver-cli.js.map

package/dist/driver-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-cli.js","sourceRoot":"","sources":["../src/driver-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAA6C,MAAM,cAAc,CAAA;AACvG,OAAO,EAAE,aAAa,EAAmB,MAAM,mBAAmB,CAAA;AAElE;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAmB,MAAM,mBAAmB,CAAA;AAgCzG,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAmC;IAC1D,MAAM,EAAE;QACN,KAAK,EAAE,aAAa,CAAC,MAAM;QAC3B,GAAG,EAAE,QAAQ;QACb,WAAW,EAAE,4FAA4F;QACzG,IAAI,EAAE;YACJ,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;YACxB,uFAAuF;YACvF,wFAAwF;YACxF,wFAAwF;YACxF,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;gBACvB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;oBAC1C,MAAM,KAAK,GAAI,MAAyC,EAAE,QAAQ,CAAA;oBAClE,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;gBACvD,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,SAAS,CAAA;gBAClB,CAAC;YACH,CAAC;YACD,GAAG,EAAE,mBAAmB;SACzB;KACF;IACD,KAAK,EAAE;QACL,KAAK,EAAE,aAAa,CAAC,KAAK;QAC1B,GAAG,EAAE,OAAO;QACZ,WAAW,EAAE,sGAAsG;QACnH,IAAI,EAAE;YACJ,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;YACzB,2FAA2F;YAC3F,+EAA+E;YAC/E,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YAChH,GAAG,EAAE,aAAa;SACnB;KACF;CACF,CAAA;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,OAAO;YACV,OAAO,IAAI,WAAW,EAAE,CAAA;QAC1B,KAAK,QAAQ;YACX,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAA;IACtD,CAAC;AACH,CAAC"}