@x12i/openrouter-runtime 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+type ApiMode = "chat" | "responses" | "auto";
+type ResolvedApiMode = "chat" | "responses";
+type ToolMode = "disabled" | "allowed" | "required";
+interface OpenRouterRuntime {
+    run(request: RuntimeRequest): Promise<RuntimeResponse>;
+    stream?(request: RuntimeRequest): AsyncIterable<RuntimeStreamEvent>;
+}
+interface OpenRouterRuntimeOptions {
+    apiKey: string;
+    baseUrl?: string;
+    defaultModel?: string;
+    defaultHeaders?: Record<string, string>;
+    appAttribution?: {
+        siteUrl?: string;
+        appName?: string;
+    };
+    defaults?: RuntimeDefaults;
+    tools?: RuntimeToolRegistry;
+    fetch?: typeof globalThis.fetch;
+    logger?: RuntimeLogger;
+    hooks?: RuntimeHooks;
+    patchApplier?: RuntimePatchApplier;
+}
+interface RuntimeDefaults {
+    apiMode?: ApiMode;
+    timeoutMs?: number;
+    maxRetries?: number;
+    retry?: {
+        enabled?: boolean;
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    serverTools?: RuntimeServerToolsPolicy;
+    temperature?: number;
+    maxTokens?: number;
+    requireCitationsWhenSearchUsed?: boolean;
+    onPolicyViolation?: "throw" | "return_error";
+}
+interface RuntimeRequest {
+    id?: string;
+    model?: string;
+    apiMode?: ApiMode;
+    messages?: RuntimeMessage[];
+    input?: string | RuntimeInputItem[];
+    instructions?: string;
+    system?: string;
+    prompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    reasoning?: RuntimeReasoningConfig;
+    responseFormat?: RuntimeResponseFormat;
+    serverTools?: RuntimeServerToolsPolicy;
+    functionTools?: RuntimeFunctionToolDefinition[];
+    toolChoice?: RuntimeToolChoice;
+    execution?: RuntimeExecutionPolicy;
+    metadata?: Record<string, unknown>;
+    rawOpenRouterOverrides?: Record<string, unknown>;
+}
+type RuntimeMessageRole = "system" | "user" | "assistant" | "tool";
+interface RuntimeMessage {
+    role: RuntimeMessageRole;
+    content: string | RuntimeContentPart[];
+    name?: string;
+    toolCallId?: string;
+}
+type RuntimeContentPart = RuntimeTextPart | RuntimeImagePart | RuntimeFilePart;
+interface RuntimeTextPart {
+    type: "text";
+    text: string;
+}
+interface RuntimeImagePart {
+    type: "image_url";
+    imageUrl: string;
+}
+interface RuntimeFilePart {
+    type: "file";
+    fileName?: string;
+    mimeType?: string;
+    data?: string;
+    url?: string;
+}
+type RuntimeInputItem = Record<string, unknown> | string;
+type RuntimeReasoningConfig = Record<string, unknown>;
+type RuntimeResponseFormat = Record<string, unknown>;
+interface RuntimeResponse {
+    id: string;
+    status: "completed" | "failed" | "requires_action" | "policy_violation";
+    apiMode: ResolvedApiMode;
+    model: string;
+    text: string;
+    messages?: RuntimeMessage[];
+    citations: RuntimeCitation[];
+    images: RuntimeGeneratedImage[];
+    patches: RuntimePatchProposal[];
+    toolUsage: RuntimeToolUsage;
+    usage?: RuntimeUsage;
+    finishReason?: string;
+    warnings: RuntimeWarning[];
+    errors: RuntimeError[];
+    raw: {
+        request: unknown;
+        response: unknown;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface RuntimeServerToolsPolicy {
+    webSearch?: WebSearchPolicy;
+    webFetch?: WebFetchPolicy;
+    datetime?: DatetimePolicy;
+    imageGeneration?: ImageGenerationPolicy;
+    applyPatch?: ApplyPatchPolicy;
+    fusion?: FusionPolicy;
+    advisor?: AdvisorPolicy | AdvisorPolicy[];
+    subagent?: SubagentPolicy;
+}
+type WebSearchEngine = "auto" | "native" | "exa" | "firecrawl" | "parallel" | "perplexity";
+type SearchContextSize = "low" | "medium" | "high";
+interface WebSearchPolicy {
+    mode: ToolMode;
+    engine?: WebSearchEngine;
+    maxResults?: number;
+    maxTotalResults?: number;
+    searchContextSize?: SearchContextSize;
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    userLocation?: {
+        type: "approximate";
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+    };
+    requireCitations?: boolean;
+    onFailure?: "fail" | "warn" | "continue";
+}
+type WebFetchEngine = "auto" | "native" | "exa" | "openrouter" | "firecrawl" | "parallel";
+interface WebFetchPolicy {
+    mode: ToolMode;
+    engine?: WebFetchEngine;
+    maxUses?: number;
+    maxContentTokens?: number;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    onFailure?: "fail" | "warn" | "continue";
+}
+interface DatetimePolicy {
+    mode: ToolMode;
+    timezone?: string;
+}
+interface ImageGenerationPolicy {
+    mode: ToolMode;
+    model?: string;
+    quality?: "low" | "medium" | "high" | string;
+    size?: string;
+    aspectRatio?: string;
+    background?: "transparent" | "opaque" | string;
+    outputFormat?: "png" | "jpeg" | "webp" | string;
+    outputCompression?: number;
+    moderation?: "auto" | "low" | string;
+}
+interface ApplyPatchPolicy {
+    mode: ToolMode;
+    behavior?: "return_only" | "apply_with_callback";
+    workspaceRoot?: string;
+    allowDelete?: boolean;
+    allowCreate?: boolean;
+    allowUpdate?: boolean;
+}
+interface FusionPolicy {
+    mode: ToolMode;
+    analysisModels?: string[];
+    judgeModel?: string;
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    reasoning?: RuntimeReasoningConfig;
+    temperature?: number;
+}
+interface AdvisorPolicy {
+    mode: ToolMode;
+    name?: string;
+    model?: string;
+    instructions?: string;
+    tools?: NestedOpenRouterServerToolPolicy[];
+    forwardTranscript?: boolean;
+    stream?: boolean;
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    reasoning?: RuntimeReasoningConfig;
+    temperature?: number;
+}
+interface SubagentPolicy {
+    mode: ToolMode;
+    model?: string;
+    instructions?: string;
+    tools?: NestedOpenRouterServerToolPolicy[];
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    reasoning?: RuntimeReasoningConfig;
+    temperature?: number;
+}
+type NestedOpenRouterServerToolPolicy = {
+    type: "openrouter:web_search";
+    parameters?: Record<string, unknown>;
+} | {
+    type: "openrouter:web_fetch";
+    parameters?: Record<string, unknown>;
+} | {
+    type: "openrouter:datetime";
+    parameters?: Record<string, unknown>;
+} | {
+    type: "openrouter:image_generation";
+    parameters?: Record<string, unknown>;
+};
+interface RuntimeFunctionToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    executor?: RuntimeToolExecutor;
+}
+type RuntimeToolExecutor = (args: unknown, context: RuntimeToolExecutionContext) => Promise<unknown> | unknown;
+interface RuntimeToolExecutionContext {
+    requestId: string;
+    toolName: string;
+    callId: string;
+    metadata?: Record<string, unknown>;
+}
+interface RuntimeToolRegistry {
+    [toolName: string]: RuntimeToolExecutor;
+}
+interface RuntimeExecutionPolicy {
+    maxToolIterations?: number;
+    maxServerToolCalls?: number;
+    maxFunctionToolCalls?: number;
+    timeoutMs?: number;
+}
+type RuntimeToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    functionName: string;
+} | {
+    type: "server_tool";
+    serverTool: "web_search" | "web_fetch" | "datetime" | "image_generation" | "apply_patch" | "fusion" | "advisor" | "subagent";
+};
+interface RuntimeCitation {
+    type: "url";
+    url: string;
+    title?: string;
+    excerpt?: string;
+    startIndex?: number;
+    endIndex?: number;
+    sourceProvider: "openrouter";
+    raw?: unknown;
+}
+interface RuntimeGeneratedImage {
+    imageUrl: string;
+    status: "ok" | "error";
+    error?: string;
+    raw?: unknown;
+}
+interface RuntimeUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    costUsd?: number;
+    raw?: unknown;
+}
+interface RuntimeToolUsage {
+    serverTools: Record<ServerToolKey, ServerToolUsage>;
+    functionTools: RuntimeFunctionToolUsage[];
+}
+type ServerToolKey = "webSearch" | "webFetch" | "datetime" | "imageGeneration" | "applyPatch" | "fusion" | "advisor" | "subagent";
+interface ServerToolUsage {
+    requested: boolean;
+    required: boolean;
+    used: boolean;
+    callCount?: number;
+    policyViolation?: string;
+}
+interface RuntimeFunctionToolUsage {
+    name: string;
+    callId: string;
+    status: "completed" | "failed";
+    args?: unknown;
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+}
+interface RuntimePatchProposal {
+    callId: string;
+    status: "completed" | "failed";
+    operation: RuntimeCreateFilePatch | RuntimeUpdateFilePatch | RuntimeDeleteFilePatch;
+    raw: unknown;
+}
+interface RuntimeCreateFilePatch {
+    type: "create_file";
+    path: string;
+    diff: string;
+}
+interface RuntimeUpdateFilePatch {
+    type: "update_file";
+    path: string;
+    diff: string;
+}
+interface RuntimeDeleteFilePatch {
+    type: "delete_file";
+    path: string;
+}
+interface RuntimeError {
+    code: string;
+    message: string;
+    source: "runtime" | "validation" | "openrouter" | "tool_executor" | "policy";
+    retryable?: boolean;
+    details?: unknown;
+}
+interface RuntimeWarning {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+interface RuntimeLogger {
+    debug?(event: string, data?: unknown): void;
+    info?(event: string, data?: unknown): void;
+    warn?(event: string, data?: unknown): void;
+    error?(event: string, data?: unknown): void;
+}
+interface RuntimeHooks {
+    beforeCompile?(request: RuntimeRequest): Promise<void> | void;
+    afterCompile?(compiled: CompiledOpenRouterRequest): Promise<void> | void;
+    beforeOpenRouterRequest?(compiled: CompiledOpenRouterRequest): Promise<void> | void;
+    afterOpenRouterResponse?(response: unknown): Promise<void> | void;
+    beforeFunctionToolExecution?(call: RuntimeFunctionToolCall): Promise<void> | void;
+    afterFunctionToolExecution?(result: RuntimeFunctionToolResult): Promise<void> | void;
+    onPolicyViolation?(violation: RuntimePolicyViolation): Promise<void> | void;
+}
+interface CompiledOpenRouterRequest {
+    apiMode: ResolvedApiMode;
+    url: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+    warnings: RuntimeWarning[];
+}
+interface RuntimeFunctionToolCall {
+    name: string;
+    callId: string;
+    args: unknown;
+}
+interface RuntimeFunctionToolResult {
+    name: string;
+    callId: string;
+    status: "completed" | "failed";
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+}
+interface RuntimePolicyViolation {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+interface RuntimeStreamEvent {
+    type: string;
+    data?: unknown;
+}
+type RuntimePatchApplier = (patch: RuntimePatchProposal) => Promise<unknown> | unknown;
+
+declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): OpenRouterRuntime;
+
+declare function compileRuntimeRequest(request: RuntimeRequest, defaults: RuntimeDefaults, options?: OpenRouterRuntimeOptions): CompiledOpenRouterRequest;
+
+declare class RuntimeConfigError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(code: string, message: string, details?: unknown | undefined);
+}
+declare class OpenRouterHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body?: unknown | undefined;
+    readonly retryable: boolean;
+    constructor(status: number, code: string, message: string, body?: unknown | undefined, retryable?: boolean);
+}
+
+interface OpenRouterTool {
+    type: string;
+    function?: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+    parameters?: Record<string, unknown>;
+}
+
+declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy): OpenRouterTool[];
+
+export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeMessage, type RuntimePatchProposal, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createOpenRouterRuntime };