@eddyskywalker/dsh-chatgpt-subscription 0.46.1 → 0.47.0

package/lib/types/host/workbuddy/adapter.d.ts

@@ -0,0 +1,249 @@
+import { LlmAdapter, LlmError, ReasoningEffortId, type GenerateOptions, type LlmModelInfo, type LlmProviderInfo, type LlmResolvedModelInfo, type PreparedAdapterCall, type ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { PROVIDER_ID, PROVIDER_NAME } from './types.ts';
+import { FileCredentialStore, FileModelSettingsStore, type WorkBuddyPreferenceStore } from './token-store.ts';
+import { type WorkBuddyModelEntry } from './model-catalog.ts';
+import { type AttachmentImageReader } from './mapper.ts';
+import { type WorkBuddyAccountRestrictionDto } from '../../shared/workbuddy-contracts.ts';
+import type { WorkBuddyCredentials } from './token-store.ts';
+import { type WorkBuddyUsageLedger } from './guardrails.ts';
+/**
+ * Effort this route materializes when the caller names none.
+ *
+ * Preference order: the user's configured level when the model accepts it,
+ * otherwise the level the gateway's own catalog declares for that model (the
+ * same default the official CLI applies), otherwise nothing — which leaves the
+ * provider's own default in charge. A configured level the model does not
+ * accept is ignored rather than sent, since the endpoint rejects an unsupported
+ * level with `code 11150`.
+ */
+export declare function resolveDefaultReasoningEffort(efforts: readonly string[], configuredEffort?: string | null, modelDefaultEffort?: string | null): ReasoningEffortId | undefined;
+/** Cooldown a 429 imposes when the service names no reset instant. */
+export declare const POOL_COOLDOWN_MS: number;
+/**
+ * The account pool this adapter drives, declared STRUCTURALLY.
+ *
+ * The pool module (`account-pool.ts`) and the settings routes are outside this
+ * file's boundary — Wave 3 owns them — so the adapter cannot import the class.
+ * Declaring the shape it calls has one property that matters here: this file is
+ * typechecked against the CONTRACT, so a method renamed on the pool side fails
+ * the build instead of failing at run time in the middle of a rotation loop.
+ *
+ * `markAccountRestriction` is the one member the pool worker FROZE for Wave 2B:
+ * code 11140 is an account verdict (who is asking), not a model verdict, and a
+ * `cooldownUntil` on the account or on a model cannot express "this account is
+ * barred from everything".
+ */
+export interface WorkBuddyAccountPool {
+    listAccounts(): Promise<readonly {
+        id: string;
+    }[]>;
+    getEffectiveCredential(tried: ReadonlySet<string>, fetchFn: typeof fetch, model?: string): Promise<{
+        account: {
+            id: string;
+        };
+        credentials: WorkBuddyCredentials;
+    }>;
+    renewCredential(accountId: string, fetchFn: typeof fetch, current: WorkBuddyCredentials): Promise<WorkBuddyCredentials>;
+    hasAnotherAvailableAccount(tried: ReadonlySet<string>): Promise<boolean>;
+    hasAnotherAvailableAccountFor(tried: ReadonlySet<string>, model: string): Promise<boolean>;
+    markCooldown(accountId: string, ms: number, reason: string): Promise<unknown>;
+    markModelCooldown(accountId: string, model: string, until: number): void;
+    /** Freeze this account out of every model after code 11140. */
+    markAccountRestriction(accountId: string, restriction: WorkBuddyAccountRestrictionDto): Promise<void>;
+}
+/**
+ * The pool's own "everything is stopped" error.
+ *
+ * Read structurally (by `name`) rather than by `instanceof`: the class lives in
+ * the pool module this file may not import, and a plugin build that loaded the
+ * pool and the adapter through two module instances would fail an `instanceof`
+ * check that the name comparison passes.
+ */
+export interface WorkBuddyPoolPausedErrorLike extends Error {
+    name: 'WorkBuddyPoolPausedError';
+    /** Why the whole pool is stopped; composed by the host, never a token. */
+    pauseReason?: string;
+    /** Unix milliseconds the pause lifts on its own, when it does. */
+    pausedUntil?: number;
+}
+/** Whether one thrown value is the pool's whole-pool pause. */
+export declare function isPoolPausedError(error: unknown): error is WorkBuddyPoolPausedErrorLike;
+/**
+ * Which of the account's models the picker may offer.
+ *
+ * The stored list is kept relative to what the ACCOUNT can serve, and the
+ * shipped default is not a stored preference: a user who never visited the
+ * picker has exactly the shipped defaults stored, and that state has to mean
+ * "everything this account can serve" — otherwise a model the catalog gained
+ * after the last visit would be hidden from someone who never hid it.
+ */
+export declare function resolveEnabledModelIds(stored: readonly string[], available: readonly string[], enabled?: boolean): string[];
+/** Most system texts this process remembers (FIFO beyond it). */
+export declare const REFUSED_SYSTEM_MEMORY_LIMIT = 256;
+/** Remember one refused system text, evicting the oldest past the limit. */
+export declare function rememberRefusedSystemKey(key: string): void;
+/** Whether this process has already been refused for that system text. */
+export declare function refusedSystemKeyKnown(key: string): boolean;
+/** How many system texts are remembered (test and diagnostics seam). */
+export declare function refusedSystemKeyCount(): number;
+/** Forget every remembered refusal (test seam; never called by the adapter). */
+export declare function clearRefusedSystemKeys(): void;
+export interface WorkBuddyAdapterOptions {
+    /**
+     * Per-account daily token counters behind the local guardrails.
+     *
+     * Absent means the guardrails cannot be evaluated, so a deployment without it
+     * never refuses a request for a reason nothing is counting.
+     */
+    usageLedger?: WorkBuddyUsageLedger;
+    fetchFn?: typeof fetch;
+    attachments?: AttachmentImageReader;
+    /** Live catalog loader seam; defaults to the gateway `/v3/config` call. */
+    loadCatalog?: (credentials: WorkBuddyCredentials) => Promise<WorkBuddyModelEntry[]>;
+    /**
+     * Multi-account pool this adapter rotates through.
+     *
+     * Absent leaves the line on its single-credential path, which is what the
+     * headless tests and any caller that predates the pool use.
+     */
+    accountPool?: WorkBuddyAccountPool;
+}
+export declare class WorkBuddyAdapter extends LlmAdapter {
+    private readonly store;
+    private readonly modelSettings;
+    private readonly preferences?;
+    private readonly options;
+    /** Null keeps the pre-pool single-credential path. */
+    private readonly accountPool;
+    constructor(store?: FileCredentialStore, modelSettings?: FileModelSettingsStore, preferences?: WorkBuddyPreferenceStore | undefined, options?: WorkBuddyAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): ResolvedRetryPolicy;
+    imageRequestPricing(): undefined;
+    /**
+     * Request version the harness should hand this route for one image.
+     *
+     * This is the other half of the request image budget and it has to come from
+     * the same place: the shared kernel decides the target (long edge 1024,
+     * 256 KiB per image) and the shared budget decides what still fits, so a
+     * mapper cannot ask for a target the harness does not produce, and cannot
+     * send an image the kernel already paid to downscale. Answering undefined
+     * here used to mean send-as-stored while the mapper applied its own private
+     * 12 MB ceiling, which is exactly the drift this pairing removes.
+     */
+    imageRequestTarget(_provider: string, _model: string, image: ImageAttachmentRef): {
+        width: number;
+        height: number;
+        maxBytes: number;
+    };
+    private settings;
+    private credentials;
+    /**
+     * Catalog for the picker: the live gateway listing when reachable, the
+     * shipped table otherwise.
+     *
+     * The gateway is the authority on capabilities, so its answer replaces the
+     * fallback rather than merging with it — a model whose context window changed
+     * upstream must not keep a stale local value.
+     */
+    private catalog;
+    /**
+     * Models the picker may offer.
+     *
+     * The catalog is filtered by the account's own region: asking a region for a
+     * model it does not serve answers 400 `code 11102`, so offering one would
+     * hand the user a model that cannot work.
+     */
+    listModels(provider?: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, modelId: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Effort this request should carry, or `undefined` to send none.
+     *
+     * Order: the caller's explicit choice, then the user's configured level, then
+     * the level the gateway catalog declares for this model. The last step
+     * matters because the endpoint returns an **empty `reasoning_content`** when
+     * no `reasoning_effort` is present, even for a reasoning-only model: measured
+     * on `deepseek-v4.1-flash`, the same prompt yields 0 reasoning characters
+     * with no field and 130-215 with one. Omitting it therefore silently drops
+     * the model's thinking instead of letting the provider pick, so the catalog's
+     * own default (which is what the official CLI sends) is materialized here.
+     *
+     * A candidate the model does not accept is discarded rather than sent, since
+     * the endpoint rejects an unsupported level with `code 11150`.
+     */
+    /**
+     * Accounts the LOCAL guardrails refuse for this model right now.
+     *
+     * Reads only numbers this plugin already owns — the billing snapshot's
+     * remaining credits and this line's own token counters — so it never becomes a
+     * second, disagreeing source of truth about the upstream allowance.
+     */
+    private guardrailBlockedAccounts;
+    private effortFor;
+    private requestStream;
+    /**
+     * Re-read the stored credential, for a token another process may have written.
+     *
+     * The desktop app and any sibling plugin share this directory, and a token
+     * written there is already the newest one available: refreshing over it would
+     * rotate the account's refresh token out from under whoever signed in last.
+     * A failed read answers null — it is a fallback, not a verdict.
+     */
+    private rereadCredential;
+    /**
+     * Count this request's billed tokens off its usage frame.
+     *
+     * Both protocols send exactly one usage frame at the end; the cache counts are
+     * added back because the aggregate the surfaces report excludes them, so a
+     * cached turn would otherwise be recorded as almost free.
+     */
+    private countedChunks;
+    /**
+     * Read one SSE body into chunks, protocol-agnostically.
+     *
+     * Bytes on the wire are the liveness signal: a heartbeat or status frame that
+     * produces no displayable chunk still proves the connection is alive, so the
+     * watchdog timer is reset at the transport layer, not at the parser.
+     */
+    private drainStream;
+}
+/**
+ * The failure a 11140 is reported as.
+ *
+ * Account-scoped, so it is classified apart from every model-scoped refusal: the
+ * message says the ACCOUNT is barred (not that a model is unavailable, not that
+ * a quota window is full), because the fix is a different account or a release
+ * from the service, and no retry can help.
+ */
+export declare function accountRestrictedFailure(detail: string, status: number): LlmError;
+/**
+ * Map one failed HTTP response onto a DSH failure.
+ *
+ * The subscription reports its own conditions inside a JSON `code` while the
+ * status line stays generic, so the body is read for the specific cases the
+ * status alone cannot express — notably the quota signal, whose message carries
+ * the instant the allowance resets.
+ */
+export declare function classifyFailure(status: number, detail: string, headers?: Headers): LlmError;
+/**
+ * The reset instant a quota refusal names, as a delay from now.
+ *
+ * A 24h allowance that is exhausted answers 429 / `code 6004` with the wall
+ * clock it lifts — but only in the MESSAGE, never in a header, and in two
+ * realm-specific wordings (measured: intl "… resets at 2026-09-20 10:50:48
+ * UTC+8", cn "… 将在 2026-10-09 14:44:59 UTC+8 重置"). Reading the status alone
+ * therefore loses the only fact that says how long the account is out, and the
+ * pool parks a 24-hour limit for five minutes before trying it again.
+ *
+ * Deliberately tolerant, in the same direction as their gateway: an unparseable
+ * body yields `undefined` (callers keep their default cooldown) rather than an
+ * error, because this runs on a failure path. An absent `UTC±h` marker means
+ * UTC, which is how the sibling implementation reads it too.
+ */
+export declare function readRateLimitReset(detail: string, now?: number): number | undefined;
+/** Read the subscription's own numeric error code out of a response body. */
+export declare function readErrorCode(detail: string): number | null;
+export { PROVIDER_ID, PROVIDER_NAME };
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/host/workbuddy/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/host/workbuddy/adapter.ts"],"names":[],"mappings":"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"}

package/lib/types/host/workbuddy/atrest.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `$wbEncrypted` at-rest credential envelope.
+ *
+ * The CodeBuddy/WorkBuddy desktop client stopped writing plaintext tokens on
+ * 2026-09-24: `auth.accessToken` / `auth.refreshToken` became
+ * `{"$wbEncrypted": 1, "envelope": base64}` (the domestic build also seals
+ * `nickname` / `phoneNumber`). Reading such a file the way this plugin used to
+ * yields the envelope TEXT as the bearer token, so every request answers 401 —
+ * the adoption path has to decrypt before it can use the credential.
+ *
+ * The scheme below is transcribed from the client's `packages/at-rest-crypto`
+ * as reimplemented by workbuddy2api-hub (`wb_atrest.py`, MIT); the framing
+ * constants are the part that must match byte for byte:
+ *
+ *     key      = sha256(atRestSecretKey as an ASCII string)   # the protector key
+ *     keyId    = sha256(key).hex[0..16]                       # `protectorKeyId`
+ *     AAD      = "WB-AAD\0" | 0x01 | LP(fileMagic) | LP("sym-v1")
+ *                | u32(suite) | LP(keyId) | framingCode | 0x00 | 0x00
+ *     envelope = base64(JSON{suite, keyId, nonce, authTag, ciphertext})  # AES-256-GCM
+ *     framing  : the keyblob's wrapped master key is `WBEF1`/1, a sealed `.info`
+ *                field is `WBEV1`/2 — the SAME protector key opens both.
+ *
+ * Key material never leaves the process and is never logged: the user pastes it
+ * once, it is stored through the platform credential store (DPAPI / Keychain /
+ * Secret Service), and every read re-validates it against the client's own
+ * keyblob when that file exists.
+ */
+/** Field name the client uses to mark a sealed value. */
+export declare const ENVELOPE_KEY = "$wbEncrypted";
+/** Framing kinds and the code each carries in the AAD. */
+declare const FRAMING: {
+    readonly file: {
+        readonly magic: "WBEF1";
+        readonly code: 1;
+    };
+    readonly field: {
+        readonly magic: "WBEV1";
+        readonly code: 2;
+    };
+};
+type Framing = keyof typeof FRAMING;
+/** Every failure the at-rest path can report to a user. */
+export declare class AtRestError extends Error {
+    constructor(message: string);
+}
+/** The GCM associated data, byte-identical to the client's. */
+export declare function associatedData(keyId: string, suite: number, framing: Framing): Buffer;
+/** `protectorKeyId` / `envelope.keyId`: the first 16 hex characters of sha256(key). */
+export declare function deriveKeyId(key: Buffer): string;
+/**
+ * Whether a value is a sealed envelope rather than plaintext.
+ *
+ * Older clients sometimes stored the whole envelope as a JSON STRING in the
+ * field, so that shape is recognised too.
+ */
+export declare function isSealedValue(value: unknown): boolean;
+interface SealedEnvelope {
+    suite: number;
+    keyId: string;
+    nonce: Buffer;
+    authTag: Buffer;
+    ciphertext: Buffer;
+}
+/** Split one envelope into its GCM parts. */
+export declare function parseEnvelope(value: unknown): SealedEnvelope;
+/** Open one envelope with the protector key, returning the plaintext bytes. */
+export declare function openEnvelope(key: Buffer, value: unknown, framing: Framing): Buffer;
+/** Decrypt a field that may be sealed, leaving plaintext values untouched. */
+export declare function openSealedField(key: Buffer, value: unknown): string;
+/**
+ * Normalise a pasted secret into the 32-byte protector key.
+ *
+ * Two spellings are accepted, neither requiring the user to compute anything:
+ * a 64-character hex protector key (used as-is), or the 44-character base64
+ * `atRestSecretKey` the client carries in its payload — that one is hashed as
+ * the STRING, which is what produces the protector key.
+ */
+export declare function parseKeyText(text: string): Buffer;
+/** Path of the client's keyblob, or null when the client is not installed here. */
+export declare function keyBlobPath(): string | null;
+/**
+ * Validate a protector key against the client's own keyblob.
+ *
+ * This is the check that turns a typo into an error instead of a mystery: the
+ * key must match the `static-v1` slot's `protectorKeyId` and must unwrap a
+ * 32-byte master whose derived id matches the blob's own `keyId`. Returns
+ * `false` when there is no keyblob to check against (the desktop client is not
+ * installed on this machine) — absence of evidence, not evidence of a bad key.
+ */
+export declare function verifyKeyAgainstKeyBlob(key: Buffer): Promise<boolean>;
+/** Install the protector key for this process (already persisted by the caller). */
+export declare function setActiveAtRestKey(key: Buffer | null): void;
+/** The protector key this process holds, if any. */
+export declare function activeAtRestKey(): Buffer | null;
+/** Whether sealed credentials can be opened right now. */
+export declare function hasAtRestKey(): boolean;
+export {};
+//# sourceMappingURL=atrest.d.ts.map

package/lib/types/host/workbuddy/atrest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atrest.d.ts","sourceRoot":"","sources":["../../../../src/host/workbuddy/atrest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH,yDAAyD;AACzD,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,0DAA0D;AAC1D,QAAA,MAAM,OAAO;;;;;;;;;CAGH,CAAC;AAEX,KAAK,OAAO,GAAG,MAAM,OAAO,OAAO,CAAC;AAQpC,2DAA2D;AAC3D,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAeD,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAWrF;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUrD;AAED,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAOD,6CAA6C;AAC7C,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAsB5D;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAkBlF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKnE;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQjD;AAUD,mFAAmF;AACnF,wBAAgB,WAAW,IAAI,MAAM,GAAG,IAAI,CAM3C;AAwBD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAkB3E;AAID,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE3D;AAED,oDAAoD;AACpD,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/lib/types/host/workbuddy/checkin.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Daily check-in scheduler for the CN-region billing activity.
+ *
+ * Ported from workbuddy2api's `daily_checkin.py` and adapted to this host:
+ * the cron job becomes an in-process timer (the plugin runs inside the DSH
+ * host, so a day the host never runs is a day nothing signs in — accepted and
+ * documented), and the per-file state JSON becomes one state document under
+ * the harness home. The semantics are kept exactly:
+ *
+ * - **CN only.** The international deployment exposes no check-in surface, so
+ *   those accounts are skipped rather than failing daily.
+ * - **Idempotent.** The activity status is queried first; an account already
+ *   signed in (by anyone) is only recorded. An account whose activity reports
+ *   no entitlement is parked (see {@link CHECKIN_INACTIVE_RECHECK_MS}) rather
+ *   than abandoned for the day: the host often starts before the activity's
+ *   daily opening, and treating that first answer as final cost the account its
+ *   only chance to sign in. Once everyone is settled, a tick sends no requests.
+ * - **Bounded.** A failing account is retried at most {@link CHECKIN_ATTEMPT_CAP}
+ *   times a day, so a broken account cannot turn the ten-minute tick into a
+ *   request loop. A manual run ignores the cap and the window, like the
+ *   reference script's `--now`, and is queued behind an in-flight run rather
+ *   than dropped into it (a click must actually mean "try again now").
+ *
+ * Tokens stay host-side: the only write beyond the state file is the existing
+ * credential store's refresh write-back, reused here unchanged.
+ */
+import { type FileCredentialStore } from './token-store.ts';
+import type { WorkBuddyCheckinSettings, WorkBuddyCheckinSummary } from '../../shared/workbuddy-contracts.ts';
+/** Activity status surface; answers whether today is signed in already. */
+export declare const CHECKIN_STATUS_PATH = "/billing/meter/checkin-activity-status";
+/** Check-in surface; credits are granted by posting here once a day. */
+export declare const CHECKIN_PATH = "/billing/meter/daily-checkin";
+/**
+ * Scheduler cadence. The first tick at host startup is the daily run; the
+ * interval keeps a long-lived process signing in on later days without a
+ * restart. Idle ticks cost no requests — the day state short-circuits them.
+ */
+export declare const CHECKIN_TICK_MS: number;
+/** Daily retry ceiling for one account after a failed attempt. */
+export declare const CHECKIN_ATTEMPT_CAP = 3;
+export declare const CHECKIN_TIMEOUT_MS = 20000;
+/**
+ * How long an unentitled account waits before the activity is polled again.
+ *
+ * The activity opens on its own schedule, so the first inactive answer of the
+ * day is frequently 'not open yet' rather than 'no entitlement today'. Hourly
+ * re-checks keep a host that booted early from missing the day, while still
+ * costing at most one status request per hour per account.
+ */
+export declare const CHECKIN_INACTIVE_RECHECK_MS: number;
+/**
+ * Random pause between two accounts in one pass.
+ *
+ * Sequential accounts already serialise their requests, but they still arrive as
+ * one tight cluster from one outbound IP; a dozen-account pool doing that at the
+ * same minute is the burst pattern the sibling gateway added jitter for after
+ * seeing upstream rate-limit whole pools.
+ */
+export declare const CHECKIN_JITTER_MIN_MS = 2000;
+export declare const CHECKIN_JITTER_MAX_MS = 5000;
+/** State document the scheduler keeps beside the other plugin stores. */
+export declare function checkinStatePath(): string;
+/** Local calendar day an instant belongs to; state entries are keyed by it. */
+export declare function localDateString(nowMs: number): string;
+export interface WorkBuddyCheckinServiceOptions {
+    fetchFn?: typeof fetch;
+    /** State document path; tests redirect it, production uses {@link checkinStatePath}. */
+    statePath?: string;
+    /** Live preferences, re-read on every tick so the toggle applies at once. */
+    settings: () => WorkBuddyCheckinSettings;
+    /**
+     * Resolves once the preference store has read its stored document.
+     *
+     * Optional for callers whose settings are already in memory; the host passes
+     * the preference store's own warmup so the startup pass cannot act on a
+     * default that the stored document is about to overwrite.
+     */
+    ready?: () => Promise<void>;
+    /** Clock injection for tests. */
+    now?: () => number;
+    /** Wait between two accounts in one pass; injected so tests run without delays. */
+    pause?: (ms: number) => Promise<void>;
+    /** Jitter source; injected so a test can pin the delay it caused. */
+    random?: () => number;
+    logger?: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+}
+/**
+ * The check-in scheduler. One instance per plugin load; the host owns the
+ * interval and clears it from the same `ctx.effect` that created it.
+ */
+export declare class WorkBuddyCheckinService {
+    private readonly store;
+    private readonly options;
+    private readonly fetchFn;
+    private readonly statePath;
+    private readonly now;
+    private readonly pause;
+    private readonly random;
+    private readonly logger;
+    private state;
+    private loaded;
+    /** Passes waiting to run, in order; `true` marks a manual pass. */
+    private readonly queue;
+    /** The drain loop currently working the queue, if any. */
+    private draining;
+    private lastRunAt;
+    /** Memoized preference warmup, so it is awaited once however many passes run. */
+    private readyWait;
+    constructor(store: FileCredentialStore, options: WorkBuddyCheckinServiceOptions);
+    /**
+     * One scheduler pass. Automatic passes honour the toggle and the retry cap;
+     * a manual pass (`manual: true`, the card's "check in now") ignores both
+     * but still respects an account already signed in today.
+     *
+     * A manual pass that lands while a run is already in flight is *queued*, not
+     * absorbed: joining the running pass would silently discard the one thing the
+     * button promises, that the retry cap and the toggle are bypassed now.
+     */
+    tick(manual?: boolean): Promise<void>;
+    /** Run queued passes one after another until the queue empties. */
+    private drain;
+    private runQueue;
+    private run;
+    /** Wait for the preference store's warmup read, once. */
+    private ready;
+    /** Check one account in, recording the outcome in its today's entry. */
+    private checkinOne;
+    /** Record a confirmed sign-in, clearing the transient failure bookkeeping. */
+    private markSignedIn;
+    /**
+     * Refresh a token the server rejected, bypassing the store's expiry check.
+     *
+     * `ensureFresh` only acts on a locally expired token, so a session the server
+     * revoked early would otherwise fail every retry until the file's own clock
+     * caught up. The rotation is written back through the store either way.
+     */
+    private forceRefresh;
+    /**
+     * The aggregate the settings card renders. Reads only local state and the
+     * account list; it never spends a network request.
+     */
+    summary(): Promise<WorkBuddyCheckinSummary>;
+    private load;
+    private save;
+    private post;
+}
+//# sourceMappingURL=checkin.d.ts.map

package/lib/types/host/workbuddy/checkin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkin.d.ts","sourceRoot":"","sources":["../../../../src/host/workbuddy/checkin.ts"],"names":[],"mappings":"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"}