@cleocode/contracts 2026.5.65 → 2026.5.67

package/dist/llm/normalized-response.d.ts

@@ -0,0 +1,304 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=normalized-response.d.ts.map

package/dist/llm/normalized-response.d.ts.map

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

package/dist/llm/normalized-response.js

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=normalized-response.js.map

package/dist/llm/normalized-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalized-response.js","sourceRoot":"","sources":["../../src/llm/normalized-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/llm/provider-id.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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' | 'anthropic_messages' | 'codex_responses' | 'bedrock_converse';
+/**
+ * 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>);
+//# sourceMappingURL=provider-id.d.ts.map

package/dist/llm/provider-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-id.d.ts","sourceRoot":"","sources":["../../src/llm/provider-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GACf,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,YAAY,GACZ,SAAS,GACT,UAAU,GACV,KAAK,GACL,MAAM,GACN,WAAW,CAAC;AAEhB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC"}

package/dist/llm/provider-id.js

@@ -0,0 +1,13 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=provider-id.js.map

package/dist/llm/provider-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-id.js","sourceRoot":"","sources":["../../src/llm/provider-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/llm/provider-profile.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=provider-profile.d.ts.map

package/dist/llm/provider-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-profile.d.ts","sourceRoot":"","sources":["../../src/llm/provider-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC;IAE9B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IAEpB,qDAAqD;IACrD,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAE7C;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAElD;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEhC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAE9F;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,KAAK,EAAE,MAAM,KACV,SAAS,gBAAgB,EAAE,CAAC;IAEjC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CACxB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,KAAK,EAAE,SAAS,aAAa,EAAE,KAC5B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEvC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,KAAK,EAAE,SAAS,aAAa,EAAE,KAC5B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,gBAAgB,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;CACtD"}

package/dist/llm/provider-profile.js

@@ -0,0 +1,13 @@
+/**
+ * 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)
+ */
+export {};
+//# sourceMappingURL=provider-profile.js.map

package/dist/llm/provider-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-profile.js","sourceRoot":"","sources":["../../src/llm/provider-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/llm/resolved-credential.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=resolved-credential.d.ts.map

package/dist/llm/resolved-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolved-credential.d.ts","sourceRoot":"","sources":["../../src/llm/resolved-credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC"}