@combycode/llm-sdk 2.0.1 → 2.2.0

package/dist/helpers/define-tool.d.ts

@@ -50,17 +50,26 @@ type InferParam<S> = S extends 'string' ? string : S extends 'number' | 'integer
 } ? number : S extends {
     type: 'boolean';
 } ? boolean : unknown;
-type InferArgs<P extends Record<string, ParamSpec>> = {
-    [K in keyof P]: InferParam<P[K]>;
+/** Keys named in `optional` are optional HERE TOO. Typing them as always-present is
+ *  a lie the compiler then helps enforce: `args.unit.toUpperCase()` typechecks and
+ *  throws at runtime whenever the model omits the argument — which, for an argument
+ *  declared optional, is the expected case rather than the edge one. */
+type InferArgs<P extends Record<string, ParamSpec>, O extends keyof P = never> = {
+    [K in Exclude<keyof P, O>]: InferParam<P[K]>;
+} & {
+    [K in Extract<O, keyof P>]?: InferParam<P[K]>;
 };
-export interface DefineToolInput<P extends Record<string, ParamSpec>> {
+export interface DefineToolInput<P extends Record<string, ParamSpec>, O extends keyof P & string = never> {
     name: string;
     description: string;
     /** Object spec — keys are arg names. All keys are treated as required by
      *  default; mark optional ones via `optional: ['x']`. */
     params: P;
-    optional?: ReadonlyArray<keyof P & string>;
-    execute: (args: InferArgs<P>, context: ToolExecutionContext) => Promise<string | ContentPart[]> | string | ContentPart[];
+    optional?: readonly O[];
+    /** Register the tool without declaring it — the model finds it via `tool_search` and
+     *  calls it through `call_tool`. See `AgentTool.lazy`. */
+    lazy?: boolean;
+    execute: (args: InferArgs<P, O>, context: ToolExecutionContext) => Promise<string | ContentPart[]> | string | ContentPart[];
 }
-export declare function defineTool<P extends Record<string, ParamSpec>>(input: DefineToolInput<P>): AgentTool;
+export declare function defineTool<P extends Record<string, ParamSpec>, const O extends keyof P & string = never>(input: DefineToolInput<P, O>): AgentTool;
 export {};

package/dist/helpers/engine.d.ts

@@ -18,11 +18,13 @@
 import { AgentBus } from '../bus/agent-bus';
 import { HookBus } from '../bus/hook-bus';
 import type { ProviderName } from '../llm/types/provider';
-import { NetworkEngine } from '../network/engine';
+import { NetworkEngine, type QueueSettings } from '../network/engine';
+import type { RetryPolicyOverride } from '../network/queue-state-config';
 import type { EngineConnect, EngineFetch, EngineFetchStream, FetchFn } from '../network/types';
 import { Cache } from '../plugins/cache/cache';
 import { CostCollector } from '../plugins/cost-collector/collector';
 import { ModelCatalog } from '../plugins/model-catalog/catalog';
+import { TelemetryAdapter, type TelemetryAdapterOptions } from '../plugins/telemetry/telemetry';
 import type { Persistence } from '../plugins/persistence/types';
 export interface EngineHandle {
     /** Trace session id — minted once for this engine (the holder), shared by
@@ -53,6 +55,10 @@ export interface EngineHandle {
     /** CostCollector — subscribes to onCompletion + onMediaGenerated and
      *  prices via catalog. Call `engine.cost.total()` for a running tally. */
     cost: CostCollector;
+    /** TelemetryAdapter — present only when `telemetry` was configured, because an
+     *  unwanted one would sit there accumulating spans for a process that never reads
+     *  them. Subscribe with `engine.telemetry.onTrace(...)`, or use it directly. */
+    telemetry: TelemetryAdapter | null;
     /** API keys per provider. Helpers (createLLM, createAgent,
      *  createMediaOutput, complete) read these to wire LLM clients without
      *  the caller passing apiKey explicitly. */
@@ -94,6 +100,35 @@ export interface EngineConfig {
     /** Per-provider API keys. Helpers consult this when no apiKey is passed
      *  alongside `model: 'provider/...'`. */
     apiKeys?: Partial<Record<ProviderName, string>>;
+    /** Observability. Omitted → no adapter is built and nothing is collected.
+     *
+     *  ```ts
+     *  createEngine({
+     *    telemetry: {
+     *      types: ['agent', 'tool'],        // http/llm detail stays out
+     *      content: 'none',                 // conversation text off by default
+     *      sample: 0.05,                    // per trace, not per span
+     *      onTrace: (e) => myPipeline.push(e),
+     *    },
+     *  });
+     *  ```
+     */
+    telemetry?: TelemetryAdapterOptions;
+    /** Retry policy for every request this engine makes.
+     *
+     *  Retry is a cross-cutting concern, so it is configured once here rather than threaded through
+     *  each call. Anything omitted falls back to the built-in policy (`DEFAULT_RETRY`).
+     *
+     *  ```ts
+     *  createEngine({ retry: { maxRetries: 5, backoff: { initialMs: 200, maxMs: 8_000 } } });
+     *  ```
+     *
+     *  Three layers, narrowest wins: `HttpRequest.retry` (one request) > `queues[name].retry`
+     *  (one provider queue) > this (everything). */
+    retry?: RetryPolicyOverride;
+    /** Per-queue overrides, keyed by queue name (`provider/model` unless routed otherwise).
+     *  Use when one provider needs a different policy from the rest. */
+    queues?: Record<string, QueueSettings>;
     /** Register this engine as the default for `coreRegistry.get()` (used by
      *  helpers when the caller doesn't pass an explicit `engine`). Defaults to
      *  `true` so `createEngine({ ... })` followed by helper calls just works.

package/dist/helpers/mcp.d.ts

@@ -40,6 +40,15 @@ export interface ConnectMcpOptions {
     roots?: McpRoot[] | (() => McpRoot[] | Promise<McpRoot[]>);
     /** Validate tool `structuredContent` against the tool's `outputSchema`. */
     validateOutput?: boolean;
+    /** Register this server's tools WITHOUT declaring them: the model finds them with
+     *  `tool_search` and calls them through `call_tool`. Exposure only — every tool is
+     *  still registered, namespaced and collision-checked exactly as today.
+     *
+     *  This is the common case for the feature, since an MCP server is where a large tool
+     *  block usually comes from. Measured over 308 tools: identical correctness, −72% cost
+     *  per task on claude-haiku-4.5 and −97% on gpt-5.4-nano, for one extra round trip.
+     *  Not worth it for a small server — see `AgentTool.lazy`. */
+    lazy?: boolean;
     /** Send a `ping` every N ms to keep the connection alive (0 = off).
      *  Ignored on a 2026-07-28 session, where `ping` no longer exists. */
     keepAliveMs?: number;

package/dist/helpers/moderate.d.ts

@@ -9,5 +9,17 @@
  *
  *  The moderations endpoint is FREE; an honest-zero cost entry is always emitted
  *  so the cost ledger has a record of each call. HTTP flows through engine.fetch. */
-import type { ModerateOptions, ModerationResult } from './moderate-types';
+import type { ModerateOptions, ModerationContentPart, ModerationResult } from './moderate-types';
+/** One input in, one result out: a single string, or one content-part array that
+ *  together forms a single multimodal item. */
+export declare function moderate(opts: ModerateOptions & {
+    input: string | ModerationContentPart[];
+}): Promise<ModerationResult>;
+/** Many inputs in, one result each, in the same order. */
+export declare function moderate(opts: ModerateOptions & {
+    input: string[] | ModerationContentPart[][];
+}): Promise<ModerationResult[]>;
+/** Fallback for a caller holding the wide `ModerateOptions['input']` union: the
+ *  arity is only knowable at runtime, so the union comes back. Kept so existing
+ *  code that already narrows the result keeps compiling. */
 export declare function moderate(opts: ModerateOptions): Promise<ModerationResult | ModerationResult[]>;

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>;