@combycode/llm-sdk 1.0.0 → 1.1.0

package/dist/llm/moderation/native.d.ts

@@ -0,0 +1,18 @@
+/** Native OpenAI inline-moderation wire helpers.
+ *
+ *  buildNativeModeration → the `moderation` request field OpenAI accepts on both
+ *  the Responses API and Chat Completions.
+ *
+ *  parseNativeModeration → reads the `moderation` field OpenAI returns. Handles
+ *  BOTH wire shapes:
+ *    - Responses API:      moderation.{input,output} = moderation_result | error
+ *    - Chat Completions:   moderation.{input,output} = moderation_results | error,
+ *                          where moderation_results wraps `results: [moderation_result]`. */
+import type { ModerationReport, ModerationRequest } from './types';
+/** The `moderation` request field for the OpenAI native path. */
+export declare function buildNativeModeration(mod: ModerationRequest): {
+    model: string;
+};
+/** Parse OpenAI's returned `moderation` object into a unified report, or undefined
+ *  when the server returned nothing usable. */
+export declare function parseNativeModeration(raw: unknown): ModerationReport | undefined;

package/dist/llm/moderation/runner.d.ts

@@ -0,0 +1,33 @@
+/** Emulated-moderation runner + streaming strategy wrappers.
+ *
+ *  The emulated path runs OpenAI's moderations endpoint around a call for any
+ *  provider. This module owns:
+ *    - mode resolution (native vs emulate, by provider)
+ *    - input-text extraction (the last user message)
+ *    - a single moderation call (errors → an `{error}` entry, report-only)
+ *    - the buffer / parallel / post stream wrappers
+ *
+ *  It depends only on Layer-2 primitives (the OpenAI moderations adapter + the
+ *  injected fetch) — never on the helpers layer — so the client can use it
+ *  without an upward import. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { Message } from '../types/messages';
+import type { ProviderName } from '../types/provider';
+import type { StreamEvent } from '../types/stream';
+import type { EmulationConfig, ModerationEntry, ModerationRequest, ModerationStreamStrategy } from './types';
+/** Native for OpenAI, emulated for everyone else — unless explicitly forced. */
+export declare function resolveModerationMode(provider: ProviderName, mod: ModerationRequest): 'native' | 'emulate';
+/** Text of the last user message — what input moderation runs on. */
+export declare function moderationInputText(messages: Message[]): string;
+/** One moderation call. Empty text → an un-flagged empty result (nothing to check).
+ *  A moderation-infra failure → an `{error}` entry (report-only; never throws so a
+ *  flaky moderations endpoint can't take down the primary call). */
+export declare function runModeration(text: string, cfg: EmulationConfig): Promise<ModerationEntry>;
+export declare function moderationModel(mod: ModerationRequest): string;
+/** Emit an honest-zero cost entry for one emulated moderation call (the
+ *  moderations endpoint is free) so the cost ledger has no gaps. */
+export declare function emitModerationZeroCost(hooks: HookBus, model: string): void;
+type Moderate = (text: string) => Promise<ModerationEntry>;
+/** Dispatch to the chosen strategy. `interval` defaults applied by the caller. */
+export declare function wrapModeratedStream(raw: AsyncIterable<StreamEvent>, strategy: ModerationStreamStrategy, interval: number, moderate: Moderate): AsyncIterable<StreamEvent>;
+export {};

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

@@ -0,0 +1,75 @@
+/** Inline-moderation option + result shapes (parity with OpenAI's `moderation`
+ *  request field, extended to work across all providers).
+ *
+ *  Two halves:
+ *    - `ModerationRequest` — the per-call request option (ExecuteOptions.moderation).
+ *    - `ModerationReport`  — what lands on `CompletionResponse.moderation`.
+ *
+ *  The option is REPORT-ONLY: it attaches results, it never aborts the call. To
+ *  BLOCK on flagged content use `moderationGuardrail` at the agent layer.
+ *
+ *  Provider coverage:
+ *    - OpenAI satisfies it NATIVELY (one round-trip; `mode:'native'`).
+ *    - Every other provider is satisfied by EMULATION — the client runs OpenAI's
+ *      moderations endpoint around the call (`mode:'emulate'`). Emulation needs an
+ *      OpenAI API key (the only public moderations endpoint). */
+import type { EngineFetch } from '../../network/types';
+import type { ModerationResult } from '../../helpers/moderate-types';
+/** One side's outcome: a result, or an error string if moderation itself failed. */
+export type ModerationEntry = ModerationResult | {
+    error: string;
+};
+/** Streaming output-moderation strategy (emulated path only):
+ *    - `buffer`   — hold chunks, moderate at each boundary, emit the result BEFORE
+ *                   releasing the held chunks (flag never arrives later than the
+ *                   text it refers to). Highest containment, adds latency.
+ *    - `parallel` — forward chunks in real-time; moderate concurrently; surface the
+ *                   result as soon as it lands. Preserves streaming; the triggering
+ *                   segment is already delivered when the flag arrives.
+ *    - `post`     — forward everything, moderate once after the stream ends. Pure
+ *                   after-the-fact observability. */
+export type ModerationStreamStrategy = 'buffer' | 'parallel' | 'post';
+export interface ModerationStreamOptions {
+    /** How output moderation interleaves with streamed chunks. Default 'buffer'. */
+    strategy?: ModerationStreamStrategy;
+    /** Characters of new output between moderation checks (also released on newline
+     *  boundaries). Default 400. */
+    interval?: number;
+}
+export interface ModerationRequest {
+    /** Moderation model. Default 'omni-moderation-latest'. */
+    model?: string;
+    /** Moderate the request input. Default true. */
+    input?: boolean;
+    /** Moderate the generated output. Default true. */
+    output?: boolean;
+    /** Force native (OpenAI passthrough) or emulated (client-side moderations call).
+     *  Default: 'native' for the OpenAI provider, 'emulate' for everyone else. */
+    mode?: 'native' | 'emulate';
+    /** OpenAI API key for the emulated path. Falls back to the client's own key when
+     *  the client provider is OpenAI; otherwise required (emulation throws without it). */
+    apiKey?: string;
+    /** Streaming output-moderation controls (emulated path). */
+    stream?: ModerationStreamOptions;
+}
+/** Moderation outcome attached to a response (`CompletionResponse.moderation`). */
+export interface ModerationReport {
+    /** Moderation of the request input, when requested. */
+    input?: ModerationEntry;
+    /** Moderation of the generated output, when requested. */
+    output?: ModerationEntry;
+    /** Whether the provider produced it natively or the client emulated it. */
+    source: 'native' | 'emulated';
+}
+/** Resolved config for one emulated-moderation call (OpenAI moderations endpoint). */
+export interface EmulationConfig {
+    apiKey: string;
+    model: string;
+    fetch: EngineFetch;
+}
+/** Default moderation model when none is specified. */
+export declare const MODERATION_DEFAULT_MODEL = "omni-moderation-latest";
+/** Default streaming strategy. */
+export declare const MODERATION_DEFAULT_STRATEGY: ModerationStreamStrategy;
+/** Default characters between streaming moderation checks. */
+export declare const MODERATION_DEFAULT_INTERVAL = 400;

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

@@ -0,0 +1,15 @@
+/** Google service-tier mapping — provider-specific (shared by the generate adapter),
+ *  never leaked into the SDK core. Google accepts flex|standard|priority on the request
+ *  (top-level `serviceTier`) and reports the billed tier on `usageMetadata.serviceTier`. */
+import type { ServiceTier } from '../../types/tiers';
+/** unified ServiceTier → Google request `serviceTier`. Unsupported values
+ *  ('auto', 'scale', or anything Google doesn't take) are omitted so Google
+ *  applies its default (standard). */
+export declare function googleRequestTier(t?: ServiceTier): string | undefined;
+/** Google billed tier (response `usageMetadata.serviceTier`, e.g. 'FLEX') →
+ *  {raw, normalized catalog key}. pricingTier is lower-cased to key `pricing.tiers`;
+ *  serviceTier preserves the provider's raw value. */
+export declare function googleBilledTier(raw: unknown): {
+    serviceTier?: string;
+    pricingTier?: string;
+};

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

@@ -1,6 +1,7 @@
 /** ExecuteOptions — per-call overrides for client.complete()/.stream(). */
 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 { ServiceTier } from './tiers';
@@ -35,6 +36,10 @@ export interface ExecuteOptions {
      *  any provider-accepted string). Maps per-provider; unsupported → no-op.
      *  `batch` is the separate Batch API, not a value here. */
     serviceTier?: ServiceTier;
+    /** Inline content moderation (report-only — attaches results, never blocks).
+     *  OpenAI runs it natively; other providers are emulated via OpenAI's
+     *  moderations endpoint. See ModerationRequest. */
+    moderation?: ModerationRequest;
     providerOptions?: Record<string, unknown>;
     previousResponseId?: string;
     /** Server-state optimization: when the prior assistant turn carries a usable

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

@@ -3,6 +3,7 @@
  *  In v2, the public surface is `client.complete(input, options?)` — model
  *  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 { AudioOptions } from './audio';
 import type { Message } from './messages';
 import type { ServiceTier } from './tiers';
@@ -28,6 +29,7 @@ export interface NormalizedRequest {
     thinking?: ThinkingConfig;
     cache?: CacheConfig;
     serviceTier?: ServiceTier;
+    moderation?: ModerationRequest;
     providerOptions?: Record<string, unknown>;
     audio?: AudioOptions;
     outputModalities?: Array<'text' | 'audio'>;
@@ -35,12 +37,20 @@ export interface NormalizedRequest {
     timeout?: number;
     signal?: AbortSignal;
 }
+/** OpenAI Responses-only: which of the model's prior-turn reasoning items are
+ *  rendered back to it on later turns of a stateful conversation (chained via
+ *  `previousResponseId` / server-state). `all_turns` keeps continuity at higher
+ *  token cost; `current_turn` drops earlier reasoning; `auto` lets OpenAI decide.
+ *  Ignored by every other provider. */
+export type ReasoningContext = 'auto' | 'current_turn' | 'all_turns';
 export type ThinkingConfig = {
     mode: 'auto';
     effort?: 'low' | 'medium' | 'high' | 'max';
+    context?: ReasoningContext;
 } | {
     mode: 'on';
     effort?: 'low' | 'medium' | 'high' | 'max';
+    context?: ReasoningContext;
 } | {
     mode: 'off';
 };

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

@@ -1,4 +1,5 @@
 /** Universal completion response. */
+import type { ModerationReport } from '../moderation/types';
 import type { ContentPart, MediaOutputPart, ToolCallPart } from './messages';
 export interface CompletionResponse {
     id: string;
@@ -11,9 +12,31 @@ export interface CompletionResponse {
     thinking: string | null;
     /** Media output parts (images, audio, video generated by model). */
     media: MediaOutputPart[];
+    /** Files produced by hosted tools (e.g. code execution) - charts, data files,
+     *  etc. Unified across providers. When only `id` is set, fetch the bytes via the
+     *  provider's files API; some providers return `data` inline. Absent when none. */
+    files?: FileOutput[];
+    /** Inline-moderation outcome, when the `moderation` request option was used.
+     *  Report-only: present for observability; it never blocks the call. Absent when
+     *  moderation was not requested. */
+    moderation?: ModerationReport;
     latencyMs: number;
     raw: unknown;
 }
+/** A file produced by a hosted tool (code execution output, etc.). */
+export interface FileOutput {
+    /** Provider file id, to fetch the bytes separately (e.g. Anthropic container
+     *  file_id, OpenAI file_id). */
+    id?: string;
+    /** Filename, when the provider supplies one. */
+    name?: string;
+    /** MIME type, when known. */
+    mimeType?: string;
+    /** Inline bytes (base64) when the provider returns the file inline; else absent. */
+    data?: string;
+    /** What produced it (e.g. 'code_execution'). */
+    source?: string;
+}
 export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
 export interface Usage {
     inputTokens: number;

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

@@ -1,4 +1,5 @@
 /** Universal streaming event types. */
+import type { ModerationEntry } from '../moderation/types';
 import type { Usage } from './response';
 export type MediaStreamType = 'image' | 'audio' | 'video';
 export type StreamEvent = {
@@ -39,4 +40,13 @@ export type StreamEvent = {
 } | {
     type: 'media_end';
     mediaId?: string;
+}
+/** A moderation result for the input or output. `source` distinguishes a
+ *  provider-native result from a client-emulated one. Emitted by the moderation
+ *  option (report-only). */
+ | {
+    type: 'moderation';
+    phase: 'input' | 'output';
+    result: ModerationEntry;
+    source: 'native' | 'emulated';
 };

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

@@ -11,6 +11,27 @@ export interface BuiltinTool {
     type: 'image_generation' | 'web_search' | 'code_interpreter' | 'file_search' | 'mcp';
     params?: Record<string, unknown>;
 }
+/** Typed shape for an `mcp` builtin's `params` (OpenAI hosted MCP tool). The
+ *  adapter forwards `params` verbatim, so this is for editor help — assign it as
+ *  `{ type: 'mcp', params: <McpToolParams> }`. Exactly one of `server_url`,
+ *  `connector_id`, or `tunnel_id` identifies the server (OpenAI enforces this):
+ *    - `server_url`   — a publicly reachable MCP server OpenAI dials directly.
+ *    - `connector_id` — a managed first-party connector (Gmail, Drive, …).
+ *    - `tunnel_id`    — a Secure MCP Tunnel: reach a private/local server with no
+ *                       public URL (behind NAT/firewall) via an outbound tunnel. */
+export interface McpToolParams {
+    server_label: string;
+    server_url?: string;
+    connector_id?: string;
+    tunnel_id?: string;
+    authorization?: string;
+    headers?: Record<string, string>;
+    require_approval?: 'always' | 'never' | Record<string, unknown>;
+    allowed_tools?: string[] | Record<string, unknown>;
+    server_description?: string;
+    /** Forward-compat: any other field OpenAI accepts is passed through. */
+    [key: string]: unknown;
+}
 export type Tool = FunctionTool | BuiltinTool;
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     name: string;

package/dist/plugins/model-catalog/catalog.d.ts

@@ -105,6 +105,9 @@ export interface ModelInfo {
     version?: string;
     /** Lifecycle: stable | preview | legacy. */
     status?: string;
+    /** Access tier, independent of lifecycle: undefined = generally available;
+     *  'limited' = gated / not enabled for every account; 'preview' = early access. */
+    availability?: string;
     /** Callable from this account/SDK now (probe-verified). false = don't call. */
     active?: boolean;
     /** End-of-life signalled by a source. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",