@cleocode/contracts 2026.5.68 → 2026.5.69

package/src/index.ts

@@ -210,7 +210,6 @@ export type {
   ClaudeSpawnMode,
   CleoConfig,
   ConfigSource,
-  DaemonLLMConfig,
   DateFormat,
   DecisionsConfig,
   DepsRequiredAt,
@@ -221,8 +220,8 @@ export type {
   LlmConfig,
   LlmDefaultConfig,
   LlmProviderEntry,
+  LlmProviderTransport,
   LlmRoleConfig,
-  LlmTransport,
   LoggingConfig,
   LogLevel,
   MemoryBridgeMode,
@@ -239,6 +238,12 @@ export type {
   SignalDockMode,
 } from './config.js';
 export type { AdapterContextMonitorProvider } from './context-monitor.js';
+// === Claude Code credential parsing (T9307 — pure helper, no core imports) ===
+export type {
+  ClaudeCodeOAuthBlock,
+  ParsedClaudeCodeCredential,
+} from './credentials.js';
+export { parseClaudeCodeCredentials } from './credentials.js';
 // === DataAccessor Interface ===
 export type {
   ArchiveFields,
@@ -431,7 +436,6 @@ export type { ClassifiedError, FailoverReason } from './llm/failover-reason.js';
 // === Phase 4 Unified Architecture (T9281 / ADR-072) — Session + Executor interfaces ===
 export type {
   AggregatedUsage,
-  ContextEngine,
   ExecutionEvent,
   ExecutionRequest,
   ExecutorFactoryOptions,
@@ -447,11 +451,11 @@ export type {
   TransportContext,
 } from './llm/interfaces.js';
 // === Normalized LLM Transport Types (T9263 — Phase 3 T-LLM-CRED) ===
-// Note: LlmTransport (the interface) is intentionally NOT re-exported at the
-// top level here because `config.ts` already exports `LlmTransport` as a type
-// alias for `ModelTransport`. Consumers that need the transport interface
-// should import the LlmTransport interface from the llm/normalized-response.js
-// subpath rather than the package root.
+// Note: LlmTransport (the wire-level interface from normalized-response.ts) is
+// intentionally NOT re-exported at the top level here. The config-layer alias
+// was renamed LlmProviderTransport (T9308) to eliminate the name collision.
+// Consumers that need the transport interface should import LlmTransport from
+// the llm/normalized-response.js subpath rather than the package root.
 export type {
   NormalizedResponse,
   NormalizedToolCall,
@@ -460,6 +464,11 @@ export type {
   TransportRequest,
   TransportTool,
 } from './llm/normalized-response.js';
+// === OAuth types — SSoT shared between core and cleo (T9302) ===
+export type { OAuthMode, OAuthTokens, PkceFlowConfig, ProviderOAuthConfig } from './llm/oauth.js';
+// === Phase 4 Plugin LLM facade types (T9305) ===
+export type { PluginLlmComplete, PluginLlmContext } from './llm/plugin-llm.js';
+export { PluginLlmError, PluginModelGateError } from './llm/plugin-llm.js';
 // === Phase 4 Unified Architecture (T9281 / ADR-072) — Provider identity ===
 export type { ApiMode, BuiltinProviderId, ProviderId } from './llm/provider-id.js';
 // === Provider Profile + Plugin Contracts (T9262 — Phase 3 T-LLM-CRED) ===
@@ -470,6 +479,8 @@ export type {
 } from './llm/provider-profile.js';
 // === Phase 4 Unified Architecture (T9281 / ADR-072) — Resolved credential ===
 export type { ResolvedCredential } from './llm/resolved-credential.js';
+// === ContextEngine contract (canonical home — T9304) ===
+export type { CompressedContext, ContextEngine } from './memory/context-engine.js';
 export type {
   BridgeDecision,
   BridgeLearning,
@@ -675,8 +686,11 @@ export type {
   LlmListResult,
   LlmProfileParams,
   LlmProfileResult,
+  LlmProviderSourceWire,
+  LlmProviderStatusEntry,
   LlmRemoveParams,
   LlmRemoveResult,
+  LlmStatusResult,
   LlmStoredCredentialView,
   LlmTestParams,
   LlmTestResult,

package/src/llm/failover-reason.ts

@@ -1,7 +1,7 @@
 /**
  * Structured taxonomy of LLM failure modes — mirrors Hermes' FailoverReason enum.
  *
- * Consumers (CredentialPool, auxiliary-router, CLI error envelopes) use this
+ * Consumers (CredentialPool, ConcreteSession, CLI error envelopes) use this
  * to drive deterministic recovery actions instead of ad-hoc status-code
  * inspection.
  *

package/src/llm/interfaces.ts

@@ -32,6 +32,12 @@ import type {
 } from './normalized-response.js';
 import type { ProviderId } from './provider-id.js';
 
+// Re-export canonical ContextEngine types from their new home in memory/.
+// The definition was moved to packages/contracts/src/memory/context-engine.ts
+// (T9304) so that the memory package can import it without a circular dep on
+// the llm/ subtree. This re-export preserves back-compat for all existing
+// consumers that import ContextEngine from llm/interfaces.js.
+export type { CompressedContext, ContextEngine } from '../memory/context-engine.js';
 // Re-export LlmTransport so consumers of this module can reference it without
 // an additional import from normalized-response.js.
 export type { LlmTransport };
@@ -391,51 +397,11 @@ export interface ExecutionRequest {
 }
 
 // ---------------------------------------------------------------------------
-// Context engine
+// Context engine (canonical definition: packages/contracts/src/memory/context-engine.ts)
 // ---------------------------------------------------------------------------
-
-/**
- * Optional context-compression engine supplied to {@link LlmExecutor}.
- *
- * When present, the executor calls {@link shouldCompress} after each model
- * turn. If it returns `true`, the executor calls {@link compress} to reduce
- * the session history before the next iteration, then emits a
- * `context_compressed` event.
- *
- * When absent (undefined), the executor skips all compression checks silently.
- *
- * @see ADR-072 §"LlmExecutor — agent-loop level"
- */
-export interface ContextEngine {
-  /**
-   * Returns `true` when the current history warrants compression.
-   *
-   * @param history - Current read-only conversation history snapshot.
-   * @returns Whether compression should be applied before the next model turn.
-   */
-  shouldCompress(history: readonly TransportMessage[]): boolean;
-  /**
-   * Compresses the session history in-place (or returns a compressed copy).
-   *
-   * The executor replaces the session history with the returned messages after
-   * calling this method. It also emits a `context_compressed` event carrying
-   * the token counts before and after.
-   *
-   * @param history - Current read-only conversation history snapshot.
-   * @returns The compressed message array.
-   */
-  compress(history: readonly TransportMessage[]): Promise<TransportMessage[]>;
-  /**
-   * Estimate token count for a history snapshot.
-   *
-   * Used by the executor to populate {@link ExecutionEvent} `tokensBefore` /
-   * `tokensAfter` fields. May be an approximation (e.g. character / 4).
-   *
-   * @param history - Conversation history snapshot to measure.
-   * @returns Estimated token count.
-   */
-  estimateTokens(history: readonly TransportMessage[]): number;
-}
+// ContextEngine and CompressedContext are re-exported above from their new
+// canonical location. This section is intentionally empty — see the re-export
+// near the top of this file.
 
 // ---------------------------------------------------------------------------
 // Executor interface

package/src/llm/oauth.ts

@@ -0,0 +1,144 @@
+/**
+ * Shared OAuth type contracts for the CLEO LLM credential layer.
+ *
+ * Defines the SSoT types shared between `@cleocode/core` (PKCE implementation)
+ * and `@cleocode/cleo` (CLI dispatcher). No runtime dependencies — types only.
+ *
+ * @module contracts/llm/oauth
+ * @task T9302
+ * @epic T9261 T-LLM-CRED-CENTRALIZATION
+ */
+
+// ---------------------------------------------------------------------------
+// OAuth mode discriminant
+// ---------------------------------------------------------------------------
+
+/**
+ * OAuth grant mode supported by a provider profile.
+ *
+ * - `pkce` — RFC 7636 Authorization Code + PKCE (browser-based or headless
+ *   with manual code paste). Used by Anthropic.
+ * - `device-code` — RFC 8628 Device Authorization Grant (polling). Used by
+ *   Kimi Code.
+ */
+export type OAuthMode = 'pkce' | 'device-code';
+
+// ---------------------------------------------------------------------------
+// Token response
+// ---------------------------------------------------------------------------
+
+/**
+ * Successful token response from an OAuth token endpoint.
+ *
+ * Returned by both {@link exchangePkceCode} and {@link refreshPkceToken} in
+ * `@cleocode/core/llm/oauth/pkce.ts`.
+ *
+ * @task T9302
+ */
+export interface OAuthTokens {
+  /** Bearer access token. */
+  accessToken: string;
+  /**
+   * Refresh token for obtaining new access tokens without user interaction.
+   *
+   * Not all providers return a refresh token. When absent, the user must
+   * re-authorize when the access token expires.
+   */
+  refreshToken?: string;
+  /** Seconds until `accessToken` expires. `undefined` when not provided. */
+  expiresIn?: number;
+  /** Token type (virtually always `'bearer'`). */
+  tokenType: string;
+}
+
+// ---------------------------------------------------------------------------
+// PKCE flow config
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for a RFC 7636 PKCE OAuth flow.
+ *
+ * All URLs and client credentials are provider-specific. Callers obtain an
+ * instance from the builtin registry (e.g., `anthropicProfile.oauth`) or
+ * construct one directly for a custom provider.
+ *
+ * @task T9302
+ */
+export interface PkceFlowConfig {
+  /** Provider name — used only for logging / error messages. */
+  provider: string;
+  /** OAuth 2.0 client ID registered with the provider. */
+  clientId: string;
+  /**
+   * Authorization endpoint (RFC 6749 §3.1).
+   *
+   * The user (or headless code) navigates here to grant consent. When the
+   * grant succeeds the provider redirects to `redirectUri` with an
+   * authorization `code` and the original `state` parameter.
+   */
+  authorizationEndpoint: string;
+  /**
+   * Token endpoint (RFC 6749 §3.2).
+   *
+   * POSTed to when exchanging the authorization `code` for tokens, and again
+   * when refreshing an existing access token.
+   */
+  tokenEndpoint: string;
+  /**
+   * Space-separated OAuth scopes to request.
+   *
+   * @example 'org:create_api_key user:profile user:inference'
+   */
+  scope?: string;
+  /**
+   * Redirect URI registered with the provider.
+   *
+   * For CLI / headless flows this is typically `http://localhost:<port>/callback`
+   * or a custom URI scheme handled by the CLI binary.
+   *
+   * @default 'http://localhost'
+   */
+  redirectUri?: string;
+  /**
+   * Additional HTTP headers sent with every token-endpoint request.
+   *
+   * Used for provider-specific version headers (e.g. Anthropic's
+   * `anthropic-beta`).
+   */
+  extraHeaders?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// ProviderProfile oauth config shape
+// ---------------------------------------------------------------------------
+
+/**
+ * OAuth configuration embedded in a {@link ProviderProfile}.
+ *
+ * Added as an optional field `oauth?` on `ProviderProfile` so the CLI login
+ * dispatcher can read the mode and endpoints without importing provider-
+ * specific modules.
+ *
+ * @task T9302
+ */
+export interface ProviderOAuthConfig {
+  /** OAuth grant mode this provider uses. */
+  mode: OAuthMode;
+  /** OAuth 2.0 client ID. */
+  clientId: string;
+  /**
+   * Authorization endpoint URL (required for `pkce` mode; omit for
+   * `device-code`).
+   */
+  authorizationEndpoint?: string;
+  /** Token endpoint URL. */
+  tokenEndpoint: string;
+  /** Space-separated OAuth scopes. */
+  scope?: string;
+  /**
+   * Redirect URI (required for `pkce` mode; omit for `device-code`).
+   *
+   * @default 'http://localhost'
+   */
+  redirectUri?: string;
+}

package/src/llm/plugin-llm.ts

@@ -0,0 +1,128 @@
+/**
+ * Plugin LLM access types for the CLEO trust-gating layer.
+ *
+ * Defines the context, completion signature, and error types that the plugin
+ * LLM facade exposes to plugin consumers. Sandboxing (filesystem/network
+ * isolation) is deferred to Phase 5 (T9313). This module covers model-gating
+ * and credential-redaction concerns only.
+ *
+ * @module llm/plugin-llm
+ * @task T9305
+ * @epic T9261 T-LLM-CRED-CENTRALIZATION
+ * @see ADR-072 §6 plugin facade
+ */
+
+import type { SendOptions } from './interfaces.js';
+import type { NormalizedResponse, TransportMessage } from './normalized-response.js';
+
+// ---------------------------------------------------------------------------
+// Plugin context
+// ---------------------------------------------------------------------------
+
+/**
+ * Context describing a plugin's identity and LLM access constraints.
+ *
+ * `allowedModels` and `allowedProviders` are additive allow-lists. When both
+ * are supplied the request must satisfy BOTH. When a list is omitted (or
+ * empty) that axis is unconstrained.
+ */
+export interface PluginLlmContext {
+  /** Unique plugin identifier registered in the plugin manifest. */
+  readonly pluginId: string;
+  /**
+   * Optional list of model identifiers the plugin is permitted to call.
+   *
+   * Values are matched against the `model` field on the resolved role config.
+   * When omitted or empty any model is allowed.
+   */
+  readonly allowedModels?: readonly string[];
+  /**
+   * Optional list of provider identifiers the plugin is permitted to use.
+   *
+   * Values are matched against the `ModelTransport` union members
+   * (e.g. `'anthropic'`, `'openai'`). When omitted or empty any provider is
+   * allowed.
+   */
+  readonly allowedProviders?: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Completion signature
+// ---------------------------------------------------------------------------
+
+/**
+ * Single-turn plugin LLM completion function.
+ *
+ * Implementations MUST:
+ * - Validate `ctx.allowedModels` / `ctx.allowedProviders` before dispatching.
+ * - Redact credential patterns from errors before re-throwing.
+ * - NOT append messages to the underlying session history.
+ *
+ * @param ctx - Plugin identity and access constraints.
+ * @param messages - Conversation messages in provider-neutral form.
+ * @param opts - Optional per-call send options forwarded to the executor.
+ * @returns A promise resolving to a {@link NormalizedResponse}.
+ */
+export type PluginLlmComplete = (
+  ctx: PluginLlmContext,
+  messages: TransportMessage[],
+  opts?: SendOptions,
+) => Promise<NormalizedResponse>;
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a plugin requests a model or provider not in its allow-list.
+ *
+ * Consumers can `instanceof PluginModelGateError` to distinguish trust-gating
+ * failures from general executor errors.
+ */
+export class PluginModelGateError extends Error {
+  /** Plugin that triggered the gate. */
+  readonly pluginId: string;
+  /** The model or provider identifier that was denied. */
+  readonly denied: string;
+  /** Which axis triggered the gate: model or provider. */
+  readonly axis: 'model' | 'provider';
+
+  /**
+   * @param pluginId - Plugin whose request was denied.
+   * @param denied - The specific value that was not in the allow-list.
+   * @param axis - Whether the denial was on the `model` or `provider` axis.
+   */
+  constructor(pluginId: string, denied: string, axis: 'model' | 'provider') {
+    super(
+      `Plugin "${pluginId}" is not permitted to use ${axis} "${denied}". ` +
+        `Check the plugin manifest's allowed${axis === 'model' ? 'Models' : 'Providers'} list.`,
+    );
+    this.name = 'PluginModelGateError';
+    this.pluginId = pluginId;
+    this.denied = denied;
+    this.axis = axis;
+  }
+}
+
+/**
+ * Wraps an underlying executor error after credential patterns have been
+ * redacted from its message and stack.
+ *
+ * The original cause is preserved in `Error.cause` for internal logging but
+ * the message and stack exposed to the plugin are sanitised.
+ */
+export class PluginLlmError extends Error {
+  /** Plugin on whose behalf the call was made. */
+  readonly pluginId: string;
+
+  /**
+   * @param pluginId - Plugin on whose behalf the failing call was made.
+   * @param redactedMessage - Credential-scrubbed error message.
+   * @param cause - Original unscrubbed error (for internal diagnostics).
+   */
+  constructor(pluginId: string, redactedMessage: string, cause: unknown) {
+    super(redactedMessage, { cause });
+    this.name = 'PluginLlmError';
+    this.pluginId = pluginId;
+  }
+}

package/src/llm/provider-profile.ts

@@ -12,6 +12,7 @@
 
 import type { ModelTransport, StoredAuthTypeWire } from '../operations/llm.js';
 import type { TransportMessage, TransportTool } from './normalized-response.js';
+import type { ProviderOAuthConfig } from './oauth.js';
 
 /**
  * Describes a single LLM provider — its auth capabilities, base URL,
@@ -162,6 +163,19 @@ export interface ProviderProfile {
    * @default false
    */
   readonly supportsThinkingBudget?: boolean;
+
+  /**
+   * OAuth configuration for this provider.
+   *
+   * When present, `cleo llm login <provider>` dispatches to the specified
+   * OAuth flow rather than requiring a manual API key. The `mode` field
+   * selects the grant type:
+   * - `pkce` — RFC 7636 Authorization Code + PKCE (browser or headless).
+   * - `device-code` — RFC 8628 Device Authorization Grant (polling).
+   *
+   * @task T9302
+   */
+  readonly oauth?: ProviderOAuthConfig;
 }
 
 /**

package/src/memory/context-engine.ts

@@ -0,0 +1,78 @@
+/**
+ * ContextEngine interface contract — canonical location.
+ *
+ * Defines the compression contract used by {@link LlmExecutor} to keep
+ * session history within the model's context budget. An engine is injected
+ * at executor construction time; when absent the executor silently skips
+ * all compression checks.
+ *
+ * @module memory/context-engine
+ * @task T9304
+ * @epic T9261 T-LLM-CRED-CENTRALIZATION
+ * @see ADR-072 §"LlmExecutor — agent-loop level"
+ */
+
+import type { TransportMessage } from '../llm/normalized-response.js';
+
+// ---------------------------------------------------------------------------
+// CompressedContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Result returned by {@link ContextEngine.compress}.
+ *
+ * Carries the compressed message array alongside before/after token counts so
+ * the executor can emit a `context_compressed` event with accurate metrics.
+ */
+export interface CompressedContext {
+  /** The compressed message array that replaces the original history. */
+  readonly compressedMessages: TransportMessage[];
+  /** Estimated token count of the original history before compression. */
+  readonly beforeTokens: number;
+  /** Estimated token count of the compressed history after compression. */
+  readonly afterTokens: number;
+}
+
+// ---------------------------------------------------------------------------
+// ContextEngine
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional context-compression engine supplied to {@link LlmExecutor}.
+ *
+ * When present, the executor calls {@link shouldCompress} before each model
+ * turn. If it returns `true`, the executor calls {@link compress} to reduce
+ * the session history, replaces it with {@link CompressedContext.compressedMessages},
+ * then emits a `context_compressed` event with the before/after token counts.
+ *
+ * When absent (undefined), the executor skips all compression checks silently.
+ *
+ * @see ADR-072 §"LlmExecutor — agent-loop level"
+ */
+export interface ContextEngine {
+  /**
+   * Returns `true` when the current prompt size warrants compression.
+   *
+   * The executor passes the estimated prompt token count and the model's
+   * effective context budget so the engine can apply a threshold ratio
+   * (e.g. compress when `promptTokens / contextBudget >= 0.75`).
+   *
+   * @param promptTokens - Estimated token count of the current session history.
+   * @param contextBudget - Effective context-window budget for the bound model.
+   * @returns Whether compression should be applied before the next model turn.
+   */
+  shouldCompress(promptTokens: number, contextBudget: number): boolean;
+
+  /**
+   * Compresses the session history and returns the result.
+   *
+   * Implementations SHOULD preserve the first few and last few messages
+   * verbatim to maintain context anchoring, and summarize the middle window
+   * via an auxiliary LLM call.
+   *
+   * @param messages - Current read-only conversation history snapshot.
+   * @param focusTopic - Optional topic hint to guide summarization focus.
+   * @returns Promise resolving to the compressed context with token metrics.
+   */
+  compress(messages: readonly TransportMessage[], focusTopic?: string): Promise<CompressedContext>;
+}

package/src/operations/llm.ts

@@ -206,15 +206,13 @@ export interface CredentialResultWire {
  * 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
+ *   3. `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.
+ * Useful for `cleo llm whoami` diagnostics.
  *
- * @task T9255
+ * @task T9306
  */
-export type ResolutionSource = 'role' | 'default' | 'daemon-legacy' | 'implicit-fallback';
+export type ResolutionSource = 'role' | 'default' | 'implicit-fallback';
 
 /**
  * Result envelope returned by `resolveLLMForRole(role)`.
@@ -568,3 +566,49 @@ export interface LlmWhoamiResult {
 // 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.
+
+// ---------------------------------------------------------------------------
+// llm-status types (T9323)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolved credential source for a single LLM provider.
+ *
+ * Mirrors the subset of `CredentialSource` relevant for human-facing status
+ * output. `'none'` means no credential was found at any tier.
+ *
+ * @task T9323
+ */
+export type LlmProviderSourceWire = 'env' | 'cred-file' | 'claude-creds' | 'config' | 'none';
+
+/**
+ * Per-provider status entry emitted by `cleo memory llm-status`.
+ *
+ * @task T9323
+ */
+export interface LlmProviderStatusEntry {
+  /** Provider identifier (e.g. `'anthropic'`, `'kimi-code'`). */
+  provider: string;
+  /** Which credential tier resolved the key, or `'none'` if unavailable. */
+  resolvedSource: LlmProviderSourceWire;
+  /** `true` when a usable credential was found. */
+  hasCredential: boolean;
+}
+
+/**
+ * Result envelope for `memory.llm-status` (query).
+ *
+ * @task T9323
+ */
+export interface LlmStatusResult {
+  /** Legacy anthropic-only resolved source (kept for backward compat). */
+  resolvedSource: string;
+  /** `true` when an Anthropic credential is available (legacy compat field). */
+  extractionEnabled: boolean;
+  /** ISO timestamp of the most recent extraction run, or `null`. */
+  lastExtractionRun: string | null;
+  /** Suggested test command. */
+  testCommand: string;
+  /** Per-provider status for all known OAuth providers. */
+  providers: LlmProviderStatusEntry[];
+}