@cleocode/contracts 2026.5.65 → 2026.5.67

package/src/llm/normalized-response.ts

@@ -0,0 +1,313 @@
+/**
+ * Normalized provider response types for the CLEO LLM transport layer.
+ *
+ * Ported from Hermes `agent/transports/types.py` (Python dataclasses →
+ * TypeScript interfaces, snake_case → camelCase). These types define the
+ * canonical shape that all provider transports normalize responses to. The
+ * shared surface is intentionally minimal — only fields that every downstream
+ * consumer reads are top-level. Protocol-specific state goes in `providerData`
+ * dicts so that protocol-aware code paths can access it without polluting the
+ * shared type.
+ *
+ * @module llm/normalized-response
+ * @task T9263
+ * @task T9282 (W0c — Phase 4 multimodal + stream extensions)
+ * @epic T-LLM-CRED-CENTRALIZATION
+ * @see ADR-072 §LlmTransport — pure wire level
+ */
+
+import type { ModelTransport } from '../operations/llm.js';
+import type { NormalizedDelta, TransportContext } from './interfaces.js';
+import type { ApiMode } from './provider-id.js';
+
+/**
+ * Token usage reported by the provider for a single API call.
+ *
+ * `cachedTokens` is only populated when the provider supports prompt-cache
+ * read accounting (Anthropic extended caching, Gemini cached content).
+ */
+export interface NormalizedUsage {
+  /** Tokens consumed by the prompt. */
+  inputTokens: number;
+  /** Tokens generated by the model. */
+  outputTokens: number;
+  /** Tokens served from prompt cache (if provider supports caching). */
+  cachedTokens?: number;
+}
+
+/**
+ * A single normalized tool call emitted by the model.
+ *
+ * `id` is the protocol-canonical identifier used when constructing tool result
+ * messages. May be `null` when the provider omits it (rare in practice but
+ * possible with some adapters).
+ *
+ * `providerData` carries per-tool-call protocol metadata that only
+ * protocol-aware code reads. Examples:
+ * - Codex: `{ call_id: "call_XXX", response_item_id: "fc_XXX" }`
+ * - Gemini: `{ extra_content: { thought_signature: "..." } }`
+ */
+export interface NormalizedToolCall {
+  /** Provider-assigned tool-call id (may be null if provider does not surface one). */
+  id: string | null;
+  /** Tool name as declared in the request. */
+  name: string;
+  /** Arguments as a JSON string (provider-agnostic). */
+  arguments: string;
+  /** Provider-specific extras (raw shape, do not depend on). */
+  providerData?: Record<string, unknown>;
+}
+
+/**
+ * Normalized API response from any LLM provider.
+ *
+ * Shared fields are truly cross-provider — every caller can rely on them
+ * without branching on transport. Protocol-specific state goes in
+ * `providerData` so that only protocol-aware code paths read it.
+ *
+ * `raw` is the unmodified SDK response object. Consumers MUST narrow it with
+ * a type guard before accessing fields. NEVER log `raw` without scrubbing
+ * auth headers.
+ */
+export interface NormalizedResponse {
+  /** Response id from the provider (or a synthesized id if absent). */
+  id: string;
+  /** Model identifier as reported by the provider. */
+  model: string;
+  /** Plain text content (null when the model returned only tool calls). */
+  content: string | null;
+  /** Tool calls, or null when none. */
+  toolCalls: NormalizedToolCall[] | null;
+  /**
+   * Provider-reported stop reason.
+   * Common values: `'end_turn'`, `'tool_use'`, `'stop'`, `'max_tokens'`,
+   * `'stop_sequence'`, `'tool_calls'`, `'length'`.
+   */
+  stopReason: string;
+  /** Token usage for this call. */
+  usage: NormalizedUsage;
+  /**
+   * Optional model-internal reasoning trace.
+   * Populated for Anthropic extended-thinking and OpenAI o1-series models.
+   */
+  reasoning?: string | null;
+  /** Provider-specific response-level extras (raw shape, do not depend on). */
+  providerData?: Record<string, unknown>;
+  /**
+   * Raw provider response — DO NOT log this without scrubbing auth headers.
+   *
+   * Typed as `unknown` because the concrete SDK response shapes
+   * (Anthropic.Message, OpenAI.ChatCompletion, …) are not imported from
+   * contracts. Consumers MUST narrow with a type guard before accessing fields.
+   */
+  raw: unknown;
+}
+
+/**
+ * An image content block for multimodal messages.
+ *
+ * `source.type` determines how the image data is provided:
+ * - `'base64'` — raw image bytes encoded as base64, with `mediaType` identifying
+ *   the MIME type (e.g. `'image/png'`, `'image/jpeg'`).
+ * - `'url'` — a publicly accessible URL; `data` is the URL string and `mediaType`
+ *   is still populated (sniffed by {@link image-routing.ts} when not supplied by
+ *   the caller).
+ *
+ * @see ADR-072 §LlmTransport — pure wire level (W4d image routing)
+ */
+export interface TransportImageBlock {
+  /** Discriminant — always `'image'`. */
+  readonly type: 'image';
+  readonly source: {
+    /** How the image data is provided. */
+    readonly type: 'base64' | 'url';
+    /**
+     * Base64-encoded image bytes (when `type === 'base64'`) or a URL string
+     * (when `type === 'url'`).
+     */
+    readonly data: string;
+    /** MIME type, e.g. `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
+    readonly mediaType: string;
+  };
+}
+
+/**
+ * A text content block for multimodal messages.
+ */
+export interface TransportTextBlock {
+  /** Discriminant — always `'text'`. */
+  readonly type: 'text';
+  /** Plain text string. */
+  readonly text: string;
+}
+
+/**
+ * A single message in a provider-neutral conversation turn.
+ *
+ * `toolUseId` is required when `role` is `'tool'` — it identifies which
+ * tool call this result resolves, matching {@link NormalizedToolCall.id}.
+ *
+ * `content` supports both the legacy plain-string form and a multimodal block
+ * array. When `content` is a string, the transport treats it as a single text
+ * block. When it is an array, each element is either a {@link TransportTextBlock}
+ * or a {@link TransportImageBlock} — enabling image routing (W4d) without
+ * breaking existing transport consumers that only read the string form.
+ */
+export interface TransportMessage {
+  /** Conversation turn role. */
+  role: 'user' | 'assistant' | 'tool';
+  /**
+   * Message content.
+   *
+   * - Plain `string` — backwards-compatible single-text-block form used by
+   *   all existing transports. Transports that do not support images receive
+   *   this form only.
+   * - `ReadonlyArray<TransportTextBlock | TransportImageBlock>` — multimodal
+   *   block array enabling image routing (ADR-072 W4d). Transports that do not
+   *   support images MUST stringify text blocks and drop image blocks (or throw
+   *   if `imageMode` on the request is `'native'` — see {@link TransportRequest}).
+   */
+  readonly content: string | ReadonlyArray<TransportTextBlock | TransportImageBlock>;
+  /** Tool-result messages: id of the call this resolves. */
+  toolUseId?: string;
+}
+
+/**
+ * A tool definition passed to the provider.
+ *
+ * `inputSchema` is a JSON Schema object describing the tool's input parameters.
+ * The transport layer passes it through verbatim after any provider-specific
+ * adaptation (e.g. Anthropic wraps it in `{ type: "object", ... }`).
+ */
+export interface TransportTool {
+  /** Tool name as it will appear in {@link NormalizedToolCall.name}. */
+  name: string;
+  /** Human-readable description for the model. */
+  description: string;
+  /** JSON Schema for input parameters. */
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * Request parameters passed to {@link LlmTransport.complete} and
+ * {@link LlmTransport.stream}.
+ *
+ * `temperature` is normalized to the 0.0–1.0 range; each transport clamps it
+ * to the provider's supported range before sending.
+ *
+ * `signal` may be used to abort in-flight requests (passed through to the
+ * underlying fetch / SDK call where supported).
+ *
+ * @see ADR-072 §LlmTransport — pure wire level
+ */
+export interface TransportRequest {
+  /** Model identifier — provider-specific (e.g. `'claude-sonnet-4-6'`). */
+  model: string;
+  /** Conversation messages in provider-neutral form. */
+  messages: TransportMessage[];
+  /** Maximum tokens to generate (NOT input budget). */
+  maxTokens: number;
+  /** Optional system prompt (Anthropic top-level `system`) or system message (OpenAI). */
+  system?: string;
+  /** Optional tools the model may call. */
+  tools?: TransportTool[];
+  /** Sampling temperature in 0.0–1.0 range; provider clamps to its own range. */
+  temperature?: number;
+  /** AbortSignal for request cancellation. */
+  signal?: AbortSignal;
+  /**
+   * Prompt-cache breakpoint injection strategy.
+   *
+   * - `'system_and_3'` — inject cache breakpoints after the system prompt and
+   *   after the last 3 user messages (Anthropic extended-caching strategy).
+   * - `'prefix_and_2'` — inject at the shared prefix boundary and after the 2
+   *   most-recent turns (optimised for Gemini cached content).
+   * - `null` — no cache injection (default when not set).
+   *
+   * Transports apply the selected strategy before constructing the SDK request.
+   * Unsupported strategies on a given transport are silently ignored.
+   *
+   * @see ADR-072 §LlmTransport — pure wire level
+   */
+  readonly cacheStrategy?: 'system_and_3' | 'prefix_and_2' | null;
+  /**
+   * Image handling mode for multimodal content blocks in {@link TransportMessage.content}.
+   *
+   * - `'native'` — send image blocks as-is to the provider's multimodal API.
+   *   The transport MUST throw if the provider does not support native images.
+   * - `'text'` — strip all image blocks; only text blocks are sent. Useful for
+   *   text-only providers or when images are redundant.
+   * - `'auto'` — the transport decides based on provider capability (default).
+   *   Falls back to `'text'` for providers that do not support native images.
+   *
+   * Used by the image-routing layer (W4d) to select the per-turn input mode.
+   *
+   * @see ADR-072 §LlmTransport — pure wire level
+   */
+  readonly imageMode?: 'native' | 'text' | 'auto';
+}
+
+/**
+ * Provider transport contract.
+ *
+ * Each concrete transport (Anthropic, OpenAI, Gemini) implements this
+ * interface and maps provider-specific API shapes to/from
+ * {@link NormalizedResponse}. Role-resolver and executor code works
+ * exclusively against this interface so providers are swappable.
+ *
+ * As of Phase 4 (ADR-072) the interface gains two additional members:
+ * - {@link apiMode} — the wire protocol spoken by this transport.
+ * - {@link stream} — streaming completion returning {@link NormalizedDelta} chunks.
+ *
+ * Existing transport implementations MUST add stub implementations of both to
+ * maintain compile parity (W0c). Wave 1 migrations replace stubs with real impls.
+ *
+ * @see ADR-072 §LlmTransport — pure wire level
+ */
+export interface LlmTransport {
+  /**
+   * Provider identifier — matches the `ModelTransport` union so role-resolver
+   * can select the correct transport at runtime.
+   */
+  readonly provider: ModelTransport;
+  /**
+   * Wire protocol this transport speaks. Used by the session and executor layers
+   * to select correct transports for providers that support multiple protocols.
+   *
+   * @see ADR-072 §Type lock-in — `ApiMode` closed 4-value union
+   */
+  readonly apiMode: ApiMode;
+  /**
+   * Execute a single completion call and return a normalized response.
+   *
+   * Implementations MUST:
+   * - Never return raw credentials in the response envelope.
+   * - Preserve the full provider response in {@link NormalizedResponse.raw}.
+   * - Map provider-specific stop reasons to the canonical set where possible.
+   *
+   * @param request - Provider-neutral request parameters.
+   * @param ctx - Contextual metadata (request ID, abort signal, feature flags).
+   * @returns A promise that resolves to a {@link NormalizedResponse}.
+   */
+  complete(request: TransportRequest, ctx?: TransportContext): Promise<NormalizedResponse>;
+  /**
+   * Stream a completion. Each {@link NormalizedDelta} carries incremental text
+   * or reasoning content.
+   *
+   * Implementors MUST run streaming deltas through `StreamingThinkScrubber`
+   * before yielding them — reasoning content goes to `delta.reasoning`;
+   * visible text goes to `delta.text`. The final delta has a non-null
+   * `stopReason` and carries full usage stats in `delta.usage`.
+   *
+   * W0c transports carry a stub that throws until Wave 1 migration lands:
+   * ```ts
+   * throw new Error('STUB: W1 migration will implement stream() for <provider>');
+   * ```
+   *
+   * @param request - Provider-neutral request parameters.
+   * @param ctx - Contextual metadata (request ID, abort signal, feature flags).
+   * @returns An async iterable of normalized delta chunks.
+   * @see ADR-072 §LlmTransport — pure wire level
+   */
+  stream(request: TransportRequest, ctx: TransportContext): AsyncIterable<NormalizedDelta>;
+}

package/src/llm/provider-id.ts

@@ -0,0 +1,63 @@
+/**
+ * Provider identity and API protocol types for the unified LLM provider architecture.
+ *
+ * These types anchor the Phase 4 contract layer (ADR-072). All downstream code
+ * that references a provider by name or by wire-protocol uses these types.
+ *
+ * @module llm/provider-id
+ * @task T9281
+ * @epic T9261 T-LLM-CRED-CENTRALIZATION
+ * @see ADR-072 §Type lock-in
+ */
+
+/**
+ * Canonical wire-level API protocol supported by a provider.
+ *
+ * Closed 4-value union. Providers that speak multiple protocols (e.g. OpenAI
+ * supports both chat_completions and codex_responses) declare separate
+ * ProviderProfiles, one per ApiMode.
+ *
+ * Adding a fifth value is a major breaking change — confirm in ADR-072 before doing so.
+ *
+ * @see ADR-072 §Type lock-in
+ */
+export type ApiMode =
+  | 'chat_completions' // OpenAI, OpenRouter, Groq, DeepSeek, Moonshot, xAI, Gemini-via-OR
+  | 'anthropic_messages' // Native Anthropic SDK — full prompt-cache + thinking
+  | 'codex_responses' // OpenAI Responses API (Codex CLI, xAI-responses)
+  | 'bedrock_converse'; // AWS Bedrock ConversationAPI
+
+/**
+ * Fixed set of builtin provider identifiers shipped with CLEO core.
+ *
+ * Plugin providers registered at runtime may use any non-empty string —
+ * see {@link ProviderId}.
+ *
+ * MIGRATION NOTE: The legacy `ModelTransport` ('anthropic'|'openai'|'gemini'|'moonshot')
+ * is re-typed as `Extract<ProviderId, BuiltinProviderId>` for one release cycle
+ * (deprecated, then removed).
+ */
+export type BuiltinProviderId =
+  | 'anthropic'
+  | 'openai'
+  | 'gemini'
+  | 'moonshot'
+  | 'openrouter'
+  | 'bedrock'
+  | 'deepseek'
+  | 'xai'
+  | 'groq'
+  | 'kimi-code';
+
+/**
+ * Provider identity string.
+ *
+ * Builtin providers use the fixed literals in {@link BuiltinProviderId}.
+ * Plugin providers registered at runtime via `ProviderRegistry` may use any
+ * non-empty string. The open string union allows plugins without forcing
+ * exhaustive switch checks in transport code (match arms should include a
+ * default/unknown branch).
+ *
+ * @see ADR-072 §Type lock-in
+ */
+export type ProviderId = BuiltinProviderId | (string & Record<never, never>);

package/src/llm/provider-profile.ts

@@ -0,0 +1,191 @@
+/**
+ * ProviderProfile interface and plugin contracts for the CLEO provider registry.
+ *
+ * Ported idiomatically from the Hermes provider registry (Python dataclass +
+ * importlib pattern → TypeScript interface + dynamic ESM import). This is the
+ * canonical type lock for Phase 3 of T-LLM-CRED-CENTRALIZATION — all
+ * subsequent Phase 3 tasks depend on this interface shape.
+ *
+ * @task T9262
+ * @epic T9261 (T-LLM-CRED-CENTRALIZATION Phase 3)
+ */
+
+import type { ModelTransport, StoredAuthTypeWire } from '../operations/llm.js';
+import type { TransportMessage, TransportTool } from './normalized-response.js';
+
+/**
+ * Describes a single LLM provider — its auth capabilities, base URL,
+ * default model, and optional live model-discovery hook.
+ *
+ * Builtin providers (anthropic, openai, gemini, moonshot) ship with the
+ * registry. User plugins under `${CLEO_HOME}/plugins/model-providers/` may
+ * register additional profiles or override builtins (last-writer-wins).
+ */
+export interface ProviderProfile {
+  /**
+   * Canonical provider name. For builtin providers this MUST match a
+   * {@link ModelTransport} so the credential resolver can wire the two
+   * systems together. User plugins may use any unique string.
+   */
+  name: ModelTransport | string;
+
+  /** Human-readable display name shown in pickers and diagnostic output. */
+  displayName: string;
+
+  /** Authentication schemes this provider supports. */
+  authTypes: ReadonlyArray<StoredAuthTypeWire>;
+
+  /**
+   * Base URL for the provider's API — no trailing slash.
+   *
+   * @example 'https://api.anthropic.com'
+   */
+  baseUrl: string;
+
+  /**
+   * Recommended default model identifier for this provider.
+   *
+   * @example 'claude-haiku-X-Y' (use the latest haiku from @cleocode/core/llm)
+   */
+  defaultModel: string;
+
+  /**
+   * Alternate names that resolve to this profile. Resolution is
+   * case-insensitive. Alias conflicts with another profile's primary name
+   * cause a `TypeError` at registration time.
+   */
+  aliases?: ReadonlyArray<string>;
+
+  /**
+   * HTTP headers sent with every request to this provider.
+   * Merged into the SDK client's `defaultHeaders`.
+   *
+   * @example { 'anthropic-version': '2023-06-01' }
+   */
+  defaultHeaders?: Readonly<Record<string, string>>;
+
+  /**
+   * Environment variable names that supply credentials for this provider.
+   * Sourced from the `env` field in the models.dev catalog when generated,
+   * or declared by hand-written builtins and plugins. Resolver chains may
+   * check these env vars for an API key before falling back to the
+   * credentials store.
+   *
+   * @example ['ANTHROPIC_API_KEY']
+   */
+  envVars?: ReadonlyArray<string>;
+
+  /**
+   * Optional live model-discovery hook. When present, the registry may
+   * call this to enumerate available model identifiers. Returns `null`
+   * when the provider does not support live model listing or when the
+   * fetch fails — callers MUST fall back to static model lists in that
+   * case.
+   *
+   * @param apiKey - The resolved API key (or OAuth bearer token).
+   * @param signal - Optional abort signal for request cancellation.
+   */
+  fetchModels?: (apiKey: string, signal?: AbortSignal) => Promise<ReadonlyArray<string> | null>;
+
+  /**
+   * Hook: transform messages before they are passed to the SDK.
+   *
+   * Default behavior (when `undefined`): identity — messages are forwarded
+   * unchanged. Providers use this hook for shape conversions such as:
+   * - Gemini: hoisting the system message to `systemInstruction`.
+   * - Anthropic: injecting an assistant-prefill block for structured output.
+   * - OpenAI o-series: merging consecutive same-role messages.
+   *
+   * Port of Hermes `ProviderProfile.prepare_messages` (Hermes §3.1).
+   *
+   * @param messages - The transport-level messages prior to provider conversion.
+   * @param model - The resolved model identifier.
+   * @returns Possibly-modified messages array. Implementations MUST NOT mutate
+   *          the input array; return a new array if changes are needed.
+   */
+  readonly prepareMessages?: (
+    messages: readonly TransportMessage[],
+    model: string,
+  ) => readonly TransportMessage[];
+
+  /**
+   * Hook: contribute provider-specific extra body fields.
+   *
+   * The returned object is merged into the SDK request's `extra_body`
+   * (OpenAI-style) or equivalent provider field. Providers use this for:
+   * - Gemini: `thinkingConfig` for extended reasoning budget.
+   * - OpenRouter: Pareto router plugin parameters.
+   * - Anthropic-via-OpenRouter: fine-grained tool streaming control.
+   *
+   * Port of Hermes `ProviderProfile.build_extra_body`.
+   *
+   * @param model - The resolved model identifier.
+   * @param messages - The transport-level messages at call time.
+   * @param tools - The tool definitions at call time.
+   * @returns Object merged into the provider request's `extra_body` field.
+   */
+  readonly buildExtraBody?: (
+    model: string,
+    messages: readonly TransportMessage[],
+    tools: readonly TransportTool[],
+  ) => Readonly<Record<string, unknown>>;
+
+  /**
+   * Hook: contribute provider-specific top-level API kwargs.
+   *
+   * The returned object is shallow-merged into the SDK call kwargs. Providers
+   * use this for top-level fields that do not fit into `extra_body`:
+   * - xAI Grok: `x-grok-conv-id` conversation pinning header.
+   * - Kimi: `reasoning_effort` top-level reasoning control.
+   * - Moonshot: JSON-schema sanitization applied at the request level.
+   *
+   * Port of Hermes `ProviderProfile.build_api_kwargs_extras`.
+   *
+   * @param model - The resolved model identifier.
+   * @param messages - The transport-level messages at call time.
+   * @param tools - The tool definitions at call time.
+   * @returns Object shallow-merged into the SDK call kwargs.
+   */
+  readonly buildApiKwargsExtras?: (
+    model: string,
+    messages: readonly TransportMessage[],
+    tools: readonly TransportTool[],
+  ) => Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Shape that user plugin modules MUST satisfy.
+ *
+ * A plugin file is any `*.{ts,mjs,js,cjs}` under
+ * `${CLEO_HOME}/plugins/model-providers/`. The registry imports it
+ * dynamically and calls either its default export or named `register`
+ * export with a {@link ProviderPluginApi} instance.
+ *
+ * @example
+ * ```ts
+ * // my-plugin.mjs
+ * export function register(api) {
+ *   api.registerProvider({
+ *     name: 'my-provider',
+ *     displayName: 'My Provider',
+ *     authTypes: ['api_key'],
+ *     baseUrl: 'https://api.myprovider.com',
+ *     defaultModel: 'my-model-v1',
+ *   });
+ * }
+ * ```
+ */
+export interface ProviderPlugin {
+  /** Called by the registry with access to {@link ProviderPluginApi}. */
+  register: (api: ProviderPluginApi) => void;
+}
+
+/**
+ * Minimal surface exposed to plugin modules at load time.
+ * Intentionally narrow — plugins should only register providers,
+ * not reach into registry internals.
+ */
+export interface ProviderPluginApi {
+  /** Register a provider profile. Last-writer-wins on name collision. */
+  registerProvider: (profile: ProviderProfile) => void;
+}

package/src/llm/resolved-credential.ts

@@ -0,0 +1,62 @@
+/**
+ * Fully-resolved credential type for the unified LLM provider architecture.
+ *
+ * This type replaces the partial `CredentialResultWire` at the runtime level.
+ * `CredentialResultWire` is retained solely as a wire diagnostic type for
+ * `cleo llm whoami` CLI output.
+ *
+ * @module llm/resolved-credential
+ * @task T9281
+ * @epic T9261 T-LLM-CRED-CENTRALIZATION
+ * @see ADR-072 §Type lock-in
+ */
+
+import type { ProviderId } from './provider-id.js';
+
+/**
+ * Fully-resolved credential ready for use in a transport constructor.
+ *
+ * The transport consumes this at construction time and MUST NOT store it
+ * beyond initialization. {@link extraHeaders} is merged into SDK
+ * defaultHeaders.
+ *
+ * Replaces the partial `CredentialResultWire` for runtime use.
+ * `CredentialResultWire` is retained as a wire diagnostic type for
+ * `cleo llm whoami` CLI output only.
+ *
+ * @see ADR-072 §Type lock-in
+ */
+export interface ResolvedCredential {
+  /** Provider this credential targets. */
+  readonly provider: ProviderId;
+  /** Human-readable store label (e.g. 'personal', 'work'). */
+  readonly label: string;
+  /**
+   * API key, OAuth bearer token, or empty string for aws_sdk auth.
+   * NEVER log this field. NEVER include in NormalizedResponse.providerData.
+   */
+  readonly token: string;
+  /** How the token is presented to the provider. */
+  readonly authType: 'api_key' | 'oauth' | 'aws_sdk';
+  /**
+   * Unix epoch ms at which the token expires. null = never expires.
+   * LlmSession checks this before each send() and triggers OAuth refresh
+   * when less than 60 seconds remain.
+   */
+  readonly expiresAt: number | null;
+  /**
+   * OAuth refresh token. null for api_key and aws_sdk credentials.
+   * LlmSession holds this; the transport never sees it.
+   */
+  readonly refreshToken: string | null;
+  /**
+   * Extra HTTP headers merged into every SDK request from this credential.
+   * Typically carries 'Authorization: Bearer ...' for oauth authType,
+   * and 'anthropic-beta: ...' when needed.
+   */
+  readonly extraHeaders: Readonly<Record<string, string>>;
+  /** Base URL override (proxy, on-prem deployment). null = use provider default. */
+  readonly baseUrl: string | null;
+  /** AWS profile name for Bedrock. null for all other providers. */
+  readonly awsProfile: string | null;
+}

package/src/operations/llm.ts

@@ -9,8 +9,21 @@
  * @epic T1386
  */
 
-/** Supported provider transport names. */
-export type ModelTransport = 'anthropic' | 'openai' | 'gemini' | 'moonshot';
+import type { BuiltinProviderId, ProviderId } from '../llm/provider-id.js';
+
+/**
+ * @deprecated since Phase 4 (ADR-072). Use {@link ProviderId} from
+ * `@cleocode/contracts/llm/provider-id.js` for new code. This alias remains
+ * for one release cycle to ease migration of legacy callers, then is removed.
+ *
+ * The alias resolves to {@link BuiltinProviderId} — a superset of the previous
+ * closed literal union (`'anthropic' | 'openai' | 'gemini' | 'moonshot'`).
+ * All existing consumers that pattern-match on the previous four values continue
+ * to compile without changes.
+ *
+ * @see ADR-072 §Type lock-in — ModelTransport deprecation cycle
+ */
+export type ModelTransport = Extract<ProviderId, BuiltinProviderId>;
 
 /** Cache policy mode for prompt prefix caching. */
 export type PromptCachePolicyMode = 'gemini_cached_content';
@@ -550,3 +563,8 @@ export interface LlmWhoamiResult {
   /** One entry per role resolved (filtered by `params.role` when set). */
   entries: LlmWhoamiEntry[];
 }
+
+// ProviderProfile interface lives in ./llm/provider-profile.ts (T9262).
+// The generated catalog (packages/core/src/llm/generated/provider-profiles.ts)
+// imports the canonical type from the contracts package and emits each
+// generated entry as a plain ProviderProfile literal.