@cleocode/contracts 2026.4.139 → 2026.4.141

package/dist/operations/index.d.ts

@@ -8,6 +8,7 @@ export * from './brain.js';
 export * from './conduit.js';
 export * from './issues.js';
 export * from './lifecycle.js';
+export * from './llm.js';
 export * from './memory.js';
 export * from './nexus.js';
 export * from './nexus-user-profile.js';

package/dist/operations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}

package/dist/operations/index.js

@@ -8,6 +8,7 @@ export * from './brain.js';
 export * from './conduit.js';
 export * from './issues.js';
 export * from './lifecycle.js';
+export * from './llm.js';
 export * from './memory.js';
 export * from './nexus.js';
 export * from './nexus-user-profile.js';

package/dist/operations/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}

package/dist/operations/llm.d.ts

@@ -0,0 +1,108 @@
+/**
+ * LLM operations contract types for the CLEO LLM abstraction layer.
+ *
+ * These are the wire-format types for the new `cleoLlmCall()` API surface
+ * ported from PSYCHE's llm/ layer. They live in contracts so that packages
+ * outside core can reference them without importing the full SDK.
+ *
+ * @task T1399 (T1386-W13)
+ * @epic T1386
+ */
+/** Supported provider transport names. */
+export type ModelTransport = 'anthropic' | 'openai' | 'gemini';
+/** Cache policy mode for prompt prefix caching. */
+export type PromptCachePolicyMode = 'gemini_cached_content';
+/** Prompt caching policy descriptor. */
+export interface PromptCachePolicy {
+    /** Cache mode — only 'gemini_cached_content' currently supported. */
+    mode: PromptCachePolicyMode;
+    /** TTL in seconds for the cached content (default: 300). */
+    ttlSeconds?: number;
+    /** Key version for cache invalidation. */
+    keyVersion?: string;
+}
+/** Model configuration for a single provider. */
+export interface ModelConfig {
+    /** Provider SDK transport. */
+    transport: ModelTransport;
+    /** Full model identifier string (e.g. 'claude-sonnet-4-6', 'gpt-4o', 'gemini-pro'). */
+    model: string;
+    /** Override API key (uses env defaults if null). */
+    apiKey?: string | null;
+    /** Override base URL for proxy providers. */
+    baseUrl?: string | null;
+    /** Sampling temperature. */
+    temperature?: number | null;
+    top_p?: number | null;
+    top_k?: number | null;
+    frequencyPenalty?: number | null;
+    presencePenalty?: number | null;
+    seed?: number | null;
+    /** OpenAI reasoning effort level. */
+    thinkingEffort?: string | null;
+    /** Anthropic extended thinking budget tokens. */
+    thinkingBudgetTokens?: number | null;
+    /** Provider-specific passthrough params. */
+    providerParams?: Record<string, unknown> | null;
+    /** Override max output tokens (null = use per-call maxTokens). */
+    maxOutputTokens?: number | null;
+    /** Stop sequences. */
+    stopSequences?: string[] | null;
+    /** Prompt caching policy. */
+    cachePolicy?: PromptCachePolicy | null;
+    /** Fallback model config used on final retry attempt. */
+    fallback?: Omit<ModelConfig, 'fallback'> | null;
+}
+/** Parameters for a single LLM call. */
+export interface LLMCallParams {
+    modelConfig: ModelConfig;
+    prompt: string;
+    maxTokens: number;
+    /** Optional pre-built message list (overrides prompt string). */
+    messages?: Array<Record<string, unknown>> | null;
+    temperature?: number | null;
+    stopSeqs?: string[] | null;
+    jsonMode?: boolean;
+    reasoningEffort?: string | null;
+    verbosity?: 'low' | 'medium' | 'high' | null;
+    thinkingBudgetTokens?: number | null;
+    enableRetry?: boolean;
+    retryAttempts?: number;
+    stream?: boolean;
+    streamFinalOnly?: boolean;
+    tools?: Array<Record<string, unknown>> | null;
+    toolChoice?: string | Record<string, unknown> | null;
+    maxToolIterations?: number;
+    maxInputTokens?: number | null;
+    traceName?: string | null;
+    trackName?: string | null;
+}
+/** Tool call parameters from the LLM. */
+export interface ToolCallParams {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    thoughtSignature?: string | null;
+}
+/** Tool execution result to feed back to the LLM. */
+export interface ToolResult {
+    toolId: string;
+    toolName: string;
+    result: unknown;
+    isError?: boolean;
+}
+/** Result of a completed LLM call. */
+export interface LLMCallResult<T = string> {
+    content: T;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    finishReasons: string[];
+    toolCallsMade: ToolCallParams[];
+    iterations: number;
+    thinkingContent: string | null;
+    thinkingBlocks: Array<Record<string, unknown>>;
+    reasoningDetails: Array<Record<string, unknown>>;
+}
+//# sourceMappingURL=llm.d.ts.map

package/dist/operations/llm.d.ts.map

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

package/dist/operations/llm.js

@@ -0,0 +1,12 @@
+/**
+ * LLM operations contract types for the CLEO LLM abstraction layer.
+ *
+ * These are the wire-format types for the new `cleoLlmCall()` API surface
+ * ported from PSYCHE's llm/ layer. They live in contracts so that packages
+ * outside core can reference them without importing the full SDK.
+ *
+ * @task T1399 (T1386-W13)
+ * @epic T1386
+ */
+export {};
+//# sourceMappingURL=llm.js.map

package/dist/operations/llm.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.4.139",
+  "version": "2026.4.141",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/operations/index.ts

@@ -9,6 +9,7 @@ export * from './brain.js';
 export * from './conduit.js';
 export * from './issues.js';
 export * from './lifecycle.js';
+export * from './llm.js';
 export * from './memory.js';
 export * from './nexus.js';
 export * from './nexus-user-profile.js';

package/src/operations/llm.ts

@@ -0,0 +1,115 @@
+/**
+ * LLM operations contract types for the CLEO LLM abstraction layer.
+ *
+ * These are the wire-format types for the new `cleoLlmCall()` API surface
+ * ported from PSYCHE's llm/ layer. They live in contracts so that packages
+ * outside core can reference them without importing the full SDK.
+ *
+ * @task T1399 (T1386-W13)
+ * @epic T1386
+ */
+
+/** Supported provider transport names. */
+export type ModelTransport = 'anthropic' | 'openai' | 'gemini';
+
+/** Cache policy mode for prompt prefix caching. */
+export type PromptCachePolicyMode = 'gemini_cached_content';
+
+/** Prompt caching policy descriptor. */
+export interface PromptCachePolicy {
+  /** Cache mode — only 'gemini_cached_content' currently supported. */
+  mode: PromptCachePolicyMode;
+  /** TTL in seconds for the cached content (default: 300). */
+  ttlSeconds?: number;
+  /** Key version for cache invalidation. */
+  keyVersion?: string;
+}
+
+/** Model configuration for a single provider. */
+export interface ModelConfig {
+  /** Provider SDK transport. */
+  transport: ModelTransport;
+  /** Full model identifier string (e.g. 'claude-sonnet-4-6', 'gpt-4o', 'gemini-pro'). */
+  model: string;
+  /** Override API key (uses env defaults if null). */
+  apiKey?: string | null;
+  /** Override base URL for proxy providers. */
+  baseUrl?: string | null;
+  /** Sampling temperature. */
+  temperature?: number | null;
+  top_p?: number | null;
+  top_k?: number | null;
+  frequencyPenalty?: number | null;
+  presencePenalty?: number | null;
+  seed?: number | null;
+  /** OpenAI reasoning effort level. */
+  thinkingEffort?: string | null;
+  /** Anthropic extended thinking budget tokens. */
+  thinkingBudgetTokens?: number | null;
+  /** Provider-specific passthrough params. */
+  providerParams?: Record<string, unknown> | null;
+  /** Override max output tokens (null = use per-call maxTokens). */
+  maxOutputTokens?: number | null;
+  /** Stop sequences. */
+  stopSequences?: string[] | null;
+  /** Prompt caching policy. */
+  cachePolicy?: PromptCachePolicy | null;
+  /** Fallback model config used on final retry attempt. */
+  fallback?: Omit<ModelConfig, 'fallback'> | null;
+}
+
+/** Parameters for a single LLM call. */
+export interface LLMCallParams {
+  modelConfig: ModelConfig;
+  prompt: string;
+  maxTokens: number;
+  /** Optional pre-built message list (overrides prompt string). */
+  messages?: Array<Record<string, unknown>> | null;
+  temperature?: number | null;
+  stopSeqs?: string[] | null;
+  jsonMode?: boolean;
+  reasoningEffort?: string | null;
+  verbosity?: 'low' | 'medium' | 'high' | null;
+  thinkingBudgetTokens?: number | null;
+  enableRetry?: boolean;
+  retryAttempts?: number;
+  stream?: boolean;
+  streamFinalOnly?: boolean;
+  tools?: Array<Record<string, unknown>> | null;
+  toolChoice?: string | Record<string, unknown> | null;
+  maxToolIterations?: number;
+  maxInputTokens?: number | null;
+  traceName?: string | null;
+  trackName?: string | null;
+}
+
+/** Tool call parameters from the LLM. */
+export interface ToolCallParams {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+  thoughtSignature?: string | null;
+}
+
+/** Tool execution result to feed back to the LLM. */
+export interface ToolResult {
+  toolId: string;
+  toolName: string;
+  result: unknown;
+  isError?: boolean;
+}
+
+/** Result of a completed LLM call. */
+export interface LLMCallResult<T = string> {
+  content: T;
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+  finishReasons: string[];
+  toolCallsMade: ToolCallParams[];
+  iterations: number;
+  thinkingContent: string | null;
+  thinkingBlocks: Array<Record<string, unknown>>;
+  reasoningDetails: Array<Record<string, unknown>>;
+}