@cleocode/contracts 2026.5.66 → 2026.5.67

package/src/llm/normalized-response.ts

@@ -11,10 +11,14 @@
  *
  * @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.
@@ -99,17 +103,71 @@ export interface NormalizedResponse {
   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 as plain text. */
-  content: string;
+  /**
+   * 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;
 }
@@ -131,13 +189,16 @@ export interface TransportTool {
 }
 
 /**
- * Request parameters passed to {@link LlmTransport.complete}.
+ * 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'`). */
@@ -154,6 +215,36 @@ export interface TransportRequest {
   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';
 }
 
 /**
@@ -163,6 +254,15 @@ export interface TransportRequest {
  * 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 {
   /**
@@ -170,6 +270,13 @@ export interface LlmTransport {
    * 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.
    *
@@ -179,7 +286,28 @@ export interface LlmTransport {
    * - 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): Promise<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

@@ -11,6 +11,7 @@
  */
 
 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,
@@ -85,6 +86,71 @@ export interface ProviderProfile {
    * @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>>;
 }
 
 /**

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';