@infinityi/engine-lib 1.0.0

package/dist/providers/stream.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The unified streaming model shared by every provider adapter.
+ *
+ * Each adapter translates its vendor's SSE events into this {@link StreamEvent}
+ * union. The stable application contract is the `StreamEvent` union itself;
+ * {@link StreamAccumulator} and {@link collectStream} are advanced helpers for
+ * adapter authors, tests, and provider-subpath users.
+ *
+ * The shape follows the rule every provider doc calls out: assemble tool-call
+ * arguments by **index**, never assume one flat string.
+ *
+ * @module
+ */
+import type { ProviderError } from "../errors";
+import type { CompletionResult, FinishReason, Usage } from "./types";
+/**
+ * A single normalized streaming event.
+ *
+ * A well-formed stream starts with `message_start`, then yields zero or more
+ * text/tool-call delta events, and ends with `finish`. `error` may appear when
+ * a provider reports a recoverable stream error; thrown stream failures surface
+ * as `ProviderError`.
+ *
+ * Tool-call argument chunks are keyed by `index`: consumers must assemble
+ * `tool_call_delta` events by index and wait for `tool_call_end`.
+ */
+export type StreamEvent = {
+    readonly type: "message_start";
+    readonly model: string;
+} | {
+    readonly type: "text_delta";
+    readonly text: string;
+} | {
+    readonly type: "tool_call_start";
+    readonly index: number;
+    readonly id: string;
+    readonly name: string;
+} | {
+    readonly type: "tool_call_delta";
+    readonly index: number;
+    readonly argumentsTextDelta: string;
+} | {
+    readonly type: "tool_call_end";
+    readonly index: number;
+} | {
+    readonly type: "finish";
+    readonly finishReason: FinishReason;
+    readonly usage?: Usage;
+} | {
+    readonly type: "error";
+    readonly error: ProviderError;
+};
+/**
+ * Folds a {@link StreamEvent} sequence into a single {@link CompletionResult}.
+ * Tool calls are keyed by their stream index so out-of-order deltas assemble
+ * correctly.
+ */
+export declare class StreamAccumulator {
+    private model?;
+    private text;
+    private finishReason;
+    private usage?;
+    private readonly toolCalls;
+    push(event: StreamEvent): void;
+    /** Build the final result. `model` is a fallback when no `message_start` was seen. */
+    result(model: string, raw?: unknown): CompletionResult;
+}
+/** Drain an event stream into a {@link CompletionResult}. */
+export declare function collectStream(events: AsyncIterable<StreamEvent>, model: string, raw?: unknown): Promise<CompletionResult>;

package/dist/providers/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The normalized LLM provider contract.
+ *
+ * A {@link Provider} hides each vendor's wire format behind two methods —
+ * {@link Provider.complete} (one buffered turn) and {@link Provider.stream}
+ * (a unified delta stream) — both speaking the Phase-1 {@link Message} model
+ * and {@link JsonSchema} tool/output schemas. Adapters translate to/from the
+ * provider's native shape; nothing above this layer knows which vendor is in
+ * use. The stable application surface is the {@link Provider} contract, request
+ * / result / stream types, capabilities, and the built-in provider factories.
+ * Adapter scaffolding lives on `@infinityi/engine-lib/providers` as an advanced extension
+ * surface.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { EngineContext } from "../runtime/types";
+import type { JsonSchema } from "../schema/types";
+import type { StreamEvent } from "./stream";
+/** A tool advertised to the model: a name plus JSON-Schema parameters. */
+export interface ProviderTool {
+    readonly name: string;
+    readonly description?: string;
+    /** JSON Schema for the arguments object (from a Phase-1 `Schema.jsonSchema`). */
+    readonly parameters: JsonSchema;
+}
+/** How the model is allowed to use tools this turn. */
+export type ToolChoice = "auto" | "none" | "required" | {
+    readonly name: string;
+};
+/** Request a structured (JSON-Schema-constrained) response. */
+export interface ResponseSchema {
+    readonly name: string;
+    readonly schema: JsonSchema;
+    /** Enforce exact schema conformance where the provider supports it. Default `true`. */
+    readonly strict?: boolean;
+}
+/**
+ * A provider-neutral request for a single model turn.
+ *
+ * `model` overrides the provider's `defaultModel` for this request only.
+ * Generation knobs are normalized across providers. `providerOptions` is the
+ * sanctioned escape hatch for vendor-specific fields that are not yet
+ * first-classed in this interface.
+ */
+export interface CompletionRequest {
+    /** Model id; falls back to the provider's `defaultModel` when omitted. */
+    readonly model?: string;
+    /** Conversation so far (Phase-1 model); adapters extract any system message. */
+    readonly messages: Message[];
+    /** Provider-facing tool declarations for this turn. */
+    readonly tools?: ProviderTool[];
+    /** How the model may use tools this turn. */
+    readonly toolChoice?: ToolChoice;
+    /** Optional structured-output schema for providers that support it. */
+    readonly responseSchema?: ResponseSchema;
+    /** Maximum tokens the model may generate in the response. */
+    readonly maxOutputTokens?: number;
+    /** Sampling temperature, provider-normalized where possible. */
+    readonly temperature?: number;
+    /** Nucleus sampling value, provider-normalized where possible. */
+    readonly topP?: number;
+    /** Stop sequences passed through when supported. */
+    readonly stopSequences?: readonly string[];
+    /** Vendor-neutral request metadata (e.g. an end-user id). */
+    readonly metadata?: Record<string, string>;
+    /**
+     * Escape hatch merged into the provider request body, for features not yet
+     * first-classed here (reasoning/thinking knobs, server-side built-in tools,
+     * safety settings, stateful conversation ids, …).
+     */
+    readonly providerOptions?: Record<string, unknown>;
+}
+/** Token accounting, normalized across providers. */
+export interface Usage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    /** Reasoning/thinking tokens, when the provider reports them separately. */
+    readonly reasoningTokens?: number;
+    /** Prompt tokens served from cache, when reported. */
+    readonly cachedInputTokens?: number;
+}
+/** Why the model stopped generating, normalized across providers. */
+export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error" | "other";
+/** A tool call the model requested. `arguments` is parsed JSON when possible. */
+export interface ToolCall {
+    /** Correlation id (OpenAI `call_id` / Anthropic `tool_use.id` / Gemini `functionCall.id`). */
+    readonly id: string;
+    readonly name: string;
+    /** Parsed arguments object, or `undefined` if the raw text was not valid JSON. */
+    readonly arguments: unknown;
+    /** Raw arguments text as emitted by the model (always preserved). */
+    readonly argumentsText?: string;
+}
+/** The normalized result of a single completion. */
+export interface CompletionResult {
+    /** Assistant message in the Phase-1 model (text + tool-call parts). */
+    readonly message: Message;
+    /** Tool calls surfaced from the message, for convenience. */
+    readonly toolCalls: ToolCall[];
+    readonly finishReason: FinishReason;
+    readonly usage?: Usage;
+    /** The model id that produced this result. */
+    readonly model: string;
+    /**
+     * The provider-native response object. This intentionally remains `unknown`:
+     * consumers may narrow it when they know the adapter, while engine-lib keeps
+     * the normalized result portable.
+     */
+    readonly raw: unknown;
+}
+/**
+ * Declared, queryable provider capabilities so callers can degrade gracefully.
+ *
+ * Adapter authors should treat these as capability truth: the conformance suite
+ * validates that built-in adapters are honest about supported features.
+ */
+export interface ProviderCapabilities {
+    readonly tools: boolean;
+    readonly streaming: boolean;
+    readonly multimodalInput: boolean;
+    readonly parallelToolCalls: boolean;
+    readonly structuredOutput: boolean;
+}
+/** The normalized LLM provider contract. */
+export interface Provider {
+    /** Stable provider id, e.g. `"openai"`, `"anthropic"`, `"google"`. */
+    readonly name: string;
+    /** Model used when a {@link CompletionRequest} omits `model`. */
+    readonly defaultModel: string;
+    readonly capabilities: ProviderCapabilities;
+    /** Run one turn and return the buffered, normalized result. */
+    complete(req: CompletionRequest, ctx?: EngineContext): Promise<CompletionResult>;
+    /** Run one turn, yielding a unified stream of {@link StreamEvent}s. */
+    stream(req: CompletionRequest, ctx?: EngineContext): AsyncIterable<StreamEvent>;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@infinityi/engine-lib/runtime` — the forge integration surface.
+ *
+ * Re-exports forge's `Secret` helpers so hosts wiring config-sourced
+ * credentials don't need to dual-import from `@infinityi/forge/config`.
+ *
+ * @module
+ */
+export { resolveSecret } from "./secret";
+export type { EngineContext, Logger, Telemetry, TelemetryHandle } from "./types";
+export { isSecret, Secret } from "@infinityi/forge/config";

package/dist/runtime/index.js

@@ -0,0 +1,11 @@
+import"../index-jg19te9v.js";
+import {
+  Secret,
+  isSecret,
+  resolveSecret
+} from "../index-xsv43c5j.js";
+export {
+  resolveSecret,
+  isSecret,
+  Secret
+};

package/dist/runtime/secret.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bridge to `forge/config` secrets.
+ *
+ * @module
+ */
+import type { Secret } from "@infinityi/forge/config";
+/**
+ * Unwrap a forge {@link Secret} or pass a raw string through, so provider
+ * adapters (Phase 2) can accept either an inline key or a config-sourced
+ * secret without each adapter re-implementing the check.
+ */
+export declare function resolveSecret(value: string | Secret<string>): string;

package/dist/runtime/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Forge integration conventions threaded through engine-lib.
+ *
+ * Observability is expressed entirely in terms of forge's `Telemetry`
+ * handle and `Logger`, so engine-lib never invents its own logging or
+ * metrics surface.
+ *
+ * @module
+ */
+import type { Telemetry } from "@infinityi/forge/telemetry";
+import type { Logger } from "@infinityi/forge/telemetry/log";
+/** The unit of observability threaded through engine-lib (forge's `Telemetry` handle). */
+export type TelemetryHandle = Telemetry;
+/**
+ * Options common to every engine-lib entry point (provider calls in
+ * Phase 2, agent runs in Phase 4). All fields are optional so the library
+ * is usable with zero observability wiring.
+ */
+export interface EngineContext {
+    /** Forge telemetry handle for traces / metrics / logs. */
+    readonly telemetry?: TelemetryHandle;
+    /** Structured logger (defaults to `telemetry.log` when omitted). */
+    readonly logger?: Logger;
+    /** Cancellation signal honored by long-running operations (Phase 4). */
+    readonly signal?: AbortSignal;
+}
+export type { Logger, Telemetry };

package/dist/schema/builder.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The `s` builder — the public entry point for declaring schemas.
+ *
+ * `s` constructs {@link Schema} values for the JSON-Schema-expressible types
+ * engine-lib needs to describe tool parameters and structured outputs. Objects
+ * are strict by default (`additionalProperties: false`), and fields wrapped in
+ * `s.optional()` infer as optional TypeScript properties. It is intentionally
+ * dependency-free; external schema libraries (e.g. Zod) plug in through
+ * `asSchema` rather than as a hard dependency.
+ *
+ * @example
+ * ```ts
+ * import { s, type Infer } from "@infinityi/engine-lib/schema";
+ *
+ * const Params = s.object({
+ *   service: s.string(),
+ *   lines: s.optional(s.number({ int: true })),
+ * });
+ * type Params = Infer<typeof Params>; // { service: string; lines?: number }
+ * ```
+ *
+ * @module
+ */
+import type { OptionalSchema, Schema } from "./types";
+type ObjectShape = Record<string, Schema<unknown>>;
+type OptionalKeys<P extends ObjectShape> = {
+    [K in keyof P]: P[K] extends OptionalSchema<unknown> ? K : never;
+}[keyof P];
+type RequiredKeys<P extends ObjectShape> = Exclude<keyof P, OptionalKeys<P>>;
+type InferShape<P extends ObjectShape> = {
+    [K in RequiredKeys<P>]: P[K] extends Schema<infer T> ? T : never;
+} & {
+    [K in OptionalKeys<P>]?: P[K] extends Schema<infer T> ? Exclude<T, undefined> : never;
+};
+/** Public schema-builder surface. */
+export declare const s: {
+    /** A string, optionally constrained to an enum. */
+    readonly string: (opts?: {
+        description?: string;
+        enum?: readonly string[];
+    }) => Schema<string>;
+    /** A number. Pass `{ int: true }` to require an integer. */
+    readonly number: (opts?: {
+        description?: string;
+        int?: boolean;
+    }) => Schema<number>;
+    /** A boolean. */
+    readonly boolean: (opts?: {
+        description?: string;
+    }) => Schema<boolean>;
+    /** One of a fixed set of string variants. */
+    readonly enum: <V extends string>(values: readonly V[], opts?: {
+        description?: string;
+    }) => Schema<V>;
+    /** An array of `item`. */
+    readonly array: <T>(item: Schema<T>, opts?: {
+        description?: string;
+    }) => Schema<T[]>;
+    /**
+     * An object with the given properties. Properties wrapped in
+     * {@link s.optional} are excluded from `required`; all others are required.
+     * Unknown properties are rejected (`additionalProperties: false`).
+     */
+    readonly object: <P extends ObjectShape>(props: P, opts?: {
+        description?: string;
+    }) => Schema<InferShape<P>>;
+    /** Mark a schema optional: `undefined` validates, and object keys become non-required. */
+    readonly optional: <T>(inner: Schema<T>) => OptionalSchema<T>;
+};
+export {};

package/dist/schema/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@infinityi/engine-lib/schema` — the schema contract used to describe and validate
+ * tool parameters and structured outputs.
+ *
+ * Providers read `Schema.jsonSchema`; the runtime calls `Schema.parse` to
+ * validate model-supplied arguments at the boundary.
+ *
+ * @module
+ */
+export { s } from "./builder";
+export { asSchema, fromJsonSchema, toJsonSchema } from "./json-schema";
+export { validateJsonSchema } from "./validate";
+export type { Infer, JsonSchema, OptionalSchema, SafeParseResult, Schema, SchemaIssue, } from "./types";

package/dist/schema/index.js

@@ -0,0 +1,15 @@
+import {
+  asSchema,
+  fromJsonSchema,
+  s,
+  toJsonSchema,
+  validateJsonSchema
+} from "../index-02s1fjxr.js";
+import"../index-7690reng.js";
+export {
+  validateJsonSchema,
+  toJsonSchema,
+  s,
+  fromJsonSchema,
+  asSchema
+};

package/dist/schema/json-schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Helpers for moving between {@link Schema} and raw {@link JsonSchema}.
+ *
+ * @module
+ */
+import type { JsonSchema, Schema } from "./types";
+/** Return the provider-facing {@link JsonSchema} for a schema. */
+export declare function toJsonSchema<T>(schema: Schema<T>): JsonSchema;
+/**
+ * Adapt an external schema implementation (e.g. a Zod adapter) into the
+ * engine-lib {@link Schema} contract. Only `jsonSchema` and `parse` are
+ * required; `safeParse` is derived if absent.
+ */
+export declare function asSchema<T>(impl: Pick<Schema<T>, "jsonSchema" | "parse"> & Partial<Pick<Schema<T>, "safeParse">>): Schema<T>;
+/**
+ * Wrap a raw {@link JsonSchema} as a {@link Schema}. Validation uses the
+ * built-in validator; the output type is supplied by the caller (`T`).
+ */
+export declare function fromJsonSchema<T = unknown>(jsonSchema: JsonSchema): Schema<T>;

package/dist/schema/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Core types for the `@infinityi/engine-lib` schema layer.
+ *
+ * The {@link Schema} contract is the seam between engine-lib and LLM
+ * providers: providers read `.jsonSchema` (to advertise tool parameters /
+ * structured outputs), while the runtime calls `.parse` or `.safeParse` to
+ * validate model-supplied arguments at the boundary.
+ *
+ * @module
+ */
+import type { SchemaIssue, SchemaValidationError } from "../errors";
+/**
+ * A structural subset of JSON Schema (draft 2020-12) sufficient to describe
+ * tool parameters and structured outputs for every supported provider.
+ * Intentionally minimal and extensible; unsupported JSON Schema keywords are
+ * outside the stable validation contract.
+ */
+export interface JsonSchema {
+    type?: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+    description?: string;
+    /** Object: property schemas. */
+    properties?: Record<string, JsonSchema>;
+    /** Object: required property names. */
+    required?: string[];
+    /**
+     * Object: whether unknown properties are permitted. Builders created with
+     * `s.object()` set this to `false`, making tool arguments strict by default.
+     */
+    additionalProperties?: boolean;
+    /** Array: element schema. */
+    items?: JsonSchema;
+    /** Enumerated allowed values. */
+    enum?: ReadonlyArray<string | number>;
+}
+/** Result of a non-throwing parse. */
+export type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: SchemaValidationError;
+};
+/**
+ * The engine-lib schema contract. A `Schema<T>` couples a provider-facing
+ * {@link JsonSchema} with runtime validation that yields a typed `T`.
+ *
+ * The stable surface is intentionally small: `jsonSchema`, `parse`,
+ * `safeParse`, and the type-only `_output` marker used by {@link Infer}.
+ */
+export interface Schema<T> {
+    /** Provider-facing JSON Schema (consumed by provider adapters in Phase 2+). */
+    readonly jsonSchema: JsonSchema;
+    /** Validate and return `T`, or throw {@link SchemaValidationError}. */
+    parse(input: unknown): T;
+    /** Validate without throwing. */
+    safeParse(input: unknown): SafeParseResult<T>;
+    /** Phantom marker carrying the output type for {@link Infer}. Never present at runtime. */
+    readonly _output?: T;
+}
+/**
+ * A schema marked optional by `s.optional`. The `__optional` marker is a
+ * phantom (never present at runtime) used purely to make the corresponding
+ * object key optional in {@link Infer}.
+ */
+export interface OptionalSchema<T> extends Schema<T | undefined> {
+    readonly __optional: true;
+}
+/** Infer the TypeScript type carried by a {@link Schema}. */
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+export type { SchemaIssue };

package/dist/schema/validate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Recursive validator backing every {@link Schema}.
+ *
+ * Validation is driven entirely by a {@link JsonSchema} node so that the
+ * same logic covers both the built-in `s` builder and externally-supplied
+ * schemas adapted via `asSchema`. It collects *all* issues (rather than
+ * failing on the first) so callers get a complete picture.
+ *
+ * @module
+ */
+import type { SchemaIssue } from "../errors";
+import type { JsonSchema } from "./types";
+type Path = ReadonlyArray<string | number>;
+/**
+ * Validate `input` against a {@link JsonSchema} node, accumulating issues.
+ * Returns an empty array when `input` is valid.
+ */
+export declare function validateJsonSchema(node: JsonSchema, input: unknown, path?: Path): SchemaIssue[];
+export {};

package/dist/session/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@infinityi/engine-lib/session` — durable conversation state: the {@link SessionStore}
+ * persistence contract, the built-in {@link InMemorySessionStore}, and the
+ * {@link createSession} handle threaded into a run.
+ *
+ * @module
+ */
+export { createSession } from "./session";
+export type { CreateSessionOptions } from "./session";
+export { InMemorySessionStore } from "./store";
+export type { Session, SessionState, SessionStore } from "./types";

package/dist/session/index.js

@@ -0,0 +1,8 @@
+import {
+  InMemorySessionStore,
+  createSession
+} from "../index-vnby35rm.js";
+export {
+  createSession,
+  InMemorySessionStore
+};

package/dist/session/session.d.ts

@@ -0,0 +1,31 @@
+/**
+ * {@link createSession} — the synchronous factory for a {@link Session} handle.
+ *
+ * Construction never performs I/O: the underlying {@link SessionStore} is consulted
+ * lazily on the first {@link Session.messages} / {@link Session.append} call. When a
+ * store already holds history for the id, that history is resumed; otherwise any
+ * `messages` seed is written through on first access.
+ *
+ * `runAgent` appends to a session only after a successful run. Instructions and
+ * injected context are request-time system messages and are never persisted.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { Session, SessionStore } from "./types";
+/** Options for {@link createSession}. */
+export interface CreateSessionOptions {
+    /** Stable id; when omitted a random id is generated. */
+    readonly id?: string;
+    /** Backing store; defaults to a fresh {@link InMemorySessionStore}. */
+    readonly store?: SessionStore;
+    /** Seed history, written through only once and only if the store has no history for this id. */
+    readonly messages?: readonly Message[];
+    /** Free-form metadata attached to the session handle. */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Create a {@link Session} handle. Synchronous: the store is read on first use,
+ * so an existing conversation is resumed by passing its `id`.
+ */
+export declare function createSession(opts?: CreateSessionOptions): Session;

package/dist/session/store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-memory {@link SessionStore} — the default, deterministic persistence double.
+ *
+ * Holds each session's history in a `Map`, copying message arrays on the way in
+ * and out so callers cannot mutate stored state by reference. Suitable for tests
+ * and ephemeral (single-process) runs; swap in a durable store for persistence
+ * across restarts.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { SessionState, SessionStore } from "./types";
+/** A process-local {@link SessionStore} backed by a `Map`. */
+export declare class InMemorySessionStore implements SessionStore {
+    private readonly entries;
+    load(id: string): Promise<SessionState | undefined>;
+    append(id: string, messages: readonly Message[]): Promise<void>;
+    save(state: SessionState): Promise<void>;
+    delete(id: string): Promise<void>;
+}

package/dist/session/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Durable conversation state.
+ *
+ * A {@link SessionStore} is the pluggable persistence seam (an in-memory double
+ * ships built-in); a {@link Session} is the per-conversation handle threaded into
+ * a run. History is read before a run and appended after it. Only the *conversation*
+ * (user input + produced assistant/tool messages) is persisted — the run-time
+ * system/instruction and injected-context messages are rebuilt fresh every run and
+ * are never stored.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+/** Ordered, durable conversation state keyed by id. */
+export interface SessionState {
+    readonly id: string;
+    readonly messages: readonly Message[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Pluggable persistence for session history.
+ *
+ * Implementations must preserve message order, treat {@link append} as an
+ * atomic add to the tail, and return snapshots that callers cannot mutate to
+ * alter stored history by reference. The built-in {@link InMemorySessionStore}
+ * is the reference double; a `forge/data`-backed store can be layered on later
+ * behind this same contract.
+ */
+export interface SessionStore {
+    /** Load the full state for `id`, or `undefined` if none exists yet. */
+    load(id: string): Promise<SessionState | undefined>;
+    /** Append `messages` to the tail of `id`'s history (creating it if absent). */
+    append(id: string, messages: readonly Message[]): Promise<void>;
+    /** Replace the full state for `state.id`. */
+    save(state: SessionState): Promise<void>;
+    /** Remove all history for `id` (no-op if absent). */
+    delete(id: string): Promise<void>;
+}
+/**
+ * A per-conversation handle passed to `runAgent`.
+ *
+ * Created synchronously by {@link createSession}; history is resolved lazily
+ * (on the first {@link Session.messages}, {@link Session.append}, or
+ * {@link Session.clear} call) so construction never blocks on I/O.
+ */
+export interface Session {
+    readonly id: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Snapshot of the current ordered history. */
+    messages(): Promise<Message[]>;
+    /** Append messages to the conversation and persist them. */
+    append(messages: readonly Message[]): Promise<void>;
+    /** Drop all history for this session. */
+    clear(): Promise<void>;
+}