@combycode/llm-sdk 2.2.1 → 2.3.0

package/dist/llm/client-config.d.ts

@@ -1,7 +1,7 @@
 /** LLMClient configuration types. */
 import type { HookBus } from '../bus/hook-bus';
 import type { EngineFetch, EngineFetchStream } from '../network/types';
-import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { ModelCatalog } from '../catalog/catalog';
 import type { RequestContext } from '../types/request-context';
 import type { ApiType, ProviderAdapter, ProviderName } from './types/provider';
 import type { NormalizedRequest } from './types/request';

package/dist/llm/client-internal.d.ts

@@ -34,6 +34,17 @@ export declare function extractSystem(messages: Message[]): {
 /** Strip leading/trailing markdown fences and JSON.parse. Exported so AgentLoop
  *  + helper can share the same parsing rules. */
 export declare function parseStructured<T>(text: string): T;
+/** The routing names `buildContext` needs from a client.
+ *
+ *  These were read with `as unknown as { queueName: string }` casts straight into
+ *  LLMClient's privates — which compiles, and silently returns `undefined` the
+ *  day a field is renamed. LLMClient now exposes them deliberately as
+ *  `client.routing`, so a rename is a type error instead. */
+export interface ClientRouting {
+    readonly queueName: string;
+    readonly configName: string;
+    readonly cacheName: string;
+}
 export declare function buildContext(client: LLMClient, options: ExecuteOptions): RequestContext;
 export declare function resolveApi(provider: ProviderName, api?: ApiType | 'auto'): ApiType;
 export declare function resolveAdapter(config: LLMClientConfig, api: ApiType): ProviderAdapter;

package/dist/llm/client.d.ts

@@ -25,6 +25,7 @@ import type { ApiType, ProviderName } from './types/provider';
 import type { CompletionResponse, FileOutput } from './types/response';
 import type { StreamEvent } from './types/stream';
 import type { LLMClientConfig } from './client-config';
+import { type ClientRouting } from './client-internal';
 export declare class LLMClient {
     readonly id: string;
     /** Trace session id (from the engine, or self-minted for a standalone client). */
@@ -44,6 +45,9 @@ export declare class LLMClient {
     private readonly queueName;
     private readonly configName;
     private readonly cacheName;
+    /** The routing names this client was configured with, exposed so context
+     *  building does not have to cast into the privates above. */
+    readonly routing: ClientRouting;
     private readonly cacheKeyFn?;
     private readonly catalog;
     constructor(config: LLMClientConfig);

package/dist/llm/providers/_shared/sse.d.ts

@@ -0,0 +1,19 @@
+/** The one piece of SSE handling every provider genuinely shares.
+ *
+ *  Report 035 proposed a shared "SSE -> StreamEvent parser" because the parsing
+ *  looked duplicated ~5x. Measured, it is not: the six parse bodies (76-149
+ *  lines each) share ZERO runs of three or more identical lines, because they
+ *  decode different wire schemas — Anthropic's `content_block_*` events,
+ *  OpenAI chat's `choices[].delta`, OpenAI Responses' typed events, and Google's
+ *  `candidates[].content.parts`. A "shared" parser would be a switch on provider
+ *  wearing a common signature.
+ *
+ *  What IS shared is exactly this line, repeated six times. Naming it gives the
+ *  three language ports one primitive to agree on instead of six independent
+ *  decisions, and one place to harden if malformed frames ever need handling
+ *  (today a bad frame throws out of the parser, which is the existing
+ *  behaviour and deliberately unchanged here).
+ */
+import type { SSEEvent } from '../../../network/types';
+/** Decode an SSE frame's `data` payload as a JSON object. */
+export declare function sseJson(event: SSEEvent): Record<string, unknown>;

package/dist/llm/providers/google/files.d.ts

@@ -3,6 +3,21 @@
 import type { EngineFetch } from '../../../network/types';
 import type { FileAttachment } from '../../../plugins/files/attachment';
 import type { FileProviderAdapter, FileUploadResult, RemoteFileInfo } from '../../../plugins/files/provider-adapter';
+/** Reduce any form of Google file id to the bare name the REST path wants.
+ *
+ *  Three forms reach this, and only two used to work:
+ *
+ *    https://.../v1beta/files/abc  the `uri` this adapter hands back from
+ *                                 upload() and list() — matched on `/files/`
+ *    abc                          a bare name — passed through
+ *    files/abc                    Google's CANONICAL resource name, the `name`
+ *                                 field its own API returns
+ *
+ *  The third fell through the `/files/` test (no leading slash) and produced
+ *  `/v1beta/files/files/abc` — a 404. It never broke this library's own
+ *  round-trip, because upload() and list() return the `uri`; it broke the
+ *  moment a caller passed the id Google itself gave them. */
+export declare function googleFileName(remoteId: string): string;
 export interface GoogleFileAdapterConfig {
     apiKey: string;
     baseURL?: string;

package/dist/llm/providers/google/media.d.ts

@@ -1,6 +1,6 @@
 /** Google media adapter — Imagen (:predict) + Veo (:predictLongRunning).
  *  All HTTP calls go through an injected EngineFetch (NetworkEngine queue). */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult, VideoGenRequest, VideoStatus } from '../../../plugins/media/types';
 export interface GoogleMediaAdapterConfig {
     apiKey: string;
@@ -12,14 +12,32 @@ export declare class GoogleMediaAdapter implements MediaProviderAdapter {
     private readonly baseURL;
     constructor(config: GoogleMediaAdapterConfig);
     capabilities(): MediaCapabilities;
+    /** Imagen image generation: the Vertex-style `:predict` envelope. */
+    buildImagenRequest(req: ImageGenRequest, model?: string): HttpRequest;
+    /** The inline-media path shared by gemini image generation, editing and TTS. */
+    buildGenerateContentRequest(model: string, text: string, generationConfig: Record<string, unknown>, extraParts?: Array<Record<string, unknown>>): HttpRequest;
+    /** Veo video submission — a long-running operation, hence the endpoint. */
+    buildVideoRequest(req: VideoGenRequest, model?: string): HttpRequest;
+    /** `generationConfig` for the gemini image paths — generation and editing take
+     *  the same one. */
+    private imageGenerationConfig;
+    /** The complete image request, whichever of the two Google image paths applies:
+     *  Imagen models use `:predict`, gemini-* models generate inline via
+     *  `:generateContent` steered by responseModalities. */
+    buildImageRequest(req: ImageGenRequest, model?: string): HttpRequest;
+    /** Gemini TTS: the same inline path with an AUDIO modality and a speechConfig. */
+    buildAudioRequest(req: AudioGenRequest, model?: string): HttpRequest;
+    /** Image-to-image edit: image generation plus the source image as a second part. */
+    buildEditImageRequest(req: ImageEditRequest, model?: string): HttpRequest;
     generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
     /** Image-to-image edit: gemini generateContent with the source image as an
      *  extra inline/file part next to the instruction. */
     editImage(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
-    /** Shared inline-media path: POST :generateContent and collect inlineData
-     *  parts + the reported token usage (token-priced media). */
-    private generateContentMedia;
+    /** Collect inlineData parts + reported usage from a `:generateContent`
+     *  response. The request half is `buildGenerateContentRequest`; keeping the two
+     *  apart is what lets a request be asserted without performing it. */
+    private parseGenerateContent;
     submitVideo(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
     getVideoStatus(operationId: string, fetch: EngineFetch): Promise<VideoStatus>;
     downloadVideo(operationId: string, fetch: EngineFetch): Promise<RawMediaResult>;

package/dist/llm/providers/google/realtime.d.ts

@@ -13,8 +13,8 @@
  *
  *  Gemini Live models are audio-native: with responseModalities ['AUDIO'] the
  *  parts carry inlineData audio, not text. */
-import type { EngineConnect } from '../../../network/types';
-import type { RealtimeProviderAdapter, RealtimeSession, RealtimeSessionConfig } from '../../realtime/types';
+import type { EngineConnect, WsRequest } from '../../../network/types';
+import type { RealtimeInput, RealtimeProviderAdapter, RealtimeSession, RealtimeSessionConfig } from '../../realtime/types';
 export interface GoogleRealtimeAdapterConfig {
     apiKey: string;
     baseURL?: string;
@@ -23,5 +23,18 @@ export declare class GoogleRealtimeAdapter implements RealtimeProviderAdapter {
     private readonly apiKey;
     private readonly base;
     constructor(config: GoogleRealtimeAdapterConfig);
+    /** The WebSocket descriptor. Separated from `connect` so it can be asserted
+     *  without opening a socket. Gemini authenticates with a query-string key and
+     *  does NOT name the model in the URL — that goes in the setup frame. */
+    buildConnectRequest(config: RealtimeSessionConfig): WsRequest;
     connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
 }
+/** The handshake frame. Pure: a function of the session config, so it can be
+ *  asserted without opening a socket. Gemini Live names the model HERE rather
+ *  than in the URL, which is the opposite of OpenAI. */
+export declare function buildGoogleSetupFrame(config: RealtimeSessionConfig): Record<string, unknown>;
+/** The frames for one turn. Gemini carries turn completion as a FIELD, where
+ *  OpenAI signals it by sending a second frame. */
+export declare function buildGoogleTurnFrames(input: RealtimeInput, opts?: {
+    turnComplete?: boolean;
+}): Array<Record<string, unknown>>;

package/dist/llm/providers/openai/media.d.ts

@@ -1,7 +1,7 @@
 /** OpenAI media adapter — image generation (/v1/images/generations) and TTS
  *  (/v1/audio/speech). All HTTP calls flow through an injected EngineFetch
  *  so they share the NetworkEngine queue, rate-limits, retry, and hooks. */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult, VideoGenRequest, VideoStatus } from '../../../plugins/media/types';
 export interface OpenAIMediaAdapterConfig {
     apiKey: string;
@@ -14,6 +14,15 @@ export declare class OpenAIMediaAdapter implements MediaProviderAdapter {
     constructor(config: OpenAIMediaAdapterConfig);
     capabilities(): MediaCapabilities;
     private authHeaders;
+    /** Text-to-image. */
+    buildGenerateImageRequest(req: ImageGenRequest, model?: string): HttpRequest;
+    /** Image-to-image edit. Generation's field set minus `style`, plus the source
+     *  image and an optional mask. */
+    buildEditImageRequest(req: ImageEditRequest, model?: string): HttpRequest;
+    /** TTS. `responseType` is arraybuffer because the response is audio bytes. */
+    buildAudioRequest(req: AudioGenRequest, model: string): HttpRequest;
+    /** Sora video submission. `seconds` goes on the wire as a string. */
+    buildVideoRequest(req: VideoGenRequest, model?: string): HttpRequest;
     generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     /** Parse `/v1/images/{generations,edits}` response → RawMediaResult[], with
      *  the request-level usage attached to the first item (billed once). */

package/dist/llm/providers/openai/realtime.d.ts

@@ -10,8 +10,8 @@
  *        response.output_audio.delta  → { audio, base64 delta }
  *        response.done                → turn complete
  *        error                        → error */
-import type { EngineConnect } from '../../../network/types';
-import type { RealtimeProviderAdapter, RealtimeSession, RealtimeSessionConfig } from '../../realtime/types';
+import type { EngineConnect, WsRequest } from '../../../network/types';
+import type { RealtimeInput, RealtimeProviderAdapter, RealtimeSession, RealtimeSessionConfig } from '../../realtime/types';
 export interface OpenAIRealtimeAdapterConfig {
     apiKey: string;
     baseURL?: string;
@@ -20,5 +20,18 @@ export declare class OpenAIRealtimeAdapter implements RealtimeProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAIRealtimeAdapterConfig);
+    /** The WebSocket descriptor. Separated from `connect` so it can be asserted
+     *  without opening a socket. Note the auth: OpenAI carries the key in a
+     *  SUBPROTOCOL, not a header or query param, because browsers cannot set
+     *  WebSocket headers. */
+    buildConnectRequest(config: RealtimeSessionConfig): WsRequest;
     connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
 }
+/** The handshake frame, sent once the socket opens. */
+export declare function buildOpenAISessionUpdate(config: Pick<RealtimeSessionConfig, 'modalities' | 'instructions' | 'voice'>): Record<string, unknown>;
+/** The frames for one turn. `response.create` is what asks the model to reply,
+ *  so `turnComplete: false` withholds it and the turn stays open — where Gemini
+ *  carries the same meaning as a field on its single frame. */
+export declare function buildOpenAITurnFrames(input: RealtimeInput, opts?: {
+    turnComplete?: boolean;
+}): Array<Record<string, unknown>>;

package/dist/llm/server-state.d.ts

@@ -13,7 +13,7 @@
  *    - it's within the retention TTL (catalog duration),
  *    - the model matches, OR the provider is not model-bound (catalog).
  *  Otherwise we fall back to resending full history (always correct). */
-import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { ModelCatalog } from '../catalog/catalog';
 import type { Message } from './types/messages';
 import type { ProviderName } from './types/provider';
 export interface ServerStateDecision {

package/dist/llm/types/options.d.ts

@@ -3,7 +3,7 @@ import type { ConversationHistory } from '../../agent/history';
 import type { RequestContext } from '../../types/request-context';
 import type { ModerationRequest } from '../moderation/types';
 import type { AudioOptions } from './audio';
-import type { CacheConfig, ThinkingConfig } from './request';
+import type { CacheConfig, ProviderOptions, ThinkingConfig } from './request';
 import type { ServiceTier } from './tiers';
 import type { Tool, ToolChoice } from './tools';
 export interface ExecuteOptions {
@@ -65,7 +65,7 @@ export interface ExecuteOptions {
      *  OpenAI runs it natively; other providers are emulated via OpenAI's
      *  moderations endpoint. See ModerationRequest. */
     moderation?: ModerationRequest;
-    providerOptions?: Record<string, unknown>;
+    providerOptions?: ProviderOptions;
     previousResponseId?: string;
     /** Server-state optimization: when the prior assistant turn carries a usable
      *  server id (same provider, within TTL, model ok), send the id + only the new

package/dist/llm/types/request.d.ts

@@ -4,10 +4,54 @@
  *  and system are fixed at construction. The LLMClient internally builds
  *  this `NormalizedRequest` from (input, options, this.model, this.system). */
 import type { ModerationRequest } from '../moderation/types';
+import type { ModelWire } from '../../catalog/catalog';
 import type { AudioOptions } from './audio';
 import type { Message } from './messages';
 import type { ServiceTier } from './tiers';
 import type { Tool, ToolChoice } from './tools';
+/** Provider-specific request options that have no unified equivalent.
+ *
+ *  This was `Record<string, unknown>` — the one untyped hole in the request, and
+ *  therefore the one place a typo produced silence rather than an error:
+ *  `promtCacheOptions` type-checked and was simply never sent.
+ *
+ *  Every key below is one an adapter actually reads; the list is derived from
+ *  the read sites, not invented. The index signature stays so a caller can still
+ *  pass something the SDK does not know about yet — a provider ships a parameter
+ *  before we model it, and refusing it would make the escape hatch useless. What
+ *  changed is that the keys we DO know are checked and discoverable.
+ *
+ *  Keys are grouped by the provider that consumes them; sending one to a
+ *  different provider is ignored, not an error. */
+export interface ProviderOptions {
+    /** Forwarded as the `anthropic-user-profile-id` header: identifies the end
+     *  user a request acts on behalf of. Needs the account-level
+     *  `user-profiles` beta. */
+    userProfileId?: string;
+    /** Native moderation policy, sent alongside the `moderation` request field. */
+    moderationPolicy?: Record<string, unknown>;
+    /** `prompt_cache_options` — OpenAI-only prompt-cache controls. */
+    promptCacheOptions?: Record<string, unknown>;
+    /** `reasoning.mode` on the Responses API. */
+    reasoningMode?: 'standard' | 'pro';
+    /** Overrides `generationConfig.responseModalities`, e.g. for image or audio
+     *  generation. Wins over the modality implied by `outputModalities`. */
+    responseModalities?: string[];
+    /** `generationConfig.speechConfig` — voice selection for audio output. */
+    speechConfig?: Record<string, unknown>;
+    /** `generationConfig.imageConfig` — aspect ratio / size for image output. */
+    imageConfig?: Record<string, unknown>;
+    /** `generationConfig.translationConfig`. */
+    translationConfig?: Record<string, unknown>;
+    /** Name of a cached-content handle to reuse. Forwarded only when it is a
+     *  non-empty string. */
+    cachedContent?: string;
+    /** Routing options merged into the request body (provider order, transforms,
+     *  and the rest of OpenRouter's routing surface). */
+    openrouter?: Record<string, unknown>;
+    /** Anything the SDK does not model yet. Adapters ignore what they do not read. */
+    [key: string]: unknown;
+}
 export interface NormalizedRequest {
     /** From LLMClientConfig.model — fixed at construction. */
     model: string;
@@ -47,7 +91,12 @@ export interface NormalizedRequest {
     cache?: CacheConfig;
     serviceTier?: ServiceTier;
     moderation?: ModerationRequest;
-    providerOptions?: Record<string, unknown>;
+    providerOptions?: ProviderOptions;
+    /** Wire traits for THIS model, resolved from the catalog by `LLMClient`.
+     *  Adapters prefer this over parsing the model id. Absent when the engine runs
+     *  without a catalog or the model is not catalogued, in which case adapters
+     *  fall back to the id. */
+    wire?: ModelWire;
     audio?: AudioOptions;
     outputModalities?: Array<'text' | 'audio'>;
     previousResponseId?: string;

package/dist/plugins/context-measurer/counter/count-api.d.ts

@@ -2,7 +2,7 @@
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
 import type { FetchFn } from '../../../network/types';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
 /** Anthropic count endpoint: POST /v1/messages/count_tokens */
 export declare class AnthropicCountApi {
     private readonly apiKey;

package/dist/plugins/context-measurer/counter/heuristic.d.ts

@@ -1,7 +1,7 @@
 /** Heuristic token counter — chars-per-token with optional calibration. */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
 import type { CalibrationStore } from '../types';
 /** Count chars across a message's content parts. */
 export declare function messageChars(msg: Message): number;

package/dist/plugins/context-measurer/counter/hybrid.d.ts

@@ -1,7 +1,7 @@
 /** HybridTokenCounter — selects strategy per model based on catalog config. */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
 import type { CalibrationStore } from '../types';
 export interface HybridCounterConfig {
     catalog?: ModelCatalog;

package/dist/plugins/context-measurer/measurer.d.ts

@@ -4,7 +4,7 @@ import type { HookBus } from '../../bus/hook-bus';
 import type { Message } from '../../llm/types/messages';
 import type { TokenCounter } from '../../agent/types';
 import type { ConversationHistory } from '../../agent/history';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import type { Persistence } from '../persistence/types';
 import type { CalibrationStore, ContextThresholds, CalibrationConfig } from './types';
 export interface ContextMeasurerConfig {

package/dist/plugins/cost-collector/collector.d.ts

@@ -2,7 +2,7 @@
  *  pricing or provider-reported totals, emits onCostEntry/onBudgetWarning/
  *  onBudgetExceeded. */
 import type { CostEntry } from '../../bus/hook-map';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import type { Budget, CostCollectorConfig, CostFilter, CostSummary } from './cost-collector-types';
 export declare class CostCollector {
     private ledger;

package/dist/plugins/cost-collector/cost-collector-internal.d.ts

@@ -1,7 +1,7 @@
 /** CostCollector internals — pure cost-math + filtering helpers, split out of
  *  the class so each is independently testable. */
 import type { CostEntry } from '../../bus/hook-map';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import type { CostFilter, CostSummary } from './cost-collector-types';
 /** Pull provider-reported cost evidence out of a raw response body. */
 export declare function extractProviderCost(provider: string, raw: unknown): Record<string, unknown>;

package/dist/plugins/cost-collector/cost-collector-types.d.ts

@@ -1,6 +1,6 @@
 /** CostCollector public types: config, budgets, filters, summaries. */
 import type { HookBus } from '../../bus/hook-bus';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 export interface CostCollectorConfig {
     hooks: HookBus;
     catalog: ModelCatalog;

package/dist/plugins/files/registry.d.ts

@@ -3,7 +3,7 @@
  *  parts (provider_ref / inline base64 / url). */
 import type { HookBus } from '../../bus/hook-bus';
 import type { EngineFetch } from '../../network/types';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import { FileAttachment, type FileContent } from './attachment';
 import type { FileProviderAdapter, RemoteFileInfo } from './provider-adapter';
 import { type FileStrategy } from './strategy';

package/dist/plugins/files/strategy.d.ts

@@ -1,5 +1,5 @@
 /** FileStrategy — pluggable decision maker for how to attach files. */
-import type { ModelInfo } from '../model-catalog/catalog';
+import type { ModelInfo } from '../../catalog/catalog';
 import type { FileAttachment } from './attachment';
 export interface FileStrategyContext {
     file: FileAttachment;

package/dist/plugins/internal-tools/registry.d.ts

@@ -1,6 +1,6 @@
 /** ToolRegistry — unified access across multiple backends with caching, search, filtering. */
 import type { InternalTool, ToolBackend, ToolFilter, SearchOptions } from './types';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 export declare class ToolRegistry {
     private backends;
     private cache;

package/dist/plugins/internal-tools/runner/types.d.ts

@@ -3,7 +3,7 @@ import type { HookBus } from '../../../bus/hook-bus';
 import type { LLMClientConfig } from '../../../llm/client-config';
 import type { ProviderName } from '../../../llm/types/provider';
 import type { JsonSchema } from '../../../llm/types/tools';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
 import type { ToolRegistry } from '../registry';
 import type { CompatFile, ModelPreference } from '../types';
 import type { TokenCounter } from '../../../agent/types';

package/dist/plugins/mcp/sampling.d.ts

@@ -4,6 +4,7 @@
  *  custom handler or a model id to auto-wire. */
 import type { EngineHandle } from '../../helpers/engine';
 import type { ProviderName } from '../../llm/types/provider';
+import type { Message } from '../../llm/types/messages';
 import type { McpCreateMessageParams, McpCreateMessageResult } from './types';
 export type McpSamplingHandler = (params: McpCreateMessageParams) => Promise<McpCreateMessageResult>;
 /** Auto-wire sampling to our LLM. */
@@ -13,5 +14,26 @@ export interface McpSamplingViaLLM {
     engine?: EngineHandle;
 }
 export type McpSamplingConfig = McpSamplingHandler | McpSamplingViaLLM;
+/** The one thing this module needs from the ergonomic layer: run a completion.
+ *
+ *  Taken as a parameter rather than imported, because `plugins` importing
+ *  `helpers` closed a cycle (`helpers` already imports most of `plugins`). The
+ *  public `samplingHandler` lives in `helpers/mcp` and supplies `complete`; the
+ *  mapping between MCP's message shape and ours stays here, where it belongs. */
+export type McpCompleteFn = (args: {
+    model: string;
+    provider?: ProviderName;
+    engine?: EngineHandle;
+    system?: string;
+    prompt: Message[];
+    maxTokens?: number;
+    temperature?: number;
+}) => Promise<{
+    text: string;
+    response: {
+        model: string;
+        finishReason: string;
+    };
+}>;
 /** Build a sampling handler: pass-through a custom function, or auto-wire a model. */
-export declare function samplingHandler(config: McpSamplingConfig): McpSamplingHandler;
+export declare function samplingHandlerWith(complete: McpCompleteFn, config: McpSamplingConfig): McpSamplingHandler;

package/dist/plugins/media/output.d.ts

@@ -7,7 +7,7 @@
  *  by core LLM adapters + an onCompletion subscriber, NOT this class. */
 import type { HookBus } from '../../bus/hook-bus';
 import type { EngineFetch } from '../../network/types';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import { type AudioGenRequest, type ImageEditRequest, type ImageGenRequest, type MediaOutputConfig, type MediaProviderAdapter, type MediaResult, type MediaStore, type VideoGenRequest } from './types';
 export interface MediaOutputInit {
     hooks: HookBus;

package/dist/plugins/telemetry/telemetry.d.ts

@@ -10,7 +10,8 @@
  *  An in-memory store backs the sandbox sidebar; `toOtlpTraces()` shapes spans
  *  into OTLP-compatible JSON for a real OTel exporter to forward. */
 import type { HookBus } from '../../bus/hook-bus';
-import type { HookName } from '../../bus/hook-map';
+export type { Span, SpanKind, TelemetryAdapterOptions, TelemetryEvent, TelemetryMetrics, TelemetryResource, TraceEvent, TraceEventType, TraceFilter, TraceHandler, } from './types';
+import type { Span, TelemetryAdapterOptions, TelemetryEvent, TelemetryMetrics, TelemetryResource, TraceFilter, TraceHandler } from './types';
 /** Derive a conformant hex id from one of our readable ids. `bytes` is 16 for a trace
  *  id, 8 for a span id.
  *
@@ -22,81 +23,6 @@ export declare function toOtlpId(input: string, bytes: 8 | 16): string;
  *  `intValue` carrying a STRING, which is how OTLP/JSON encodes 64-bit integers; send
  *  them as plain strings instead and no backend can sum them. */
 export declare function toOtlpValue(value: unknown): Record<string, unknown>;
-export type SpanKind = 'llm' | 'http' | 'media' | 'agent' | 'tool' | 'mcp' | 'other';
-export interface Span {
-    traceId: string;
-    spanId: string;
-    /** The span this one runs under. Without it every span is a sibling and a backend
-     *  draws a flat list instead of a tree — so a run reads as "9 things happened", not
-     *  "a turn, which called a tool, which asked a second model".
-     *
-     *  Resolved in this order: the innermost container span still open on this trace
-     *  (`agent.run` / `tool.call`), else the app's span from a supplied `traceparent`,
-     *  else none — this span is the root. */
-    parentSpanId?: string;
-    name: string;
-    kind: SpanKind;
-    startTime: number;
-    endTime?: number;
-    durationMs?: number;
-    status: 'unset' | 'ok' | 'error';
-    attributes: Record<string, unknown>;
-}
-/** What kind of work an event describes. `message` is conversation content, which is not
- *  a span — it is the thing you want in a debug store and NOT in your metrics backend,
- *  which is exactly why it filters separately. */
-export type TraceEventType = 'agent' | 'tool' | 'llm' | 'http' | 'mcp' | 'media' | 'message' | 'other';
-/** One piece of work, carrying enough of the tree that a consumer can push it straight
- *  into their own tracer without reconstructing anything. */
-export interface TraceEvent {
-    type: TraceEventType;
-    /** The app's trace when it supplied a `traceparent`, else ours. */
-    traceId: string;
-    spanId: string;
-    /** Already resolved past anything this subscriber filtered out — see `survivingParent`. */
-    parentSpanId?: string;
-    /** The conventional name (`chat gpt-5.4-nano`, `execute_tool search`). */
-    name: string;
-    startTime: number;
-    endTime?: number;
-    durationMs?: number;
-    status: 'unset' | 'ok' | 'error';
-    attributes: Record<string, unknown>;
-}
-/** Declarative on purpose, rather than a predicate: knowing the types up front lets a
- *  filtered-out event cost nothing, where a predicate would force us to build the payload
- *  just to let the caller throw it away. */
-export interface TraceFilter {
-    types?: readonly TraceEventType[];
-}
-export type TraceHandler = (event: TraceEvent) => void;
-export interface TelemetryEvent {
-    seq: number;
-    time: number;
-    name: HookName;
-    category: string;
-    traceId?: string;
-    ctx: unknown;
-}
-export interface TelemetryMetrics {
-    requests: number;
-    errors: number;
-    retries: number;
-    rateLimitHits: number;
-    completions: number;
-    mediaGenerated: number;
-    costUsd: number;
-    inputTokens: number;
-    outputTokens: number;
-    inFlight: number;
-    queueDepth: number;
-    latency: {
-        count: number;
-        min: number;
-        max: number;
-        avg: number;
-    };
-}
 /** Parse a W3C `traceparent`: `00-<32 hex trace>-<16 hex span>-<flags>`.
  *  Returns null for anything malformed or for the all-zero ids the spec forbids —
  *  a bad header must not silently reroute telemetry into a garbage trace. */
@@ -104,63 +30,6 @@ export declare function parseTraceparent(value: string | undefined): {
     traceId: string;
     spanId: string;
 } | null;
-/** OpenTelemetry Resource — identifies the SERVICE producing this telemetry, so
- *  a shared backend can separate streams from different apps and attribute cost
- *  per service (`sum by service.name`). Stamped on every span/metric/log. */
-export interface TelemetryResource {
-    /** Primary grouping key, e.g. "billing-api". OTel default: "unknown_service". */
-    serviceName: string;
-    /** Optional namespace/group, e.g. "prod" or a team. */
-    serviceNamespace?: string;
-    /** Unique instance (pod/host/process); a good default is the engine sessionId. */
-    serviceInstanceId?: string;
-    serviceVersion?: string;
-    /** Arbitrary resource attributes (deployment.environment, cloud.region, …). */
-    attributes?: Record<string, string>;
-}
-export interface TelemetryAdapterOptions {
-    /** Cap on retained events (ring buffer). Default 2000. */
-    maxEvents?: number;
-    /** Service identity stamped on all exported telemetry. */
-    resource?: TelemetryResource;
-    /** Whether provider error TEXT may be stored in telemetry. Default `true`
-     *  (unchanged behaviour, and the same default as the OpenAI Agents SDK's
-     *  `trace_include_sensitive_data`).
-     *
-     *  A provider's `error.message` / `error.raw` can echo request content back —
-     *  a moderation refusal quotes the prompt, a validation error names the offending
-     *  field and value. URLs and headers are always redacted regardless; this switch
-     *  governs the free-text payload. Set `false` when telemetry leaves your trust
-     *  boundary (a shared collector, a vendor APM) and the message is replaced by a
-     *  fixed `[redacted]` string while name/code/status are kept for triage. */
-    includeSensitiveData?: boolean;
-    /** Which event types to hand to `onTrace`. Omitted → everything.
-     *
-     *  Filtering SPLICES the tree rather than punching holes in it: drop `http` and the
-     *  spans under it re-parent to the nearest surviving ancestor. Dropping without that
-     *  leaves orphans, and a backend draws an orphan as a second root — worse than not
-     *  filtering at all. */
-    types?: readonly TraceEventType[];
-    /** Whether conversation content rides along on `message` events. Default `'none'`:
-     *  prompts and completions are the debugging gold AND the PII, so sending them is a
-     *  decision to make on purpose rather than inherit. `'full'` adds the Opt-In
-     *  `gen_ai.input.messages` / `gen_ai.output.messages` attributes; `'none'` still
-     *  reports the shape (counts and sizes), which is enough to spot a runaway prompt. */
-    content?: 'none' | 'full';
-    /** Fraction of TRACES to emit, 0..1. Default 1.
-     *
-     *  Per trace, never per span: sampling spans independently shreds every tree it touches
-     *  — a tool call with no run, a model call with no tool. The decision is a hash of the
-     *  trace id, so it is stable across processes and two services sharing a trace agree
-     *  without coordinating.
-     *
-     *  This is HEAD sampling: the choice is made when the trace first appears, before we
-     *  know whether it ends in an error. Keeping all errors needs tail sampling, which
-     *  needs buffering; do that in your collector, which is built for it. */
-    sample?: number;
-    /** Convenience for the common case of a single sink — same as calling `onTrace`. */
-    onTrace?: TraceHandler;
-}
 export declare class TelemetryAdapter {
     readonly events: TelemetryEvent[];
     readonly spans: Span[];