@eddyskywalker/dsh-chatgpt-subscription 0.46.1 → 0.47.0

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

@@ -0,0 +1,238 @@
+/**
+ * Wire mapping for the WorkBuddy / CodeBuddy subscription chat endpoint.
+ *
+ * The endpoint is OpenAI Chat Completions shaped, but with three measured
+ * deviations from the OpenAI default that this module exists to absorb:
+ *
+ * 1. **Stream only.** `stream: false` answers 400 `code 11101`. The request
+ *    builder therefore always sends `stream: true`, and there is no
+ *    non-streaming code path to keep in sync.
+ * 2. **A leading system message is mandatory on the international backend.**
+ *    A request whose first message is a user turn answers 400 `code 11128`
+ *    ("first message is not system prompt"). {@link buildChatRequest} injects
+ *    one when the caller supplied none, so a hand-built one-shot request cannot
+ *    trip this. Note that the same code is also the gateway's channel-verification
+ *    refusal (`msg: "conversation id missing"`), which the conversation header
+ *    group this route sends is what satisfies — see `conversationHeaders` in
+ *    `client.ts`. A history that is already correct can still answer 11128 for
+ *    that second reason, so the code alone does not implicate the messages.
+ * 3. **Reasoning rides `delta.reasoning_content`,** not OpenAI's
+ *    `reasoning_summary`, and is emitted as its own DSH reasoning block.
+ */
+import { type OutboundContentBlock, type GenerateOptions, type StreamChunk } from '../common/llm-compat.ts';
+import { MAX_REQUEST_IMAGE_BYTES, NO_RESOLVED_IMAGES, SUPPORTED_IMAGE_MEDIA_TYPES, attachmentLabel, imageBlockToInline, offloadOldestRequestImages, requestImageTargetOrOriginal, resolveRequestImages, unavailableImageText, type AttachmentImageReader, type ResolvedRequestImage, type ResolvedRequestImages } from '../common/request-images.ts';
+import { stripMetaSchema } from '../common/tool-schema.ts';
+export declare function sanitizeText(text: string): string;
+/**
+ * The system prompt every request must open with.
+ *
+ * The international backend rejects a request whose first message is not a
+ * system turn, so this stands in when the caller supplies no prompt at all. It
+ * is deliberately neutral: it must not change model behaviour beyond satisfying
+ * the shape check.
+ */
+declare const IMPLICIT_SYSTEM_PROMPT = "You are a helpful assistant.";
+/**
+ * The image seam is the SHARED kernel's, not this route's own.
+ *
+ * The old copy here carried a private 12 MB budget while the shared kernel
+ * bounds a request at {@link MAX_REQUEST_IMAGE_BYTES} (1.5 MB), and the adapter
+ * answered no `imageRequestTarget` at all — so the harness downscaled for a
+ * ceiling this mapper never applied, and the body could still exceed the one
+ * the kernel had already paid for. Re-exporting the kernel here keeps the
+ * projection, the budget and the target a single number.
+ *
+ * What stays route-specific is only what the WIRE shape needs ({@link
+ * MAX_REQUEST_IMAGE_BYTES} is imported for the doc link and the tests that pin
+ * it): the chat and Messages builders both consume the same resolution.
+ */
+export { MAX_REQUEST_IMAGE_BYTES, NO_RESOLVED_IMAGES, SUPPORTED_IMAGE_MEDIA_TYPES, attachmentLabel, imageBlockToInline, offloadOldestRequestImages, requestImageTargetOrOriginal, resolveRequestImages, unavailableImageText, stripMetaSchema, };
+export type { AttachmentImageReader, ResolvedRequestImage, ResolvedRequestImages };
+/**
+ * Build one `/v2/chat/completions` body.
+ *
+ * Always `stream: true`: the endpoint rejects a non-streaming request outright
+ * (400 `code 11101`), so there is no second shape to produce.
+ */
+export declare function buildChatRequest(options: GenerateOptions, images?: ResolvedRequestImages): Record<string, unknown>;
+interface PendingToolCall {
+    blockIndex: number;
+    id: string;
+    name: string;
+    arguments: string;
+    started: boolean;
+}
+export interface WorkBuddyStreamState {
+    blocks: OutboundContentBlock[];
+    current: {
+        index: number;
+        type: 'text' | 'reasoning';
+        text: string;
+    } | null;
+    /** wire tool index -> accumulating call. */
+    toolCalls: Map<number, PendingToolCall>;
+    hasContent: boolean;
+    hasToolCall: boolean;
+    finishReason: string | null;
+    /** The `[DONE]` sentinel arrived. */
+    done: boolean;
+    /** Terminal chunks were already emitted. */
+    finished: boolean;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    sawUsage: boolean;
+    /**
+     * Text held back while it may still turn into a printed tool call.
+     *
+     * `holding` is set once a `<` that could open a call region was seen; the
+     * buffer then grows until the region closes (or the cap is hit), and is
+     * resolved into prose or calls exactly once.
+     */
+    printed: {
+        pending: string;
+        holding: boolean;
+    };
+}
+export declare function createStreamState(): WorkBuddyStreamState;
+/** Feed one SSE line from `/v2/chat/completions`. */
+export declare function processStreamLine(line: string, state: WorkBuddyStreamState): StreamChunk[];
+/** Flush every open block, then emit usage and the terminal finish. */
+export declare function closeStream(state: WorkBuddyStreamState): StreamChunk[];
+/**
+ * A stream that ends without a terminal event is truncated, not complete.
+ *
+ * The endpoint always terminates with either `finish_reason` or `[DONE]`, so
+ * their absence means the connection dropped mid-answer and the partial text
+ * must not be presented as a finished reply.
+ */
+export declare function assertStreamComplete(state: WorkBuddyStreamState): void;
+/** Whether one 11128 body is the channel refusal a system move can repair. */
+export declare function isChannelRefusal11128(detail: string): boolean;
+/**
+ * What a chat's system prompt is known by.
+ *
+ * The key is the system TEXT, not the conversation: one agent refused once must
+ * not pay the refusal again on its next conversation, which is a different
+ * message list with the same opening. A body whose system text is already the
+ * neutral default has nothing to move, so it keys as the empty string.
+ */
+export declare function chatSystemKey(body: unknown): string;
+/**
+ * Move a chat's system prompt into the first user turn, in INSTRUCTIONS tags,
+ * and leave the neutral default in the leading system position.
+ *
+ * A system message LATER in the history becomes a user message where it stands:
+ * the gateway refuses those too, and the position is meaningful to the model, so
+ * it is rewritten rather than lifted out and merged. String content is prefixed
+ * with the tagged text and a blank line; block content gets one extra leading
+ * text part, which is what keeps images and tool parts exactly where they were.
+ *
+ * Returns the new body as JSON, or NULL when there is nothing to move — a caller
+ * that gets null must not retry, because the second request would be the first
+ * one again.
+ */
+export declare function relocateSystemToInstructions(body: unknown): string | null;
+/**
+ * The id one USER SEND is known by, for the request-id header family.
+ *
+ * Derived from the harness history rather than from a clock or a counter: every
+ * tool step of one send appends to the history AFTER the user's own last
+ * message, so the same key is computed for all of them, and the user's next
+ * message is what changes it. Tool-result turns are skipped because they are the
+ * harness answering the model, not the user speaking — including them would give
+ * each tool step its own id, which is the behaviour this exists to prevent.
+ *
+ * Empty when there is no user turn to name, which the caller reads as "make a
+ * fresh id for this request" (config probes, compactions, and one-shot calls).
+ */
+export declare function userTurnKey(options: GenerateOptions): string;
+/**
+ * `anthropic-version` the Messages surface requires.
+ *
+ * Sent for every Messages request: without it the endpoint answers 400 rather
+ * than falling back to a default, so it is a protocol requirement and not a
+ * feature negotiation.
+ */
+export declare const ANTHROPIC_VERSION = "2023-06-01";
+/**
+ * Thinking control the Messages surface takes.
+ *
+ * Not the chat endpoint's `reasoning_effort`: Messages asks for thinking
+ * (`thinking.type: 'adaptive'`) and expresses the LEVEL in
+ * `output_config.effort`. Sending the chat spelling here is what made an
+ * effort pick do nothing, and 'max' is a legal level of this ladder, so it is
+ * carried verbatim rather than filtered through the chat ladder.
+ */
+export declare const MESSAGES_THINKING_FIELD = "thinking";
+export declare const MESSAGES_EFFORT_FIELD = "output_config";
+export interface MessagesRequestOptions {
+    /** Durable user images resolved for this request. */
+    images?: ResolvedRequestImages;
+    /** Effort ladder the gateway catalog declares for this model; empty = no thinking. */
+    efforts?: readonly string[];
+    /** Effort the caller picked, carried verbatim (no chat-ladder filtering). */
+    effort?: string;
+    /** Output cap to use when the caller names none. */
+    defaultMaxTokens?: number;
+}
+/**
+ * Build one `/v1/messages` body.
+ *
+ * `stream: true` is mandatory: the adapter reads every response as SSE, and a
+ * non-streaming answer is one JSON document with no `data:` lines, no
+ * `message_stop` and no `stop_reason`.
+ *
+ * The system prompt travels as the top-level `system` string — the surface has
+ * a field for it, so the chat endpoint's "the first message must be a system
+ * turn" requirement does not exist here and no relocation is ever needed.
+ */
+export declare function buildMessagesRequest(options: GenerateOptions, request?: MessagesRequestOptions): Record<string, unknown>;
+interface MessagesTextBlock {
+    index: number;
+    kind: 'text' | 'reasoning';
+    text: string;
+}
+interface MessagesToolCall {
+    index: number;
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface MessagesStreamState {
+    blocks: OutboundContentBlock[];
+    /** wire content index -> open text or reasoning block. */
+    open: Map<number, MessagesTextBlock>;
+    /** wire content index -> accumulating tool call. */
+    toolCalls: Map<number, MessagesToolCall>;
+    hasContent: boolean;
+    hasToolCall: boolean;
+    finishReason: string | null;
+    sawMessageStart: boolean;
+    sawMessageStop: boolean;
+    sawUsage: boolean;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    finished: boolean;
+}
+export declare function createMessagesStreamState(): MessagesStreamState;
+/** Flush every open block, then emit usage and the terminal finish. */
+export declare function closeMessagesStream(state: MessagesStreamState): StreamChunk[];
+/** A stream that ends without `message_stop` is truncated, not complete. */
+export declare function assertMessagesStreamComplete(state: MessagesStreamState): void;
+/**
+ * Feed one SSE line from `/v1/messages`.
+ *
+ * Both fragments of one event arrive as two lines (`event:` then `data:`), so
+ * the parser keys on `data:` alone and ignores the event name: the JSON payload
+ * carries its own `type`, which is the same discriminator and cannot disagree
+ * with the label above it.
+ */
+export declare function processMessagesStreamLine(line: string, state: MessagesStreamState): StreamChunk[];
+export { IMPLICIT_SYSTEM_PROMPT };
+//# sourceMappingURL=mapper.d.ts.map

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

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

package/lib/types/host/workbuddy/model-catalog.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Model catalog for the WorkBuddy / CodeBuddy subscription.
+ *
+ * The subscription exposes no `/v1/models`-style listing on the chat host
+ * (that path answers 404), but the gateway does publish an **authoritative
+ * catalog** at `GET /v3/config`, which the official CLI reads at startup. That
+ * payload carries each model's real context window, output cap, image support,
+ * and the exact reasoning ladder it accepts — so this route prefers the live
+ * catalog and keeps the table below only as an offline fallback.
+ *
+ * The fallback is a verbatim transcription of a live `/v3/config` read, not
+ * hand-written guesses: an earlier revision of this file guessed context
+ * windows from vendor marketing and was wrong in both directions (`glm-5.3`
+ * and `kimi-k3` are 1M, not 200K/256K).
+ *
+ * One entry serves both regions, so a model the regions disagree about needs a
+ * merged figure. The rule is asymmetric on purpose: the **larger maximum** is
+ * kept, while the **served default** and the **output cap** take the **smaller**
+ * of the two. Over-declaring either one is a hard failure — DSH would send a
+ * request the gateway rejects — whereas under-declaring only compresses a
+ * conversation earlier than needed, and both remain overridable per model from
+ * the settings card. Measured disagreements (`glm-5.3-flash`, `glm-5.3`,
+ * `glm-5.2`, `kimi-k2.8-preview` served 300000/48000/48000/32000 by intl
+ * against 1000000/64000/64000/64000 by cn) are reconciled that way.
+ *
+ * The regions also do not serve the same ids. intl added `glm-5.3-flash` and
+ * keeps `gemini-3.5-flash`, `kimi-k3` and the `*-model` aliases to itself; cn
+ * keeps `glm-5.3-flash`, `kimi-k3-1` and its own `-x` variants.
+ *
+ * `regions` is a routing fact, not a preference: asking a region for a model it
+ * does not serve answers 400 `code 11102`.
+ *
+ * A second `code 11102` source was measured and is deliberately NOT filtered
+ * out here: the gateway lists models the *current account* is not entitled to
+ * call (on a free plan, `glm-5.0`, `glm-4.7`, `glm-4.6`, `glm-4.6v`,
+ * `kimi-k2-thinking`, `hy4-preview-x` and `minimax-m2.5` all advertise a context
+ * window and then answer 11102). Those entries are kept because the gating is
+ * per-account, not per-model — a paid plan may serve them — and because the
+ * shipped default selection excludes them anyway. The adapter's failure message
+ * names this case so a user knows to pick another model rather than to retry.
+ *
+ * `credits` is the consumption multiplier the same payload publishes as a
+ * string (`x0.79 credits` on cn, `x6.67` on intl), stored here in the bare
+ * numeric form the settings card renders. It is kept per region because the two
+ * backends do not always agree — measured 2026-10-09, `deepseek-v4.1-flash`
+ * is `0.11` on cn against `0.00` on intl — and a key is written only for a
+ * region that actually published one (every `gpt-5.x` and `gpt-6-astra` is
+ * intl-only, the `minimax` and `glm-5.0`/`glm-4.x` rows carry no intl key).
+ * An empty string (`default-model`) means no rate was declared at all, so that
+ * row has no `credits` field rather than a zeroed one: a guessed rate on a
+ * spend figure is worse than a missing one.
+ *
+ * `reasoningEfforts` carries the ladder a model accepts, transcribed from the
+ * gateway's own declaration. `/v3/config` uses two shapes and they were once
+ * conflated, in opposite directions: a lone `{ effort: 'high' }` (no
+ * `supportedEfforts`) first became a one-entry ladder, which rejected a
+ * caller's explicit `low`; widening it to every level this route can name then
+ * advertised `minimal`/`xhigh` on a model that has three. Such a model accepts
+ * exactly `low`/`high`/`max` (measured on `deepseek-v4.1-flash`), the same
+ * three the gateway declares explicitly for `glm-5.3-flash` and
+ * `kimi-k2.8-preview`, and routes any other value into the nearest of them.
+ */
+import type { WorkBuddyModelCredits, WorkBuddyRegion } from '../../shared/workbuddy-contracts.ts';
+export interface WorkBuddyModelEntry {
+    id: string;
+    name: string;
+    /**
+     * Context length the gateway serves **by default** for this model.
+     *
+     * This route sends no explicit context-length parameter, so this is the
+     * figure DSH's compaction and overflow decisions must use. It is not always
+     * the model's maximum: the gateway reports both (for example
+     * `deepseek-v4.1-flash` serves 300000 by default and allows 1000000).
+     */
+    contextWindow: number;
+    /** Largest context length the model accepts when one is requested. */
+    maxContextWindow: number;
+    /** Output cap requested when the caller omits one. */
+    maxTokens: number;
+    /** Regions whose backend serves this id. */
+    regions: readonly WorkBuddyRegion[];
+    /**
+     * Consumption multiplier per region, as `/v3/config` publishes it.
+     *
+     * Optional on purpose: the multiplier is the one field the gateway may omit
+     * for a model it otherwise describes (`default-model` ships an empty string),
+     * so every catalog literal in this repo — test fixtures and the live parser
+     * alike — must stay valid without it. Absent therefore means "nothing usable
+     * was published", never "zero": `x0.00` is a real declaration and is kept.
+     */
+    credits?: WorkBuddyModelCredits;
+    /** Whether the model accepts image input. */
+    supportsImage: boolean;
+    /** Reasoning ladder the model accepts; empty for a non-reasoning model. */
+    reasoningEfforts: readonly string[];
+    /** Level this route selects when the caller names none. */
+    defaultReasoningEffort: string | null;
+    /** Whether the model can be asked to skip thinking entirely. */
+    canDisableThinking: boolean;
+    /** One-line note shown beside the model in the settings card. */
+    description: string;
+}
+/**
+ * Models the gateway serves but does not publish in `/v3/config`.
+ *
+ * The catalog is a published list, not the served one: measured on the
+ * international backend, `gpt-6-sol`, `gpt-6-luna` and `gemini-3.8-flash` all
+ * answer a normal streaming completion with 200 while being absent from
+ * `/v3/config` entirely, and a reachable gateway *replaces* the shipped table
+ * with that list. Without these rows the picker would simply never show them, so
+ * they are declared here and merged into a live catalog too
+ * ({@link withUnpublishedModels}) rather than living in the fallback alone.
+ *
+ * What each row records, and how it was established, differs by field:
+ *
+ * - **Existence, the reasoning ladder, image support** were measured against the
+ *   live endpoint, not inferred from the name. A rejected level answers 400
+ *   `code 11133` with `extError` `400002`; `gpt-6-sol` takes exactly the ladder
+ *   `gpt-6-astra` publishes (`minimal` refused, `low`/`medium`/`high`/`xhigh`/
+ *   `max` accepted) and both accept a 1x1 PNG.
+ * - **Context window, output cap and `canDisableThinking` are inherited from the
+ *   published sibling in the same family** — `gpt-6-astra` for `gpt-6-sol` and
+ *   `gpt-6-luna`, `gemini-3.5-flash` for `gemini-3.8-flash`. They are marked
+ *   here rather than measured because the gateway publishes nothing for these
+ *   ids and offers no cheap way to read the real figure: it accepts a
+ *   `max_tokens` larger than any published window (even for `gpt-6-astra`, whose
+ *   own catalog caps at 128000), so the number is neither enforced nor
+ *   discoverable from the request side.
+ *
+ * Every field stays overridable per model from the settings card, and an
+ * inherited window errs low rather than high: over-declaring overflows the
+ * gateway mid-session, while under-declaring only compresses earlier.
+ */
+export declare const UNPUBLISHED_MODELS: readonly WorkBuddyModelEntry[];
+/**
+ * Offline fallback catalog, transcribed from a live `/v3/config` read.
+ *
+ * Used when the gateway cannot be reached (first run before sign-in, or a
+ * network failure); a reachable gateway always wins.
+ */
+export declare const FALLBACK_MODELS: readonly WorkBuddyModelEntry[];
+/**
+ * Models the picker offers on a fresh install.
+ *
+ * Deliberately short: the catalog holds every id the subscription serves, and
+ * the picker is far more usable with the handful of general-purpose models. The
+ * card lets a user add the rest, and a first-run default expands to everything
+ * the account's region can actually call.
+ */
+export declare const DEFAULT_VISIBLE_MODEL_IDS: readonly string[];
+/** Every id the fallback knows, in declaration order. */
+export declare const WORKBUDDY_MODEL_IDS: readonly string[];
+/**
+ * Add the served-but-unpublished models to a live `/v3/config` catalog.
+ *
+ * A reachable gateway replaces the shipped table with the list it publishes, so
+ * a model it serves without listing ({@link UNPUBLISHED_MODELS}) would drop out
+ * of the picker the moment the catalog loads. Merging here keeps it offered.
+ *
+ * A published entry always wins: the gateway is the authority on anything it
+ * does describe, so these rows only fill ids the payload is silent about.
+ */
+export declare function withUnpublishedModels(catalog: readonly WorkBuddyModelEntry[], region: WorkBuddyRegion): WorkBuddyModelEntry[];
+/**
+ * Resolve one entry from a catalog.
+ *
+ * An unknown id resolves to a synthetic text-only entry rather than the first
+ * catalog row: reporting a real model's capabilities for an id it does not
+ * describe would mis-declare image support and route a request to a 400.
+ */
+export declare function resolveWorkBuddyModel(id: string, catalog?: readonly WorkBuddyModelEntry[]): WorkBuddyModelEntry;
+/** Whether one catalog knows this exact id. */
+export declare function isWorkBuddyModelId(id: unknown, catalog?: readonly WorkBuddyModelEntry[]): id is string;
+/** The vendor family one model belongs to. */
+export declare function workBuddyModelVendor(id: string): string;
+/**
+ * Group a list so every vendor's models sit together.
+ *
+ * Families appear in the order their first model does — the catalog decides
+ * which vendor leads, not this function — and each family is ordered newest
+ * generation first.
+ */
+export declare function groupWorkBuddyModelsByVendor<T extends {
+    id: string;
+}>(models: readonly T[]): T[];
+/**
+ * Models an account in `region` can actually call, grouped by vendor.
+ *
+ * Grouped here rather than in the settings card because this is also what the
+ * request path resolves against: one ordering rule, so the picker and the
+ * adapter can never disagree about which models a region offers.
+ */
+export declare function modelsForRegion(region: WorkBuddyRegion, catalog?: readonly WorkBuddyModelEntry[]): WorkBuddyModelEntry[];
+/** Whether one model accepts image input. */
+export declare function workBuddyModelSupportsImage(id: string, catalog?: readonly WorkBuddyModelEntry[]): boolean;
+/**
+ * Reasoning ladder one model accepts, plus `none` when its trace can be turned off.
+ *
+ * The ladder in the catalog is what the model ACCEPTS, so `none` never appears
+ * in it; `canDisableThinking` is the separate statement that switching thinking
+ * off is allowed, and this is the single place that turns it into the one level
+ * the picker can offer. Callers that need the ladder alone read the entry.
+ */
+export declare function workBuddyReasoningEfforts(id: string, catalog?: readonly WorkBuddyModelEntry[]): readonly string[];
+/**
+ * Consumption multiplier per region one model publishes.
+ *
+ * Read through {@link resolveWorkBuddyModel} like the other accessors, so an id
+ * no catalog describes reports `{}` — "no rate published" rather than a rate
+ * of zero.
+ */
+export declare function workBuddyModelCredits(id: string, catalog?: readonly WorkBuddyModelEntry[]): WorkBuddyModelCredits;
+/** Output cap requested when the caller omits one. */
+export declare function maxOutputTokensFor(id: string, catalog?: readonly WorkBuddyModelEntry[]): number;
+/** Context window assumed when no override is saved. */
+export declare function defaultContextWindowFor(id: string, catalog?: readonly WorkBuddyModelEntry[]): number;
+//# sourceMappingURL=model-catalog.d.ts.map

package/lib/types/host/workbuddy/model-catalog.d.ts.map

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

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

@@ -0,0 +1,47 @@
+import { FileCredentialStore, type WorkBuddyCredentials } from './token-store.ts';
+import { type WorkBuddyTokenIdentity } from './identity.ts';
+import type { WorkBuddyRegion } from '../../shared/workbuddy-contracts.ts';
+export type WorkBuddyLoginStatus = 'idle' | 'pending' | 'complete' | 'error';
+export interface WorkBuddyLoginFlowState {
+    status: WorkBuddyLoginStatus;
+    region?: WorkBuddyRegion;
+    authUrl?: string;
+    progress?: string;
+    accountId?: string;
+    startedAt?: number;
+    completedAt?: number;
+    error?: string;
+}
+export declare function getWebLoginStatus(): WorkBuddyLoginFlowState;
+export declare function resetWebLogin(): void;
+export interface WorkBuddyLoginAttempt {
+    state: string;
+    authUrl: string;
+    region: WorkBuddyRegion;
+    domain: string;
+}
+export declare function requestLoginState(region: WorkBuddyRegion, fetchFn?: typeof fetch, signal?: AbortSignal): Promise<WorkBuddyLoginAttempt>;
+/** Parse the successful token-poll shape while accepting the two observed wrappers. */
+export declare function parseLoginCredential(payload: unknown, attempt: WorkBuddyLoginAttempt): WorkBuddyCredentials | null;
+export declare function pollLogin(attempt: WorkBuddyLoginAttempt, fetchFn?: typeof fetch, signal?: AbortSignal): Promise<WorkBuddyCredentials | null>;
+/** Where a completed sign-in is written; the default is this line's own store. */
+export interface WorkBuddyLoginOptions {
+    /**
+     * Persist the completed credential.
+     *
+     * The account pool owns routing, so it is what a completed sign-in must reach;
+     * the default writes to the credential store alone, which is what a caller
+     * running without a pool needs.
+     */
+    onSave?: (credentials: WorkBuddyCredentials) => Promise<unknown>;
+    /**
+     * Resolve the signed-in account's identity before it is saved.
+     *
+     * The token response does not say which account it belongs to, so the default
+     * reads it from the account endpoint; a test can replace this, and a caller
+     * that already knows the identity can skip the extra request.
+     */
+    resolveIdentity?: (credentials: WorkBuddyCredentials) => Promise<WorkBuddyTokenIdentity | null>;
+}
+export declare function beginWebLogin(store: FileCredentialStore, region: WorkBuddyRegion, fetchFn?: typeof fetch, options?: WorkBuddyLoginOptions): Promise<WorkBuddyLoginFlowState>;
+//# sourceMappingURL=oauth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../../../src/host/workbuddy/oauth.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,mBAAmB,EAAsB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACrG,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAEjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAE1E,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAA;AAE5E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,oBAAoB,CAAA;IAC5B,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAKD,wBAAgB,iBAAiB,IAAI,uBAAuB,CAE3D;AAED,wBAAgB,aAAa,IAAI,IAAI,CAIpC;AA0CD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,eAAe,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,OAAO,KAAa,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,qBAAqB,CAAC,CAwBhC;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,IAAI,CAoClH;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE,OAAO,KAAa,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CActC;AAED,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAChE;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAA;CAChG;AA8BD,wBAAsB,aAAa,CACjC,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,OAAO,KAAa,EAC7B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,uBAAuB,CAAC,CAuClC"}

package/lib/types/host/workbuddy/outbound-identity.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Outbound client identities this route can present.
+ *
+ * The subscription gateway gates on client identity, and it gates DIFFERENTLY
+ * per surface: measured on this route, `CodeBuddyIDE` is rejected by
+ * `/v3/config` with 400 `code 12403` ("check ua") and 401'd outright by the
+ * international chat endpoint, which is why the CLI identity is what the line
+ * ships and has always used.
+ *
+ * Two more identities exist on the same backend. Both were captured by sibling
+ * gateways that reverse-engineered the real clients' requests; this file's
+ * version block below names the exact source of every string it sends.
+ *
+ *   desktop   `WorkBuddy/<app> <appName>/<app> CLI/<cli>`, where `<app>` is
+ *             the desktop build, `<appName>` is `WorkBuddy` (domestic) or
+ *             `workbuddy-ai` (international) and `<cli>` is the CLI bundled
+ *             inside that build
+ *             + `X-IDE-Type/Name: WorkBuddy`, `X-IDE-Version`, `X-Agent-Intent: craft`
+ *             + `X-Agent-Purpose: conversation`, `X-Agent-Type: main`,
+ *             + `X-Agent-Runtime: local-agent` (the 5.9 client names where the
+ *               agent runs; the header is absent in 5.8), trace headers
+ *   vscode    `VSCode/<ide> WorkBuddy/<product>`
+ *             + `X-IDE-Type/Name: VSCode`, `X-IDE-Version`, `X-Product-Version`, `X-Env-ID`
+ *   cli       `CLI/2.63.2 CodeBuddy/2.63.2` + no overrides
+ *
+ * The `cli` literal is kept byte-identical to what this line has always sent,
+ * but it is NO LONGER the default: upstream now refuses any agent that is not a
+ * `WorkBuddy/<version>` one with error 10085, which is exactly what a bare
+ * `CLI/...` agent is. `DEFAULT_OUTBOUND_SETTING` therefore names `workbuddy`,
+ * and {@link migrateOutboundSettingDocument} moves a stored pre-marker document
+ * across without overriding a choice the user has since made.
+ *
+ * Quota is NOT per identity: the subscription meters an account × model over a
+ * 24h window (429 `code 6004`), so switching identity cannot create allowance.
+ * What it can do is give each account a stable, plausible client — the same
+ * reason the gateway projects one device per account.
+ */
+import type { WorkBuddyOutboundProduct, WorkBuddyOutboundSetting } from '../../shared/workbuddy-contracts.ts';
+export type { WorkBuddyOutboundProduct, WorkBuddyOutboundSetting };
+/** Everything the settings card may offer, in display order. */
+export declare const OUTBOUND_PRODUCTS: readonly WorkBuddyOutboundProduct[];
+/**
+ * Shipped default: the desktop identity.
+ *
+ * It used to be `cli`, because that literal is what this line measured working
+ * first. That is no longer true — upstream refuses any agent that is not a
+ * `WorkBuddy/<version>` one with error 10085, and a bare `CLI/...` agent is
+ * exactly such a request (see the version block below, which cites the source
+ * of both facts). The desktop identity is the shipped one because it is the
+ * identity that presents a `WorkBuddy/<version>` agent.
+ *
+ * A document written while `cli` was the default is moved across ONCE by
+ * {@link migrateOutboundSettingDocument}; a choice made after that is never
+ * revisited.
+ */
+export declare const DEFAULT_OUTBOUND_SETTING: WorkBuddyOutboundProduct;
+/** Narrow a stored or patched value into a supported preference. */
+export declare function normalizeOutboundSetting(value: unknown): WorkBuddyOutboundSetting;
+/**
+ * Which identity one account uses.
+ *
+ * `auto` assigns by hashing the account key, so an account keeps the same
+ * client for its whole life — the one property that matters for a device
+ * fingerprint — while a pool as a whole spreads over the available clients.
+ */
+export declare function resolveOutboundProduct(setting: WorkBuddyOutboundSetting, accountKey: string): WorkBuddyOutboundProduct;
+/**
+ * A stable pseudo-device id for one account.
+ *
+ * Same derivation as the measured clients (`derive_id`: md5 of `salt:uid`
+ * reshaped into a UUID), so the value is a well-formed v4-shaped machine id
+ * that never changes for an account and never collides between accounts. A
+ * per-PROCESS id would be worse than none here: it would present every account
+ * in the pool as the same machine.
+ */
+export declare function deriveMachineId(uid: string): string;
+/** Identity-specific headers and user agent for one request. */
+export interface OutboundIdentity {
+    product: WorkBuddyOutboundProduct;
+    userAgent: string;
+    /** Extra or overriding headers; `conversation` supplies the ids already minted. */
+    headers(conversation: Readonly<Record<string, string>>): Record<string, string>;
+}
+/** Resolve the identity block for one product on one region. */
+export declare function outboundIdentity(product: WorkBuddyOutboundProduct, region: 'cn' | 'intl', uid: string): OutboundIdentity;
+/**
+ * Version of the outbound-identity semantics one settings document carries.
+ *
+ * 1 (never written as a number) = the era whose shipped default was `cli`. That
+ *   era wrote `cli` into a document as soon as it normalised an unset
+ *   preference, so a stored `cli` from it cannot be told apart from "untouched".
+ * 2 = the desktop default.
+ *
+ * A document with no marker is version 1 — that direction is load-bearing. A
+ * register-backed scope whose schema defaulted the marker to the CURRENT version
+ * would declare every stale document already migrated, which is the same
+ * upgrade-breaks-everyone bug reached through the other storage path.
+ */
+export declare const OUTBOUND_IDENTITY_VERSION = 2;
+/** What an absent marker means. Deliberately not the current version. */
+export declare const LEGACY_OUTBOUND_IDENTITY_VERSION = 1;
+/** One stored preference, as {@link migrateOutboundSettingDocument} reads it. */
+export interface OutboundSettingDocument {
+    /** The stored preference, in whatever shape the document holds it. */
+    outboundIdentity?: unknown;
+    /** The marker; absent on a pre-marker document. */
+    outboundIdentityVersion?: unknown;
+}
+/** What a caller must use, and whether it must write the document back. */
+export interface MigratedOutboundSetting {
+    /** The identity this host is to present. */
+    outboundIdentity: WorkBuddyOutboundSetting;
+    /** Marker the document carries after this read. */
+    outboundIdentityVersion: number;
+    /** Whether the caller must persist the document (marker and/or new value). */
+    migrated: boolean;
+}
+/**
+ * Read one stored outbound preference, migrating the pre-marker default once.
+ *
+ * The rule, and the reason for each half:
+ *
+ * - `marker >= 2`: this document has been through the migration. Whatever it
+ *   holds is a choice now — `cli` included, which a deployment may pin on
+ *   purpose — so the value is returned untouched and nothing is written.
+ * - no marker and a stored `cli`: the era's default, indistinguishable from a
+ *   deliberate one, and a value upstream now refuses (10085). It becomes
+ *   {@link DEFAULT_OUTBOUND_SETTING} and the marker is stamped. The stamp is
+ *   what makes this idempotent AND what stops a genuine `cli` pinned AFTER the
+ *   migration from being flipped on the next read.
+ * - no marker and any other value (`auto`/`workbuddy`/`vscode`): a real user
+ *   setting, kept as-is; only the marker is stamped, so a later upgrade never
+ *   re-decides it.
+ *
+ * An unparseable stored value normalises to the shipped default, exactly as an
+ * absent one does, and is stamped: garbage is not a preference.
+ */
+export declare function migrateOutboundSettingDocument(document: OutboundSettingDocument): MigratedOutboundSetting;
+//# sourceMappingURL=outbound-identity.d.ts.map