@cleocode/contracts 2026.6.13 → 2026.6.14

package/src/llm/catalog-schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cleocode.dev/schemas/llm/curated-catalog.json",
+  "title": "Curated Models Catalog",
+  "description": "The shipped, offline-first provider+model catalog seed (E8 · T11731). One self-contained snapshot of the models.dev wire shape that seeds the global `models_catalog` table and backs offline/degraded reads. NO network access is implied by this file — it is the build-time committed mirror.",
+  "type": "object",
+  "required": ["version", "lastUpdated", "providers", "models"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver version of this catalog snapshot. Bumped on every regeneration; drives the seeder skip/re-seed decision."
+    },
+    "lastUpdated": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) the snapshot was generated."
+    },
+    "providers": {
+      "type": "object",
+      "description": "Provider records keyed by models.dev provider id (e.g. `anthropic`, `openai`, `google`).",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["id", "endpoint", "authTypes"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "description": "Provider id (matches the map key)." },
+          "endpoint": {
+            "type": "string",
+            "description": "Provider API base URL (e.g. `https://api.anthropic.com`)."
+          },
+          "authTypes": {
+            "type": "array",
+            "description": "Supported auth mechanisms keyed by provider id.",
+            "items": { "type": "string", "enum": ["api_key", "oauth", "bedrock", "vertex"] },
+            "minItems": 1
+          },
+          "npm": {
+            "type": "string",
+            "description": "Provider SDK npm package, when applicable (e.g. `@anthropic-ai/sdk`)."
+          }
+        }
+      }
+    },
+    "models": {
+      "type": "object",
+      "description": "Model entries keyed by provider id; each value is a map of model-id → model entry.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "$ref": "#/$defs/modelEntry"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "modelEntry": {
+      "type": "object",
+      "description": "Full models.dev wire capability set for a single model.",
+      "required": [
+        "id",
+        "name",
+        "family",
+        "attachment",
+        "reasoning",
+        "temperature",
+        "interleaved",
+        "tool_call",
+        "modalities",
+        "cost",
+        "limit",
+        "status",
+        "release_date",
+        "provider"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "description": "Model identifier (e.g. `claude-haiku-4-5`)." },
+        "name": { "type": "string", "description": "Human-readable display name." },
+        "family": { "type": "string", "description": "Model family (e.g. `claude`, `gpt`, `gemini`)." },
+        "attachment": { "type": "boolean", "description": "Supports file/image attachments." },
+        "reasoning": { "type": "boolean", "description": "Supports extended reasoning / thinking." },
+        "temperature": { "type": "boolean", "description": "Honours a temperature parameter." },
+        "interleaved": { "type": "boolean", "description": "Supports interleaved thinking blocks." },
+        "tool_call": { "type": "boolean", "description": "Supports tool/function calling." },
+        "modalities": {
+          "type": "object",
+          "required": ["input", "output"],
+          "additionalProperties": false,
+          "properties": {
+            "input": { "type": "array", "items": { "type": "string" } },
+            "output": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "cost": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "input": { "type": "number" },
+            "output": { "type": "number" },
+            "cache_read": { "type": "number" },
+            "cache_write": { "type": "number" },
+            "context_over_200k": { "type": "number" }
+          }
+        },
+        "limit": {
+          "type": "object",
+          "required": ["context", "output"],
+          "additionalProperties": false,
+          "properties": {
+            "context": { "type": "number", "description": "Max context window (tokens)." },
+            "output": { "type": "number", "description": "Max output tokens." }
+          }
+        },
+        "status": {
+          "type": "string",
+          "enum": ["stable", "beta", "preview", "deprecated", "retired"],
+          "description": "Availability lifecycle of the model."
+        },
+        "release_date": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "ISO release date (YYYY-MM-DD). The SSoT sort key — latest wins."
+        },
+        "provider": {
+          "type": "object",
+          "required": ["npm", "api"],
+          "additionalProperties": false,
+          "properties": {
+            "npm": { "type": "string" },
+            "api": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/src/llm/catalog-schema.ts

@@ -0,0 +1,184 @@
+/**
+ * Zod mirror + TypeScript types for the curated models catalog (E8 · T11731).
+ *
+ * This is the type+validation SSoT for the **shipped, offline-first** provider+model
+ * catalog seed that populates the global `models_catalog` table (T11733) and backs
+ * offline/degraded catalog reads (T11737). It mirrors the JSON Schema in the sibling
+ * `catalog-schema.json` (draft 2020-12) one-to-one.
+ *
+ * ## Offline-first — NO network is implied by these types
+ *
+ * The {@link CuratedCatalog} shape describes a committed, build-time snapshot of the
+ * models.dev wire shape. Nothing here fetches; the network refresh op
+ * (`cleo llm refresh-catalog`) is a SEPARATE leaf. The seeder reads the bundled
+ * `curated-catalog.json` (validated against {@link curatedCatalogSchema}) and upserts
+ * every row offline.
+ *
+ * ## models_catalog row parity (AC4)
+ *
+ * {@link modelsCatalogRowSelectSchema} / {@link modelsCatalogRowInsertSchema} describe the
+ * FLATTENED per-row shape persisted in the `models_catalog` DB table — the json/cost/
+ * modalities sub-objects serialize to TEXT columns, booleans to `integer({mode:'boolean'})`.
+ * {@link flattenCatalogToRows} (in core) maps a {@link CuratedCatalog} → these rows.
+ *
+ * Contracts-purity (Gate 10): this module exports ONLY zod schemas (values) and
+ * `z.infer` types — no bodied runtime helpers. The flatten/seed logic lives in core.
+ *
+ * @module llm/catalog-schema
+ * @task T11731
+ * @epic T11694 (E8-CATALOG-CURATION)
+ */
+
+import { z } from 'zod';
+
+/** Legal `models_catalog.status` availability-lifecycle values. */
+export const CATALOG_MODEL_STATUSES = [
+  'stable',
+  'beta',
+  'preview',
+  'deprecated',
+  'retired',
+] as const;
+
+/** TypeScript union of {@link CATALOG_MODEL_STATUSES}. */
+export type CatalogModelStatus = (typeof CATALOG_MODEL_STATUSES)[number];
+
+/** Legal provider auth mechanisms carried in a catalog provider entry. */
+export const CATALOG_AUTH_TYPES = ['api_key', 'oauth', 'bedrock', 'vertex'] as const;
+
+/** TypeScript union of {@link CATALOG_AUTH_TYPES}. */
+export type CatalogAuthType = (typeof CATALOG_AUTH_TYPES)[number];
+
+/** ISO date `YYYY-MM-DD` matcher (the catalog sort/version key shape). */
+const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'must be an ISO date (YYYY-MM-DD)');
+
+/** Semver `MAJOR.MINOR.PATCH` matcher for the catalog snapshot version. */
+const semver = z.string().regex(/^\d+\.\d+\.\d+$/, 'must be semver (MAJOR.MINOR.PATCH)');
+
+/** Input/output modality lists for a model. */
+export const catalogModalitiesSchema = z
+  .object({
+    input: z.array(z.string()),
+    output: z.array(z.string()),
+  })
+  .strict();
+
+/** Per-1M-token cost facets for a model (all optional — providers vary). */
+export const catalogCostSchema = z
+  .object({
+    input: z.number().optional(),
+    output: z.number().optional(),
+    cache_read: z.number().optional(),
+    cache_write: z.number().optional(),
+    context_over_200k: z.number().optional(),
+  })
+  .strict();
+
+/** Context/output token-window limits for a model. */
+export const catalogLimitSchema = z
+  .object({
+    context: z.number(),
+    output: z.number(),
+  })
+  .strict();
+
+/** The provider-of-record (npm package + api protocol) for a model. */
+export const catalogModelProviderSchema = z
+  .object({
+    npm: z.string(),
+    api: z.string(),
+  })
+  .strict();
+
+/** Full models.dev wire capability set for a single model entry. */
+export const catalogModelEntrySchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    family: z.string(),
+    attachment: z.boolean(),
+    reasoning: z.boolean(),
+    temperature: z.boolean(),
+    interleaved: z.boolean(),
+    tool_call: z.boolean(),
+    modalities: catalogModalitiesSchema,
+    cost: catalogCostSchema,
+    limit: catalogLimitSchema,
+    status: z.enum(CATALOG_MODEL_STATUSES),
+    release_date: isoDate,
+    provider: catalogModelProviderSchema,
+  })
+  .strict();
+
+/** A provider record in the catalog envelope. */
+export const catalogProviderSchema = z
+  .object({
+    id: z.string(),
+    endpoint: z.string(),
+    authTypes: z.array(z.enum(CATALOG_AUTH_TYPES)).min(1),
+    npm: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * Top-level shape of the curated catalog seed (`curated-catalog.json`).
+ *
+ * `providers` is keyed by provider id; `models` is keyed by provider id → model id →
+ * {@link catalogModelEntrySchema}.
+ */
+export const curatedCatalogSchema = z
+  .object({
+    $schema: z.string().optional(),
+    version: semver,
+    lastUpdated: isoDate,
+    providers: z.record(z.string(), catalogProviderSchema),
+    models: z.record(z.string(), z.record(z.string(), catalogModelEntrySchema)),
+  })
+  .strict();
+
+/** The validated curated catalog seed shape. */
+export type CuratedCatalog = z.infer<typeof curatedCatalogSchema>;
+/** A single model entry from the curated catalog. */
+export type CatalogModelEntry = z.infer<typeof catalogModelEntrySchema>;
+/** A single provider entry from the curated catalog. */
+export type CatalogProvider = z.infer<typeof catalogProviderSchema>;
+
+/**
+ * INSERT/UPSERT shape for one `models_catalog` row (the flattened persistence form).
+ *
+ * The catalog's nested `modalities` / `cost` sub-objects are JSON-serialized into the
+ * `modalities` / `cost` TEXT columns; booleans persist as `integer({mode:'boolean'})`.
+ * `provider_id` is the catalog key; `models_dev_id` mirrors the entry `id`.
+ */
+export const modelsCatalogRowInsertSchema = z
+  .object({
+    id: z.string(),
+    providerId: z.string(),
+    name: z.string(),
+    family: z.string(),
+    attachment: z.boolean(),
+    reasoning: z.boolean(),
+    temperature: z.boolean(),
+    interleaved: z.boolean(),
+    toolCall: z.boolean(),
+    modalities: z.string(),
+    cost: z.string(),
+    contextLimit: z.number().nullable().optional(),
+    outputLimit: z.number().nullable().optional(),
+    status: z.enum(CATALOG_MODEL_STATUSES),
+    releaseDate: isoDate,
+    modelsDevId: z.string(),
+    source: z.string(),
+    seededAt: z.string().optional(),
+  })
+  .strict();
+
+/** SELECT shape for one `models_catalog` row (adds the always-present `seededAt`). */
+export const modelsCatalogRowSelectSchema = modelsCatalogRowInsertSchema.extend({
+  seededAt: z.string(),
+});
+
+/** INSERT/UPSERT row type for `models_catalog`. */
+export type ModelsCatalogRowInsert = z.infer<typeof modelsCatalogRowInsertSchema>;
+/** SELECT row type for `models_catalog`. */
+export type ModelsCatalogRowSelect = z.infer<typeof modelsCatalogRowSelectSchema>;

package/src/llm/index.ts

@@ -0,0 +1,29 @@
+/**
+ * `@cleocode/contracts/llm` — LLM contract subpath barrel.
+ *
+ * Re-exports the declarative provider contracts so consumers can import from the
+ * `./llm` subpath (`@cleocode/contracts/llm`) in addition to the package root.
+ * Currently fronts the M3 Provider SSoT {@link ProviderDef} contract (T11702);
+ * other `llm/*` modules continue to export from the package root barrel.
+ *
+ * @module llm
+ * @task T11702
+ * @epic T11667
+ */
+
+export type {
+  AiSdkEndpoint,
+  AnthropicMessagesEndpoint,
+  OAuthFlowDef,
+  OpenAICompletionsEndpoint,
+  OpenAIResponsesEndpoint,
+  ProviderDef,
+  ProviderEndpoint,
+  ProviderTransport,
+  RequestQuirk,
+  RequestQuirkKind,
+} from './provider-def.js';
+export {
+  PROVIDER_TRANSPORTS,
+  REQUEST_QUIRK_KINDS,
+} from './provider-def.js';

package/src/llm/oauth.ts

@@ -154,8 +154,22 @@ 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';
 }

package/src/llm/onboarding.ts

@@ -0,0 +1,131 @@
+/**
+ * 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;
+}