@infinityi/engine-lib 1.0.0

package/dist/lifecycle/index.js

@@ -0,0 +1,72 @@
+// src/lifecycle/component.ts
+var DEFAULT_NAME = "agent-runtime";
+function validateProviders(providers) {
+  const seen = new Set;
+  for (const provider of providers) {
+    if (typeof provider.name !== "string" || provider.name.trim() === "") {
+      throw new Error("agentRuntimeComponent: every provider must have a non-empty name");
+    }
+    if (seen.has(provider.name)) {
+      throw new Error(`agentRuntimeComponent: duplicate provider name "${provider.name}"`);
+    }
+    seen.add(provider.name);
+    if (typeof provider.defaultModel !== "string" || provider.defaultModel.trim() === "") {
+      throw new Error(`agentRuntimeComponent: provider "${provider.name}" has an empty defaultModel`);
+    }
+  }
+}
+async function probeAll(providers, probe, signal) {
+  const failures = [];
+  for (const provider of providers) {
+    try {
+      await probe(provider, signal);
+    } catch (error) {
+      failures.push({ name: provider.name, error });
+    }
+  }
+  return failures;
+}
+function agentRuntimeComponent(opts) {
+  const name = opts.name ?? DEFAULT_NAME;
+  const providers = opts.providers ?? [];
+  const { probe, onStop } = opts;
+  return {
+    name,
+    async start(ctx) {
+      validateProviders(providers);
+      if (opts.probeOnStart === true && probe !== undefined) {
+        const failures = await probeAll(providers, probe, ctx.signal);
+        if (failures.length > 0) {
+          const names = failures.map((f) => f.name).join(", ");
+          throw new Error(`agentRuntimeComponent: provider probe failed on start for: ${names}`);
+        }
+      }
+      ctx.logger.info("agent runtime started", {
+        providers: providers.length,
+        sessionStore: opts.sessionStore !== undefined
+      });
+    },
+    async stop(ctx) {
+      if (onStop !== undefined)
+        await onStop(ctx.signal);
+      ctx.logger.info("agent runtime stopped");
+    },
+    async healthcheck(ctx) {
+      if (probe === undefined || providers.length === 0) {
+        return { status: "healthy", data: { providers: providers.length } };
+      }
+      const failures = await probeAll(providers, probe, ctx.signal);
+      const status = failures.length === 0 ? "healthy" : failures.length < providers.length ? "degraded" : "unhealthy";
+      const result = {
+        status,
+        data: { providers: providers.length, unhealthy: failures.length }
+      };
+      if (failures.length === 0)
+        return result;
+      return { ...result, detail: `provider probe failed: ${failures.map((f) => f.name).join(", ")}` };
+    }
+  };
+}
+export {
+  agentRuntimeComponent
+};

package/dist/messages/factory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Constructors and normalization helpers for the message model.
+ *
+ * {@link normalizeContent} is the single seam that coerces a bare string
+ * into `[text(string)]`, so every other factory and (later) provider
+ * adapter can assume `content` is always an array of parts.
+ *
+ * @module
+ */
+import type { ContentPart, Message, TextPart } from "./types";
+/** A {@link TextPart}. */
+export declare function text(value: string): TextPart;
+/** Coerce `string` → `[text(string)]`; pass part arrays through unchanged. */
+export declare function normalizeContent(content: string | ContentPart[]): ContentPart[];
+/** A `system` message. */
+export declare function system(content: string): Message;
+/** A `user` message. */
+export declare function user(content: string | ContentPart[]): Message;
+/** An `assistant` message. */
+export declare function assistant(content: string | ContentPart[]): Message;
+/** A `tool` message carrying the result of a single tool call. */
+export declare function toolResult(toolCallId: string, output: string | TextPart[], opts?: {
+    isError?: boolean;
+}): Message;

package/dist/messages/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@infinityi/engine-lib/messages` — the provider-neutral conversation model and its
+ * constructors.
+ *
+ * @module
+ */
+export { assistant, normalizeContent, system, text, toolResult, user, } from "./factory";
+export type { ContentPart, ImagePart, Message, Role, TextPart, ToolCallPart, ToolResultPart, } from "./types";

package/dist/messages/index.js

@@ -0,0 +1,17 @@
+import"../index-19pwq79t.js";
+import {
+  assistant,
+  normalizeContent,
+  system,
+  text,
+  toolResult,
+  user
+} from "../index-1p6mb2vz.js";
+export {
+  user,
+  toolResult,
+  text,
+  system,
+  normalizeContent,
+  assistant
+};

package/dist/messages/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The provider-neutral conversation model.
+ *
+ * Messages and their content parts are normalized so that history is
+ * portable across providers (Phase 2 adapters translate to/from each
+ * provider's native shape). `content` is *always* an array of parts.
+ *
+ * @module
+ */
+/** Who authored a message. */
+export type Role = "system" | "user" | "assistant" | "tool";
+/** Plain text. */
+export interface TextPart {
+    readonly type: "text";
+    readonly text: string;
+}
+/** An assistant request to invoke a tool. `arguments` is the raw (unvalidated) model output. */
+export interface ToolCallPart {
+    readonly type: "tool_call";
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: unknown;
+}
+/**
+ * The outcome of a tool invocation, fed back to the model.
+ *
+ * Phase 3's structured `ToolResult` schema maps *into* this part; kept
+ * minimal here so Phase 1 carries no forward dependency.
+ */
+export interface ToolResultPart {
+    readonly type: "tool_result";
+    readonly toolCallId: string;
+    readonly content: TextPart[];
+    readonly isError?: boolean;
+}
+/** Image input. `data` is a base64 payload or a URL. */
+export interface ImagePart {
+    readonly type: "image";
+    readonly mimeType: string;
+    readonly data: string;
+}
+/** Any content part a message may carry. */
+export type ContentPart = TextPart | ToolCallPart | ToolResultPart | ImagePart;
+/** A single normalized message. */
+export interface Message {
+    readonly role: Role;
+    readonly content: ContentPart[];
+    /** Optional author/tool name (e.g. for `role: "tool"`). */
+    readonly name?: string;
+    /** Free-form, host-defined metadata (never sent to providers). */
+    readonly metadata?: Record<string, unknown>;
+}

package/dist/providers/adapter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared adapter scaffolding for custom providers.
+ *
+ * {@link createProvider} turns a small per-vendor {@link AdapterSpec} (how to
+ * build the request body, where to POST it, how to parse the response, and how
+ * to translate the SSE stream) into a full {@link Provider}, centralizing the
+ * forge HTTP/resilience plumbing so each adapter stays focused on mapping.
+ *
+ * This is an advanced extension surface exported from `@infinityi/engine-lib/providers`;
+ * ordinary application code should prefer the built-in provider factories.
+ *
+ * @module
+ */
+import type { ProviderHttpOptions } from "./http";
+import type { SseMessage } from "./sse";
+import type { StreamEvent } from "./stream";
+import type { CompletionRequest, CompletionResult, Provider, ProviderCapabilities } from "./types";
+/** Per-vendor behavior consumed by {@link createProvider}. */
+export interface AdapterSpec {
+    readonly name: string;
+    readonly defaultModel: string;
+    readonly capabilities: ProviderCapabilities;
+    /** Base transport options (baseUrl, headers, timeout, resilience, fetch). */
+    readonly http: ProviderHttpOptions;
+    /** Path for a buffered completion, resolved against `baseUrl`. */
+    completePath(model: string, req: CompletionRequest): string;
+    /** Path for a streaming completion, resolved against `baseUrl`. */
+    streamPath(model: string, req: CompletionRequest): string;
+    /** Build the provider-native request body. */
+    buildBody(req: CompletionRequest, model: string, stream: boolean): unknown;
+    /** Parse a buffered provider response into the normalized result. */
+    parseResponse(raw: unknown, model: string): CompletionResult;
+    /** Translate the provider's SSE messages into unified {@link StreamEvent}s. */
+    translateStream(messages: AsyncIterable<SseMessage>, model: string): AsyncIterable<StreamEvent>;
+}
+/**
+ * Build a {@link Provider} from an {@link AdapterSpec}.
+ *
+ * Use this for third-party adapters that want engine-lib's normalized
+ * completion/streaming shape plus Forge-backed HTTP, resilience, and telemetry.
+ */
+export declare function createProvider(spec: AdapterSpec): Provider;

package/dist/providers/anthropic/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anthropic provider adapter — the **Messages** API
+ * (`POST {baseUrl}/messages`).
+ *
+ * @module
+ */
+import type { Secret } from "@infinityi/forge/config";
+import type { FetchLike, PipelineLike } from "@infinityi/forge/http/client";
+import type { Provider } from "../types";
+/** Construction options for the Anthropic adapter. */
+export interface AnthropicOptions {
+    readonly apiKey: string | Secret<string>;
+    /** Model used when a request omits `model`. Default `"claude-opus-4-7"`. */
+    readonly model?: string;
+    /** Override the API base URL. Default `"https://api.anthropic.com/v1"`. */
+    readonly baseUrl?: string;
+    /** `anthropic-version` header. Default `"2023-06-01"`. */
+    readonly version?: string;
+    readonly timeoutMs?: number;
+    readonly resilience?: PipelineLike;
+    readonly fetch?: FetchLike;
+    readonly defaultHeaders?: Record<string, string>;
+}
+/**
+ * Create an Anthropic (Messages API) {@link Provider}.
+ *
+ * `apiKey` may be a raw string or Forge `Secret`. `model` becomes the
+ * provider's `defaultModel`; callers can still override `CompletionRequest.model`
+ * per request.
+ */
+export declare function createAnthropic(opts: AnthropicOptions): Provider;

package/dist/providers/anthropic/map.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mapping between the Phase-1 message model and the Anthropic **Messages** API.
+ *
+ * @module
+ */
+import type { CompletionRequest, CompletionResult, FinishReason } from "../types";
+/** Build an Anthropic `POST /messages` request body. */
+export declare function buildAnthropicBody(req: CompletionRequest, model: string, stream: boolean): unknown;
+/** Map an Anthropic `stop_reason` to a normalized {@link FinishReason}. */
+export declare function mapStopReason(stopReason: string | null | undefined, hadToolCalls: boolean): FinishReason;
+/** Parse an Anthropic message response into a {@link CompletionResult}. */
+export declare function parseAnthropicResponse(raw: unknown, model: string): CompletionResult;

package/dist/providers/anthropic/stream.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Translate Anthropic Messages SSE events into the unified stream.
+ *
+ * @module
+ */
+import type { SseMessage } from "../sse";
+import type { StreamEvent } from "../stream";
+/** Translate Anthropic SSE messages into {@link StreamEvent}s. */
+export declare function translateAnthropicStream(messages: AsyncIterable<SseMessage>, model: string): AsyncIterable<StreamEvent>;

package/dist/providers/google/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Google Gemini provider adapter — the **generateContent** API
+ * (`POST {baseUrl}/models/{model}:generateContent`).
+ *
+ * @module
+ */
+import type { Secret } from "@infinityi/forge/config";
+import type { FetchLike, PipelineLike } from "@infinityi/forge/http/client";
+import type { Provider } from "../types";
+/** Construction options for the Google Gemini adapter. */
+export interface GoogleOptions {
+    readonly apiKey: string | Secret<string>;
+    /** Model used when a request omits `model`. Default `"gemini-2.5-pro"`. */
+    readonly model?: string;
+    /** Override the API base URL. Default `"https://generativelanguage.googleapis.com/v1beta"`. */
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly resilience?: PipelineLike;
+    readonly fetch?: FetchLike;
+    readonly defaultHeaders?: Record<string, string>;
+}
+/**
+ * Create a Google Gemini (generateContent API) {@link Provider}.
+ *
+ * `apiKey` may be a raw string or Forge `Secret`. `model` becomes the
+ * provider's `defaultModel`; callers can still override `CompletionRequest.model`
+ * per request.
+ */
+export declare function createGoogle(opts: GoogleOptions): Provider;

package/dist/providers/google/map.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mapping between the Phase-1 message model and the Google Gemini
+ * **generateContent** API.
+ *
+ * @module
+ */
+import type { CompletionRequest, CompletionResult, FinishReason } from "../types";
+/** Build a Gemini generateContent request body. */
+export declare function buildGoogleBody(req: CompletionRequest, _model: string, _stream: boolean): unknown;
+/** Map a Gemini `finishReason` to a normalized {@link FinishReason}. */
+export declare function mapGoogleFinish(reason: string | undefined, hadToolCalls: boolean): FinishReason;
+/** Parse a Gemini generateContent response into a {@link CompletionResult}. */
+export declare function parseGoogleResponse(raw: unknown, model: string): CompletionResult;

package/dist/providers/google/stream.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Translate Gemini `streamGenerateContent?alt=sse` chunks into the unified
+ * stream. Gemini delivers whole `functionCall`s per chunk (no incremental
+ * argument deltas), so each is emitted as a start/delta/end triple.
+ *
+ * @module
+ */
+import type { SseMessage } from "../sse";
+import type { StreamEvent } from "../stream";
+/** Translate Gemini SSE chunks into {@link StreamEvent}s. */
+export declare function translateGoogleStream(messages: AsyncIterable<SseMessage>, model: string): AsyncIterable<StreamEvent>;

package/dist/providers/http.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Provider HTTP transport, built on `forge/http/client` + `forge/resilience`.
+ *
+ * Adapters call {@link createProviderHttp} to get a `fetch` wrapper that is
+ * resilient (retry + timeout) and traced (via the {@link EngineContext}
+ * telemetry handle) by composition — exactly the forge pattern. Non-2xx
+ * responses are parsed into errors and re-thrown as {@link ProviderError} by
+ * {@link toProviderError}.
+ *
+ * @module
+ */
+import type { FetchLike, HttpClient, PipelineLike } from "@infinityi/forge/http/client";
+import { ProviderError } from "../errors";
+import type { EngineContext } from "../runtime/types";
+/** Default per-request timeout for provider calls. */
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+/** Construction options for a provider's HTTP transport. */
+export interface ProviderHttpOptions {
+    /** Provider base URL (e.g. `https://api.openai.com/v1`). */
+    readonly baseUrl: string;
+    /** Headers merged into every request (auth + version), already resolved. */
+    readonly headers: Record<string, string>;
+    /** Per-request timeout. Default {@link DEFAULT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Override the default resilience pipeline. */
+    readonly resilience?: PipelineLike;
+    /** Inject a `fetch` implementation (tests / pre-wrapped fetch). */
+    readonly fetch?: FetchLike;
+    /** Allow request URLs to resolve to a different origin than `baseUrl`. */
+    readonly allowAbsoluteUrls?: boolean;
+}
+/**
+ * The default provider resilience pipeline: up to 3 attempts with exponential
+ * backoff, each bounded by `timeoutMs`. Only transient failures are retried.
+ */
+export declare function defaultProviderResilience(timeoutMs: number): PipelineLike;
+/**
+ * Build a forge {@link HttpClient} for a provider, wiring telemetry/logger from
+ * the {@link EngineContext} and a default resilience pipeline.
+ */
+export declare function createProviderHttp(opts: ProviderHttpOptions, ctx?: EngineContext): HttpClient;
+/** A streaming request the adapter wants to open. */
+export interface SseRequest {
+    /** Request path, resolved against `baseUrl`. */
+    readonly path: string;
+    /** JSON request body (serialized here). */
+    readonly body: unknown;
+    /** Caller cancellation signal. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Open a streaming (SSE) provider request and return the raw body stream.
+ *
+ * The connection attempt is wrapped in the resilience pipeline (retry +
+ * timeout bound *time-to-headers*; once the response resolves the timeout is
+ * settled and never aborts the in-flight body). Non-2xx responses are mapped
+ * to {@link ProviderError}.
+ */
+export declare function openSseStream(provider: string, opts: ProviderHttpOptions, req: SseRequest, ctx?: EngineContext): Promise<ReadableStream<Uint8Array>>;
+/** Wrap any thrown HTTP/transport error as a {@link ProviderError}. */
+export declare function toProviderError(provider: string, error: unknown): ProviderError;

package/dist/providers/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@infinityi/engine-lib/providers` — the unified LLM provider surface.
+ *
+ * Re-exports the normalized {@link Provider} contract, the streaming model, the
+ * four shipped adapters ({@link createOpenAI}, {@link createAnthropic},
+ * {@link createGoogle}, {@link createOpenAICompatible}), and advanced adapter
+ * plumbing.
+ *
+ * Most applications should import provider factories from the root package or
+ * from this subpath. `createProvider`, HTTP/SSE helpers, and stream
+ * accumulation utilities are for custom provider adapters and conformance
+ * tests; they are intentionally not re-exported from the root barrel.
+ *
+ * @module
+ */
+export type { CompletionRequest, CompletionResult, FinishReason, Provider, ProviderCapabilities, ProviderTool, ResponseSchema, ToolCall, ToolChoice, Usage, } from "./types";
+export type { StreamEvent } from "./stream";
+export { collectStream, StreamAccumulator } from "./stream";
+export { createProviderHttp, defaultProviderResilience, openSseStream, toProviderError, DEFAULT_TIMEOUT_MS, } from "./http";
+export type { ProviderHttpOptions, SseRequest } from "./http";
+export { parseSse } from "./sse";
+export type { SseMessage } from "./sse";
+export { createProvider } from "./adapter";
+export type { AdapterSpec } from "./adapter";
+export { createOpenAI } from "./openai/index";
+export type { OpenAIOptions } from "./openai/index";
+export { createAnthropic } from "./anthropic/index";
+export type { AnthropicOptions } from "./anthropic/index";
+export { createGoogle } from "./google/index";
+export type { GoogleOptions } from "./google/index";
+export { createOpenAICompatible } from "./openai-compatible/index";
+export type { OpenAICompatibleOptions } from "./openai-compatible/index";

package/dist/providers/index.js

@@ -0,0 +1,35 @@
+import {
+  DEFAULT_TIMEOUT_MS,
+  createAnthropic,
+  createGoogle,
+  createOpenAI,
+  createOpenAICompatible,
+  createProvider,
+  createProviderHttp,
+  defaultProviderResilience,
+  openSseStream,
+  parseSse,
+  toProviderError
+} from "../index-64tt9696.js";
+import"../index-bqg01r42.js";
+import"../index-xsv43c5j.js";
+import {
+  StreamAccumulator,
+  collectStream
+} from "../index-zfgr4xx3.js";
+import"../index-7690reng.js";
+export {
+  toProviderError,
+  parseSse,
+  openSseStream,
+  defaultProviderResilience,
+  createProviderHttp,
+  createProvider,
+  createOpenAICompatible,
+  createOpenAI,
+  createGoogle,
+  createAnthropic,
+  collectStream,
+  StreamAccumulator,
+  DEFAULT_TIMEOUT_MS
+};

package/dist/providers/openai/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OpenAI provider adapter — the **Responses** API
+ * (`POST {baseUrl}/responses`).
+ *
+ * @module
+ */
+import type { Secret } from "@infinityi/forge/config";
+import type { PipelineLike, FetchLike } from "@infinityi/forge/http/client";
+import type { Provider } from "../types";
+/** Construction options shared by the OpenAI adapter. */
+export interface OpenAIOptions {
+    /** API key (raw string or a forge `Secret`). */
+    readonly apiKey: string | Secret<string>;
+    /** Model used when a request omits `model`. Default `"gpt-5"`. */
+    readonly model?: string;
+    /** Override the API base URL. Default `"https://api.openai.com/v1"`. */
+    readonly baseUrl?: string;
+    /** Per-request timeout (ms). */
+    readonly timeoutMs?: number;
+    /** Override the resilience pipeline. */
+    readonly resilience?: PipelineLike;
+    /** Inject a `fetch` implementation (tests). */
+    readonly fetch?: FetchLike;
+    /** Extra headers merged into every request. */
+    readonly defaultHeaders?: Record<string, string>;
+}
+/**
+ * Create an OpenAI (Responses API) {@link Provider}.
+ *
+ * `apiKey` may be a raw string or Forge `Secret`. `model` becomes the
+ * provider's `defaultModel`; callers can still override `CompletionRequest.model`
+ * per request.
+ */
+export declare function createOpenAI(opts: OpenAIOptions): Provider;

package/dist/providers/openai/map.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mapping between the Phase-1 message model and the OpenAI **Responses** API.
+ *
+ * @module
+ */
+import type { CompletionRequest, CompletionResult } from "../types";
+/** Build a Responses `POST /responses` request body. */
+export declare function buildOpenAIBody(req: CompletionRequest, model: string, stream: boolean): unknown;
+/** Parse a Responses response object into a {@link CompletionResult}. */
+export declare function parseOpenAIResponse(raw: unknown, model: string): CompletionResult;

package/dist/providers/openai/stream.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Translate OpenAI Responses SSE events into the unified stream.
+ *
+ * @module
+ */
+import type { SseMessage } from "../sse";
+import type { StreamEvent } from "../stream";
+/** Translate Responses SSE messages into {@link StreamEvent}s. */
+export declare function translateOpenAIStream(messages: AsyncIterable<SseMessage>, model: string): AsyncIterable<StreamEvent>;

package/dist/providers/openai-compatible/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Generic OpenAI-compatible provider adapter — the **Chat Completions** API
+ * (`POST {baseUrl}/chat/completions`). Targets vLLM, Together, Groq,
+ * OpenRouter, LM Studio, and anything else speaking that wire format.
+ *
+ * @module
+ */
+import type { Secret } from "@infinityi/forge/config";
+import type { FetchLike, PipelineLike } from "@infinityi/forge/http/client";
+import type { Provider, ProviderCapabilities } from "../types";
+/** Construction options for the OpenAI-compatible adapter. */
+export interface OpenAICompatibleOptions {
+    /** Required base URL for the OpenAI-compatible server (e.g. `https://api.together.xyz/v1`). */
+    readonly baseUrl: string;
+    /** API key (raw string or a forge `Secret`). Optional for keyless local servers. */
+    readonly apiKey?: string | Secret<string>;
+    /** Adapter name, surfaced on the {@link Provider} and in errors. Default `"openai-compatible"`. */
+    readonly name?: string;
+    /** Model used when a request omits `model`. */
+    readonly model: string;
+    readonly timeoutMs?: number;
+    readonly resilience?: PipelineLike;
+    readonly fetch?: FetchLike;
+    readonly defaultHeaders?: Record<string, string>;
+    /** Override the declared capabilities (servers vary in tool/stream support). */
+    readonly capabilities?: Partial<ProviderCapabilities>;
+}
+/**
+ * Create a generic OpenAI-compatible (Chat Completions) {@link Provider}.
+ *
+ * `apiKey` may be omitted for local/keyless servers or supplied as a raw string
+ * or Forge `Secret`. `model` becomes the provider's `defaultModel`; callers can
+ * still override `CompletionRequest.model` per request. Use `capabilities` to
+ * honestly describe the target server when it lacks tool, stream, multimodal,
+ * parallel-tool, or structured-output support.
+ */
+export declare function createOpenAICompatible(opts: OpenAICompatibleOptions): Provider;

package/dist/providers/openai-compatible/map.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mapping between the Phase-1 message model and the OpenAI-compatible
+ * **Chat Completions** API (vLLM, Together, Groq, OpenRouter, …).
+ *
+ * @module
+ */
+import type { CompletionRequest, CompletionResult, FinishReason } from "../types";
+/** Build a Chat Completions request body. */
+export declare function buildChatBody(req: CompletionRequest, model: string, stream: boolean): unknown;
+/** Map a Chat Completions `finish_reason` to a normalized {@link FinishReason}. */
+export declare function mapChatFinish(reason: string | undefined, hadToolCalls: boolean): FinishReason;
+/** Parse a Chat Completions response into a {@link CompletionResult}. */
+export declare function parseChatResponse(raw: unknown, model: string): CompletionResult;

package/dist/providers/openai-compatible/stream.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Translate OpenAI-compatible Chat Completions SSE chunks into the unified
+ * stream. Tool-call arguments arrive incrementally and are keyed by the
+ * provider's `tool_calls[].index`.
+ *
+ * @module
+ */
+import type { SseMessage } from "../sse";
+import type { StreamEvent } from "../stream";
+/** Translate Chat Completions SSE chunks into {@link StreamEvent}s. */
+export declare function translateChatStream(messages: AsyncIterable<SseMessage>, model: string): AsyncIterable<StreamEvent>;

package/dist/providers/shared.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Small mapping helpers shared by the provider adapters.
+ *
+ * @module
+ */
+import type { ImagePart, Message, TextPart, ToolCallPart, ToolResultPart } from "../messages/types";
+import type { FinishReason } from "./types";
+/**
+ * Resolve an {@link ImagePart} to a value usable in an `image_url`-style field:
+ * an `http(s)` URL is passed through, raw base64 is wrapped as a `data:` URI.
+ */
+export declare function imageDataUrl(part: ImagePart): string;
+/** Concatenated text of every `system` message, or `undefined` if none. */
+export declare function systemText(messages: readonly Message[]): string | undefined;
+/** Messages excluding `system` (which providers carry out-of-band). */
+export declare function withoutSystem(messages: readonly Message[]): Message[];
+/** Join the text of a tool-result's content parts. */
+export declare function toolResultText(part: ToolResultPart): string;
+/** Type guards for content parts. */
+export declare const isText: (p: {
+    type: string;
+}) => p is TextPart;
+export declare const isToolCall: (p: {
+    type: string;
+}) => p is ToolCallPart;
+export declare const isToolResult: (p: {
+    type: string;
+}) => p is ToolResultPart;
+/** Parse a JSON arguments string, tolerating empty/invalid input. */
+export declare function parseJsonArguments(text: string): unknown;
+/** Serialize tool-call arguments to the JSON string providers expect. */
+export declare function stringifyArguments(value: unknown): string;
+/** A `finish`-style normalization shared where vendors use the same buckets. */
+export declare function defaultFinish(hadToolCalls: boolean, base: FinishReason): FinishReason;

package/dist/providers/sse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A minimal Server-Sent Events reader for provider streaming endpoints.
+ *
+ * Decodes a `ReadableStream<Uint8Array>` (the `res.raw.body` of a streaming
+ * provider response) into `{ event?, data }` records, handling multi-line
+ * `data:` fields, `event:` names, comment lines, and CRLF/LF newlines per the
+ * SSE spec. Adapters parse each record's `data` as the provider's JSON event.
+ *
+ * @module
+ */
+/** One dispatched SSE message. */
+export interface SseMessage {
+    /** The `event:` name, if the stream set one. */
+    readonly event?: string;
+    /** The concatenated `data:` payload (lines joined with `\n`). */
+    readonly data: string;
+}
+/** Decode an SSE byte stream into dispatched {@link SseMessage}s. */
+export declare function parseSse(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseMessage>;