@cleocode/contracts 2026.6.13 → 2026.6.14

package/src/llm/provider-def.ts

@@ -0,0 +1,291 @@
+/**
+ * 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 const PROVIDER_TRANSPORTS = [
+  'openai-completions',
+  'openai-responses',
+  'anthropic-messages',
+  'aisdk',
+] as const;
+
+/** 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 const REQUEST_QUIRK_KINDS = [
+  'grok-conv-id',
+  'gemini-thinking-config',
+  'kimi-reasoning-effort',
+  'moonshot-schema-sanitize',
+  'openrouter-pareto',
+] as const;
+
+/** 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>;
+}

package/src/llm/system-resolver.ts

@@ -135,4 +135,49 @@ export interface ResolveLLMForSystemOptions {
    * @internal
    */
   skipCatalogDefault?: boolean;
+
+  /**
+   * Raw prompt used to derive a role from complexity when neither an explicit
+   * tier/role nor a role-mapped system label is available (L1 proposer · T11906).
+   *
+   * When the `system` argument is the flat `'default'` label (which maps to NO
+   * role) and `roleOverride` is unset, the resolver runs the L1 complexity
+   * classifier over this prompt and proposes a {@link RoleName} from the
+   * resulting tier (`low → hygiene`, `mid → consolidation`, `high → judgement`).
+   * This is a COMPLEMENT to the resolver — it only supplies a role when one is
+   * otherwise absent; an explicit label, descriptor, or `roleOverride` always
+   * wins. The classifier returns a TIER only and constructs no LLM client.
+   *
+   * Ignored when the role is already determined by the input or `roleOverride`.
+   */
+  complexityPrompt?: string;
+
+  /**
+   * Explicit encoded system-of-use key for the `llm.systems[key]` granular
+   * override tier (T11759 · M4).
+   *
+   * The flat-label input form derives this key from `system` itself; this option
+   * lets a caller resolving an OPEN-axis system (whose identity is NOT a flat
+   * {@link SystemOfUseLabel}) — e.g. a `.cantbook` node keyed
+   * `cantbook:<playbook>#<nodeId>` — supply that identity as the granular
+   * override + audit key while passing a resolvable background label as
+   * `system`. When set, it OVERRIDES the label-derived key. Omit it and the
+   * pre-T11759 derivation is unchanged.
+   *
+   * @task T11759
+   */
+  systemKey?: string;
+
+  /**
+   * Optional named profile (a key of `llm.profiles`) that pins the resolution to
+   * a specific provider/model/credential, winning over the role tier (T11759 ·
+   * M4).
+   *
+   * Threaded down to `ResolveLLMForRoleOptions.profileOverride`. A `.cantbook`
+   * stage's `profile:` flows through here. When the named profile is
+   * absent/incomplete, resolution falls through the normal chain unchanged.
+   *
+   * @task T11759
+   */
+  profile?: string;
 }

package/src/operations/admin.ts

@@ -380,6 +380,9 @@ export type AdminOp =
   | 'admin.health'
   | 'admin.config.show'
   | 'admin.config.presets'
+  | 'admin.config.get'
+  | 'admin.config.list'
+  | 'admin.config.validate'
   | 'admin.stats'
   | 'admin.context'
   | 'admin.context.pull'
@@ -406,6 +409,7 @@ export type AdminOp =
   | 'admin.health.mutate'
   | 'admin.config.set'
   | 'admin.config.set-preset'
+  | 'admin.config.unset'
   | 'admin.backup.mutate'
   | 'admin.migrate'
   | 'admin.cleanup'
@@ -513,6 +517,109 @@ export interface AdminConfigPresetsResult {
   presets: AdminPresetDefinition[];
 }
 
+// ---------------------------------------------------------------------------
+// admin.config.get (T11917 — config-as-domain, ConfigManifest cascade)
+// ---------------------------------------------------------------------------
+
+/**
+ * Cascade slice selector for the config-as-domain query ops.
+ *
+ * - `'global'`  — read ONLY `~/.cleo/config.json` (precedence 10)
+ * - `'project'` — read ONLY `<project>/.cleo/config.json` (precedence 20)
+ * - `'merged'`  — read the deep-merge `{ ...global, ...project }` (default)
+ *
+ * Mirrors the `ResolveScope` of the `resolveCleoConfig` cascade resolver.
+ *
+ * @task T11917
+ */
+export type AdminConfigScope = 'global' | 'project' | 'merged';
+
+/** Parameters for `admin.config.get`. */
+export interface AdminConfigGetParams {
+  /** Dot-notation config key to read a single value (required). */
+  key: string;
+  /** Cascade slice to read from. Defaults to `'merged'`. */
+  scope?: AdminConfigScope;
+}
+
+/**
+ * Result of `admin.config.get`.
+ *
+ * Returns the resolved value for `key`, or `null` when the key is absent in the
+ * selected cascade slice. `found` disambiguates a present `null` value from an
+ * absent key.
+ *
+ * @task T11917
+ */
+export interface AdminConfigGetResult {
+  /** The dot-notation key that was resolved. */
+  key: string;
+  /** Cascade slice the value was resolved against. */
+  scope: AdminConfigScope;
+  /** Resolved value, or `null` when the key is absent. */
+  value: unknown;
+  /** `true` IFF the key resolved to a defined value in the cascade. */
+  found: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// admin.config.list (T11917 — full resolved cascade)
+// ---------------------------------------------------------------------------
+
+/** Parameters for `admin.config.list`. */
+export interface AdminConfigListParams {
+  /** Cascade slice to project. Defaults to `'merged'`. */
+  scope?: AdminConfigScope;
+}
+
+/**
+ * Result of `admin.config.list`.
+ *
+ * Returns the full resolved config object for the selected cascade slice plus
+ * the flattened dot-notation key list for discovery.
+ *
+ * @task T11917
+ */
+export interface AdminConfigListResult {
+  /** Cascade slice the config was resolved against. */
+  scope: AdminConfigScope;
+  /** Full resolved config object for the slice. */
+  config: Record<string, unknown>;
+  /** Flattened dot-notation keys present in the resolved config. */
+  keys: string[];
+}
+
+// ---------------------------------------------------------------------------
+// admin.config.validate (T11917 — schema-validate the cascade entry)
+// ---------------------------------------------------------------------------
+
+/** Parameters for `admin.config.validate`. */
+export interface AdminConfigValidateParams {
+  /**
+   * Scope to validate. Only the cascade-participating scopes are valid —
+   * `'merged'` is rejected because validation runs against a single file's
+   * manifest entry schema. Defaults to `'project'`.
+   */
+  scope?: 'global' | 'project';
+}
+
+/**
+ * Result of `admin.config.validate`.
+ *
+ * `ok` is `true` IFF the file passed its manifest entry's schema gate (or no
+ * schema was configured). `issues` carries human-readable rejection reasons.
+ *
+ * @task T11917
+ */
+export interface AdminConfigValidateResult {
+  /** Scope that was validated. */
+  scope: 'global' | 'project';
+  /** `true` IFF every gate passed. */
+  ok: boolean;
+  /** Human-readable schema issues. Empty when `ok === true`. */
+  issues: string[];
+}
+
 // ---------------------------------------------------------------------------
 // admin.stats
 // ---------------------------------------------------------------------------
@@ -1466,6 +1573,35 @@ export interface AdminConfigSetResult {
   value: unknown;
 }
 
+// ---------------------------------------------------------------------------
+// admin.config.unset (T11917 — remove a key from a scoped config file)
+// ---------------------------------------------------------------------------
+
+/** Parameters for `admin.config.unset`. */
+export interface AdminConfigUnsetParams {
+  /** Dot-notation config key to remove (required). */
+  key: string;
+  /** Remove from the global file instead of the project file. */
+  global?: boolean;
+}
+
+/**
+ * Result of `admin.config.unset`.
+ *
+ * `removed` is `true` IFF the key existed and was deleted; `false` when the key
+ * was already absent (idempotent no-op).
+ *
+ * @task T11917
+ */
+export interface AdminConfigUnsetResult {
+  /** Config key that was targeted. */
+  key: string;
+  /** Scope the key was removed from. */
+  scope: 'project' | 'global';
+  /** `true` IFF a value was actually deleted. */
+  removed: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // admin.config.set-preset
 // ---------------------------------------------------------------------------
@@ -1996,6 +2132,13 @@ export type AdminOps =
       params: AdminConfigPresetsParams;
       result: AdminConfigPresetsResult;
     }
+  | { op: 'admin.config.get'; params: AdminConfigGetParams; result: AdminConfigGetResult }
+  | { op: 'admin.config.list'; params: AdminConfigListParams; result: AdminConfigListResult }
+  | {
+      op: 'admin.config.validate';
+      params: AdminConfigValidateParams;
+      result: AdminConfigValidateResult;
+    }
   | { op: 'admin.stats'; params: AdminStatsParams; result: AdminStatsResult }
   | { op: 'admin.context'; params: AdminContextParams; result: AdminContextResult }
   | { op: 'admin.context.pull'; params: AdminContextPullParams; result: AdminContextPullResult }
@@ -2046,6 +2189,7 @@ export type AdminOps =
       params: AdminConfigSetPresetParams;
       result: AdminConfigSetPresetResult;
     }
+  | { op: 'admin.config.unset'; params: AdminConfigUnsetParams; result: AdminConfigUnsetResult }
   | {
       op: 'admin.backup.mutate';
       params: AdminBackupMutateParams;