dsh-connect-workbuddy 1.3.0 → 2.0.0

package/lib/index.d.ts

@@ -33,8 +33,22 @@ interface WorkBuddyAuthStatus {
 interface WorkBuddyStoreOptions {
   /** Explicit desktop auth-file path, overriding env and platform defaults. */
   desktopPath?: string;
-  /** Explicit plugin-owned copy path, defaulting under `$DSH_HOME`. */
+  /**
+   * Explicit plugin-owned copy path, overriding the per-region default.
+   * Injectable so the copy/refresh cycle is testable without a real machine.
+   */
   ownPath?: string;
+  /**
+   * Region this store serves. When set, only credentials whose login domain
+   * maps to this region are discovered, selected, or refreshed — the two
+   * regions' stores run side by side without seeing each other's accounts.
+   */
+  region?: WorkBuddyRegion;
+  /**
+   * Legacy single-copy path read as a migration source; defaults to the
+   * pre-dual-provider location. Injectable for tests.
+   */
+  legacyOwnPath?: string;
   /**
    * Auth directories to scan, overriding the platform defaults. Injectable so
    * the multi-account scan is testable without touching a real machine.
@@ -58,12 +72,22 @@ interface WorkBuddyAccountChoice {
   filePath: string;
   selected: boolean;
 }
-/** Basename of the plugin-owned credential copy inside the Harness home. */
+/** Legacy single-copy basename (pre-dual-provider); kept as migration source. */
 declare const WORKBUDDY_AUTH_FILENAME = ".workbuddy-auth.json";
 /** Env variable that overrides the desktop auth-file location. */
 declare const WORKBUDDY_AUTH_FILE_ENV = "WORKBUDDY_AUTH_FILE";
-/** Plugin-owned copy path inside the Harness home. */
-declare function workbuddyOwnAuthPath(): string;
+/**
+ * Plugin-owned copy path for one region inside the Harness home. Each
+ * region's store refreshes into its own file so two simultaneously signed-in
+ * regions never overwrite each other's refreshed token.
+ */
+declare function workbuddyOwnAuthPath(region: WorkBuddyRegion): string;
+/**
+ * Pre-dual-provider single-copy path. Still read as a migration source (a
+ * legacy credential serves the region it belongs to until that region's own
+ * first refresh writes the per-region file), and removed by `logout`.
+ */
+declare function legacyWorkbuddyOwnAuthPath(): string;
 /**
  * Platform-default directories holding the WorkBuddy desktop app's auth file.
  *
@@ -110,12 +134,34 @@ declare function workbuddyAccountId(credential: Pick<WorkBuddyCredential, 'uin'
 declare class WorkBuddyCredentialStore {
   private readonly refresh;
   private readonly refreshMarginMs;
-  private readonly ownPath;
+  private readonly region;
+  private readonly ownPathExplicit;
+  private readonly legacyOwnPath;
+  private readonly legacyOwnPathExplicit;
   private readonly authDirs;
   private desktopPathOverride;
   private accountId;
   private inflight;
   constructor(options: WorkBuddyStoreOptions);
+  /** Whether a credential's login domain belongs to this store's region. */
+  private matchesRegion;
+  /**
+   * The path this store refreshes into: the per-region file for a
+   * region-scoped store, the legacy single file otherwise, or an explicitly
+   * injected path in tests.
+   */
+  ownAuthPath(): string;
+  /**
+   * Every plugin-owned copy to read, most preferred first. A region-scoped
+   * store reads the legacy single copy as its migration source (readAll's
+   * region filter drops it when it carries the other region's credential); an
+   * unscoped store reads everything so diagnostics see both regions.
+   *
+   * With an explicitly injected own path the legacy source is read ONLY when
+   * it was injected too — a test that pins one file must not accidentally see
+   * the real machine's legacy copy.
+   */
+  private ownCandidates;
   /** Repoint the desktop file or directory; applies on the next read. */
   setDesktopPath(path: string | undefined): void;
   /** Select an account by id; tokens stay outside settings. */
@@ -126,8 +172,6 @@ declare class WorkBuddyCredentialStore {
   private resolveDesktopCandidates;
   /** The resolved desktop auth-file path, for diagnostics. */
   desktopAuthPath(): string | undefined;
-  /** The plugin-owned copy path, for diagnostics. */
-  ownAuthPath(): string;
   /**
    * Every auth file to scan: the live file plus the timestamped backups
    * WorkBuddy leaves beside it.
@@ -146,6 +190,10 @@ declare class WorkBuddyCredentialStore {
   /**
    * Read every local credential, deduplicated by account id. Files are
    * probed newest-first, so the first entry for an account is its freshest.
+   *
+   * A region-scoped store sees only its own region's credentials: the other
+   * region's accounts are invisible to selection, refresh, and status alike,
+   * which is what keeps the two regions' providers from cross-billing.
    */
   private readAll;
   /**
@@ -164,12 +212,22 @@ declare class WorkBuddyCredentialStore {
   resolve(): Promise<WorkBuddyCredential>;
   /** Read-only sign-in summary; never refreshes and never throws. */
   status(): Promise<WorkBuddyAuthStatus>;
-  /** Remove the plugin-owned copy; the desktop files are untouched. */
+  /**
+   * Remove every plugin-owned copy this store could read (per-region file,
+   * legacy single file, and their lock siblings); the desktop files are
+   * untouched. A region store's logout therefore also clears the legacy
+   * migration source — deliberate: `logout` is the user's "forget what the
+   * plugin stored" action, not a per-account toggle.
+   */
   logout(): Promise<void>;
   private needsRefresh;
   private refreshNow;
   private saveOwn;
-  private readOwn;
+  /**
+   * Every readable plugin-owned copy, in candidate order; absent or corrupt
+   * files are skipped rather than propagated.
+   */
+  private readOwns;
   /** Whether any candidate file exists as a regular file; diagnostics only. */
   desktopFilePresent(): Promise<boolean>;
 }
@@ -294,8 +352,15 @@ declare class WorkBuddyUpstreamClient {
   /** POST the token-refresh endpoint; the caller merges the outcome. */
   refreshToken(credential: WorkBuddyCredential): Promise<WorkBuddyRefreshOutcome>;
   /**
-   * GET the personal model catalog and keep the `cli` agent's models only,
-   * preserving the capability fields the plugin card displays.
+   * Read the model directory for the credential's region.
+   *
+   * The two regions expose their chat roster through different documents:
+   * CN answers `/v2/enterprises/personal/models`, while the global gateway's
+   * personal-models path returns HTTP 500 and the CLI channel's `/v3/config`
+   * omits chat-usable models — so global reads `/v3/config` as the desktop
+   * channel (see {@link DESKTOP_UA}). Both documents share the entry shape, so
+   * one parser serves them. No user-side toggle is involved: the region comes
+   * from the credential's `domain`.
    */
   fetchModels(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<readonly WorkBuddyUpstreamModel[]>;
   /** Query today's check-in status without changing account state. */
@@ -320,6 +385,21 @@ type WorkBuddyModelInfo = WorkBuddyUpstreamModel;
  * with a usable catalog even while the first fetch is in flight or offline.
  */
 declare const FALLBACK_WORKBUDDY_MODELS: readonly WorkBuddyModelInfo[];
+/**
+ * Static CLI models captured from the INTERNATIONAL gateway's desktop-channel
+ * product config (`www.workbuddy.ai/v3/config`, 2026-09-11). The two regions
+ * expose different rosters — the CN list has no `gpt-*`/`gemini-*` entries —
+ * so a global account must never be seeded with the CN list. Like the CN
+ * fallback this is replaced by the live refresh; it only keeps the provider
+ * usable before the first fetch lands. Order and rates mirror the upstream.
+ */
+declare const FALLBACK_WORKBUDDY_MODELS_GLOBAL: readonly WorkBuddyModelInfo[];
+/**
+ * Static fallback directory for a region. Each region keeps its own model
+ * slot in settings; the fallback must match the region so an account never
+ * shows the other region's roster.
+ */
+declare function fallbackModelsFor(region: 'cn' | 'global'): readonly WorkBuddyModelInfo[];
 /**
  * Derive the runtime catalog from the last-refreshed directory plus the
  * user's selection. This is the single source of truth for what DSH exposes,
@@ -333,6 +413,12 @@ declare function deriveCatalog(catalog: readonly WorkBuddyModelInfo[], enabled:
 /** Mutable catalog shared by the shim's `/v1/models` and the adapter. */
 declare class WorkBuddyCatalog {
   private models;
+  /**
+   * @param region Seeds the static fallback for this region; each region's
+   * provider must never serve the other region's roster before its first
+   * live refresh lands.
+   */
+  constructor(region?: 'cn' | 'global');
   /** Current entries; the fallback list until the upstream answer lands. */
   current(): readonly WorkBuddyModelInfo[];
   /** Replace the list; callers invalidate their adapter snapshot after this. */
@@ -375,8 +461,16 @@ interface WorkBuddyShimOptions {
 declare function createWorkBuddyShim(options: WorkBuddyShimOptions): WorkBuddyShim;
 //#endregion
 //#region src/adapter.d.ts
-/** Provider route this bundle owns. */
+/** Provider route this bundle owns for the domestic (CN) gateway. */
 declare const WORKBUDDY_PROVIDER = "workbuddy";
+/** Provider route this bundle owns for the international gateway. */
+declare const WORKBUDDY_GLOBAL_PROVIDER = "workbuddy-global";
+/** The provider id each region registers as. */
+declare const WORKBUDDY_PROVIDERS: Readonly<Record<WorkBuddyRegion, string>>;
+/** Region a provider route id belongs to. */
+declare function regionOfProvider(provider: string): WorkBuddyRegion | undefined;
+/** Human-readable provider name, shown in the DSH model picker. */
+declare const WORKBUDDY_PROVIDER_DISPLAY_NAMES: Readonly<Record<WorkBuddyRegion, string>>;
 /** Provider idle ceiling while one stream read is outstanding. */
 declare const WORKBUDDY_STREAM_IDLE_TIMEOUT_MS = 300000;
 /** Constructor dependencies. */
@@ -384,6 +478,10 @@ interface WorkBuddyAdapterOptions {
   shim: WorkBuddyShim;
   store: WorkBuddyCredentialStore;
   catalog: WorkBuddyCatalog;
+  /** Provider route id this instance serves; defaults to the CN route. */
+  provider?: string;
+  /** pi-ai provider name and profile display name; defaults to the CN name. */
+  displayName?: string;
   /** Resolve the durable attachment service at request time, when present. */
   resolveAttachments?: () => AttachmentStore | undefined;
 }
@@ -507,6 +605,21 @@ declare const WORKBUDDY_MODELS_REFRESH_PATH = "/plugins/dsh-connect-workbuddy/mo
 declare const WORKBUDDY_ACCOUNTS_REFRESH_PATH = "/plugins/dsh-connect-workbuddy/accounts/refresh";
 /** Plugin-owned daily check-in action endpoint. */
 declare const WORKBUDDY_CHECKIN_PATH = "/plugins/dsh-connect-workbuddy/checkin";
+/** Query parameter naming the region a card request addresses. */
+declare const WORKBUDDY_REGION_PARAM = "region";
+/** Every region, in card tab order. */
+declare const WORKBUDDY_REGIONS: readonly WorkBuddyWebRegion[];
+/**
+ * Address one region's status route. The two regions are separate provider
+ * stacks; every card request carries the region whose tab the user is on.
+ */
+declare function withWorkBuddyRegion(path: string, region: WorkBuddyWebRegion): string;
+/**
+ * Read the region parameter off a status-route URL. Absent means the domestic
+ * tab (`cn`); a present-but-unknown value returns undefined so the route can
+ * answer 400 instead of guessing.
+ */
+declare function regionOfStatusUrl(url: string): WorkBuddyWebRegion | undefined;
 /** One credit package as the upstream returns it, node-free. */
 interface WorkBuddyWebCreditPackage {
   packageName: string;
@@ -579,6 +692,12 @@ interface WorkBuddyWebAccount {
   selected: boolean;
 }
 type WorkBuddyWebPackage = WorkBuddyWebCreditPackage;
+/**
+ * Region of the signed-in credential: the CN app (`codebuddy.cn` /
+ * `workbuddy.cn`) or the international WorkBuddy AI app (`workbuddy.ai`).
+ * The card uses this to read and write the matching per-region model slot.
+ */
+type WorkBuddyWebRegion = 'cn' | 'global';
 /** The JSON document the plugin card renders. */
 type WorkBuddyWebUsage = {
   status: 'signed-out';
@@ -590,6 +709,8 @@ type WorkBuddyWebUsage = {
   accountName: string;
   uin?: string;
   domain?: string;
+  /** Which per-region model directory and selection this account owns. */
+  region: WorkBuddyWebRegion;
   source?: 'desktop' | 'dsh';
   tokenExpiresAtMs: number;
   accounts: readonly WorkBuddyWebAccount[];
@@ -608,25 +729,33 @@ type WorkBuddyWebUsage = {
 //#region src/web-status.d.ts
 /** Constructor dependencies. */
 interface WorkBuddyStatusRouteOptions {
-  store: WorkBuddyCredentialStore;
+  /** The region-scoped credential store backing each region's requests. */
+  store(region: WorkBuddyRegion): WorkBuddyCredentialStore;
   client: Pick<WorkBuddyUpstreamClient, 'fetchCredits' | 'fetchCheckinStatus' | 'claimDailyCheckin'>;
-  /** The last-refreshed model directory (unfiltered) for card display. */
-  displayModels(): readonly WorkBuddyModelInfo[];
-  /** The user's selection, stored as model ids. */
-  enabledModelIds(): readonly string[];
-  /** Model ids the user opted into image input. */
-  imageModelIds(): readonly string[];
-  /** Saved local DSH context budgets by model id. */
-  contextBudgets(): Readonly<Record<string, number | undefined>>;
-  /** Re-read the live catalog from the upstream. */
-  discoverModels?(signal?: AbortSignal): Promise<readonly WorkBuddyModelInfo[]>;
+  /**
+   * The requested region's last-refreshed model directory (unfiltered) for
+   * card display. Region-scoped because the CN and international apps expose
+   * different rosters; showing one region's directory on the other account is
+   * the bug this parameter exists to prevent.
+   */
+  displayModels(region: WorkBuddyRegion): readonly WorkBuddyModelInfo[];
+  /** The requested region's selection, stored as model ids. */
+  enabledModelIds(region: WorkBuddyRegion): readonly string[];
+  /** Model ids the user opted into image input, for the requested region. */
+  imageModelIds(region: WorkBuddyRegion): readonly string[];
+  /** Saved local DSH context budgets by model id, for the requested region. */
+  contextBudgets(region: WorkBuddyRegion): Readonly<Record<string, number | undefined>>;
+  /** Re-read the live catalog of one region from the upstream. */
+  discoverModels?(region: WorkBuddyRegion, signal?: AbortSignal): Promise<readonly WorkBuddyModelInfo[]>;
 }
 /**
- * Assemble the card's usage document. Sign-in state is read-only; credit is a
- * live billing answer whose failure degrades to `creditsError` rather than
- * failing the whole document.
+ * Assemble one region's card document. `region` is the tab the card is on;
+ * the region-scoped store already answers with only that region's accounts,
+ * so the document's model slots and account list are that region's by
+ * construction. Sign-in state is read-only; credit is a live billing answer
+ * whose failure degrades to `creditsError` rather than failing the document.
  */
-declare function workBuddyWebStatus(deps: WorkBuddyStatusRouteOptions): Promise<WorkBuddyWebUsage>;
+declare function workBuddyWebStatus(deps: WorkBuddyStatusRouteOptions, region: WorkBuddyRegion): Promise<WorkBuddyWebUsage>;
 /**
  * Mount the read-only routes on a context where `webServer` is available.
  * The caller uses `ctx.inject(['webServer'], ...)`, so Desktop startup order
@@ -641,28 +770,71 @@ declare const name = "dsh-connect-workbuddy";
 declare const inject: string[];
 /** Settings namespace for the plugin configuration card. */
 declare const WORKBUDDY_SETTINGS_NS: SettingsNamespace;
+/** One region's model directory and the user's selection within it. */
+interface WorkBuddyRegionState {
+  /** The last-refreshed directory for this region; what the card displays. */
+  lastCatalog?: WorkBuddyModelInfo[];
+  /** The user's selection in this region, as model ids. */
+  enabledModelIds?: string[];
+  /** Model ids the user explicitly opted into image input. */
+  imageModelIds?: string[];
+  /** Local DSH context budget per model in this region. */
+  contextBudgets?: Record<string, WorkBuddyContextBudget>;
+}
 /** Plugin configuration. */
 interface Config {
   /** Explicit WorkBuddy desktop auth-file path, overriding env and platform defaults. */
   authFile?: string;
-  /** Stable local account selector; tokens remain outside settings. */
+  /**
+   * @deprecated Legacy single-slot account selector from before the dual
+   * provider split. It is attributed to whichever region the account actually
+   * belongs to (resolved once at startup from the local account scan); new
+   * writes go to {@link Config.accounts}.
+   */
   accountId?: string;
-  /** The last-refreshed model directory; what the plugin card displays. */
+  /**
+   * Per-region account selections, keyed `cn` | `global`. Each region's tab
+   * writes its own slot; tokens remain outside settings.
+   */
+  accounts?: Partial<Record<WorkBuddyRegion, string>>;
+  /**
+   * Per-region model state, keyed `cn` | `global`. The CN app and the
+   * international WorkBuddy AI app expose different rosters, so each keeps its
+   * own directory and selection and switching accounts never drops the other
+   * region's picks.
+   */
+  regions?: Partial<Record<WorkBuddyRegion, WorkBuddyRegionState>>;
+  /**
+   * @deprecated Legacy single-slot fields from before the region split. They
+   * predate international support and are read as the CN region's state when
+   * `regions.cn` is absent; new writes go to `regions`.
+   */
   lastCatalog?: WorkBuddyModelInfo[];
-  /** The user's selection, as model ids. */
+  /** @deprecated See {@link Config.lastCatalog}. */
   enabledModelIds?: string[];
-  /** Model ids the user explicitly opted into image input. */
+  /** @deprecated See {@link Config.lastCatalog}. */
   imageModelIds?: string[];
-  /** Local DSH context budget per model; models above 200K default to 200K. */
+  /** @deprecated See {@link Config.lastCatalog}. */
   contextBudgets?: Record<string, WorkBuddyContextBudget>;
 }
 declare const Config: z<Config>;
 /**
- * Start the loopback endpoint, register the `workbuddy` provider, and
- * refresh the model catalog from the upstream once credentials allow it.
- * The static fallback catalog serves from the first moment, so an offline
- * upstream never leaves the provider empty.
+ * One region's saved model state. A config written before the region split has
+ * only the flat fields: those were always captured from the CN endpoint (the
+ * plugin had no international support), so they are read as the CN state and
+ * only when no explicit CN slot exists. The global region never inherits them —
+ * that inheritance is exactly the bug where a stale CN directory was
+ * intersected with the international catalog and silently dropped the user's
+ * picks.
+ */
+declare function regionStateOf(config: Config, region: WorkBuddyRegion): WorkBuddyRegionState;
+/**
+ * Start both regions' loopback endpoints, register the `workbuddy` (CN) and
+ * `workbuddy-global` (international) providers, and refresh each region's
+ * model catalog from the upstream once that region's credentials allow it.
+ * The static fallback catalogs serve from the first moment, so an offline
+ * upstream never leaves a provider empty.
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, FALLBACK_WORKBUDDY_MODELS, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyReasoning, type WorkBuddyRefreshOutcome, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyWebAccount, type WorkBuddyWebCheckin, type WorkBuddyWebCredits, type WorkBuddyWebModel, type WorkBuddyWebPackage, type WorkBuddyWebUsage, apply, authFileName, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveCatalog, inject, isHeartbeatProcessAlive, name, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readHostHeartbeat, regionOf, registerWorkBuddyStatusRoute, toPersistedWorkBuddyModel, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };
+export { Config, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyReasoning, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyWebAccount, type WorkBuddyWebCheckin, type WorkBuddyWebCredits, type WorkBuddyWebModel, type WorkBuddyWebPackage, type WorkBuddyWebRegion, type WorkBuddyWebUsage, apply, authFileName, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveCatalog, fallbackModelsFor, inject, isHeartbeatProcessAlive, legacyWorkbuddyOwnAuthPath, name, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readHostHeartbeat, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, toPersistedWorkBuddyModel, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };