@eddyskywalker/dsh-chatgpt-subscription 0.8.4 → 0.9.0

package/lib/types/host/claude/adapter.d.ts

@@ -0,0 +1,267 @@
+/**
+ * DSH adapter for the `claude-subscription` route.
+ *
+ * This file is the only place the harness talks to. It owns: the model catalog
+ * the picker sees, the per-model resolution DSH asks for before a call, the one
+ * request loop, and the mapping of a failed response onto a DSH failure. It owns
+ * NO credential lifecycle of its own — refreshing is oauth.ts's job, storage is
+ * token-store.ts's job, the wire is client.ts's, the body and the SSE parse are
+ * mapper.ts's — and it re-implements none of them.
+ *
+ * ---------------------------------------------------------------------------
+ * 1. THE TWO LIMITS ON ACCOUNT ROTATION (the part that is easy to get wrong)
+ * ---------------------------------------------------------------------------
+ *
+ * With a pool installed, one failed response may be retried on a DIFFERENT
+ * account. Two rules bound that, and both are load-bearing:
+ *
+ * (a) WHAT may rotate. Only two conditions are attributable to one account:
+ *     a credential verdict (that account's token is dead) and an
+ *     ACCOUNT-SCOPED rate limit (that account's own usage window is spent).
+ *     Everything else — a global rate limit, an `overloaded_error`, a generic
+ *     5xx — is shared by every account behind the same gateway, so rotating
+ *     against it burns the pool and can loop. client.ts's classifyFailure
+ *     already draws exactly this line (its `accountScoped` field), so the
+ *     decision reads that rather than re-deriving it from headers here.
+ *
+ * (b) HOW FAR. At most {@link MAX_ATTEMPTS} requests per stream, ever. The loop
+ *     is additionally driven by the pool's `hasAnotherAvailableAccount`, but
+ *     that is a pool property, not a bound: a pool that keeps answering "yes"
+ *     would otherwise be retried forever.
+ *
+ * And one hard rule that outranks both: NO ROTATION ONCE ANYTHING HAS REACHED
+ * THE CALLER. A retried request would repeat text the user has already read and
+ * re-issue a tool call that may already have executed. Rotation happens only
+ * before the response body is touched, which is where a fresh request is still
+ * free; once the first chunk has been yielded, a failure is SURFACED instead of
+ * retried. That rule is stated once in {@link shouldRotateAccount} so it cannot
+ * be quietly lost by a later reordering of this file.
+ *
+ * ---------------------------------------------------------------------------
+ * 2. ONE TOOL-NAME TABLE FOR BOTH DIRECTIONS
+ * ---------------------------------------------------------------------------
+ *
+ * The body renames every offered tool to its canonical wire spelling
+ * ('read' -> 'Read'), and the response side maps that spelling back to what the
+ * caller declared. Two independent calls to yaml's translation builder would
+ * produce two DIFFERENT tables — a collision that disables normalization on one
+ * side only, or a set that changed between build and parse — and the visible
+ * failure is a tool call dispatched to a tool the caller never offered. So the
+ * table is built once, per request, and handed to BOTH the body builder and
+ * `createStreamState`.
+ *
+ * ---------------------------------------------------------------------------
+ * 3. THE PRE-EXISTING SINGLE-CREDENTIAL PATH, AND THE THIN STORE ADAPTER
+ * ---------------------------------------------------------------------------
+ *
+ * Without a pool this route serves the account the credential document offers
+ * first — or the one the user pinned in `selectedAccountId`, which the pool
+ * mirrors as its primary. oauth.ts's `ensureAccessToken` was written against a
+ * two-method `{ read, write }` store because it must not learn the document
+ * layout, while FileCredentialStore is a multi-account document keyed by an
+ * immutable `internalId`. {@link ClaudeAccountTokenStore} is that seam: it
+ * presents exactly one account's credentials as the two methods, and records
+ * WHICH record it handed out so a rotated refresh token is written back into
+ * that record and not into whichever account happens to be first by the time
+ * the refresh lands.
+ *
+ * ---------------------------------------------------------------------------
+ * 4. FAILURE CLASSIFICATION
+ * ---------------------------------------------------------------------------
+ *
+ * client.ts classifies; this file only decides which DSH code that verdict
+ * becomes, and what the user is told:
+ *
+ * - `credential` -> INVALID_CREDENTIAL (sign in again);
+ * - an account-scoped or global limit -> RATE_LIMIT;
+ * - `overloaded` and `server` -> SERVER;
+ * - `request` -> PROVIDER_ERROR;
+ * - `network` -> TRANSPORT.
+ *
+ * A reported-client-version rejection is a REQUEST problem even though it
+ * arrives as a 400 that mentions the client: it must NOT sign the user out, and
+ * it has a real remedy (raise the reported version), so it is handled
+ * explicitly with that remedy in the message.
+ *
+ * ---------------------------------------------------------------------------
+ * 5. ASSUMPTIONS AND JUDGEMENT CALLS
+ * ---------------------------------------------------------------------------
+ *
+ * - A1. The pool seam is typed STRUCTURALLY here rather than against
+ *   './account-pool.ts'. That file is written by a sibling chunk of this line;
+ *   importing it before it exists would make this adapter uncompilable, and
+ *   importing it afterwards changes nothing, because the only methods used are
+ *   the five in {@link ClaudeAccountPoolLike}.
+ * - A2. The live `GET /v1/models` listing is NOT read on the request path. It
+ *   is authoritative for the context window alone (see client.ts), and the only
+ *   model fact the body depends on — the thinking form — comes from the frozen
+ *   catalog. Loading it per request would add a cached round trip that cannot
+ *   change a byte of the body.
+ * - A3. A 429 with no `retry-after` and no reset instant cools the account for
+ *   {@link POOL_COOLDOWN_MS}. That is deliberately shorter than the 5-hour
+ *   window: an account parked for hours after a burst limit recovers would cost
+ *   the user the pool, while a too-short cooldown costs one rotation.
+ * - A4. Adoption (adopt.ts) is not handled here. An adopted Claude Code
+ *   credential is a pool concern — the pool is what must refuse to refresh it —
+ *   and this adapter only ever sees the credential the pool or the document
+ *   hands it.
+ * - A5. The enabled-model rule is stated locally in
+ *   {@link resolveEnabledModelIds} because './routes.ts' (the sibling chunk that
+ *   owns the settings card for this line) does not exist yet. It mirrors the
+ *   sibling providers' rule exactly; once routes.ts lands it is the natural home
+ *   for this function and the two should be one.
+ */
+import { LlmAdapter, LlmError, ReasoningEffortId, type GenerateOptions, type LlmModelInfo, type LlmProviderInfo, type LlmResolvedModelInfo, type PreparedAdapterCall, type ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import { PROVIDER_ID, PROVIDER_NAME } from './types.ts';
+import { FileCredentialStore, FileModelSettingsStore, type ClaudeCredentials, type ClaudePreferenceStore } from './token-store.ts';
+import { type ClaudeModelEntry } from './model-catalog.ts';
+import { type ClaudeFailure } from './client.ts';
+import { type AttachmentImageReader } from './mapper.ts';
+/**
+ * Cooldown a 429 imposes when the service names no reset instant.
+ *
+ * Deliberately far shorter than the 5-hour window it may be reporting: the
+ * accurate wait arrives as `retry-after` or as the ISO instant in the error
+ * message, and this is only the fallback for a response that states neither.
+ */
+export declare const POOL_COOLDOWN_MS: number;
+/**
+ * The pool surface this adapter uses, stated structurally.
+ *
+ * See module note A1: './account-pool.ts' is a sibling chunk's file, and typing
+ * against the five methods actually called keeps this adapter compilable
+ * whether or not that file has landed.
+ */
+export interface ClaudeAccountPoolLike {
+    getEffectiveAccount(excludeIds?: ReadonlySet<string>, fetchFn?: typeof fetch): Promise<{
+        account: {
+            id: string;
+        };
+        credentials: ClaudeCredentials;
+    }>;
+    hasAnotherAvailableAccount(triedAccountIds: ReadonlySet<string>): Promise<boolean>;
+    markCooldown(accountId: string, durationMs: number, reason: string): Promise<void>;
+    markAuthFailed(accountId: string, reason: string): Promise<void>;
+}
+export interface ClaudeAdapterOptions {
+    fetchFn?: typeof fetch;
+    /** Attachment seam: durable images become inline bytes for one request. */
+    attachments?: AttachmentImageReader;
+    /** Live catalog loader seam; defaults to this account's managed listing. */
+    loadCatalog?: (credentials: ClaudeCredentials) => Promise<readonly ClaudeModelEntry[]>;
+    /**
+     * Multi-account pool this adapter rotates through.
+     *
+     * Absent leaves the line on its single-credential path, which is what a
+     * headless test and any caller that predates the pool use.
+     */
+    accountPool?: ClaudeAccountPoolLike;
+}
+export declare class ClaudeAdapter extends LlmAdapter {
+    private readonly store;
+    private readonly modelSettings;
+    private readonly preferences?;
+    private readonly options;
+    /** Null keeps the pre-pool single-credential path. */
+    private readonly accountPool;
+    constructor(store?: FileCredentialStore, modelSettings?: FileModelSettingsStore, preferences?: ClaudePreferenceStore | undefined, options?: ClaudeAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): ResolvedRetryPolicy;
+    /**
+     * This route prices no visual tokens.
+     *
+     * The subscription bills in subscription windows rather than per image, so
+     * there is no per-image price to state and the harness's neutral estimate is
+     * the honest answer. Stated explicitly, as every sibling line does, so the
+     * absence is a decision rather than an unimplemented method.
+     */
+    imageRequestPricing(): undefined;
+    private settings;
+    /**
+     * The account record the single-credential path serves.
+     *
+     * The pinned account wins while it exists in the document — that is the
+     * account the user chose on the card, and honouring it here keeps the
+     * single-credential path agreeing with what the card shows. Otherwise the
+     * document is in insertion order and the first record is the primary one,
+     * which is also what the pool mirrors into this store.
+     */
+    private primaryAccount;
+    /**
+     * Catalog for one credential: the account's live listing, or the shipped table.
+     *
+     * client.ts's loader never rejects and never returns empty — it answers with
+     * the shipped table when the call fails, precisely so a failed listing cannot
+     * become the hard "model must be in the catalog" gate. The guard here is for a
+     * caller-supplied seam that does neither.
+     */
+    private catalog;
+    listModels(provider?: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, modelId: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Read one credential for this attempt.
+     *
+     * Pooled and pre-pool are two different questions. With a pool this is a
+     * ROUTING decision — which account should serve this request — answered
+     * through cooldowns, auth status and the rotation strategy; the pool also owns
+     * refreshing the credential it hands back. Without one there is exactly one
+     * account, so the question is whether its token is still usable, and
+     * ensureAccessToken answers it single-flightedly (the refresh token rotates,
+     * so two callers must not each spend it).
+     */
+    private resolveCredential;
+    /**
+     * One request attempt, after the credential for it has been chosen.
+     *
+     * A SEPARATE function from the rotation loop on purpose: importing
+     * './account-pool.ts' would make this adapter uncompilable while that sibling
+     * file is still being written (see the module note), so the rotation loop is
+     * driven by {@link shouldRotateAccount}, which bypasses the pool ENTIRELY when
+     * no credentials were resolved for it.
+     */
+    private attemptRequest;
+    private requestStream;
+}
+/**
+ * Effort to materialize as this route's default, or nothing.
+ *
+ * Membership, not convergence: the catalog's ladder IS the wire vocabulary, and
+ * a configured level outside it is dropped rather than moved onto a neighbour.
+ * Moving it would silently change how hard the model thinks, and the four
+ * thinking forms each carry the effort differently, so there is no single
+ * correct neighbour to pick. 'xhigh' and 'max' are real rungs on this route and
+ * pass through untouched.
+ */
+export declare function resolveDefaultReasoningEffort(efforts: readonly string[], configuredEffort?: string | null): ReasoningEffortId | undefined;
+/**
+ * Whether one failed response may be retried on another account.
+ *
+ * Only two conditions qualify, and the reason is the same for both: they are
+ * properties of ONE account. A credential verdict means that account's token is
+ * finished; an ACCOUNT-SCOPED rate limit means that account's own window is
+ * spent. A global rate limit, an overload and a generic 5xx are shared by every
+ * account behind the same gateway — rotating against them burns the pool and can
+ * loop, because the next account fails identically.
+ *
+ * The one absolute refusal is `outputStarted`: after the first chunk has
+ * reached the caller, a retry would repeat text and re-issue a tool call, so the
+ * failure is surfaced instead.
+ */
+export declare function shouldRotateAccount(failure: ClaudeFailure, outputStarted: boolean): boolean;
+/** How long a rate-limited account stays out of rotation. */
+export declare function cooldownMsFor(failure: ClaudeFailure, now?: number): number;
+/** The DSH failure code one classified failure becomes. */
+export declare function codeForFailure(failure: ClaudeFailure): string;
+/**
+ * Turn one classified failure into the DSH error the caller sees.
+ *
+ * The facts the harness needs ride along: the HTTP status, and the delay the
+ * provider asked for, which is where the retry policy reads its backoff from.
+ * An unreadable status (0 from a transport failure) is omitted rather than
+ * passed on, because LlmError validates it as a real HTTP status.
+ */
+export declare function toLlmError(failure: ClaudeFailure): LlmError;
+export { PROVIDER_ID, PROVIDER_NAME };
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/host/claude/adapter.d.ts.map

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

package/lib/types/host/claude/adopt.d.ts

@@ -0,0 +1,292 @@
+/**
+ * OPT-IN adoption of a pre-existing Claude Code sign-in.
+ *
+ * WHAT THIS IS FOR. A user who already runs the unmodified Claude Code client is
+ * already signed in to the very subscription this provider serves. Asking them
+ * to sign in a second time is pure friction, so this module offers the one thing
+ * that removes it: reading back the credential Claude Code itself stored. It is
+ * opt-in — nothing here runs until the user asks for it.
+ *
+ * ---------------------------------------------------------------------------
+ * RULE 1 — THIS MODULE NEVER WRITES. IT IS A READER, AND ONLY A READER.
+ * ---------------------------------------------------------------------------
+ * It must not create, modify, move or delete any file belonging to Claude Code.
+ * No file this module touches is ever opened for writing, no directory is
+ * created, nothing is renamed and nothing is unlinked. The guarantee is
+ * structural rather than a promise in prose: the module imports exactly two
+ * functions BY NAME from 'node:fs/promises' — readFile and stat — instead of the
+ * whole namespace, so introducing a write would require a visible change to the
+ * import list, which is the line a reviewer reads first. Nothing exported here
+ * writes. The tests assert the stronger, observable form of the rule: a
+ * credential file's bytes, size and mtime are identical before and after both
+ * entry points run, and its directory gains no entries.
+ *
+ * ---------------------------------------------------------------------------
+ * RULE 2 — PRESENCE AND CONTENT ARE TWO SEPARATE FUNCTIONS
+ * ---------------------------------------------------------------------------
+ * claudeCodeCredentialPresence() is cheap enough to call on plugin startup and
+ * answers only yes/no: it stats candidates and never opens one for reading. It
+ * exists so the settings card can offer the import before the user has agreed to
+ * it, and so a user who never opts in never has their token read at all.
+ *
+ * readClaudeCodeCredentials() is the full read, and it is called only AFTER the
+ * user explicitly opts in. Keeping the two apart is the whole point: a startup
+ * path that slurped the file "just in case" would make the opt-in decorative.
+ *
+ * ---------------------------------------------------------------------------
+ * RULE 3 — AN ADOPTED CREDENTIAL IS A SNAPSHOT, AND THIS PLUGIN NEVER REFRESHES IT
+ * ---------------------------------------------------------------------------
+ * An adopted credential is used only while its own accessToken is still valid.
+ * Once it is expired we report it as expired and tell the user to sign in again
+ * in Claude Code and re-adopt. That is deliberate, not a gap:
+ *
+ *   Claude Code's refresh token is ROTATING — every refresh both consumes the
+ *   stored refresh token and issues a new one. Two processes refreshing the same
+ *   grant therefore invalidate each other: whoever loses the race holds a token
+ *   the server has already retired, and the user ends up signed OUT of Claude
+ *   Code by this plugin's good intentions. An in-process single-flight cannot fix
+ *   that, because the race is across PROCESSES: this plugin and Claude Code are
+ *   separate programs with separate memories, and the only shared state between
+ *   them is the file — which this module must not write back into (Rule 1).
+ *
+ * So the honest contract is: borrow the access token for as long as Claude Code
+ * itself vouched for it, and never touch the refresh token. Expiry is therefore
+ * part of the adoption decision rather than a detail — see
+ * {@link isAdoptedCredentialExpired}.
+ *
+ * The marker the pool chunk must honour is the literal 'adopted: true' on every
+ * returned snapshot, plus {@link isAdoptedClaudeCredential}; an account carrying
+ * it must be treated as read-only, non-refreshable and disposable. There is
+ * deliberately no refresh function in this module to find in the first place.
+ *
+ * ---------------------------------------------------------------------------
+ * RULE 4 — AN UNRECOGNISED SHAPE YIELDS undefined, NEVER AN EXCEPTION
+ * ---------------------------------------------------------------------------
+ * The card shows 'unrecognised local sign-in format' for undefined, which is a
+ * far better outcome than a thrown error escaping into the settings route.
+ * Nothing is guessed: a document missing either token, a claudeAiOauth that is
+ * not an object, an unreadable or unparsable file — all of them are undefined.
+ * Extra and unknown fields are ignored rather than rejected, so a future Claude
+ * Code that adds one does not break adoption.
+ *
+ * THE TRAP THIS PARSER EXISTS TO AVOID. The credential document is NOT a flat bag
+ * of tokens. The same file also carries MCP server sign-ins under
+ * mcpOAuth.*.accessToken, and those are DIFFERENT tokens for DIFFERENT services.
+ * A "find the first accessToken anywhere in the JSON" scan silently picks
+ * whichever one the serializer happened to emit first, which is how an MCP token
+ * ends up presented to the Messages API as the user's subscription credential.
+ * The read is therefore a direct, specific lookup of claudeAiOauth.accessToken —
+ * never a tree walk — and the test suite holds a fixture containing BOTH tokens
+ * and asserts which one comes back.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT COULD NOT BE VERIFIED, AND IS THEREFORE NOT CLAIMED
+ * ---------------------------------------------------------------------------
+ * The file layout below (a credential file named .credentials.json inside the
+ * config home, JSON of the shape { "claudeAiOauth": { accessToken, refreshToken,
+ * expiresAt, scopes, subscriptionType } } with expiresAt in EPOCH MILLISECONDS)
+ * is assembled from secondary sources. This machine has NO Claude Code
+ * installation and NO such file — all candidate paths were checked and every one
+ * is absent — so this reader is proven by CONSTRUCTION against fixtures and NOT
+ * by a live read of a real client's file. A layout difference in a future Claude
+ * Code would surface as 'unrecognised local sign-in format' rather than as a
+ * wrong token, because the parser is written to refuse rather than to improvise.
+ *
+ * A KNOWN NON-GOAL: on macOS Claude Code also keeps an entry in the login
+ * Keychain (reported as service 'Claude Code-credentials'). This module does NOT
+ * read it. The service name is unverified — a third-party guide and the real
+ * client disagree about it — and asking the Keychain for a name that is not the
+ * real one either finds nothing or, worse, finds somebody else's item. A file
+ * path that can be printed in the UI and inspected by the user beats a guessed
+ * Keychain query, so the Keychain is left strictly alone.
+ */
+import type { ClaudeCredentials } from './token-store.ts';
+/**
+ * Environment variable that relocates Claude Code's config directory.
+ *
+ * Highest precedence, and honoured exactly as the client honours it: when it is
+ * set to a non-blank value it names the config home, whatever the platform's
+ * conventional location happens to be. This is also what makes the whole module
+ * testable without touching a developer's real profile.
+ */
+export declare const CLAUDE_CONFIG_DIR_ENV = "CLAUDE_CONFIG_DIR";
+/** File name of the credential document inside the config home. */
+export declare const CLAUDE_CODE_CREDENTIAL_FILE = ".credentials.json";
+/**
+ * Top-level key holding the subscription sign-in.
+ *
+ * Named as a constant because the specificity of this key IS the defence
+ * described in the module comment: the read addresses this key, not the first
+ * token it can find anywhere in the document.
+ */
+export declare const CLAUDE_CODE_CREDENTIAL_KEY = "claudeAiOauth";
+/** Where an adopted snapshot came from, for the card and for the pool record. */
+export declare const CLAUDE_CODE_CREDENTIAL_SOURCE = "claude-code";
+/**
+ * Expiry value stamped on a credential that states no usable one.
+ *
+ * Epoch zero, and it is a deliberate choice over "now" or "Infinity". Infinity
+ * would turn a missing field into a credential that never expires — the exact
+ * inversion of the safe reading, because a credential whose validity cannot be
+ * established must not be used. Epoch zero is unambiguous, survives a JSON round
+ * trip, and compares as expired against any clock a user's machine can hold, so
+ * a damaged document degrades into "expired, sign in again" instead of into a
+ * request carrying a token nobody vouched for.
+ */
+export declare const UNKNOWN_CREDENTIAL_EXPIRY = 0;
+/**
+ * What the user is told when an adopted credential has aged out.
+ *
+ * Exported so the settings card and the pool report the same sentence, and so the
+ * instruction is stated once: re-sign-in happens in CLAUDE CODE, not here, and
+ * the import has to be repeated afterwards.
+ */
+export declare const ADOPTED_CREDENTIAL_EXPIRED_HINT: string;
+/** One adopted credential: the store's own credential shape plus its provenance. */
+export interface ClaudeCodeAdoptedCredential {
+    /**
+     * The pool marker. Literal true on every snapshot this module returns.
+     *
+     * A discriminant rather than a description: a pool chunk that stores this
+     * record must refuse to refresh it, and a boolean it can test is harder to
+     * overlook than a comment it can read past.
+     */
+    readonly adopted: true;
+    /** Which local sign-in this was taken from. */
+    readonly source: typeof CLAUDE_CODE_CREDENTIAL_SOURCE;
+    /** The exact file it was read from, so the card can name it. */
+    readonly sourcePath: string;
+    /** The credential in the store's own shape, ready to be persisted by the caller. */
+    readonly credentials: ClaudeCredentials;
+}
+/** Answer to the startup question: is there anything to adopt? */
+export interface ClaudeCodeCredentialPresence {
+    /** Whether a candidate exists. Says nothing about whether it is usable. */
+    present: boolean;
+    /** The first candidate that exists, or null when none does. */
+    path: string | null;
+    /**
+     * Every candidate consulted, in precedence order, whether or not it existed.
+     *
+     * Returned so the card can print the exact list it looked at — the difference
+     * between "not found" and "your client stores it somewhere else" is invisible
+     * to a user who is only told the first path.
+     */
+    searched: string[];
+}
+/**
+ * Claude Code's config home.
+ *
+ * The environment override wins whenever it is set to a non-blank value — a blank
+ * or whitespace-only variable is treated as unset rather than as "the directory
+ * whose name is empty", which on Windows would resolve to a drive-relative path.
+ * Otherwise the conventional home/.claude directory is used, os.homedir() being
+ * the same %USERPROFILE% on Windows and ~ on POSIX that the client itself uses.
+ *
+ * Read at CALL time rather than captured in a module constant: a test (or an
+ * embedder) that sets the variable after import must see the change.
+ */
+export declare function claudeConfigDir(): string;
+/**
+ * Every path this module will look at, most authoritative first.
+ *
+ * The FIRST entry is always the config home from {@link claudeConfigDir} — the
+ * location the client is documented to use — so the card can print it as "the"
+ * path.
+ *
+ * The conventional home/.claude/.credentials.json follows as a FALLBACK whenever
+ * it is not already the first entry. Judgement call, stated plainly: treating the
+ * environment override as absolutely exclusive would make a stale or
+ * freshly-created override directory — a user who once pointed the variable at a
+ * scratch profile and forgot — report "no sign-in found" while a perfectly good
+ * one sits in the conventional location. The fallback costs one stat, is
+ * consulted only when the earlier candidate yields nothing usable, and the file
+ * actually used is always reported back in
+ * {@link ClaudeCodeAdoptedCredential.sourcePath}. The residual risk is adopting a
+ * snapshot belonging to a different profile than the one Claude Code is currently
+ * using; it is bounded by the fact that such a snapshot is only ever used while
+ * its own access token is unexpired, and it is visible to the user because the
+ * source path is shown.
+ *
+ * A pure function — no filesystem access at all — so it is safe to call just to
+ * render the card, and so its precedence is testable without touching a disk.
+ */
+export declare function claudeCodeCredentialPaths(): string[];
+/**
+ * Is there a local Claude Code sign-in to offer?
+ *
+ * Safe on plugin startup: this NEVER opens a candidate for reading, so a user who
+ * never opts in never has the credential's contents touched — not by this
+ * function, not by the route that renders the card. Only stat runs, which reveals
+ * existence and timestamps and nothing else.
+ *
+ * Deliberately NOT reported here: whether the file is valid, expired, or even
+ * JSON. Answering that would require the read this function exists to avoid, and
+ * the card does not need it — validity is answered by the read, after opt-in, and
+ * lands on the card as either a credential or 'unrecognised local sign-in
+ * format'.
+ *
+ * paths is injectable so tests drive it against fixtures instead of a real
+ * profile; production callers take the default.
+ */
+export declare function claudeCodeCredentialPresence(paths?: readonly string[]): Promise<ClaudeCodeCredentialPresence>;
+/**
+ * Map one parsed credential document onto the store's credential shape.
+ *
+ * Pure and exported so the format rules can be tested without a filesystem, and
+ * so a later chunk that reads the document from somewhere else (a backup, a
+ * pasted blob) reuses the one set of rules instead of growing a second, drifting
+ * copy.
+ *
+ * Returns undefined for every shape it does not recognise, and never throws — see
+ * Rule 4 in the module comment. The gate is deliberately narrow: the document must
+ * be a JSON object, claudeAiOauth must be an object, and it must carry BOTH a
+ * non-empty accessToken and a non-empty refreshToken. An access token alone is not
+ * adopted because the store's record is a sign-in, not a bare token: its identity
+ * aliases are derived from the refresh token, and a record with an empty one would
+ * mint an identity that matches nothing and can never be re-recognised.
+ *
+ * The MCP trap is handled by construction here: value.claudeAiOauth is addressed
+ * directly and no other key of the document is ever traversed, so whatever
+ * mcpOAuth holds cannot reach the result.
+ */
+export declare function parseAdoptedClaudeCredential(value: unknown, sourcePath: string): ClaudeCodeAdoptedCredential | undefined;
+/**
+ * Read the local Claude Code sign-in; the first usable candidate wins.
+ *
+ * ONLY call this after the user has explicitly opted in — see the module comment.
+ *
+ * Never throws and never rejects: an absent file, an unreadable file, a file that
+ * is not JSON, and a JSON document of an unrecognised shape all produce
+ * undefined, which the card renders as 'unrecognised local sign-in format'. A
+ * settings route must not be able to fail because a user's file was mid-write.
+ *
+ * A candidate that EXISTS but cannot be parsed does not stop the search; the next
+ * candidate is tried. That trade-off is stated in {@link claudeCodeCredentialPaths}
+ * and the file actually used is reported in the result, so a fallback is always
+ * visible rather than silent.
+ */
+export declare function readClaudeCodeCredentials(paths?: readonly string[]): Promise<ClaudeCodeAdoptedCredential | undefined>;
+/**
+ * Whether a value carries the adopted marker.
+ *
+ * The predicate the pool chunk tests a stored account with before deciding whether
+ * it may ever be refreshed. It recognises this module's snapshot and nothing else:
+ * a plain store credential has no 'adopted' field and must NOT be mistaken for
+ * one, because treating a plugin-owned account as a disposable snapshot would
+ * discard an account the user added here.
+ */
+export declare function isAdoptedClaudeCredential(value: unknown): value is ClaudeCodeAdoptedCredential;
+/**
+ * Whether an adopted credential's access token is already unusable.
+ *
+ * A structural mirror of the expiry test the OAuth module applies to its own
+ * credentials (expiresAt - Date.now() > 0), asked of an adopted snapshot so the
+ * pool can refuse it WITHOUT ever reaching for a refresh this module deliberately
+ * does not perform. A non-finite expiresAt counts as expired, matching
+ * {@link finiteEpochMs}: no field, no validity.
+ *
+ * now is injectable so a test can reason about a fixed clock.
+ */
+export declare function isAdoptedCredentialExpired(credential: Pick<ClaudeCodeAdoptedCredential, 'credentials'>, now?: number): boolean;
+//# sourceMappingURL=adopt.d.ts.map

package/lib/types/host/claude/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../../../src/host/claude/adopt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAUH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,sBAAsB,CAAA;AAExD,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,sBAAsB,CAAA;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,kBAAkB,CAAA;AAEzD,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,gBAAgB,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,QAEa,CAAA;AAEzD,oFAAoF;AACpF,MAAM,WAAW,2BAA2B;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,OAAO,6BAA6B,CAAA;IACrD,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAA;CACxC;AAED,kEAAkE;AAClE,MAAM,WAAW,4BAA4B;IAC3C,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAA;IAChB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAKpD;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,GAAE,SAAS,MAAM,EAAgC,GACrD,OAAO,CAAC,4BAA4B,CAAC,CAMvC;AA4CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,GACjB,2BAA2B,GAAG,SAAS,CA+BzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,GAAE,SAAS,MAAM,EAAgC,GACrD,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAclD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,2BAA2B,CAG9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,IAAI,CAAC,2BAA2B,EAAE,aAAa,CAAC,EAC5D,GAAG,GAAE,MAAmB,GACvB,OAAO,CAGT"}