@cleocode/contracts 2026.6.13 → 2026.6.15

package/dist/llm/catalog-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-schema.d.ts","sourceRoot":"","sources":["../../src/llm/catalog-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iEAMzB,CAAC;AAEX,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,oDAAqD,CAAC;AAErF,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAQlE,+CAA+C;AAC/C,eAAO,MAAM,uBAAuB;;;kBAKzB,CAAC;AAEZ,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB;;;;;;kBAQnB,CAAC;AAEZ,sDAAsD;AACtD,eAAO,MAAM,kBAAkB;;;kBAKpB,CAAC;AAEZ,uEAAuE;AACvE,eAAO,MAAM,0BAA0B;;;kBAK5B,CAAC;AAEZ,oEAAoE;AACpE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiBzB,CAAC;AAEZ,iDAAiD;AACjD,eAAO,MAAM,qBAAqB;;;;;;;;;;kBAOvB,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQtB,CAAC;AAEZ,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;kBAqB9B,CAAC;AAEZ,sFAAsF;AACtF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;kBAEvC,CAAC;AAEH,mDAAmD;AACnD,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,4CAA4C;AAC5C,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/llm/catalog-schema.js

@@ -0,0 +1,153 @@
+/**
+ * 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',
+];
+/** Legal provider auth mechanisms carried in a catalog provider entry. */
+export const CATALOG_AUTH_TYPES = ['api_key', 'oauth', 'bedrock', 'vertex'];
+/** 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();
+/**
+ * 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(),
+});
+//# sourceMappingURL=catalog-schema.js.map

package/dist/llm/catalog-schema.js.map

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

package/dist/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/dist/llm/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,YAAY,EACZ,yBAAyB,EACzB,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/llm/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@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 { PROVIDER_TRANSPORTS, REQUEST_QUIRK_KINDS, } from './provider-def.js';
+//# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

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"}