A local-first multi-agent app development platform, built on PenguinHarness
/**
* What the LLM side needs: the contract `context_engine` drives one model request through.
*
* The engine calls exactly one method here — `streamGenerate` — and reads exactly two things
* back: the yielded OmniMessage stream, and the generator's `LLMOutcome` return value (the
* request's terminal state; see the docs page's "control plane"). Protocol conversion to and
* from the provider is the implementation's own business.
*
* Docs: packages/docs/content/interfaces.{zh,en}.md (site path /docs/interfaces).
*/
import type { ErrorCode, OmniMessage, StopReason, ToolDefinition } from "../omnimessage/types.js";
import type { ThinkingLevelName } from "./shared.js";
// Concrete class, used only as a type annotation (type-only import; no runtime dependency, no circular reference).
import type { ToolCallIdAllocator } from "../llm/tool-call-ids.js";
/**
* GenerativeModel initialization config.
* Docs: /docs/interfaces § "GenerativeModelConfig".
*/
export interface GenerativeModelConfig {
modelId: string;
apiKey?: string;
/**
* Optional host-owned credential resolver, called before every upstream request. When it
* returns a different key, the AgentHub client is rebuilt with its stateful history intact.
* Core assigns no provider semantics to this hook.
*/
resolveApiKey?: () => Promise<string | undefined>;
baseUrl?: string;
/**
* AgentHub client protocol (`openai-chat` / `openai-responses` / `claude-4-8` /
* `deepseek-v4` / …; the bare `openai` spelling is a deprecated alias of `openai-chat`). If
* omitted, AgentHub infers it from `modelId`; custom-named models or third-party models
* using an OpenAI protocol must specify it explicitly.
*/
clientType?: string;
tools: ToolDefinition[];
/** Full system Prompt after placeholder substitution in the system_config.system_prompt template. */
systemPrompt?: string;
/**
* Model context window (tokens, from the model entry). Used to clamp each request's
* effective output cap so `input + max_tokens` stays inside the window (issue #218).
* Unset (or implausibly small, see llm/context-limits.ts resolveContextWindow): the
* clamp is disabled — a hard cap is never derived from an assumed window.
*/
contextWindow?: number;
/**
* Output token cap per Request; non-positive (-1) means no explicit cap (omitted from the
* request). With `contextWindow` set, a positive cap is a ceiling, not a constant: each
* request sends `min(maxTokens, contextWindow − estimated input − safety margin)` (see
* llm/context-limits.ts) so small-window models never fail provider validation.
*/
maxTokens?: number;
/**
* How many images ONE request may carry, when the model's seller publishes a cap (the
* catalog's `ModelCatalogEntry.maxImages`; Abliteration's is 4). Unset = no known cap.
*
* A conversation accumulates images — a `read_file` of a picture, an attached screenshot —
* and every later request replays them, so a provider that counts images refuses the
* conversation outright once the total passes its limit (`400 … media_count_exceeded`).
* The implementation therefore trims the OLDEST replayed images down to this number before
* each request, replacing each with a one-line text placeholder, and keeps the newest; the
* messages in the Session's own history and Trace are not touched.
*/
maxImages?: number;
/**
* How many videos ONE request may carry. Set by the caller for a model the catalog marks as
* taking video input (`ModelCatalogEntry.supportsVideo`); unset = the model takes none, and
* a video is never sent to it.
*
* The budget exists for the request body rather than a published count: a video travels as
* megabytes of base64 (Ark accepts one under 50 MB inside a 64 MB body) and every later
* request replays the conversation, so a history holding two videos is refused for good.
* The implementation keeps the NEWEST video and replaces older ones with a one-line text
* placeholder; the Session's history and Trace keep every video.
*/
maxVideos?: number;
/**
* Per-model fast mode (from the model entry's `fast_mode` annotation): when true, every
* request opts into the provider's faster serving tier at premium pricing (AgentHub
* UniConfig `fast_mode`). Off by default. Models without a fast tier reject the parameter
* before any network I/O (AgentHub `UnsupportedParameterError`); `streamGenerate` reports
* that as a `fatal` outcome so the engine surfaces it instead of retrying.
*/
fastMode?: boolean;
/** Construction-time default thinking level; a per-request `GenerativeModelParameters.thinkingLevel` overrides it for that request. */
thinkingLevel?: ThinkingLevelName;
/**
* Idle budget (ms) for an LLM Request: the longest wait for the NEXT upstream event, not a
* cap on the request's total duration — the timer runs only while awaiting upstream, resets
* on every event, and excludes consumer-side time (yielding, approvals, Trace writes). It
* therefore bounds the connect + first-event wait and the gaps between events, never how
* long the model generates. From system_config.model.timeoutMs; <=0 disables it. Defaults
* to 300000: a model whose reasoning never reaches the wire spends its whole thinking phase
* inside the first-event gap.
*/
requestTimeoutMs?: number;
/**
* The Session's id, for endpoints whose attribution scheme identifies the conversation
* rather than the app (OpenCode's `x-opencode-session`; see state/model-catalog.ts
* `attributionHeaders`). Unset — a request outside any Session: a connectivity test, a
* vision probe, a one-off utility completion — attributionHeaders mints a fresh id, which
* the instance then keeps for all of its requests, so they are a conversation of their own.
*/
sessionId?: string;
/**
* tool_call_id uniqueness registry (Session-level). Pass the same instance when rebuilding a new
* GenerativeModel on compaction so the uniqueness scope covers the whole Session; defaults to a fresh
* one. See llm/tool-call-ids.ts.
*/
toolCallIds?: ToolCallIdAllocator;
}
export interface GenerativeModelParameters {
/** OmniMessage array for the input newly added this turn; implementations must merge it into a single UniMessage (multiple roles not accepted). */
newMessages: OmniMessage[];
signal?: AbortSignal;
/**
* Per-request thinking level override: applied to **this request only**; omitted falls back
* to the construction-time default (`GenerativeModelConfig.thinkingLevel`). The thinking
* level is a per-turn parameter, not a Session invariant.
*/
thinkingLevel?: ThinkingLevelName;
}
/**
* The terminal state of an LLM request, returned as the **return value** of the `streamGenerate`
* async generator (not a yielded message). The status values share the same four-value protocol
* as OmniMessage `stop_reason`:
* - `completed`: finished normally (already produced `token_usage`);
* - `aborted`: user-initiated interruption — stop and hand back to the user;
* - `retryable`: a failure worth retrying — transport drops, idle timeouts, 408/429/5xx,
* malformed or truncated responses, and anything unclassifiable. `context_engine`
* reconnects on its backoff ladder; `errorMessage` names the concrete failure.
* Unclassifiable errors land here on purpose: the fatal detector is an allowlist, and a
* gateway phrasing a transient fault its own way must keep its retries;
* - `fatal`: a failure no retry can fix — a provider 4xx rejection (invalid request or
* quota; 408/429 stay retryable), a credentials failure (see `isAuthenticationError`),
* or a deterministic client-side rejection thrown before any network I/O (fast mode on
* a model without a fast tier). The engine stops the run and surfaces `errorMessage`;
* the fix is a config or credential change, then a new request (only the model
* reference is fixed at Session creation — credentials come from the current Project
* config, so a key update lets the Session continue).
* Docs: /docs/interfaces § "LLMOutcome semantics".
*/
export interface LLMOutcome {
status: StopReason;
/**
* Classified cause (the omnimessage ErrorCode vocabulary): present on every
* non-completed failure outcome. Carried onto the `request_end` event as `error_code`,
* next to `error_message` — the status answers "retry?", the code says what kind of
* error it was, machine-readably.
*/
errorCode?: ErrorCode;
/**
* Error detail (`describeError` text): present on `fatal`, and on `retryable` when a
* concrete transport/provider error was caught (a plain idle timeout has none). Carried
* onto the `request_end` event as `error_message` — one name across the internal outcome
* and the wire — so observability (the Cost center's errors panel) can show the real
* reason behind a retried request.
*/
errorMessage?: string;
}
/**
* A stateful LLM object attached to a Session.
* `streamGenerate` yields streaming `partial_*` messages as an async generator, and appends the
* corresponding complete `model_msg` once each fragment ends; Token usage is emitted as a
* `token_usage` event_msg. **Never throws to `context_engine`**: any interruption/exception is
* closed off in well-formed structure and returned normally, and **must** report the terminal
* state via `LLMOutcome` — error handling happens entirely inside the LLM interface, and
* `context_engine` only decides subsequent actions based on the outcome.
* Docs: /docs/interfaces § "LLMInterface".
*/
export interface LLMInterface {
streamGenerate(parameters: GenerativeModelParameters): AsyncGenerator<OmniMessage, LLMOutcome>;
}