@cortexkit/anthropic-auth-core 1.22.0 → 2.0.0

package/README.md

@@ -6,3 +6,5 @@ User-facing packages:
 
 - `@cortexkit/opencode-anthropic-auth` for OpenCode
 - `@cortexkit/pi-anthropic-auth` for Pi
+
+Claude Haiku 5.5 (`claude-haiku-5-5`) has a 1M-token context window and 128K max output. Standard input/output rates are $0.10/$0.50 per million tokens; all rates increase fivefold above 100K total input, including cached tokens. Optional quota priming continues to send a minimal Haiku 4.5 request to start a new quota window.

package/dist/accounts.d.ts

@@ -1,5 +1,7 @@
+import type { ProviderAccountUuid } from './claude-code.ts';
 import { type Cache1hMode } from './constants.ts';
 import { type LogLevel } from './logger.ts';
+export type { ProviderAccountUuid } from './claude-code.ts';
 export declare const ACCOUNT_FILE_NAME = "anthropic-auth.json";
 export declare const ACCOUNT_STATE_FILE_NAME = "anthropic-auth-state.json";
 export declare const QUOTA_URL = "https://api.anthropic.com/api/oauth/usage";
@@ -18,7 +20,10 @@ export type AccountBase = {
 export type OAuthAccount = AccountBase & {
     type: 'oauth';
     authLineageId?: string;
-    claustrumHandle?: string;
+    anthropicAccountUuid?: ProviderAccountUuid;
+    /** Non-secret scoped identity; never a capability handle or bearer token. */
+    claustrumScopedCredentialId?: string;
+    claustrumScopedState?: string;
     access?: string;
     refresh: string;
     expires?: number;
@@ -33,6 +38,10 @@ export type OAuthAccount = AccountBase & {
      */
     prime?: PrimeUsageCounters;
 };
+export declare function hasNoLocalCredential(account: {
+    access?: unknown;
+    refresh?: unknown;
+}): boolean;
 export type ApiKeyAccount = AccountBase & {
     type: 'api';
     apiKey?: string;
@@ -40,11 +49,21 @@ export type ApiKeyAccount = AccountBase & {
     authHeader?: 'authorization-bearer' | 'x-api-key';
 };
 export type FallbackAccount = OAuthAccount | ApiKeyAccount;
-export type ClaustrumAccountGate = {
-    enabled?: boolean;
-};
+export type ClaustrumMode = 'local' | 'claustrum';
 export type ClaustrumConfig = {
-    accounts?: Record<string, ClaustrumAccountGate>;
+    mode?: ClaustrumMode;
+    /** Set by authoritative scoped discovery, not an authentication toggle. */
+    scopedRoster?: true;
+    /** Producer inventory cursor committed with the roster; never a bearer. */
+    rosterView?: string;
+    /** Authoritative, non-secret primary identity from scoped discovery. */
+    primaryAccount?: {
+        credentialId: string;
+        accountId: ProviderAccountUuid;
+        state: string;
+    };
+    /** Preserve explicit exclusions when a vaulted account disappears and returns. */
+    disabledAccountIdentities?: string[];
 };
 export declare function isOAuthAccount(account: FallbackAccount): account is OAuthAccount;
 export declare function isApiKeyAccount(account: FallbackAccount): account is ApiKeyAccount;
@@ -105,6 +124,7 @@ export type OAuthAccountProfile = {
     checkedAt: number;
     /** Stable account identity; tokenFingerprint remains loadable for legacy state. */
     accountIdentity?: string;
+    providerAccountUuid?: ProviderAccountUuid;
     tokenFingerprint?: string;
 };
 export type OAuthQuotaSnapshot = Partial<Record<QuotaWindowName, AccountQuotaWindow>> & {
@@ -244,10 +264,11 @@ export type AccountStorage = {
  * (to display the provider's real model costs).
  */
 export declare function isCostZeroingEnabled(storage: Pick<AccountStorage, 'costZeroing'>): boolean;
-export type AccountRuntimeEntry = Partial<Pick<OAuthAccount, 'access' | 'authLineageId' | 'claustrumHandle' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota' | 'profile' | 'prime'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
+export type AccountRuntimeEntry = Partial<Pick<OAuthAccount, 'access' | 'authLineageId' | 'anthropicAccountUuid' | 'claustrumScopedCredentialId' | 'claustrumScopedState' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota' | 'profile' | 'prime'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
 export type AccountRuntimeState = {
     version: 1;
     main?: {
+        scopedAccountIdentity?: string;
         profile?: OAuthAccountProfile;
         profileToken?: string;
         quota?: OAuthQuotaSnapshot;
@@ -305,7 +326,8 @@ export declare function loadAccounts(path?: string): Promise<AccountStorage | nu
 export declare function quotaSnapshotCheckedAt(quota: OAuthQuotaSnapshot | undefined): number;
 export declare function quotaFieldSource(snapshot: OAuthQuotaSnapshot | undefined, field: QuotaFieldName): QuotaFieldSource | undefined;
 export declare function mergeHeaderQuotaForPersistence(existing: OAuthQuotaSnapshot | undefined, incoming: OAuthQuotaSnapshot): OAuthQuotaSnapshot;
-export declare function isClaustrumEnabledForAccount(storage: AccountStorage, accountId: string): boolean;
+export declare function getClaustrumMode(storage: AccountStorage | null): ClaustrumMode;
+export declare function setClaustrumModePersistent(mode: ClaustrumMode, path?: string): Promise<'changed' | 'unchanged'>;
 export interface SaveAccountsOptions {
     /** Account ids intentionally removed by this mutation. */
     removedAccountIds?: readonly string[];
@@ -313,6 +335,19 @@ export interface SaveAccountsOptions {
     preserveExistingAccountOrder?: boolean;
 }
 export declare function saveAccounts(storage: AccountStorage, path?: string, options?: SaveAccountsOptions): Promise<void>;
+/** Read-modify-write account configuration under the existing config/state lock order.
+ * The callback is synchronous: network discovery must happen under its own outer
+ * lease, never while holding the config lock. Do not call another persistence API
+ * from the callback.
+ */
+export declare function mutateAccountsPersistent<T>(path: string, mutate: (storage: AccountStorage) => {
+    storage: AccountStorage;
+    result: T;
+    options?: SaveAccountsOptions;
+    save?: boolean;
+}, options?: {
+    assertAuthority?: () => Promise<void>;
+}): Promise<T>;
 export declare function getOrCreateMainAccountId(path?: string, createId?: () => string): Promise<string>;
 export declare function saveAccountState(storage: AccountStorage, path?: string, scope?: AccountStateSaveScope): Promise<void>;
 export declare function saveOAuthProfileState(input: {
@@ -320,7 +355,6 @@ export declare function saveOAuthProfileState(input: {
     profile: OAuthAccountProfile | undefined;
     accountIdentity?: string;
 }, path?: string): Promise<boolean>;
-export declare function clearClaustrumRefreshErrorPersistent(accountId: string, handle: string, path?: string): Promise<boolean>;
 export declare function acquireRefreshFileLock(options: {
     name: string;
     ttlMs: number;
@@ -331,6 +365,7 @@ export declare function acquireRefreshFileLock(options: {
     onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | 'eviction-marker-acquired') => void | Promise<void>;
 }): Promise<{
     release: () => Promise<void>;
+    assertOwned: () => Promise<void>;
 } | null>;
 export declare function isCache1hPersistentlyEnabled(storage: AccountStorage | null): boolean;
 export declare function getCache1hPersistentMode(storage: AccountStorage | null): Cache1hMode;
@@ -459,6 +494,13 @@ export declare function fetchOAuthQuotaSnapshot(input: {
     now?: () => number;
 }): Promise<OAuthQuotaSnapshot>;
 export declare function upsertAccount(storage: AccountStorage, account: FallbackAccount): void;
+export declare function persistFallbackQuotaHeaderPersistent(input: {
+    accountId: string;
+    authLineageId?: string;
+    quota: OAuthQuotaSnapshot;
+    anthropicAccountUuid?: ProviderAccountUuid;
+}, path?: string): Promise<boolean>;
+export declare function fallbackAccountUuidForLineage(account: OAuthAccount | undefined, authLineageId?: string): string | null;
 export declare function removeAccount(storage: AccountStorage, id: string): boolean;
 export declare function reorderAccounts(storage: AccountStorage, orderedIds: string[]): void;
 export declare function setAccountEnabled(storage: AccountStorage, id: string, enabled: boolean): boolean;
@@ -467,6 +509,7 @@ export declare class FallbackAccountManager {
     private readonly fetchImpl;
     private readonly configPath;
     private readonly refreshPromises;
+    private readonly custodyVerificationAccounts;
     private refreshTimer;
     private quotaTimer;
     readonly quotaManager: import('./quota-manager.ts').QuotaManager | null;
@@ -487,6 +530,7 @@ export declare class FallbackAccountManager {
     save(storage: AccountStorage, accountIds?: string[]): Promise<void>;
     startBackgroundRefresh(): Promise<void>;
     stopBackgroundRefresh(): void;
+    withAccountRefreshLock<T>(accountId: string, fn: () => Promise<T>): Promise<T>;
     getUsableFallbackAccounts(existingStorage?: AccountStorage | null, options?: {
         modelId?: string;
     }): Promise<OAuthAccount[]>;

package/dist/cachekeep.d.ts

@@ -76,8 +76,15 @@ export type CacheKeepTarget = {
     consecutiveFailures: number;
     dayKey: string;
     oauthAccountId?: string;
+    oauthAccountIdentity?: string;
+    accountStoragePath?: string;
     isSubagent: boolean;
 };
+export type CacheKeepPrewarmAttempt = {
+    id: number;
+    /** One deadline covers credential authorization and the HTTP attempt. */
+    signal?: AbortSignal;
+};
 export type CacheKeepPrewarmResult = {
     ok: true;
     usage?: {
@@ -96,6 +103,7 @@ export declare class CacheKeepManager {
     private readonly targets;
     private timer;
     private tickPromise;
+    private nextPrewarmAttemptId;
     constructor(options: {
         loadStorage: () => Promise<AccountStorage | null>;
         fetchImpl?: typeof fetch;
@@ -103,7 +111,16 @@ export declare class CacheKeepManager {
         prewarmTimeoutMs?: number;
         setIntervalImpl?: typeof globalThis.setInterval;
         clearIntervalImpl?: typeof globalThis.clearInterval;
-        prepareHeaders?: (headers: Headers, target: CacheKeepTarget) => Promise<Headers> | Headers;
+        prepareHeaders?: (headers: Headers, target: CacheKeepTarget, attempt: CacheKeepPrewarmAttempt) => Promise<Headers | undefined> | Headers | undefined;
+        /** Optionally reauthorize a replayable prewarm after a genuine 401.
+         * Return headers only for a verified newer version of the same account;
+         * onResponse observes only the final physical attempt. */
+        retryOnUnauthorized?: (input: {
+            target: CacheKeepTarget;
+            headers: Headers;
+            bodyText: string;
+            attempt: CacheKeepPrewarmAttempt;
+        }) => Promise<Headers | undefined> | Headers | undefined;
         onTrackedSessionsChanged?: (sessions: readonly CacheKeepTrackedSession[]) => Promise<void> | void;
         prepareBody?: (bodyText: string, target: CacheKeepTarget) => string | Promise<string>;
         onResponse?: (input: {
@@ -112,6 +129,11 @@ export declare class CacheKeepManager {
             status: number;
             data: unknown;
             receivedAt: number;
+            attempt: CacheKeepPrewarmAttempt;
+        }) => void | Promise<void>;
+        onComplete?: (input: {
+            target: CacheKeepTarget;
+            attempt: CacheKeepPrewarmAttempt;
         }) => void | Promise<void>;
     });
     start(): void;
@@ -137,6 +159,8 @@ export declare class CacheKeepManager {
         storage: AccountStorage | null;
         cacheMode: string;
         oauthAccountId?: string;
+        oauthAccountIdentity?: string;
+        accountStoragePath?: string;
         isSubagent?: boolean;
     }): {
         tracked: boolean;
@@ -151,6 +175,8 @@ export declare class CacheKeepManager {
         headers: Headers;
         bodyText: string;
         oauthAccountId?: string;
+        oauthAccountIdentity?: string;
+        accountStoragePath?: string;
         isSubagent?: boolean;
     }): Promise<CacheKeepPrewarmResult>;
     tick(): Promise<void>;

package/dist/cch.d.ts

@@ -1,3 +1,9 @@
+export interface BillingLineageFields {
+    previousRequestId?: string;
+    promptId?: string;
+}
+export declare function isValidAnthropicRequestId(value: string): boolean;
+export declare function isValidBillingPromptId(value: string): boolean;
 type Message = {
     role?: string;
     content?: string | Array<{
@@ -38,5 +44,9 @@ export declare function computeCcVersionSuffix(firstUserText: string, version?:
  * Build the billing header with a cch placeholder.
  * signRequestBody() must run after final request serialization to replace it.
  */
-export declare function buildBillingHeaderValue(messages: Message[], version: string | undefined, entrypoint: string, pinnedFirstUserText?: string): string;
+export declare function buildBillingHeaderValue(messages: Message[], version: string | undefined, entrypoint: string, pinnedFirstUserText?: string, lineage?: BillingLineageFields): string;
+/** Remove request-scoped Claude Code lineage from a billing header string. */
+export declare function stripBillingLineageFields(value: string): string;
+/** Remove request-scoped Claude Code lineage before reusing a request body. */
+export declare function stripBillingLineageFromBody(body: unknown): number;
 export {};

package/dist/claude-code.d.ts

@@ -1,13 +1,35 @@
+export type ProviderAccountUuid = string & {
+    readonly __providerAccountUuid: unique symbol;
+};
 export type ClaudeCodeIdentity = {
     deviceId: string;
     accountIdentity?: string;
-    accountUuid?: string;
+    accountUuid?: ProviderAccountUuid;
     sessionId: string;
 };
 export declare function setBounded<K, V>(map: Map<K, V>, key: K, value: V, limit?: number): void;
 export declare function getClaudeCodeIdentity(seed: string): ClaudeCodeIdentity;
 export declare function resetClaudeCodeIdentityCachesForTest(): void;
+/** Use the identity already verified by the credential custodian, without an
+ * additional bootstrap request carrying a previously authorized token. */
+export declare function getClaudeCodeIdentityForVerifiedAccount(accountIdentity: string, accountUuid: ProviderAccountUuid): ClaudeCodeIdentity;
 export declare function resolveClaudeCodeIdentity(accessToken: string, model: string | undefined, accountIdentity: string | undefined): Promise<ClaudeCodeIdentity>;
+/**
+ * The access value is not a Claude OAuth access token, so Claude cannot
+ * identify its account. Asking again will not help; only a new sign-in
+ * replaces it. The message never includes the rejected value.
+ */
+export declare class ClaudeUnsupportedAccessError extends Error {
+    readonly code = "unsupported-access";
+    constructor();
+}
+/**
+ * Account lookup for credentials that must belong to a Claude account.
+ * Unlike resolveClaudeCodeIdentity, which returns an identity without an
+ * account UUID for any other access value, this rejects such a value with
+ * ClaudeUnsupportedAccessError before any network request.
+ */
+export declare function resolveClaudeCodeAccountIdentity(accessToken: string, model: string | undefined, accountIdentity: string | undefined): Promise<ClaudeCodeIdentity>;
 export declare function buildClaudeCodeMetadataUserId(identity: ClaudeCodeIdentity): string | null;
 export declare function applyClaudeCodeMetadata(body: Record<string, unknown>, identity: ClaudeCodeIdentity): boolean;
 export declare const CLAUDE_CODE_FULL_AGENT_BETAS: readonly ['oauth-2025-04-20', 'interleaved-thinking-2025-05-14', 'thinking-token-count-2026-05-13', 'context-management-2025-06-27', 'prompt-caching-scope-2026-01-05', 'claude-code-20250219', 'advisor-tool-2026-03-01', 'advanced-tool-use-2025-11-20', 'mid-conversation-system-2026-04-07', 'effort-2025-11-24', 'fallback-credit-2026-06-01', 'extended-cache-ttl-2025-04-11', 'cache-diagnosis-2026-04-07'];

package/dist/claustrum-enrollment.d.ts

@@ -0,0 +1,72 @@
+import { type ClaustrumClientOptions as ClaustrumEnrollmentClientOptions, type EnrollmentPollOutcome, type EnrollmentTokenFile, writeEnrollmentTokenFile } from '@cortexkit/claustrum-client';
+export declare const CLAUSTRUM_OPENCODE_ENROLLMENT_NAME = "anthropic-auth-opencode";
+export declare const CLAUSTRUM_PI_ENROLLMENT_NAME = "anthropic-auth-pi";
+export interface ClaustrumEnrollmentClient {
+    enrollPropose(input: {
+        name: string;
+        requestSecretHash: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    enrollPoll(input: {
+        requestId: string;
+        requestSecret: string;
+    }): Promise<EnrollmentPollOutcome>;
+}
+export interface ClaustrumEnrollmentConnection extends ClaustrumEnrollmentClient {
+    close(): void;
+}
+export declare function connectClaustrumEnrollmentClient(options?: ClaustrumEnrollmentClientOptions): Promise<ClaustrumEnrollmentConnection>;
+export type ClaustrumEnrollmentStatus = {
+    state: 'idle';
+} | {
+    state: 'pending';
+    proposedName: string;
+    requestId?: string;
+    retryCode?: string;
+} | {
+    state: 'approved';
+    proposedName: string;
+    approvedName?: string;
+    tokenGeneration: number;
+} | {
+    state: 'denied';
+    proposedName: string;
+} | {
+    state: 'blocked';
+    proposedName: string;
+    code: string;
+} | {
+    state: 'unavailable';
+    proposedName: string;
+    code: string;
+} | {
+    state: 'busy';
+};
+export interface ClaustrumEnrollmentPaths {
+    statePath: string;
+    tokenPath: string;
+}
+export declare function getClaustrumEnrollmentPaths(tokenPath: string): ClaustrumEnrollmentPaths;
+/** Resolve the independently enrolled host's owner-only token and state paths. */
+export declare function getHostClaustrumEnrollmentPaths(host: 'opencode' | 'pi', env?: NodeJS.ProcessEnv, cwd?: string): ClaustrumEnrollmentPaths;
+export declare function readClaustrumEnrollmentStatus(paths: ClaustrumEnrollmentPaths, proposedName?: string): Promise<ClaustrumEnrollmentStatus>;
+/** Read fresh bearer material for a scoped operation; never publish this value. */
+export declare function readClaustrumEnrollmentToken(tokenPath: string): Promise<EnrollmentTokenFile>;
+export declare class ClaustrumEnrollmentManager {
+    #private;
+    constructor(options: {
+        client: ClaustrumEnrollmentClient;
+        paths: ClaustrumEnrollmentPaths;
+        proposedName: string;
+        now?: () => number;
+        mintSecret?: () => string;
+        writeTokenFile?: typeof writeEnrollmentTokenFile;
+    });
+    status(): Promise<ClaustrumEnrollmentStatus>;
+    resetTerminal(): Promise<ClaustrumEnrollmentResetResult>;
+    reconcile(): Promise<ClaustrumEnrollmentStatus>;
+}
+export type ClaustrumEnrollmentResetResult = 'reset' | 'idle' | 'refused-pending' | 'refused-approved' | 'busy';
+/** Reset local terminal metadata without connecting to the credential daemon. */
+export declare function resetClaustrumEnrollmentState(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentResetResult>;

package/dist/claustrum-scoped-roster.d.ts

@@ -0,0 +1,27 @@
+import { type AccountStorage, type OAuthAccount } from './accounts.js';
+import type { ClaustrumScopedAccount, ClaustrumScopedCustody } from './claustrum-scoped.js';
+export declare class ClaustrumRosterBusyError extends Error {
+    readonly code = "claustrum_roster_busy";
+    constructor();
+}
+export interface ClaustrumScopedRoster {
+    /** The vault's conventional default record; absent when only labeled accounts exist. */
+    primary?: ClaustrumScopedAccount;
+    accounts: readonly OAuthAccount[];
+    storage: AccountStorage;
+    view: string;
+}
+/** Pure identity projection; callers must serialize discovery before persisting it. */
+export declare function projectClaustrumScopedRoster(storage: AccountStorage, rows: readonly ClaustrumScopedAccount[], view: string, now?: number): ClaustrumScopedRoster;
+/**
+ * The lease covers LIST and commit, not just the file write: opaque view hashes
+ * cannot tell a delayed old response from a newer one. A lost lease is checked
+ * while holding the config lock, before any authoritative membership write.
+ * Neither local mode nor a failed list can publish an empty inventory.
+ */
+export declare function refreshClaustrumScopedRoster(options: {
+    path: string;
+    custody: Pick<ClaustrumScopedCustody, 'discover'>;
+    signal?: AbortSignal;
+    now?: () => number;
+}): Promise<ClaustrumScopedRoster | undefined>;

package/dist/claustrum-scoped-runtime.d.ts

@@ -0,0 +1,31 @@
+import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import { type ClaustrumScopedAttempt, type ClaustrumScopedClient } from './claustrum-scoped.js';
+import { type ClaustrumScopedRoster } from './claustrum-scoped-roster.js';
+export { ClaustrumCredentialError as ClaustrumScopedCredentialError } from '@cortexkit/claustrum-client';
+export declare function connectClaustrumScopedClient(options?: ClaustrumClientOptions): Promise<ClaustrumScopedClient>;
+/** Host-owned lifecycle for metadata discovery. Bearer material is never cached. */
+export interface ClaustrumScopedRuntimeOptions {
+    storagePath: string;
+    tokenPath: string;
+    connect: () => Promise<ClaustrumScopedClient>;
+    /** Fired once per discovery change (including the initial snapshot),
+     * keyed by the inventory view digest. Repeat polls with an identical
+     * view do not notify. */
+    onRoster?: (roster: ClaustrumScopedRoster) => void;
+    onError?: () => void;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    pollIntervalMs?: number;
+}
+export declare class ClaustrumScopedRuntime {
+    #private;
+    constructor(options: ClaustrumScopedRuntimeOptions);
+    snapshot(): ClaustrumScopedRoster | undefined;
+    refresh(): Promise<ClaustrumScopedRoster | undefined>;
+    start(): void;
+    authorize(routeId: string, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    reportFailure(attempt: ClaustrumScopedAttempt, status: number, source: 'direct' | 'relay_status_field' | 'relay_message_parse'): Promise<void>;
+    fetchQuota(routeId: string, fetchImpl?: typeof fetch): Promise<import("./accounts.js").OAuthQuotaSnapshot>;
+    fetchProfile(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<import("./accounts.js").OAuthAccountProfile>;
+    close(): void;
+}

package/dist/claustrum-scoped.d.ts

@@ -0,0 +1,53 @@
+import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
+export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'>;
+export interface ClaustrumScopedIdentity {
+    readonly credentialId: string;
+    readonly accountId: string;
+}
+export interface ClaustrumScopedAccount extends ClaustrumScopedIdentity {
+    readonly state: string;
+    readonly email?: string;
+    readonly orgName?: string;
+}
+export interface ClaustrumScopedAttempt extends ClaustrumScopedIdentity {
+    /** Non-enumerable, memory-only bearer. Authorize again for every dispatch/retry. */
+    readonly accessToken: string;
+    readonly recordVersion: number;
+    readonly expiresAtMs: number;
+}
+/** Only a new version of the same account may replace an in-flight 401. */
+export declare function isScopedCredentialRotation(served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined): current is ClaustrumScopedAttempt;
+/** Send classes that retry once after a scoped 401, for diagnostics. */
+export type ScopedRetrySite = 'model' | 'model-relay' | 'cachekeep' | 'prime' | 'quota-profile' | 'pi-model' | 'pi-model-relay' | 'pi-cachekeep';
+/** Why a scoped 401 did or did not retry. Never carries credential material. */
+export type ScopedRetryReason = 'rotated' | 'reauthorize-failed' | 'credential-changed' | 'account-changed' | 'version-unchanged';
+/**
+ * Decide whether a request that got a 401 should retry with the freshly
+ * re-authorized receipt, and record the decision. The vault can refresh a
+ * credential between dispatch and the 401; this line is the consumer-side
+ * half of that timeline, pairing with the vault's refresh commit instant when
+ * a stale report has to be explained. Never logs credential material.
+ */
+export declare function decideScopedRetryAfter401(site: ScopedRetrySite, served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined): current is ClaustrumScopedAttempt;
+/**
+ * Shared OpenCode/Pi scoped read plane. There is intentionally no credential cache,
+ * handle fallback, or get single-flight: each outgoing attempt must be authorized
+ * by the daemon, including attempts made after a successful earlier request.
+ * Enrollment tokens are re-read per operation so operator reissue works on disk.
+ */
+export declare class ClaustrumScopedCustody {
+    #private;
+    constructor(options: {
+        client: ClaustrumScopedClient;
+        tokenPath?: string;
+        readToken?: () => Promise<EnrollmentTokenFile>;
+        now?: () => number;
+    });
+    discover(signal?: AbortSignal): Promise<{
+        view: string;
+        accounts: readonly ClaustrumScopedAccount[];
+    }>;
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
+    close(): void;
+}

package/dist/claustrum.d.ts

@@ -1,4 +1,3 @@
-import { type BindIdentity, type CatalogEntry, type CloseRouteOptions, type ManagedCallOptions, type ManagedCloseRouteOptions, type RequestOptions, type RouteHandle, type RouteOpenOptions, type RouteTarget, SubcClient, type SubscribeOptions, type Subscription } from '@cortexkit/subc-client';
 export type ClaustrumEndpoint = {
     host: string;
     port: number;
@@ -16,10 +15,19 @@ export type ClaustrumDetection = {
     path: string;
     reason: string;
 };
-export declare function getDefaultClaustrumConnectionPath(): string;
-export declare function detectClaustrumConnection(path?: string): Promise<ClaustrumDetection>;
+export declare const PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME = "subc-connection.json";
+export declare function findExistingClaustrumConnectionPath(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function getDefaultClaustrumConnectionPath(env?: NodeJS.ProcessEnv): string;
+export declare function resolveClaustrumConnectionPath(explicit?: string, env?: NodeJS.ProcessEnv): string;
+export declare function detectClaustrumConnection(explicitPath?: string): Promise<ClaustrumDetection>;
 export declare const CUSTODY_TOMBSTONE_PREFIX = "claustrum-tombstone:v1:";
 export declare function custodyTombstoneKey(provider: string): string;
+export declare function custodyTombstoneOAuth(provider: string): {
+    type: 'oauth';
+    access: '';
+    refresh: string;
+    expires: 0;
+};
 export declare function isCustodyTombstoneValue(value: unknown): value is string;
 export declare function isCustodyTombstoneOAuth(auth: unknown, provider: string): boolean;
 export declare class CustodyTombstoneRefreshError extends Error {
@@ -27,83 +35,9 @@ export declare class CustodyTombstoneRefreshError extends Error {
     readonly code = "custody_tombstone_refresh";
     constructor(provider: string);
 }
-export declare function assertNotCustodyTombstone(refreshToken: unknown, provider: string): void;
-export type CustodyHandleAccount = {
-    label: string;
-    handle: string;
-    credentialId: string;
-};
-export type CustodyHandleManifest = {
-    provider: string;
-    serve: string;
-    shape: string;
-    accounts: CustodyHandleAccount[];
-};
-export declare function isValidCustodyHandle(value: unknown): value is string;
-export declare function readCustodyHandles(json: unknown, provider: string): CustodyHandleManifest;
-export type ClaustrumClientOptions = {
-    connectionFile?: string;
-    handshakeTimeoutMs?: number;
-    connector?: ClaustrumConnector;
-};
-export type ClaustrumConnector = (options: {
-    connectionFile: string;
-    handshakeTimeoutMs?: number;
-}) => Promise<SubcClient>;
-export declare class ClaustrumClient {
-    #private;
-    private constructor();
-    static connect(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
-    catalogList(moduleId?: string): Promise<CatalogEntry[]>;
-    routeOpen(target: RouteTarget, identity: BindIdentity, options?: Omit<RouteOpenOptions, 'consumerIdentity'>): Promise<RouteHandle>;
-    request(handle: RouteHandle, body: unknown, options?: RequestOptions): Promise<unknown>;
-    call<Response = unknown>(moduleId: string, method: string, params?: unknown, options?: Omit<ManagedCallOptions, 'consumerIdentity'>): Promise<Response>;
-    subscribe(handle: RouteHandle, body: unknown, onEvent: (event: Uint8Array) => void, options?: SubscribeOptions): Subscription;
-    closeRoute(handle: RouteHandle, options?: CloseRouteOptions): Promise<void>;
-    closeManagedRoute(target: Extract<RouteTarget, {
-        kind: 'management_surface' | 'tool_provider';
-    }>, identity: BindIdentity, options?: Omit<ManagedCloseRouteOptions, 'consumerIdentity'>): Promise<void>;
-    close(): void;
-}
-export declare function connectClaustrumClient(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
-export declare const CLAUSTRUM_MODULE_ID = "claustrum";
-export declare const DEFAULT_CLAUSTRUM_CREDENTIAL_MIN_TTL_MS = 120000;
-export declare const ERROR_CLASS_WIRE_SET: readonly ['transient', 'permanent', 'auth_required', 'context_overflow'];
-export type ClaustrumCredentialErrorClass = (typeof ERROR_CLASS_WIRE_SET)[number];
-export type ClaustrumCredentialErrorAction = 'gone' | 'reauth' | 'retry' | 'reduce_and_retry';
-export type ClaustrumCredential = {
-    payload: string;
-    expiresAtMs: number | null;
-    recordVersion: number;
-    projectId?: string;
-    accountId?: string;
-};
-export type ClaustrumServedCredential = Pick<ClaustrumCredential, 'recordVersion'>;
-export type ClaustrumReporterSource = 'direct' | 'relay_status_field' | 'relay_message_parse';
-export declare class ClaustrumCredentialError extends Error {
-    readonly code: string;
-    readonly action: ClaustrumCredentialErrorAction;
-    readonly errorClass: ClaustrumCredentialErrorClass;
-    constructor(message: string, code: string, errorClass: ClaustrumCredentialErrorClass, action: ClaustrumCredentialErrorAction);
-}
-export type ClaustrumCredentialCacheOptions = {
-    identity?: BindIdentity;
-    now?: () => number;
-    minTtlMs?: number;
-};
-export declare class ClaustrumCredentialCache {
-    #private;
-    constructor(client: ClaustrumClient, options?: ClaustrumCredentialCacheOptions);
-    get(handle: string, minTtlMs?: number): Promise<ClaustrumCredential>;
-    peek(handle: string): ClaustrumCredential | undefined;
-    seedForTest(handle: string, credential: ClaustrumCredential): void;
-    reduceMinTtlMs(): number;
-    reportAuthFailure(handle: string, providerStatus: number, servedCredential: ClaustrumServedCredential, reporterSource?: ClaustrumReporterSource): Promise<void>;
-    reportAuthFailure(handle: string, servedCredential: ClaustrumServedCredential, providerStatus?: number, reporterSource?: ClaustrumReporterSource): Promise<void>;
-    invalidate(handle: string, recordVersion?: number): void;
-    close(): void;
+export declare class CustodyTombstoneLoginError extends Error {
+    readonly provider: string;
+    readonly code = "custody_tombstone_login";
+    constructor(provider: string);
 }
-export type ConnectClaustrumCredentialCacheOptions = ClaustrumClientOptions & ClaustrumCredentialCacheOptions & {
-    enabled?: boolean;
-};
-export declare function connectClaustrumCredentialCache(options?: ConnectClaustrumCredentialCacheOptions): Promise<ClaustrumCredentialCache | null>;
+export declare function assertNotCustodyTombstone(refreshToken: unknown, provider: string): void;