@cleocode/contracts 2026.6.12 → 2026.6.14

package/dist/llm/oauth.d.ts

@@ -134,9 +134,23 @@ export interface ProviderOAuthConfig {
      * `code_challenge`/`code_challenge_method`/`state`).
      *
      * Used by OpenAI/Codex (`id_token_add_organizations=true`,
-     * `codex_cli_simplified_flow=true`, `originator=codex_cli_rs`). Anthropic and
-     * Kimi Code leave this unset.
+     * `codex_cli_simplified_flow=true`, `originator=codex_cli_rs`) and Anthropic
+     * (`code=true` — makes the hosted callback page display the authorization
+     * code for manual paste-back). Kimi Code leaves this unset.
      */
     extraAuthParams?: Readonly<Record<string, string>>;
+    /**
+     * Encoding of the token-endpoint request body (code exchange + refresh).
+     *
+     * - `'form'` (default) — RFC 6749 §4.1.3 `application/x-www-form-urlencoded`.
+     *   Used by OpenAI/Codex and every spec-compliant authorization server.
+     * - `'json'` — non-standard `application/json` body. Anthropic's token
+     *   endpoint (`platform.claude.com/v1/oauth/token`) expects JSON and
+     *   additionally requires the authorize-time `state` echoed in the exchange
+     *   body (the same wire shape pi-ai, OpenCode, and Claude Code use).
+     *
+     * @default 'form'
+     */
+    tokenBodyFormat?: 'form' | 'json';
 }
 //# sourceMappingURL=oauth.d.ts.map

package/dist/llm/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/llm/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,aAAa,CAAC;AAM/C;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/llm/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,aAAa,CAAC;AAM/C;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC"}

package/dist/llm/onboarding.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Onboarding login engine — typed result envelope (T11724 · M3).
+ *
+ * The 3-step onboarding login flow (`runOnboardingLogin` in `@cleocode/core`)
+ * walks a provider from a cold start to a usable, validated profile binding:
+ *
+ *   1. **connect** — resolve the provider (alias → canonical) and land a
+ *      credential (Account) in the multi-credential pool (OAuth token or API
+ *      key). NO browser interaction in the engine itself: the owner-driven
+ *      OAuth code/token is passed in, so the flow is non-interactive and
+ *      testable.
+ *   2. **select** — pick a model from the catalog (latest by `release_date`,
+ *      or an explicit override validated against the catalog).
+ *   3. **bind**    — write the `llm.default` / `llm.roles[role]` config binding
+ *      that ties the account + model together.
+ *   4. **validate** — round-trip the binding through `resolveLLMForSystem` and
+ *      confirm the resolved provider/model are consistent. NOT a live LLM call:
+ *      no token is materialized, only the resolution metadata is asserted.
+ *
+ * ## Security — NO secret fields (AC2)
+ *
+ * This module is **types-only** (Gate 10 contracts-purity). The result
+ * envelope carries ONLY non-secret identifiers — provider name, account label,
+ * model id, profile/role name, and per-step status. It NEVER carries an access
+ * token, API key, refresh token, or any token-derived value beyond a redacted
+ * preview. The plaintext secret is materialized only at the wire via the
+ * {@link SealedCredential} handle — never on this envelope.
+ *
+ * @module llm/onboarding
+ * @task T11724
+ * @epic T11671 (E6-ONBOARDING-FRONT-DOOR)
+ */
+import type { ProviderId } from './provider-id.js';
+/**
+ * Discriminant naming each step of the onboarding login flow, in execution
+ * order. Surfaced on every {@link OnboardingStepResult} so a UI / CLI can
+ * render a deterministic 4-row progress checklist.
+ *
+ * @task T11724
+ */
+export type OnboardingStepName = 'connect' | 'select' | 'bind' | 'validate';
+/**
+ * Outcome of a single onboarding step.
+ *
+ * - `'ok'`      — the step completed successfully.
+ * - `'failed'`  — the step could not complete (e.g. missing credential,
+ *   unknown model, config write error). The engine STOPS at the first
+ *   `'failed'` step and returns the partial envelope; it does NOT throw.
+ * - `'skipped'` — the step was intentionally not run because an earlier step
+ *   failed (downstream steps are short-circuited but still reported so the
+ *   4-row shape is stable).
+ *
+ * @task T11724
+ */
+export type OnboardingStepStatus = 'ok' | 'failed' | 'skipped';
+/**
+ * Result of one step in the onboarding login flow.
+ *
+ * `detail` is a short, human-readable, SECRET-FREE summary of what the step
+ * did (e.g. `"account 'work' connected (oauth)"`, `"model 'claude-…' selected
+ * from catalog"`). `code` carries a stable `E_*` error code on failure so a
+ * caller can branch programmatically without string-matching `detail`.
+ *
+ * @task T11724
+ */
+export interface OnboardingStepResult {
+    /** Which step this result describes. */
+    readonly step: OnboardingStepName;
+    /** Terminal status of the step. */
+    readonly status: OnboardingStepStatus;
+    /** Human-readable, secret-free summary of the step outcome. */
+    readonly detail: string;
+    /**
+     * Stable `E_*` error code when `status === 'failed'`; omitted otherwise.
+     * Never carries a token or other secret.
+     */
+    readonly code?: string;
+}
+/**
+ * The auth scheme by which the connect step landed a credential in the pool.
+ *
+ * - `'oauth'`   — an OAuth access token (PKCE / device-code) was supplied.
+ * - `'api_key'` — a raw API key was supplied (OAuth-less providers fall
+ *   through to this path — AC4).
+ *
+ * @task T11724
+ */
+export type OnboardingAuthMode = 'oauth' | 'api_key';
+/**
+ * Typed result envelope returned by `runOnboardingLogin` (AC2).
+ *
+ * Carries NO secret fields — only the per-step trace and the non-secret
+ * identifiers needed to render the result and confirm the binding. `validated`
+ * is the single boolean a caller checks to know the end-to-end flow succeeded
+ * (all four steps `'ok'` AND the round-trip resolution was consistent).
+ *
+ * @task T11724
+ */
+export interface OnboardingResult {
+    /** The 4 step traces, always length 4, in execution order. */
+    readonly steps: ReadonlyArray<OnboardingStepResult>;
+    /** Canonical provider id the flow resolved to (alias → canonical). */
+    readonly provider: ProviderId;
+    /**
+     * Human-readable account/credential label the connect step stored in the
+     * pool (e.g. `'oauth-login'`, `'work'`). Names *which* credential the
+     * binding points at — safe to log/serialize; NOT a secret.
+     */
+    readonly accountLabel: string;
+    /** The auth scheme used by the connect step, or `null` when connect failed. */
+    readonly authMode: OnboardingAuthMode | null;
+    /** Catalog model id the select step chose, or `null` when select failed. */
+    readonly modelId: string | null;
+    /**
+     * The profile/role name the bind step wrote (e.g. `'default'` for the global
+     * binding or a {@link import('../config.js').RoleName} for a per-role
+     * binding), or `null` when bind failed.
+     */
+    readonly profileName: string | null;
+    /**
+     * `true` only when all four steps succeeded AND the validate round-trip
+     * confirmed the binding resolves to the connected provider + selected model.
+     */
+    readonly validated: boolean;
+}
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/llm/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/llm/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACpD,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC7C,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B"}

package/dist/llm/onboarding.js

@@ -0,0 +1,34 @@
+/**
+ * Onboarding login engine — typed result envelope (T11724 · M3).
+ *
+ * The 3-step onboarding login flow (`runOnboardingLogin` in `@cleocode/core`)
+ * walks a provider from a cold start to a usable, validated profile binding:
+ *
+ *   1. **connect** — resolve the provider (alias → canonical) and land a
+ *      credential (Account) in the multi-credential pool (OAuth token or API
+ *      key). NO browser interaction in the engine itself: the owner-driven
+ *      OAuth code/token is passed in, so the flow is non-interactive and
+ *      testable.
+ *   2. **select** — pick a model from the catalog (latest by `release_date`,
+ *      or an explicit override validated against the catalog).
+ *   3. **bind**    — write the `llm.default` / `llm.roles[role]` config binding
+ *      that ties the account + model together.
+ *   4. **validate** — round-trip the binding through `resolveLLMForSystem` and
+ *      confirm the resolved provider/model are consistent. NOT a live LLM call:
+ *      no token is materialized, only the resolution metadata is asserted.
+ *
+ * ## Security — NO secret fields (AC2)
+ *
+ * This module is **types-only** (Gate 10 contracts-purity). The result
+ * envelope carries ONLY non-secret identifiers — provider name, account label,
+ * model id, profile/role name, and per-step status. It NEVER carries an access
+ * token, API key, refresh token, or any token-derived value beyond a redacted
+ * preview. The plaintext secret is materialized only at the wire via the
+ * {@link SealedCredential} handle — never on this envelope.
+ *
+ * @module llm/onboarding
+ * @task T11724
+ * @epic T11671 (E6-ONBOARDING-FRONT-DOOR)
+ */
+export {};
+//# sourceMappingURL=onboarding.js.map

package/dist/llm/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../src/llm/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG"}

package/dist/llm/provider-def.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Declarative `ProviderDef` contract — the DATA shape of one LLM provider.
+ *
+ * M3 Provider SSoT (epic T11667 · task T11702). `ProviderDef` is the DECLARATIVE,
+ * serializable description of a provider: its identity, aliases, auth methods, wire
+ * endpoint (a discriminated union keyed on the `transport` literal), models.dev
+ * catalog key, default headers, optional OAuth flow, and a single request-quirk hook
+ * signature. It is the contract the `providers` global-DB table (T11703) persists and
+ * the alias resolver (T11704) reads.
+ *
+ * ## ProviderDef vs {@link ProviderProfile} — declarative DATA vs runtime BEHAVIOUR
+ *
+ * The pre-existing {@link ProviderProfile} (T9262 · T11756) is the RUNTIME provider
+ * shape carried in the in-process registry: it bundles live hook FUNCTIONS
+ * (`prepareMessages`, `buildExtraBody`, `buildApiKwargsExtras`, `fetchModels`) that
+ * cannot be serialized into a DB row. `ProviderDef` is the DECLARATIVE projection of
+ * the same provider — only serializable DATA — so it can be a `providers` table row,
+ * shipped as a seed, diffed, and resolved without importing provider-specific code.
+ * The builtin `ProviderProfile` set is the SEED SOURCE for the builtin `ProviderDef`
+ * set (the core mapper derives one from the other); the non-serializable hooks stay
+ * on `ProviderProfile`, reduced here to the single declarative {@link RequestQuirk}
+ * descriptor that records WHICH quirk a provider needs without embedding a closure.
+ *
+ * ## Endpoint is a discriminated union (AC5)
+ *
+ * {@link ProviderEndpoint} is a closed discriminated union keyed on the literal
+ * `transport` field — one variant per wire protocol CLEO knows how to speak. No
+ * `any`/`unknown` shortcut: every variant carries its own typed fields. This is the
+ * declarative analog of {@link ApiMode}; the core transport adapter table (T11767)
+ * maps a `transport` value to its `Transport` constructor.
+ *
+ * ## Contracts purity (Gate 10)
+ *
+ * This module is TYPES ONLY — interfaces, type aliases, and `as const` literal arrays.
+ * It exports NO bodied runtime helper. The builtin-set construction and the seed/upsert
+ * logic live in `@cleocode/core` (T11703 · T11704), never here.
+ *
+ * @module llm/provider-def
+ * @task T11702
+ * @epic T11667
+ * @see ./provider-profile.ts — the RUNTIME provider shape (hooks) this projects from
+ * @see ./provider-id.ts — {@link ApiMode} / {@link BuiltinProviderId} the transport mirrors
+ * @see ./oauth.ts — {@link ProviderOAuthConfig} the OAuth flow placeholder reuses
+ * @see ../../../core/src/store/schema/cleo-global/providers.ts — the persisted table (T11703)
+ */
+import type { StoredAuthTypeWire } from '../operations/llm.js';
+import type { ProviderOAuthConfig } from './oauth.js';
+import type { ProviderId } from './provider-id.js';
+/**
+ * Wire-transport discriminant for a {@link ProviderEndpoint} variant.
+ *
+ * Closed union — one literal per protocol CLEO has a transport for. The
+ * declarative analog of {@link import('./provider-id.js').ApiMode}:
+ *
+ * - `openai-completions` — OpenAI `/chat/completions` shape (OpenAI, OpenRouter,
+ *   Moonshot, Kimi, xAI, Gemini-via-OpenAI-compat) — `ApiMode 'chat_completions'`.
+ * - `openai-responses` — OpenAI Responses API (Codex backend, xAI-responses) —
+ *   `ApiMode 'codex_responses'`.
+ * - `anthropic-messages` — native Anthropic Messages API (prompt-cache + thinking) —
+ *   `ApiMode 'anthropic_messages'`.
+ * - `aisdk` — routed through the Vercel AI-SDK provider factory (the data-driven
+ *   `apiMode → provider` adapter, T11767) rather than a bespoke CLEO transport.
+ *
+ * @task T11702
+ */
+export declare const PROVIDER_TRANSPORTS: readonly ["openai-completions", "openai-responses", "anthropic-messages", "aisdk"];
+/** TypeScript union derived from {@link PROVIDER_TRANSPORTS}. */
+export type ProviderTransport = (typeof PROVIDER_TRANSPORTS)[number];
+/**
+ * Endpoint for the `openai-completions` transport — the OpenAI
+ * `/chat/completions` wire shape (OpenAI, OpenRouter, Moonshot, Kimi, xAI,
+ * Gemini-via-compat). `baseUrl` has NO trailing slash.
+ *
+ * @task T11702
+ */
+export interface OpenAICompletionsEndpoint {
+    /** Discriminant — the OpenAI chat-completions wire protocol. */
+    readonly transport: 'openai-completions';
+    /** Base URL for the provider's API — no trailing slash. */
+    readonly baseUrl: string;
+}
+/**
+ * Endpoint for the `openai-responses` transport — the OpenAI Responses API
+ * (Codex backend, xAI-responses). `baseUrl` has NO trailing slash.
+ *
+ * @task T11702
+ */
+export interface OpenAIResponsesEndpoint {
+    /** Discriminant — the OpenAI Responses wire protocol. */
+    readonly transport: 'openai-responses';
+    /** Base URL for the Responses endpoint — no trailing slash. */
+    readonly baseUrl: string;
+}
+/**
+ * Endpoint for the `anthropic-messages` transport — the native Anthropic
+ * Messages API (full prompt-cache + extended thinking). `baseUrl` has NO
+ * trailing slash.
+ *
+ * @task T11702
+ */
+export interface AnthropicMessagesEndpoint {
+    /** Discriminant — the native Anthropic Messages wire protocol. */
+    readonly transport: 'anthropic-messages';
+    /** Base URL for the Anthropic API — no trailing slash. */
+    readonly baseUrl: string;
+}
+/**
+ * Endpoint for the `aisdk` transport — the provider is reached through the
+ * Vercel AI-SDK provider factory (the data-driven adapter table, T11767) keyed
+ * by `aiSdkProvider`, rather than a bespoke CLEO transport.
+ *
+ * @task T11702
+ */
+export interface AiSdkEndpoint {
+    /** Discriminant — routed through the AI-SDK provider factory. */
+    readonly transport: 'aisdk';
+    /** Base URL passed to the AI-SDK provider factory — no trailing slash. */
+    readonly baseUrl: string;
+    /**
+     * The AI-SDK provider-factory key (e.g. `openai-compatible` | `google` |
+     * `bedrock`) the adapter table maps to a `create*` factory. NEVER an inline
+     * client construction — the factory call is the LLM chokepoint (T11783).
+     */
+    readonly aiSdkProvider: string;
+}
+/**
+ * A provider's wire endpoint — a discriminated union keyed on the `transport`
+ * literal (AC5). Exactly one variant per {@link ProviderTransport}; each carries
+ * its own typed fields, with no `any`/`unknown` shortcut.
+ *
+ * @task T11702
+ */
+export type ProviderEndpoint = OpenAICompletionsEndpoint | OpenAIResponsesEndpoint | AnthropicMessagesEndpoint | AiSdkEndpoint;
+/**
+ * Known request-quirk kinds — the DECLARATIVE record of WHICH provider-specific
+ * request adjustment a provider needs, WITHOUT embedding the closure.
+ *
+ * The live closures stay on {@link ProviderProfile} (`buildExtraBody` /
+ * `buildApiKwargsExtras` / `prepareMessages`); a `ProviderDef` row records only
+ * the quirk's stable kind so the table/seed stays serializable. The runtime maps
+ * a {@link RequestQuirk} `kind` back to its hook implementation.
+ *
+ * - `grok-conv-id` — inject the process-scoped `x-grok-conv-id` header (xAI).
+ * - `gemini-thinking-config` — inject `thinking_config` in `extra_body` (Gemini).
+ * - `kimi-reasoning-effort` — top-level `reasoning_effort` kwarg (Kimi Code).
+ * - `moonshot-schema-sanitize` — shallow tool-schema sanitization (Moonshot).
+ * - `openrouter-pareto` — inject the Pareto price-router plugin (OpenRouter).
+ *
+ * @task T11702
+ */
+export declare const REQUEST_QUIRK_KINDS: readonly ["grok-conv-id", "gemini-thinking-config", "kimi-reasoning-effort", "moonshot-schema-sanitize", "openrouter-pareto"];
+/** TypeScript union derived from {@link REQUEST_QUIRK_KINDS}. */
+export type RequestQuirkKind = (typeof REQUEST_QUIRK_KINDS)[number];
+/**
+ * A single declarative request-quirk descriptor (AC4 — the "request-quirk hook
+ * signature"). Records the quirk's stable {@link RequestQuirkKind} so a
+ * `ProviderDef` row stays serializable; the runtime resolves the `kind` to its
+ * hook implementation on {@link ProviderProfile}. The signature the hook MUST
+ * satisfy is `(model: string) => Record<string, unknown>` (the declarative shape
+ * of `buildExtraBody` / `buildApiKwargsExtras`), captured here only as the
+ * documented contract — never as an embedded closure.
+ *
+ * @task T11702
+ */
+export interface RequestQuirk {
+    /** The stable quirk kind this provider needs. */
+    readonly kind: RequestQuirkKind;
+}
+/**
+ * OAuth flow placeholder embedded on a {@link ProviderDef} (AC4).
+ *
+ * For M3 this is the existing {@link ProviderOAuthConfig} shape (PKCE / device-code
+ * endpoints + client id), aliased so the M4 vault work (T10409) can widen it without
+ * a contract rename. A `ProviderDef` carries `oauth` only when the provider supports
+ * an OAuth login flow (anthropic, openai, kimi-code); it is omitted otherwise.
+ *
+ * @task T11702
+ */
+export type OAuthFlowDef = ProviderOAuthConfig;
+/**
+ * Declarative description of one LLM provider — the serializable DATA SSoT.
+ *
+ * The contract persisted as a `providers` table row (T11703) and read by the alias
+ * resolver (T11704). Derived from the runtime {@link ProviderProfile} set: identity
+ * + aliases + auth + endpoint + catalog key + headers + optional OAuth + the
+ * declarative request quirks. Carries NO closures — only serializable DATA.
+ *
+ * @task T11702
+ */
+export interface ProviderDef {
+    /**
+     * Canonical provider id (lower-cased). For builtins this is a
+     * {@link BuiltinProviderId}; plugin providers may use any non-empty string.
+     */
+    readonly id: ProviderId;
+    /** Human-readable display name shown in pickers and diagnostic output. */
+    readonly displayName: string;
+    /**
+     * Alternate names that resolve to this provider (case-insensitive). The SINGLE
+     * source the alias resolver (T11704) reads — `codex`/`chatgpt` → `openai`,
+     * `claude` → `anthropic`, `google` → `gemini`, … An alias colliding with another
+     * provider's primary `id` is a resolution error (T11704 AC2).
+     */
+    readonly aliases: ReadonlyArray<string>;
+    /**
+     * Authentication mechanisms this provider supports (`api_key` | `oauth` |
+     * `aws_sdk`). The {@link StoredAuthTypeWire} wire enum.
+     */
+    readonly authMethods: ReadonlyArray<StoredAuthTypeWire>;
+    /**
+     * The provider's wire endpoint — a discriminated union keyed on `transport`
+     * (AC5). A provider that speaks multiple protocols (e.g. xAI completions +
+     * responses) carries the multiple variants in {@link altEndpoints}.
+     */
+    readonly endpoint: ProviderEndpoint;
+    /**
+     * Additional wire endpoints this provider also speaks, beyond the primary
+     * {@link endpoint}. Collapses the prior per-ApiMode profile duplication into ONE
+     * row (T11703 AC4 — xAI's completions + responses become one `ProviderDef`).
+     * Empty/omitted for single-protocol providers.
+     */
+    readonly altEndpoints?: ReadonlyArray<ProviderEndpoint>;
+    /**
+     * The models.dev catalog provider key joining this provider to the
+     * `models_catalog` table (T11733). Usually equals {@link id}; carried distinctly
+     * because a provider id and its catalog key can differ (e.g. `kimi-code` →
+     * `moonshot`).
+     */
+    readonly modelsDevId: string;
+    /**
+     * HTTP headers sent with every request to this provider, merged into the
+     * client's `defaultHeaders` (e.g. `{ 'anthropic-version': '2023-06-01' }`).
+     * Omitted when the provider needs no pinned headers.
+     */
+    readonly defaultHeaders?: Readonly<Record<string, string>>;
+    /**
+     * Environment variable names that may supply this provider's API key (e.g.
+     * `['ANTHROPIC_API_KEY']`). Resolver chains may check these before the vault.
+     * Omitted when the provider has no env-var credential path.
+     */
+    readonly envVars?: ReadonlyArray<string>;
+    /**
+     * OAuth flow placeholder (AC4) — present only when the provider supports an
+     * OAuth login flow (anthropic, openai, kimi-code). See {@link OAuthFlowDef}.
+     */
+    readonly oauth?: OAuthFlowDef;
+    /**
+     * Declarative request quirks this provider needs (AC4) — the stable
+     * {@link RequestQuirk} descriptors WITHOUT the closures (those stay on
+     * {@link ProviderProfile}). Empty/omitted when the provider needs no quirk.
+     */
+    readonly requestQuirks?: ReadonlyArray<RequestQuirk>;
+}
+//# sourceMappingURL=provider-def.d.ts.map

package/dist/llm/provider-def.d.ts.map

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

package/dist/llm/provider-def.js

@@ -0,0 +1,93 @@
+/**
+ * Declarative `ProviderDef` contract — the DATA shape of one LLM provider.
+ *
+ * M3 Provider SSoT (epic T11667 · task T11702). `ProviderDef` is the DECLARATIVE,
+ * serializable description of a provider: its identity, aliases, auth methods, wire
+ * endpoint (a discriminated union keyed on the `transport` literal), models.dev
+ * catalog key, default headers, optional OAuth flow, and a single request-quirk hook
+ * signature. It is the contract the `providers` global-DB table (T11703) persists and
+ * the alias resolver (T11704) reads.
+ *
+ * ## ProviderDef vs {@link ProviderProfile} — declarative DATA vs runtime BEHAVIOUR
+ *
+ * The pre-existing {@link ProviderProfile} (T9262 · T11756) is the RUNTIME provider
+ * shape carried in the in-process registry: it bundles live hook FUNCTIONS
+ * (`prepareMessages`, `buildExtraBody`, `buildApiKwargsExtras`, `fetchModels`) that
+ * cannot be serialized into a DB row. `ProviderDef` is the DECLARATIVE projection of
+ * the same provider — only serializable DATA — so it can be a `providers` table row,
+ * shipped as a seed, diffed, and resolved without importing provider-specific code.
+ * The builtin `ProviderProfile` set is the SEED SOURCE for the builtin `ProviderDef`
+ * set (the core mapper derives one from the other); the non-serializable hooks stay
+ * on `ProviderProfile`, reduced here to the single declarative {@link RequestQuirk}
+ * descriptor that records WHICH quirk a provider needs without embedding a closure.
+ *
+ * ## Endpoint is a discriminated union (AC5)
+ *
+ * {@link ProviderEndpoint} is a closed discriminated union keyed on the literal
+ * `transport` field — one variant per wire protocol CLEO knows how to speak. No
+ * `any`/`unknown` shortcut: every variant carries its own typed fields. This is the
+ * declarative analog of {@link ApiMode}; the core transport adapter table (T11767)
+ * maps a `transport` value to its `Transport` constructor.
+ *
+ * ## Contracts purity (Gate 10)
+ *
+ * This module is TYPES ONLY — interfaces, type aliases, and `as const` literal arrays.
+ * It exports NO bodied runtime helper. The builtin-set construction and the seed/upsert
+ * logic live in `@cleocode/core` (T11703 · T11704), never here.
+ *
+ * @module llm/provider-def
+ * @task T11702
+ * @epic T11667
+ * @see ./provider-profile.ts — the RUNTIME provider shape (hooks) this projects from
+ * @see ./provider-id.ts — {@link ApiMode} / {@link BuiltinProviderId} the transport mirrors
+ * @see ./oauth.ts — {@link ProviderOAuthConfig} the OAuth flow placeholder reuses
+ * @see ../../../core/src/store/schema/cleo-global/providers.ts — the persisted table (T11703)
+ */
+/**
+ * Wire-transport discriminant for a {@link ProviderEndpoint} variant.
+ *
+ * Closed union — one literal per protocol CLEO has a transport for. The
+ * declarative analog of {@link import('./provider-id.js').ApiMode}:
+ *
+ * - `openai-completions` — OpenAI `/chat/completions` shape (OpenAI, OpenRouter,
+ *   Moonshot, Kimi, xAI, Gemini-via-OpenAI-compat) — `ApiMode 'chat_completions'`.
+ * - `openai-responses` — OpenAI Responses API (Codex backend, xAI-responses) —
+ *   `ApiMode 'codex_responses'`.
+ * - `anthropic-messages` — native Anthropic Messages API (prompt-cache + thinking) —
+ *   `ApiMode 'anthropic_messages'`.
+ * - `aisdk` — routed through the Vercel AI-SDK provider factory (the data-driven
+ *   `apiMode → provider` adapter, T11767) rather than a bespoke CLEO transport.
+ *
+ * @task T11702
+ */
+export const PROVIDER_TRANSPORTS = [
+    'openai-completions',
+    'openai-responses',
+    'anthropic-messages',
+    'aisdk',
+];
+/**
+ * Known request-quirk kinds — the DECLARATIVE record of WHICH provider-specific
+ * request adjustment a provider needs, WITHOUT embedding the closure.
+ *
+ * The live closures stay on {@link ProviderProfile} (`buildExtraBody` /
+ * `buildApiKwargsExtras` / `prepareMessages`); a `ProviderDef` row records only
+ * the quirk's stable kind so the table/seed stays serializable. The runtime maps
+ * a {@link RequestQuirk} `kind` back to its hook implementation.
+ *
+ * - `grok-conv-id` — inject the process-scoped `x-grok-conv-id` header (xAI).
+ * - `gemini-thinking-config` — inject `thinking_config` in `extra_body` (Gemini).
+ * - `kimi-reasoning-effort` — top-level `reasoning_effort` kwarg (Kimi Code).
+ * - `moonshot-schema-sanitize` — shallow tool-schema sanitization (Moonshot).
+ * - `openrouter-pareto` — inject the Pareto price-router plugin (OpenRouter).
+ *
+ * @task T11702
+ */
+export const REQUEST_QUIRK_KINDS = [
+    'grok-conv-id',
+    'gemini-thinking-config',
+    'kimi-reasoning-effort',
+    'moonshot-schema-sanitize',
+    'openrouter-pareto',
+];
+//# sourceMappingURL=provider-def.js.map

package/dist/llm/provider-def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-def.js","sourceRoot":"","sources":["../../src/llm/provider-def.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,OAAO;CACC,CAAC;AA+EX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,cAAc;IACd,wBAAwB;IACxB,uBAAuB;IACvB,0BAA0B;IAC1B,mBAAmB;CACX,CAAC"}