opencode-multi-account-core 0.2.32 → 0.2.34

package/README.md

@@ -1,56 +1,56 @@
-# multi-account-core
-
-Shared core logic for multi-account OpenCode plugins. This package contains ~70% of the logic used by both [`anthropic-multi-account`](../anthropic-multi-account) and [`codex-multi-account`](../codex-multi-account).
-
-## What's inside
-
-| Module | What it does |
-|:-------|:-------------|
-| AccountStore | Single write path. Serializes all disk mutations through file locking. |
-| AccountManager | In-memory account cache and selection strategies (sticky, round-robin, hybrid). Created via `createAccountManagerForProvider`. |
-| Executor | Retry loop with account rotation on auth and rate-limit failures. Created via `createExecutorForProvider`. |
-| Claims | Cross-process coordination via claim files with zombie detection. |
-| Storage | Atomic file read/write with `proper-lockfile`. |
-| RateLimit | Per-account rate-limit tracking with configurable backoff. Created via `createRateLimitTrackerForProvider`. |
-| ProactiveRefreshQueue | Background token refresh before expiry. Created via `createProactiveRefreshForProvider`. |
-| Config | Plugin configuration loading and validation with valibot. Created via `createConfigLoaderForProvider`. |
-| AuthMigration | One-time import of existing single-account OAuth creds from OpenCode's `auth.json`. |
-| Adapters | Provider-specific OAuth adapter definitions (endpoints, client IDs, plan labels). |
-| UI | Terminal UI primitives (ANSI formatting, confirm dialogs, select menus). |
-| Utils | Config directory resolution, formatting helpers. |
-
-## Usage
-
-This package is not intended to be used directly. It is a dependency of the provider-specific plugin packages. Each module exposes a factory function that accepts provider-specific config (endpoints, client IDs, plan labels) and returns a ready-to-use instance.
-
-```ts
-import { createAccountManagerForProvider } from "opencode-multi-account-core";
-
-export const AccountManager = createAccountManagerForProvider({
-  refreshTokenFn: myRefreshToken,
-  isTokenExpiredFn: myIsTokenExpired,
-});
-```
+# opencode-multi-account-core
+
+Shared core for kyoli OpenCode Plugin Mode.
+
+This package is not a user-facing plugin. It is used by:
+
+- [`opencode-codex-multi-account`](../codex-multi-account)
+- [`opencode-anthropic-multi-account`](../anthropic-multi-account)
+
+The npm package name remains `opencode-multi-account-core` for compatibility.
+
+## What lives here
 
-## Architecture
+| Module | Purpose |
+|---|---|
+| `AccountStore` | File-locked account JSON storage |
+| `AccountManager` | Account cache, selection, state mutation |
+| `Executor` | Retry loop and account rotation |
+| `Claims` | Cross-process account claims |
+| `ProactiveRefreshQueue` | Background token refresh |
+| `NativePluginLifecycle` | OpenCode loader/runtime/refresh wiring |
+| `NativePluginAuth` | Shared OAuth method builder |
+| `NativePluginLoader` | Shared `getAuth -> lifecycle.load -> hooks` flow |
+| `NativePluginBootstrapAuth` | Stored-account to OpenCode `auth.json` sync helper |
 
+Provider wire behavior stays in the provider packages. Server Mode behavior stays in
+`@kyoli-gam/core`, `@kyoli-gam/gateway`, and `@kyoli-gam/cli`.
+
+## Safety
+
+- Disk writes go through file locks.
+- Writes are atomic temp-file-and-rename operations.
+- Concurrent refreshes for the same account are deduplicated.
+- Claim-file writes are serialized.
+- Accounts are only auto-disabled when another usable account remains.
+- Dead process claims are released automatically.
+
+## Checks
+
+```bash
+pnpm --filter opencode-multi-account-core test:contract:native
+pnpm --filter opencode-multi-account-core typecheck
+pnpm --filter opencode-multi-account-core test
 ```
-┌─────────────────────────────────────────────────┐
-│  anthropic-multi-account / codex-multi-account  │
-│  (provider-specific: auth, usage, transforms)   │
-├─────────────────────────────────────────────────┤
-│          multi-account-core  ← you are here     │
-│  AccountStore . AccountManager . Executor        │
-│  Claims . Storage . RateLimit . ProactiveRefresh │
-│  AuthMigration . Config . Utils . UI . Adapters  │
-│  (endpoints, client IDs, plan labels)            │
-└─────────────────────────────────────────────────┘
+
+Root no-live plugin gate:
+
+```bash
+pnpm run test:contract:native
 ```
 
-## Safety guarantees
+## Docs
 
-- All disk mutations go through AccountStore with file locking
-- Atomic writes via temp-file-then-rename
-- Concurrent token refresh requests for the same account are deduplicated
-- Circuit breaker: an account is only auto-disabled when at least one other remains usable
-- Dead process claims are automatically released
+- [OpenCode Plugin Mode](../../docs/opencode-plugin-mode.md)
+- [OpenCode Plugin Usage](../../docs/opencode-plugin-usage.md)
+- [OpenCode Plugin Core Redesign Notes](../../docs/opencode-plugin-core-redesign.md)

package/dist/index.d.ts

@@ -46,11 +46,15 @@ declare const CredentialRefreshPatchSchema: v.ObjectSchema<{
     readonly refreshToken: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly uuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly accountId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly accountUuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly deviceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
 declare const StoredAccountSchema: v.ObjectSchema<{
     readonly uuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly accountId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly accountUuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly deviceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly planTier: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -85,6 +89,8 @@ declare const AccountStorageSchema: v.ObjectSchema<{
     readonly accounts: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly uuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly accountId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly accountUuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly deviceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly planTier: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -139,6 +145,7 @@ type StoredAccount = v.InferOutput<typeof StoredAccountSchema>;
 type AccountStorage = v.InferOutput<typeof AccountStorageSchema>;
 type AccountSelectionStrategy = v.InferOutput<typeof AccountSelectionStrategySchema>;
 type PluginConfig = v.InferOutput<typeof PluginConfigSchema>;
+type AccountMetadataPatch = Partial<Pick<StoredAccount, "accountId" | "accountUuid" | "deviceId" | "email" | "label" | "planTier">>;
 type TokenRefreshResult = {
     ok: true;
     patch: CredentialRefreshPatch;
@@ -157,6 +164,8 @@ interface ManagedAccount {
     index: number;
     uuid?: string;
     accountId?: string;
+    accountUuid?: string;
+    deviceId?: string;
     label?: string;
     email?: string;
     planTier?: string;
@@ -214,6 +223,8 @@ interface DiskCredentials {
     accessToken?: string;
     expiresAt?: number;
     accountId?: string;
+    accountUuid?: string;
+    deviceId?: string;
 }
 declare class AccountStore {
     private readonly storagePath;
@@ -268,9 +279,9 @@ interface AccountManagerInstance {
     validateNonActiveTokens(client: PluginClient): Promise<void>;
     removeAccount(index: number): Promise<boolean>;
     clearAllAccounts(): Promise<void>;
-    addAccount(auth: OAuthCredentials, email?: string): Promise<void>;
+    addAccount(auth: OAuthCredentials, email?: string, metadata?: AccountMetadataPatch): Promise<void>;
     toggleEnabled(uuid: string): Promise<void>;
-    replaceAccountCredentials(uuid: string, auth: OAuthCredentials): Promise<void>;
+    replaceAccountCredentials(uuid: string, auth: OAuthCredentials, metadata?: AccountMetadataPatch): Promise<void>;
     retryAuth(uuid: string, client: PluginClient): Promise<TokenRefreshResult>;
 }
 interface AccountManagerClass {
@@ -460,7 +471,6 @@ interface OAuthAdapter {
     id: string;
     authProviderId: string;
     modelDisplayName: string;
-    statusToolName: string;
     authMethodLabel: string;
     serviceLogName: string;
     oauthClientId: string;
@@ -588,4 +598,130 @@ declare class CascadeStateManager {
     getSnapshot(): CascadeState | null;
 }
 
-export { ACCOUNTS_FILENAME, ANSI, type AccountManagerClass, type AccountManagerDependencies, type AccountManagerInstance, type AccountSelectionStrategy, AccountSelectionStrategySchema, type AccountStorage, AccountStorageSchema, AccountStore, type BuildFailoverPlanOptions, type CascadeState, CascadeStateManager, type ChainConfig, ChainConfigSchema, type ChainEntryConfig, ChainEntryConfigSchema, type ClaimsManager, type ClaimsMap, type ConfigLoader, type CoreConfig, type CredentialRefreshPatch, CredentialRefreshPatchSchema, type DiskCredentials, type ExecutorAccountManager, type ExecutorDependencies, type ExecutorRuntimeFactory, type FailoverCandidate, type FailoverPlan, type FailoverSkip, type KeyAction, type ManagedAccount, type MenuItem, type OAuthAdapter, type OAuthAdapterPlanLabels, type OAuthAdapterTransformConfig, type OAuthCredentials, OAuthCredentialsSchema, type PluginClient, type PluginConfig, PluginConfigSchema, type PoolChainConfig, PoolChainConfigSchema, type PoolConfig, PoolConfigSchema, PoolManager, type ProactiveRefreshDependencies, type ProactiveRefreshQueueClass, type ProactiveRefreshQueueInstance, type ProfileData, type RateLimitAccountManager, type RateLimitDependencies, type RuntimeFactoryLike, type SelectOptions, type StoredAccount, StoredAccountSchema, TokenRefreshError, type TokenRefreshResult, type UsageLimitEntry, UsageLimitEntrySchema, type UsageLimits, UsageLimitsSchema, anthropicOAuthAdapter, confirm, createAccountManagerForProvider, createClaimsManager, createConfigLoader, createExecutorForProvider, createMinimalClient, createProactiveRefreshQueueForProvider, createRateLimitHandlers, debugLog, deduplicateAccounts, formatWaitTime, getAccountLabel, getClearedOAuthBody, getConfig, getConfigDir, getErrorCode, initCoreConfig, isClaimedByOther, isTTY, isTokenRefreshError, loadAccounts, loadConfig, loadPoolChainConfig, migrateFromAuthJson, openAIOAuthAdapter, parseKey, readClaims, readStorageFromDisk, releaseClaim, resetConfigCache, savePoolChainConfig, select, setAccountsFilename, setConfigGetter, showToast, sleep, updateConfigField, withDirectoryLock, writeClaim };
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface NativePluginManagedAccount {
+    uuid?: string;
+    isAuthDisabled?: boolean;
+}
+interface NativePluginStoreLike {
+    load(): Promise<{
+        accounts: unknown[];
+    }>;
+}
+interface NativePluginManagerLike<TAccount extends NativePluginManagedAccount = NativePluginManagedAccount> {
+    getAccountCount(): number;
+    getAccounts(): TAccount[];
+    getActiveAccount?(): TAccount | null;
+    setRuntimeFactory(factory: NativePluginRuntimeFactoryLike): void;
+    validateNonActiveTokens?(client: PluginClient): Promise<void>;
+}
+interface NativePluginManagerClass<TStore extends NativePluginStoreLike, TManager extends NativePluginManagerLike> {
+    create(store: TStore, currentAuth: OAuthCredentials, client?: PluginClient): Promise<TManager>;
+}
+interface NativePluginRuntimeFactoryLike {
+    getRuntime(uuid: string): Promise<{
+        fetch: FetchLike;
+    }>;
+    invalidate(uuid: string): void;
+}
+interface NativePluginRefreshQueueLike {
+    start(): void;
+    stop(): Promise<void> | void;
+}
+interface NativePluginLifecycleOptions<TStore extends NativePluginStoreLike, TManager extends NativePluginManagerLike<TAccount>, TAccount extends NativePluginManagedAccount> {
+    store: TStore;
+    client: PluginClient;
+    managerClass: NativePluginManagerClass<TStore, TManager>;
+    createRuntimeFactory: (store: TStore, client: PluginClient) => NativePluginRuntimeFactoryLike;
+    createRefreshQueue?: (client: PluginClient, store: TStore, onInvalidate: (uuid: string) => void) => NativePluginRefreshQueueLike;
+    executeWithAccountRotation: (manager: TManager, runtimeFactory: NativePluginRuntimeFactoryLike, client: PluginClient, input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    migrateFromAuthJson?: (providerKey: string, store: TStore) => Promise<boolean>;
+    afterManagerInitialized?: (manager: TManager, runtimeFactory: NativePluginRuntimeFactoryLike) => Promise<void> | void;
+    afterOAuthLoad?: (credentials: OAuthCredentials, manager: TManager) => Promise<void> | void;
+    createFetch?: (context: {
+        getManager: () => TManager | null;
+        getRuntimeFactory: () => NativePluginRuntimeFactoryLike | null;
+        defaultFetch: FetchLike;
+    }) => FetchLike;
+    createLoaderExtras?: (manager: TManager | null) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    authJsonProviderKey: string;
+    oauthApiKey: string;
+    noAccountsMessage: string;
+    getAccountLabel: (account: TAccount) => string;
+}
+interface NativePluginLoaderResult {
+    apiKey: string;
+    fetch: FetchLike;
+    [key: string]: unknown;
+}
+interface NativePluginLifecycle<TManager extends NativePluginManagerLike = NativePluginManagerLike> {
+    getManager(): TManager | null;
+    getRuntimeFactory(): NativePluginRuntimeFactoryLike | null;
+    load(auth: Record<string, unknown>, provider?: Record<string, unknown>): Promise<NativePluginLoaderResult>;
+}
+declare function createOpenCodeNativePluginLifecycle<TStore extends NativePluginStoreLike, TAccount extends NativePluginManagedAccount, TManager extends NativePluginManagerLike<TAccount>>(options: NativePluginLifecycleOptions<TStore, TManager, TAccount>): NativePluginLifecycle<TManager>;
+
+interface OpenCodeNativeAuthMethod<TResult = unknown> {
+    label: string;
+    type: "oauth";
+    authorize: (...args: unknown[]) => Promise<TResult>;
+}
+interface OpenCodeNativeAuthMethodsOptions<TResult = unknown> {
+    oauthLabel: string;
+    authorize: (inputs?: Record<string, string>) => Promise<TResult>;
+}
+declare function createOpenCodeNativeAuthMethods<TResult>(options: OpenCodeNativeAuthMethodsOptions<TResult>): OpenCodeNativeAuthMethod<TResult>[];
+
+interface OpenCodeNativeLoaderContext<TManager extends NativePluginManagerLike = NativePluginManagerLike> {
+    auth: Record<string, unknown>;
+    provider: Record<string, unknown>;
+    lifecycle: NativePluginLifecycle<TManager>;
+    manager: TManager | null;
+    runtimeFactory: NativePluginRuntimeFactoryLike | null;
+    result: NativePluginLoaderResult;
+}
+interface OpenCodeNativeAuthLoaderOptions<TManager extends NativePluginManagerLike = NativePluginManagerLike> {
+    lifecycle: NativePluginLifecycle<TManager>;
+    debugLog?: (message: string, extra?: Record<string, unknown>) => void;
+    beforeAuth?: (provider: Record<string, unknown>) => Promise<void> | void;
+    beforeLoad?: (context: {
+        auth: Record<string, unknown>;
+        provider: Record<string, unknown>;
+        lifecycle: NativePluginLifecycle<TManager>;
+    }) => Promise<void> | void;
+    afterLoad?: (context: OpenCodeNativeLoaderContext<TManager>) => Promise<NativePluginLoaderResult | void> | NativePluginLoaderResult | void;
+}
+declare function createOpenCodeNativeAuthLoader<TManager extends NativePluginManagerLike = NativePluginManagerLike>(options: OpenCodeNativeAuthLoaderOptions<TManager>): (getAuth: () => Promise<unknown>, provider: Record<string, unknown>) => Promise<NativePluginLoaderResult>;
+
+interface OpenCodeNativeBootstrapAccount {
+    uuid?: string;
+    refreshToken: string;
+    accessToken?: string;
+    expiresAt?: number;
+    enabled?: boolean;
+    isAuthDisabled?: boolean;
+}
+interface OpenCodeNativeBootstrapStore {
+    load(): Promise<{
+        accounts: OpenCodeNativeBootstrapAccount[];
+        activeAccountUuid?: string;
+    }>;
+}
+interface OpenCodeNativeBootstrapAuthOptions {
+    client: PluginClient;
+    store: OpenCodeNativeBootstrapStore;
+    providerId: string;
+}
+declare function selectBootstrapAccount(accounts: OpenCodeNativeBootstrapAccount[], activeAccountUuid?: string): (OpenCodeNativeBootstrapAccount & {
+    refreshToken: string;
+    accessToken: string;
+    expiresAt: number;
+}) | null;
+declare function shouldSyncBootstrapAuth(currentAuth: OAuthCredentials | null, nextAuth: OAuthCredentials): boolean;
+declare function syncOpenCodeNativeBootstrapAuth(options: OpenCodeNativeBootstrapAuthOptions): Promise<boolean>;
+declare const __openCodeNativeBootstrapAuthTestUtils: {
+    selectBootstrapAccount: typeof selectBootstrapAccount;
+    shouldSyncBootstrapAuth: typeof shouldSyncBootstrapAuth;
+};
+
+export { ACCOUNTS_FILENAME, ANSI, type AccountManagerClass, type AccountManagerDependencies, type AccountManagerInstance, type AccountMetadataPatch, type AccountSelectionStrategy, AccountSelectionStrategySchema, type AccountStorage, AccountStorageSchema, AccountStore, type BuildFailoverPlanOptions, type CascadeState, CascadeStateManager, type ChainConfig, ChainConfigSchema, type ChainEntryConfig, ChainEntryConfigSchema, type ClaimsManager, type ClaimsMap, type ConfigLoader, type CoreConfig, type CredentialRefreshPatch, CredentialRefreshPatchSchema, type DiskCredentials, type ExecutorAccountManager, type ExecutorDependencies, type ExecutorRuntimeFactory, type FailoverCandidate, type FailoverPlan, type FailoverSkip, type KeyAction, type ManagedAccount, type MenuItem, type NativePluginLifecycle, type NativePluginLifecycleOptions, type NativePluginLoaderResult, type NativePluginManagedAccount, type NativePluginManagerClass, type NativePluginManagerLike, type NativePluginRefreshQueueLike, type NativePluginRuntimeFactoryLike, type NativePluginStoreLike, type OAuthAdapter, type OAuthAdapterPlanLabels, type OAuthAdapterTransformConfig, type OAuthCredentials, OAuthCredentialsSchema, type OpenCodeNativeAuthLoaderOptions, type OpenCodeNativeAuthMethod, type OpenCodeNativeAuthMethodsOptions, type OpenCodeNativeBootstrapAccount, type OpenCodeNativeBootstrapAuthOptions, type OpenCodeNativeBootstrapStore, type OpenCodeNativeLoaderContext, type PluginClient, type PluginConfig, PluginConfigSchema, type PoolChainConfig, PoolChainConfigSchema, type PoolConfig, PoolConfigSchema, PoolManager, type ProactiveRefreshDependencies, type ProactiveRefreshQueueClass, type ProactiveRefreshQueueInstance, type ProfileData, type RateLimitAccountManager, type RateLimitDependencies, type RuntimeFactoryLike, type SelectOptions, type StoredAccount, StoredAccountSchema, TokenRefreshError, type TokenRefreshResult, type UsageLimitEntry, UsageLimitEntrySchema, type UsageLimits, UsageLimitsSchema, __openCodeNativeBootstrapAuthTestUtils, anthropicOAuthAdapter, confirm, createAccountManagerForProvider, createClaimsManager, createConfigLoader, createExecutorForProvider, createMinimalClient, createOpenCodeNativeAuthLoader, createOpenCodeNativeAuthMethods, createOpenCodeNativePluginLifecycle, createProactiveRefreshQueueForProvider, createRateLimitHandlers, debugLog, deduplicateAccounts, formatWaitTime, getAccountLabel, getClearedOAuthBody, getConfig, getConfigDir, getErrorCode, initCoreConfig, isClaimedByOther, isTTY, isTokenRefreshError, loadAccounts, loadConfig, loadPoolChainConfig, migrateFromAuthJson, openAIOAuthAdapter, parseKey, readClaims, readStorageFromDisk, releaseClaim, resetConfigCache, savePoolChainConfig, select, setAccountsFilename, setConfigGetter, showToast, sleep, syncOpenCodeNativeBootstrapAuth, updateConfigField, withDirectoryLock, writeClaim };