dsh-connect-workbuddy 1.4.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>;
 }
@@ -355,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. */
@@ -397,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. */
@@ -406,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;
 }
@@ -529,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;
@@ -638,30 +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 selected region's last-refreshed model directory (unfiltered) for card
-   * display. Region-scoped because the CN and international apps expose
+   * 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 selected region's selection, stored as model ids. */
+  /** The requested region's selection, stored as model ids. */
   enabledModelIds(region: WorkBuddyRegion): readonly string[];
-  /** Model ids the user opted into image input, for the selected region. */
+  /** 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 selected region. */
+  /** 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 from the upstream. */
-  discoverModels?(signal?: AbortSignal): Promise<readonly WorkBuddyModelInfo[]>;
+  /** 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
@@ -691,8 +785,18 @@ interface WorkBuddyRegionState {
 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;
+  /**
+   * 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
@@ -725,11 +829,12 @@ declare const Config: z<Config>;
  */
 declare function regionStateOf(config: Config, region: WorkBuddyRegion): WorkBuddyRegionState;
 /**
- * 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.
+ * 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, FALLBACK_WORKBUDDY_MODELS_GLOBAL, 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, WorkBuddyRegionState, 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, fallbackModelsFor, inject, isHeartbeatProcessAlive, name, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readHostHeartbeat, regionOf, regionStateOf, 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 };