@cleocode/contracts 2026.5.62 → 2026.5.63

package/src/config.ts

@@ -9,6 +9,8 @@
  * @task T5710
  */
 
+import type { ModelTransport } from './operations/llm.js';
+
 /** Output format options. */
 export type OutputFormat = 'json' | 'text' | 'jsonl' | 'markdown' | 'table';
 
@@ -282,7 +284,11 @@ export interface BrainTieringConfig {
 export interface BrainLlmExtractionConfig {
   /** Enable LLM-driven extraction gate (default: true). */
   enabled: boolean;
-  /** Anthropic model to use for extraction (default: 'claude-haiku-4-5-20251001'). */
+  /**
+   * Anthropic model to use for extraction. Default lives in
+   * `@cleocode/core/llm/role-resolver` (`IMPLICIT_FALLBACK_MODEL`) so the
+   * literal stays in a single source location (T9255 grep guard).
+   */
   model: string;
   /** Minimum importance score (0.0–1.0) below which extractions are dropped (default: 0.6). */
   minImportance: number;
@@ -325,10 +331,11 @@ export interface BrainConfig {
    * LLM-driven extraction gate settings.
    * When enabled and ANTHROPIC_API_KEY is present, session transcripts are
    * processed by an LLM to extract typed structured memories instead of the
-   * legacy keyword regex. Defaults are enabled: true and model is the cheap
-   * Haiku class so extraction cost stays bounded.
+   * legacy keyword regex. Defaults are enabled: true and model defaults to
+   * the centralised implicit fallback (cheap Haiku class) defined in
+   * `@cleocode/core/llm/role-resolver` so extraction cost stays bounded.
    *
-   * @defaultValue { enabled: true, model: 'claude-haiku-4-5-20251001', minImportance: 0.6, maxExtractions: 7, maxTranscriptChars: 60000 }
+   * @defaultValue { enabled: true, model: IMPLICIT_FALLBACK_MODEL, minImportance: 0.6, maxExtractions: 7, maxTranscriptChars: 60000 }
    */
   llmExtraction?: BrainLlmExtractionConfig;
 }
@@ -381,7 +388,7 @@ export interface DaemonLLMConfig {
    * LLM provider transport used by daemon loops.
    * @defaultValue 'anthropic'
    */
-  provider: 'anthropic' | 'openai' | 'gemini' | 'moonshot';
+  provider: ModelTransport;
   /**
    * Full model identifier for the selected provider.
    * @defaultValue 'claude-sonnet-4-6'
@@ -389,14 +396,85 @@ export interface DaemonLLMConfig {
   model: string;
 }
 
+/**
+ * Canonical model transport identifier — re-export of {@link ModelTransport}
+ * from `operations/llm.ts` so config-layer types stay in lock-step with the
+ * operations layer with no risk of drift.
+ *
+ * Previously declared as a separate string-literal union; collapsed in the
+ * T-LLM-CRED Phase 2 DRY/SOLID review (P1-2). Adding a new transport now
+ * requires editing only `operations/llm.ts`.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 — DRY review P1-2
+ */
+export type LlmTransport = ModelTransport;
+
+/**
+ * Logical LLM role name used by role-aware resolvers (BRAIN, sentient, etc.).
+ *
+ * Each role can pin its own provider + model + credential label, with
+ * resolution falling back to `LlmConfig.default` and finally to the legacy
+ * `LlmConfig.daemon` block.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+ */
+export type RoleName = 'extraction' | 'consolidation' | 'derivation' | 'hygiene' | 'judgement';
+
+/**
+ * Canonical default LLM target for unscoped (non-role) calls.
+ *
+ * Replaces the role previously played by `LlmConfig.daemon`. The `daemon`
+ * field stays as a deprecated alias for one release cycle to give downstream
+ * consumers time to migrate.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+ */
+export interface LlmDefaultConfig {
+  /** LLM provider transport for the default model. */
+  provider: LlmTransport;
+  /** Full model identifier for the selected provider. */
+  model: string;
+}
+
+/**
+ * Per-role LLM configuration entry.
+ *
+ * Each role may optionally pin to a specific credential label (matching a
+ * `CredentialResult.label`) so that, e.g., the `extraction` role can use a
+ * different Anthropic API key than `judgement` without changing the global
+ * default.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+ */
+export interface LlmRoleConfig {
+  /** LLM provider transport for this role. */
+  provider: LlmTransport;
+  /** Full model identifier for the selected provider. */
+  model: string;
+  /**
+   * Optional credential label to pin this role to a specific credential
+   * entry resolved by `resolveCredentials()`. When omitted, the role
+   * inherits the default credential resolution order.
+   */
+  credentialLabel?: string;
+}
+
 /**
  * Top-level LLM configuration block inside CleoConfig.
  *
  * Stored at `llm` in config.json.
+ *
+ * Resolution order for role-scoped calls:
+ *   `roles[role]` → `default` → `daemon` (legacy).
  */
 export interface LlmConfig {
   /**
    * Daemon LLM settings (provider + model for background loops).
+   *
+   * @deprecated Use `default` instead. Retained as a fallback alias for
+   * one release cycle (T-LLM-CRED-CENTRALIZATION Phase 2 · T9256). New
+   * code must read `default` first and only fall through to `daemon` when
+   * `default` is absent.
    * @defaultValue { provider: 'anthropic', model: 'claude-sonnet-4-6' }
    */
   daemon?: DaemonLLMConfig;
@@ -405,6 +483,23 @@ export interface LlmConfig {
    * Keys are provider names: 'anthropic' | 'openai' | 'gemini' | 'moonshot'.
    */
   providers?: Record<string, LlmProviderEntry>;
+  /**
+   * Canonical default LLM for unscoped calls. Replaces the role previously
+   * played by `daemon`, which stays as a deprecated alias for one release
+   * cycle.
+   *
+   * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+   */
+  default?: LlmDefaultConfig;
+  /**
+   * Per-role LLM overrides. Each role optionally pins to a credential
+   * label.
+   *
+   * Resolution order: `roles[role]` → `default` → `daemon` (legacy).
+   *
+   * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+   */
+  roles?: Partial<Record<RoleName, LlmRoleConfig>>;
 }
 
 /** SignalDock transport mode. */

package/src/index.ts

@@ -219,7 +219,10 @@ export type {
   LifecycleConfig,
   LifecycleEnforcementMode,
   LlmConfig,
+  LlmDefaultConfig,
   LlmProviderEntry,
+  LlmRoleConfig,
+  LlmTransport,
   LoggingConfig,
   LogLevel,
   MemoryBridgeMode,
@@ -227,6 +230,7 @@ export type {
   OutputFormat,
   ProviderConfig,
   ResolvedValue,
+  RoleName,
   SessionConfig,
   SessionSummaryInput,
   SharingConfig,
@@ -614,6 +618,35 @@ export type {
   LifecycleStatusResult,
   StageRecord,
 } from './operations/lifecycle.js';
+// === LLM Credential + Role-Resolver Wire Types (T-LLM-CRED Phase 1/2 — T9255) ===
+export type {
+  AuthTypeWire,
+  CredentialResultWire,
+  CredentialSourceWire,
+  CredentialsStoreStrategyWire,
+  // `cleo llm` CLI / dispatch operation contracts (T9258)
+  LlmAddParams,
+  LlmAddResult,
+  LlmListParams,
+  LlmListResult,
+  LlmProfileParams,
+  LlmProfileResult,
+  LlmRemoveParams,
+  LlmRemoveResult,
+  LlmStoredCredentialView,
+  LlmTestParams,
+  LlmTestResult,
+  LlmUseParams,
+  LlmUseResult,
+  LlmWhoamiEntry,
+  LlmWhoamiParams,
+  LlmWhoamiResult,
+  ModelTransport,
+  ResolutionSource,
+  ResolvedLLM,
+  ResolveLLMForRoleOptions,
+  StoredAuthTypeWire,
+} from './operations/llm.js';
 // Multi-pass retrieval bundle types (PSYCHE Wave 4 · T1090)
 export type {
   PassMask,

package/src/operations/llm.ts

@@ -56,6 +56,15 @@ export interface ModelConfig {
   cachePolicy?: PromptCachePolicy | null;
   /** Fallback model config used on final retry attempt. */
   fallback?: Omit<ModelConfig, 'fallback'> | null;
+  /**
+   * Extra HTTP headers to attach to the provider client (merged into the SDK's
+   * `defaultHeaders`). Populated from `authHeaders(cred)` when a credential is
+   * resolved with `authType: 'oauth'` so the provider client uses the
+   * `Authorization: Bearer …` scheme instead of `x-api-key`.
+   *
+   * @task T-LLM-CRED-CENTRALIZATION Phase 1
+   */
+  extraHeaders?: Record<string, string> | null;
 }
 
 /** Parameters for a single LLM call. */
@@ -113,3 +122,431 @@ export interface LLMCallResult<T = string> {
   thinkingBlocks: Array<Record<string, unknown>>;
   reasoningDetails: Array<Record<string, unknown>>;
 }
+
+// ============================================================================
+// Credential resolution wire types (T-LLM-CRED-CENTRALIZATION Phase 1/2)
+//
+// These mirror the runtime types declared in `@cleocode/core/llm/credentials.ts`
+// but live here so packages outside `core` (CLI, harness, studio) can speak
+// the same wire vocabulary without taking a dependency on core internals.
+// The runtime module re-exports compatible aliases so existing imports keep
+// working.
+// ============================================================================
+
+/**
+ * Which credential-resolution tier produced a {@link CredentialResultWire}.
+ *
+ * Mirrors `CredentialSource` in `@cleocode/core/llm/credentials.ts`. The set is
+ * append-only; new tiers (e.g. `aws-sdk`, `gcp-sdk` in Phase 3) extend this
+ * union.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 1
+ * @task T9255
+ */
+export type CredentialSourceWire =
+  | 'explicit'
+  | 'env'
+  | 'cred-file'
+  | 'claude-creds'
+  | 'global-config'
+  | 'project-config';
+
+/**
+ * Authentication scheme used when sending the credential to the provider.
+ *
+ * - `api_key` — provider-issued long-lived key sent as `x-api-key` (Anthropic)
+ *   or `Authorization: Bearer …` (OpenAI, Gemini, Moonshot).
+ * - `oauth` — short-lived OAuth bearer token sent as `Authorization: Bearer …`
+ *   with the matching beta header.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 1
+ * @task T9255
+ */
+export type AuthTypeWire = 'api_key' | 'oauth';
+
+/**
+ * Resolved credential as returned by `resolveCredentials()` /
+ * `resolveLLMForRole()`. Mirrors `CredentialResult` in core. Compatible by
+ * structural typing.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 1
+ * @task T9255
+ */
+export interface CredentialResultWire {
+  /** Provider transport this credential is for. */
+  provider: ModelTransport;
+  /** API key or OAuth bearer token. `null` only when no credential was found. */
+  apiKey: string | null;
+  /** Which tier produced this credential. `undefined` when `apiKey` is `null`. */
+  source: CredentialSourceWire | undefined;
+  /** Scheme used to present the credential to the provider. */
+  authType: AuthTypeWire;
+}
+
+// ============================================================================
+// Role-based LLM resolution wire types (T9255 — Phase 2 T-llm-1)
+// ============================================================================
+
+/**
+ * Which configuration tier produced a {@link ResolvedLLM}.
+ *
+ * Resolution chain order:
+ *   1. `role`               — `config.llm.roles[role]` (explicit override)
+ *   2. `default`            — `config.llm.default` (canonical default)
+ *   3. `daemon-legacy`      — `config.llm.daemon` (deprecated alias)
+ *   4. `implicit-fallback`  — hard-coded fallback inside the resolver
+ *
+ * Useful for `cleo llm whoami` diagnostics and for migration tooling that
+ * needs to identify call-sites still on the legacy `daemon` block.
+ *
+ * @task T9255
+ */
+export type ResolutionSource = 'role' | 'default' | 'daemon-legacy' | 'implicit-fallback';
+
+/**
+ * Result envelope returned by `resolveLLMForRole(role)`.
+ *
+ * Carries the fully-wired SDK client plus the {@link CredentialResultWire}
+ * so raw-fetch callers (sleep-consolidation, observer-reflector, hygiene-scan)
+ * can call `authHeaders(credential)` themselves when bypassing the SDK
+ * client (e.g. to call the Anthropic Messages REST API directly).
+ *
+ * `client` is `null` only when `credential.apiKey` is also `null` — in which
+ * case the caller MUST fall back to its graceful-degradation path
+ * (`return null` / skip / log warn).
+ *
+ * `client` is typed as `unknown` here because the concrete SDK classes
+ * (Anthropic, OpenAI, GoogleGenerativeAI) are not referenced from contracts
+ * to preserve its zero-dependency footprint. Consumers MUST narrow via the
+ * typed helpers in `@cleocode/core/llm/role-resolver` (e.g.
+ * `resolveAnthropicForRole`) rather than casting with `as unknown as X`.
+ *
+ * @task T9255
+ */
+export interface ResolvedLLM {
+  /** LLM provider transport that was resolved. */
+  provider: ModelTransport;
+  /** Full model identifier. */
+  model: string;
+  /**
+   * Fully-wired SDK client constructed via `clientForModelConfig`. `null`
+   * when no credential is available. Typed as `unknown` — consumers MUST
+   * narrow via a provider-specific helper (e.g. `resolveAnthropicForRole`
+   * in `@cleocode/core/llm/role-resolver`), NEVER via an `as unknown as X`
+   * cast.
+   */
+  client: unknown;
+  /**
+   * Resolved credential. `null` when no tier produced a token. Callers
+   * MUST handle this case.
+   */
+  credential: CredentialResultWire | null;
+  /** Which config path produced this resolution. */
+  source: ResolutionSource;
+  /** When `roles[role].credentialLabel` was set, the label that was used. */
+  credentialLabel?: string;
+}
+
+/**
+ * Options accepted by `resolveLLMForRole()`.
+ *
+ * @task T9255
+ */
+export interface ResolveLLMForRoleOptions {
+  /**
+   * Absolute path to the project root. Forwarded to `loadConfig()` and to
+   * `resolveCredentials({ projectRoot })` for tier-5 project-config lookup.
+   * Defaults to `process.cwd()`.
+   */
+  projectRoot?: string;
+}
+
+// ============================================================================
+// `cleo llm` CLI / dispatch operation contracts (T9258 — Phase 2 T-llm-4)
+//
+// Wire types backing the `cleo llm` CLI subcommands and the `llm` dispatch
+// domain. Provider-redacted views of `StoredCredential` (defined in
+// `@cleocode/core/llm/credentials-store`) plus the dispatch param/result
+// shapes for add / list / remove / use / profile / test / whoami.
+//
+// Tokens are NEVER returned in raw form by these envelopes — `tokenPreview`
+// surfaces only the last 4 characters so the wire vocabulary is safe for
+// JSON output, logs, and remote dispatch consumers.
+// ============================================================================
+
+/**
+ * Storage-level authentication scheme as persisted in the credentials store.
+ *
+ * Wider than the wire-level {@link AuthTypeWire}: includes `'aws_sdk'` for
+ * Bedrock / Vertex entries where the AWS SDK supplies the credential
+ * out-of-band. The runtime resolver narrows `'aws_sdk' → 'api_key'` for
+ * wire-level use until Phase 3 widens {@link AuthTypeWire}.
+ *
+ * Mirrors `StoredAuthType` in `@cleocode/core/llm/credentials-store`.
+ *
+ * @task T9258
+ */
+export type StoredAuthTypeWire = 'api_key' | 'oauth' | 'aws_sdk';
+
+/**
+ * Strategy used by the credentials-store picker.
+ *
+ * Mirrors `CredentialsStoreStrategy` in
+ * `@cleocode/core/llm/credentials-store`. Held here so callers outside
+ * `core` can render UI without taking a dependency on the storage module.
+ *
+ * @task T9258
+ */
+export type CredentialsStoreStrategyWire = 'priorityWithFallback' | 'roundRobin' | 'priorityOnly';
+
+/**
+ * Token-redacted view of a single stored credential.
+ *
+ * `tokenPreview` is the last 4 characters of `accessToken` prefixed by
+ * `'…'` (e.g. `'…aB7q'`). The full token is NEVER returned by any
+ * `cleo llm` operation — callers that need the live token must resolve it
+ * through `resolveLLMForRole()`.
+ *
+ * @task T9258
+ */
+export interface LlmStoredCredentialView {
+  /** LLM transport this credential is for. */
+  provider: ModelTransport;
+  /** Human-readable identifier, unique within `provider`. */
+  label: string;
+  /** Storage-level auth scheme. */
+  authType: StoredAuthTypeWire;
+  /** Redacted token preview — last 4 chars, prefixed by `'…'`. */
+  tokenPreview: string;
+  /** Whether the entry carried a non-empty refresh token. */
+  hasRefreshToken: boolean;
+  /** Unix epoch ms; `null` means "never expires". */
+  expiresAt: number | null;
+  /** Lower wins. */
+  priority: number;
+  /** Free-form provenance label (`claude-code`, `cli-input`, etc.). */
+  source: string | undefined;
+  /** Optional override for provider base URL. */
+  baseUrl: string | null;
+  /** When `true`, the picker skips this entry. */
+  disabled: boolean;
+}
+
+/**
+ * Parameters for `llm.add` (mutate).
+ *
+ * Mirrors the `cleo llm add <provider> --api-key <k>` CLI surface. When
+ * `authType` is omitted, the dispatcher auto-detects from the token
+ * prefix: tokens beginning with `sk-ant-oat-` are stored as `'oauth'`,
+ * everything else as `'api_key'`.
+ *
+ * @task T9258
+ */
+export interface LlmAddParams {
+  /** Target provider transport. */
+  provider: ModelTransport;
+  /** API key or OAuth bearer token to persist. */
+  apiKey: string;
+  /** Human-readable label, unique within `provider`. Defaults to `'default'`. */
+  label?: string;
+  /** Optional override for the provider base URL. */
+  baseUrl?: string;
+  /** Optional explicit auth type override (skips prefix auto-detect). */
+  authType?: StoredAuthTypeWire;
+  /** Optional priority override (lower wins). */
+  priority?: number;
+}
+
+/**
+ * Result envelope for `llm.add`.
+ *
+ * @task T9258
+ */
+export interface LlmAddResult {
+  /** Token-redacted view of the newly stored entry. */
+  credential: LlmStoredCredentialView;
+  /** Detected auth type (`'oauth'` for `sk-ant-oat-*`, else `'api_key'`). */
+  detectedAuthType: StoredAuthTypeWire;
+}
+
+/**
+ * Parameters for `llm.list` (query).
+ *
+ * @task T9258
+ */
+export interface LlmListParams {
+  /** Optional provider filter — when set, only entries for that provider. */
+  provider?: ModelTransport;
+}
+
+/**
+ * Result envelope for `llm.list`.
+ *
+ * @task T9258
+ */
+export interface LlmListResult {
+  /** Token-redacted credentials, in store order (priority asc). */
+  credentials: LlmStoredCredentialView[];
+}
+
+/**
+ * Parameters for `llm.remove` (mutate).
+ *
+ * @task T9258
+ */
+export interface LlmRemoveParams {
+  /** Target provider transport. */
+  provider: ModelTransport;
+  /** Label of the credential to remove. */
+  label: string;
+}
+
+/**
+ * Result envelope for `llm.remove`.
+ *
+ * @task T9258
+ */
+export interface LlmRemoveResult {
+  /** `true` when a matching entry was deleted. */
+  removed: boolean;
+  /** Echo of the targeted `(provider, label)` pair. */
+  provider: ModelTransport;
+  /** Echo of the targeted label. */
+  label: string;
+}
+
+/**
+ * Parameters for `llm.use` (mutate) — set `llm.default.{provider,model}`.
+ *
+ * @task T9258
+ */
+export interface LlmUseParams {
+  /** Provider transport to mark as the default. */
+  provider: ModelTransport;
+  /** Optional default model identifier. When omitted, `default.model` is left untouched. */
+  model?: string;
+}
+
+/**
+ * Result envelope for `llm.use`.
+ *
+ * @task T9258
+ */
+export interface LlmUseResult {
+  /** Provider written to `llm.default.provider`. */
+  provider: ModelTransport;
+  /** Model written to `llm.default.model` — `null` when not provided. */
+  model: string | null;
+  /** Config scope the write landed in (`'global'` for `cleo llm use`). */
+  scope: 'project' | 'global';
+}
+
+/**
+ * Parameters for `llm.profile` (mutate) — set `llm.roles[role]`.
+ *
+ * @task T9258
+ */
+export interface LlmProfileParams {
+  /** Logical role name. */
+  role: string;
+  /** Provider transport for this role. */
+  provider: ModelTransport;
+  /** Optional model identifier for this role. */
+  model?: string;
+  /** Optional credential label to pin this role to a specific store entry. */
+  credentialLabel?: string;
+}
+
+/**
+ * Result envelope for `llm.profile`.
+ *
+ * @task T9258
+ */
+export interface LlmProfileResult {
+  /** Role name written to `llm.roles[role]`. */
+  role: string;
+  /** Provider written for the role. */
+  provider: ModelTransport;
+  /** Model written for the role (or `null` when not supplied). */
+  model: string | null;
+  /** Credential label written for the role (or `null` when not supplied). */
+  credentialLabel: string | null;
+  /** Config scope the write landed in. */
+  scope: 'project' | 'global';
+}
+
+/**
+ * Parameters for `llm.test` (query).
+ *
+ * @task T9258
+ */
+export interface LlmTestParams {
+  /** Provider transport to test. */
+  provider: ModelTransport;
+  /** Optional credential label to pin the test to a specific store entry. */
+  label?: string;
+  /** Optional model override. Defaults to the provider's implicit fallback. */
+  model?: string;
+}
+
+/**
+ * Result envelope for `llm.test`. Tokens are NEVER included.
+ *
+ * @task T9258
+ */
+export interface LlmTestResult {
+  /** Provider transport that was probed. */
+  provider: ModelTransport;
+  /** Model identifier used for the probe. */
+  model: string;
+  /** End-to-end round-trip latency in ms. */
+  latencyMs: number;
+  /** Provider response identifier (e.g. Anthropic `msg_…`). `null` when unavailable. */
+  providerResponseId: string | null;
+  /** Redacted credential preview (last 4 chars) — confirms which entry was used. */
+  credentialPreview: string;
+  /** Resolution tier that produced the credential (`env`, `cred-file`, etc.). */
+  credentialSource: CredentialSourceWire;
+}
+
+/**
+ * Single `whoami` row — one entry per `RoleName`.
+ *
+ * @task T9258
+ */
+export interface LlmWhoamiEntry {
+  /** Role name (`'extraction' | 'consolidation' | ...`). */
+  role: string;
+  /** Provider that would be picked for this role. */
+  provider: ModelTransport;
+  /** Model that would be used. */
+  model: string;
+  /** Which config tier produced the resolution. */
+  source: ResolutionSource;
+  /** Credential label, when the role pinned a specific store entry. */
+  credentialLabel: string | undefined;
+  /** Resolution tier of the eventual credential, when one was reachable. */
+  credentialSource: CredentialSourceWire | undefined;
+  /** Whether a usable credential exists for this role. */
+  hasCredential: boolean;
+}
+
+/**
+ * Parameters for `llm.whoami` (query). Reserved for future filters.
+ *
+ * @task T9258
+ */
+export interface LlmWhoamiParams {
+  /** Optional role filter — when set, only that role is resolved. */
+  role?: string;
+}
+
+/**
+ * Result envelope for `llm.whoami`.
+ *
+ * @task T9258
+ */
+export interface LlmWhoamiResult {
+  /** One entry per role resolved (filtered by `params.role` when set). */
+  entries: LlmWhoamiEntry[];
+}