dsh-workbuddy-connect 0.2.1

package/lib/index.d.ts

@@ -0,0 +1,332 @@
+import z from "@deepseek-ai/schemastery";
+import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+import { Context } from "@deepseek-ai/cordis";
+import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
+//#region src/upstream.d.ts
+/** WorkBuddy region selected by the credential's login domain. */
+type WorkBuddyRegion = 'cn' | 'global';
+/** Upstream failure classes the shim maps onto distinct HTTP answers. */
+type UpstreamErrorKind = 'hard_credit' | 'soft_rate' | 'session_dead' | 'not_found' | 'server' | 'client';
+/** One CLI-usable model as the upstream catalog describes it. */
+interface WorkBuddyUpstreamModel {
+  id: string;
+  name: string;
+  contextWindow: number;
+  maxTokens: number;
+}
+/** One billing package and its remaining credit. */
+interface WorkBuddyCreditAccount {
+  packageName: string;
+  remain: number;
+  size: number;
+}
+/** Aggregated credit answer for one credential. */
+interface WorkBuddyCredits {
+  total: number;
+  accounts: readonly WorkBuddyCreditAccount[];
+}
+/** Token refresh answer; fields the upstream omits stay absent. */
+interface WorkBuddyRefreshOutcome {
+  accessToken: string;
+  refreshToken?: string;
+  expiresInSec?: number;
+  domain?: string;
+}
+/** Chat answer: either a live SSE response or a classified failure. */
+type WorkBuddyChatResult = {
+  ok: true;
+  response: Response;
+} | {
+  ok: false;
+  status: number;
+  kind: UpstreamErrorKind;
+  message: string;
+};
+/** Classify an upstream failure from its HTTP status and body excerpt. */
+declare function classifyUpstreamError(status: number, body: string): UpstreamErrorKind;
+/** Region for a login domain; an empty domain means CN (matching upstream tooling). */
+declare function regionOf(domain: string): WorkBuddyRegion;
+/**
+ * Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
+ * force `stream: true` (the upstream rejects non-streaming) and flatten
+ * `tool_choice` (the upstream's field is a string; object forms return 400).
+ */
+declare function prepareChatBody(source: string): string;
+/**
+ * Upstream HTTP client. One instance serves the whole plugin; requests take
+ * the credential explicitly so token refreshes apply on the next call.
+ */
+declare class WorkBuddyUpstreamClient {
+  /** POST the chat endpoint; a successful answer is the raw SSE response. */
+  chatStream(credential: WorkBuddyCredential, bodyJson: string, signal?: AbortSignal): Promise<WorkBuddyChatResult>;
+  /** 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. */
+  fetchModels(credential: WorkBuddyCredential): Promise<readonly WorkBuddyUpstreamModel[]>;
+  /** POST the billing endpoint for the aggregated remaining credit. */
+  fetchCredits(credential: WorkBuddyCredential): Promise<WorkBuddyCredits>;
+}
+//#endregion
+//#region src/auth.d.ts
+/** Normalized WorkBuddy credential, timestamps in epoch milliseconds. */
+interface WorkBuddyCredential {
+  accessToken: string;
+  refreshToken: string;
+  expiresAtMs: number;
+  refreshExpiresAtMs?: number;
+  domain: string;
+  uid: string;
+  enterpriseId?: string;
+  nickname?: string;
+  /** Which storage the credential was read from; refreshes are always `dsh`. */
+  source: 'desktop' | 'dsh';
+}
+/** Read-only sign-in summary for status and doctor output. */
+interface WorkBuddyAuthStatus {
+  state: 'signed-in' | 'signed-out';
+  expiresAtMs?: number;
+  refreshExpiresAtMs?: number;
+  nickname?: string;
+  domain?: string;
+  source?: 'desktop' | 'dsh';
+}
+/** Constructor options; only {@link refresh} is required. */
+interface WorkBuddyStoreOptions {
+  /** Explicit desktop auth-file path, overriding env and platform defaults. */
+  desktopPath?: string;
+  /** Explicit plugin-owned copy path, defaulting under `$DSH_HOME`. */
+  ownPath?: string;
+  /** Performs the upstream token refresh. */
+  refresh: (credential: WorkBuddyCredential) => Promise<WorkBuddyRefreshOutcome>;
+  /** Refresh this long before actual expiry; default five minutes. */
+  refreshMarginMs?: number;
+}
+/** Basename of the plugin-owned credential copy inside the Harness home. */
+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;
+/** Platform default for the WorkBuddy desktop app's auth file. */
+declare function defaultDesktopAuthPath(): string | undefined;
+/**
+ * Parse a WorkBuddy auth document in either on-disk shape: the plugin OAuth
+ * nested form `{"auth":{...},"account":{...}}` and the flat panel form.
+ * Returns undefined when the document carries no access token.
+ */
+declare function parseWorkBuddyAuth(text: string): WorkBuddyCredential | undefined;
+/**
+ * Read-only credential store with demand-driven refresh.
+ *
+ * Refresh policy: refresh only when the access token is inside the margin
+ * (or already expired), keep the refreshed credential in the plugin-owned
+ * copy, and never write the desktop app's file. A failed refresh still
+ * returns a not-yet-expired token so an unreachable refresh endpoint does
+ * not take down a working session.
+ */
+declare class WorkBuddyCredentialStore {
+  private readonly refresh;
+  private readonly refreshMarginMs;
+  private readonly ownPath;
+  private desktopPathOverride;
+  private inflight;
+  constructor(options: WorkBuddyStoreOptions);
+  /**
+   * Configuration precedence for the desktop file: the plugin's configured
+   * path, then the environment variable, then the platform default.
+   */
+  private resolveDesktopPath;
+  /**
+   * Repoint the desktop file; a settings change applies on the next read.
+   */
+  setDesktopPath(path: string | undefined): void;
+  /** The resolved desktop auth-file path, for diagnostics. */
+  desktopAuthPath(): string | undefined;
+  /** The plugin-owned copy path, for diagnostics. */
+  ownAuthPath(): string;
+  /** Read the freshest stored credential without refreshing anything. */
+  current(): Promise<WorkBuddyCredential | undefined>;
+  /**
+   * The credential to send upstream: {@link current}, refreshed on demand.
+   * Single-flight, so parallel requests share one refresh.
+   */
+  resolve(): Promise<WorkBuddyCredential>;
+  /** Read-only sign-in summary; never refreshes and never throws. */
+  status(): Promise<WorkBuddyAuthStatus>;
+  /** Remove the plugin-owned copy; the desktop file is untouched. */
+  logout(): Promise<void>;
+  private needsRefresh;
+  private refreshNow;
+  private saveOwn;
+  private readDesktop;
+  private readOwn;
+  /** Whether the desktop file exists and is a regular file; diagnostics only. */
+  desktopFilePresent(): Promise<boolean>;
+}
+//#endregion
+//#region src/catalog.d.ts
+/** One model entry the adapter exposes. */
+type WorkBuddyModelInfo = WorkBuddyUpstreamModel;
+/**
+ * Static CLI models observed on the CN endpoint (2026-08-17). The upstream
+ * refresh replaces this list at startup; it exists so the provider registers
+ * with a usable catalog even while the first fetch is in flight or offline.
+ */
+declare const FALLBACK_WORKBUDDY_MODELS: readonly WorkBuddyModelInfo[];
+/** Mutable catalog shared by the shim's `/v1/models` and the adapter. */
+declare class WorkBuddyCatalog {
+  private models;
+  /** Current entries; the fallback list until the upstream answer lands. */
+  current(): readonly WorkBuddyModelInfo[];
+  /** Replace the list; callers invalidate their adapter snapshot after this. */
+  set(models: readonly WorkBuddyModelInfo[]): void;
+}
+//#endregion
+//#region src/shim.d.ts
+/** Minimal logger surface the plugin context already provides. */
+interface ShimLogger {
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+/** What the plugin needs from a running shim. */
+interface WorkBuddyShim {
+  /** Resolves once the listener is up; rejects if listening failed. */
+  ready: Promise<void>;
+  /** The shim origin, e.g. `http://127.0.0.1:39271`; valid after ready. */
+  baseUrl(): string;
+  /**
+   * The per-process shared secret the plugin's own client must carry as
+   * `Authorization: Bearer <token>`. Lives only in memory; the adapter
+   * resolves this instead of the upstream access token, because the shim
+   * resolves the real credential itself via the store.
+   */
+  token(): string;
+  /** Stop serving and destroy open connections. */
+  close(): Promise<void>;
+}
+/** Constructor dependencies. */
+interface WorkBuddyShimOptions {
+  store: WorkBuddyCredentialStore;
+  client: Pick<WorkBuddyUpstreamClient, 'chatStream'>;
+  catalog: WorkBuddyCatalog;
+  logger?: ShimLogger;
+}
+/**
+ * Start the loopback endpoint. Requests carry any bearer; the loopback bind
+ * is the boundary, and the upstream credential comes from the store alone.
+ */
+declare function createWorkBuddyShim(options: WorkBuddyShimOptions): WorkBuddyShim;
+//#endregion
+//#region src/adapter.d.ts
+/** Provider route this bundle owns. */
+declare const WORKBUDDY_PROVIDER = "workbuddy";
+/** Provider idle ceiling while one stream read is outstanding. */
+declare const WORKBUDDY_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Constructor dependencies. */
+interface WorkBuddyAdapterOptions {
+  shim: WorkBuddyShim;
+  store: WorkBuddyCredentialStore;
+  catalog: WorkBuddyCatalog;
+  /** Resolve the durable attachment service at request time, when present. */
+  resolveAttachments?: () => AttachmentStore | undefined;
+}
+/** What {@link createWorkBuddyAdapter} hands back. */
+interface WorkBuddyAdapter {
+  adapter: PiAiAdapter;
+  /** Rebuild the adapter's provider snapshot; call after a catalog update. */
+  invalidate: () => void;
+}
+/**
+ * Assemble the adapter. The provider's `getModels` reads the live catalog,
+ * and every model's `baseUrl` is re-resolved per read so the shim's
+ * ephemeral port applies from the first snapshot after startup.
+ */
+declare function createWorkBuddyAdapter(options: WorkBuddyAdapterOptions): WorkBuddyAdapter;
+//#endregion
+//#region src/host-heartbeat.d.ts
+/**
+ * Host-side heartbeat: a small JSON file written under `$DSH_HOME` once the
+ * `workbuddy` provider is registered. The status CLI reads it to report
+ * whether the host bundle is alive, independent of the browser card.
+ *
+ * The browser (client) bundle cannot write files; its health is reported
+ * only through `console.error` on failure (see `src/client/index.tsx`).
+ * This asymmetry is intentional: the host is the load-bearing half, and
+ * a missing heartbeat unambiguously means the host never started.
+ *
+ * @module dsh-workbuddy-connect/host-heartbeat
+ */
+/** Basename of the host heartbeat file inside the Harness home. */
+declare const WORKBUDDY_HOST_HEARTBEAT_FILENAME = ".workbuddy-host-heartbeat.json";
+/** Current on-disk heartbeat format; readers reject others. */
+declare const HEARTBEAT_FORMAT_VERSION = 1;
+/** On-disk shape of the heartbeat. */
+interface WorkBuddyHostHeartbeat {
+  version: typeof HEARTBEAT_FORMAT_VERSION;
+  package: 'dsh-workbuddy-connect';
+  pluginVersion: string;
+  /** Epoch milliseconds when the host registered the provider. */
+  registeredAt: number;
+  /** Host process PID, to distinguish a stale heartbeat after a crash. */
+  pid: number;
+}
+/** Absolute path of the host heartbeat file. */
+declare function workbuddyHostHeartbeatPath(): string;
+/** Remove the heartbeat on plugin disposal so a stale file does not linger. */
+declare function clearHostHeartbeat(): Promise<void>;
+/** Read and validate the heartbeat; returns `undefined` when absent or malformed. */
+declare function readHostHeartbeat(): Promise<WorkBuddyHostHeartbeat | undefined>;
+/**
+ * Absolute start time (epoch ms) of the process holding `pid`, or `undefined`
+ * when it cannot be determined (no such PID, platform lacks a readable source).
+ *
+ * - macOS / Linux: `ps -o lstart=` prints a local-time "EEE MMM DD HH:MM:SS YYYY";
+ *   `Date.parse` resolves it against the local clock, which matches how
+ *   `registeredAt` (a `Date.now()` absolute value) is expressed.
+ * - Windows: WMI `CreationDate` is UTC (`YYYYMMDDHHMMSS.mmm+zzzz`); parsed with
+ *   `Date.UTC`, again comparable to `registeredAt`.
+ *
+ * Failures return `undefined` so callers can fall back to plain PID liveness
+ * rather than mis-report a running host as dead.
+ */
+declare function processStartTimeMs(pid: number): number | undefined;
+/**
+ * Whether the heartbeat's PID is still alive *and* still the same process that
+ * registered it. A stale heartbeat (host crashed without clearing the file)
+ * is distinguished from a live host by two checks:
+ *
+ * 1. `process.kill(pid, 0)` — the PID exists (signal 0 tests existence).
+ * 2. The process holding that PID started at or before `registeredAt`. A host
+ *    that registered the heartbeat must have been started before writing it,
+ *    so `start <= registeredAt`; a recycled PID belongs to an unrelated process
+ *    started after the host died, so `start > registeredAt` correctly reads dead.
+ *
+ * PID-only detection is not enough: after a crash the OS may hand the same PID
+ * to an unrelated process, and the un-cleared stale heartbeat would otherwise
+ * produce a false "Host running". When the process start time cannot be read
+ * (e.g. unsupported platform) the check degrades to plain PID liveness.
+ */
+declare function isHeartbeatProcessAlive(heartbeat: WorkBuddyHostHeartbeat): boolean;
+//#endregion
+//#region src/index.d.ts
+/** Stable Cordis plugin name. */
+declare const name = "llm-workbuddy";
+/** The model registry required before the provider can register. */
+declare const inject: string[];
+/** Settings namespace reserved for the future configuration card. */
+declare const WORKBUDDY_SETTINGS_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Plugin configuration. */
+interface Config {
+  /** Explicit WorkBuddy desktop auth-file path, overriding env and platform defaults. */
+  authFile?: string;
+}
+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.
+ */
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, FALLBACK_WORKBUDDY_MODELS, type UpstreamErrorKind, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_PROVIDER, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, type WorkBuddyAdapter, type WorkBuddyAuthStatus, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, WorkBuddyCredentialStore, type WorkBuddyCredits, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyRefreshOutcome, type WorkBuddyShim, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, apply, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthPath, inject, isHeartbeatProcessAlive, name, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readHostHeartbeat, regionOf, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath };