Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Core LLM transport types.
*
* `SingleTurnProvider` and `ClassifiedError` live here (rather than in
* `./index`) to break the import cycle introduced by the provider registry:
* the factory (`registry.ts`) returns `SingleTurnProvider`, and the interface's
* `getProviderType()` references `LlmProvider`, which `registryCore.ts` derives.
* This module imports only `LlmProvider` (type-only) from `registryCore` and is
* otherwise dependency-free, so `registryCore`, `registry`, and `index` can all
* import these interfaces without a runtime cycle.
*
* `index.ts` re-exports both names so the ~11 existing import sites
* (`import { SingleTurnProvider, ClassifiedError } from '../llm'`) stay
* untouched.
*/
import { LlmErrorCode } from '../core/errors'
import type { SystemPromptParts } from '../core/reasoning/systemPrompt'
import {
CompletionResponse,
ChatMessage as CoreChatMessage,
ToolCompletionResponse,
ToolDefinition,
} from '../core/types'
import type { VisualDeliveryLimits } from '../visualInput/deliveryLimits'
import type { ImageTransportOperation } from './imageInput'
import type { LlmProvider } from './registryCore'
/**
* A structured classification of an error thrown by a provider's SDK.
* Produced by SingleTurnProvider.classifyError() and used by LlmPortAdapter
* to construct the downstream LlmError.
*
* `message` is the raw provider message, passed through verbatim (no
* reformatting).
*/
export interface ClassifiedError {
code: LlmErrorCode
retryable: boolean
message: string
/**
* Additive diagnostics (spec 02, Pieza A). The provider's HTTP status and the
* provider-native error code/type (e.g. `not_found_error`, `1211`,
* `Model.AccessDenied`) when the classifier recovered them. Threaded verbatim
* through `LlmError` → `TaskError` so downstream (desktop) can distinguish a
* retired-model 404 from an ambiguous failure without re-parsing the raw SDK
* error. Optional: transport/unknown errors leave them undefined.
*/
httpStatus?: number
providerCode?: string
/**
* Execution-phase signal. `false` means the classifier PROVED that no call
* left this process (the attempt died before authorize or before the proxy
* stream), so the physical attempt cannot have billed. `true` means a call
* left the process or may have. `undefined` means the classifier does not
* know — consumers must assume the expensive direction (dispatched).
*
* Only a classifier that can prove the negative may set `false`: marking a
* dispatched attempt as `false` would leave the idempotency key revivable
* and permit a second billable call.
*/
providerDispatched?: boolean
}
/**
* Single-turn LLM transport. No loop, no tool execution.
*/
export interface SingleTurnProvider {
/** The request contract binds distinct image sources, even when their bytes repeat. */
readonly requiresImageSourceIdentity?: boolean
completeSingleTurn(
messages: CoreChatMessage[],
options?: { max_tokens?: number; temperature?: number; signal?: AbortSignal }
): Promise<CompletionResponse>
completeSingleTurnWithTools(
messages: CoreChatMessage[],
tools: ToolDefinition[],
options?: {
max_tokens?: number
temperature?: number
tool_choice?: string
signal?: AbortSignal
verifyImageInput?: boolean
}
): Promise<ToolCompletionResponse>
getProviderType(): LlmProvider
/** The current transport instance's verified visual contract, never a primary fallback profile. */
getVisualDeliveryLimits?(operation: ImageTransportOperation): VisualDeliveryLimits | null
/**
* Classify an error thrown by this provider's SDK into a structured
* ClassifiedError. Must never throw. Must always return a valid value —
* fall back to classifyUnknown(err) if the error shape is unrecognized.
*/
classifyError(err: unknown): ClassifiedError
/**
* T2.2 — Optional cache-aware completion. When the provider implements it,
* `LlmPortAdapter` forwards `request.systemPromptParts` here so the
* provider can emit native cache markers (Anthropic `cache_control` on the
* `system` array). Providers without explicit cache support (OpenAI / ZAI /
* Bailian) leave it undefined; the adapter concats the parts into a single
* `system` string and calls `completeSingleTurnWithTools` instead.
*/
completeSingleTurnWithToolsAndCache?(
parts: SystemPromptParts,
messages: CoreChatMessage[],
tools: ToolDefinition[],
options?: {
max_tokens?: number
temperature?: number
tool_choice?: string
signal?: AbortSignal
verifyImageInput?: boolean
}
): Promise<ToolCompletionResponse>
/**
* T2.2 — Optional cache-aware completion without tools. Symmetric to
* `completeSingleTurnWithToolsAndCache` but for the tool-less path.
*/
completeSingleTurnAndCache?(
parts: SystemPromptParts,
messages: CoreChatMessage[],
options?: { max_tokens?: number; temperature?: number; signal?: AbortSignal }
): Promise<CompletionResponse>
}