@combycode/llm-sdk 2.0.0 → 2.1.0

package/dist/helpers/one-shot.d.ts

@@ -15,6 +15,7 @@
  *  LLMClient.complete. Either way the helper destroys its created client
  *  before returning so callers don't leak. */
 import type { AgentTool } from '../agent/types';
+import type { CacheConfig } from '../llm/types/request';
 import type { LLMClientConfig } from '../llm/client-config';
 import type { AudioOptions } from '../llm/types/audio';
 import type { ContentPart, Message } from '../llm/types/messages';
@@ -51,6 +52,12 @@ export interface CompleteOptions {
     /** Generation control. */
     maxTokens?: number;
     temperature?: number;
+    /** Top-k sampling. Emitted only where the wire accepts it (Anthropic, Google, xAI,
+     *  OpenRouter) and dropped for OpenAI, which defines no top-k. */
+    topK?: number;
+    /** Best-effort deterministic sampling. Dropped on Anthropic, which has no seed.
+     *  Determinism is never guaranteed. */
+    seed?: number;
     structured?: {
         schema: Record<string, unknown>;
         name?: string;
@@ -63,6 +70,13 @@ export interface CompleteOptions {
     /** Service tier for this call. Also settable as a `model:tier` suffix (e.g.
      *  `anthropic/claude-opus-4.8:priority`); an explicit value here wins. */
     serviceTier?: ServiceTier;
+    /** Provider prompt caching: `'auto'`, `'off'`, or which segments to mark
+     *  (`{ system: true, tools: true }`).
+     *
+     *  It matters most exactly where this helper is convenient — a long system
+     *  prompt or a large tool block, both of which sit at the front of the request
+     *  and are the cheapest part to cache. */
+    cache?: CacheConfig;
     /** Optional engine to use. Falls back to coreRegistry default. */
     engine?: EngineHandle;
     /** Provider-specific request options (e.g. `{ openrouter: { models: [...] } }`). */
@@ -83,6 +97,11 @@ export interface CompleteResult<T = unknown> {
      *  otherwise `undefined`. The generic on `complete<T>(...)` types this. */
     parsed?: T;
     response: CompletionResponse;
+    /** In-band provider failure. Some providers report a failed generation IN the
+     *  response rather than by throwing (OpenAI Responses `status: 'failed'`, Google
+     *  Interactions likewise), so a caller that only catches sees empty text and no
+     *  exception — a failure indistinguishable from a successful empty answer. */
+    error?: CompletionResponse['error'];
     /** Fetch a hosted-tool output file (from `response.files`): bytes (`Blob`) +
      *  `name` / `mimeType` / `size` — bound to the SAME model + key this call used. */
     retrieveFile(file: FileOutput): Promise<RetrievedFile>;