@combycode/llm-sdk 1.0.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `@combycode/llm-sdk` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-06-13
+
+First public release.
+
+### Added
+- Unified API across Anthropic, OpenAI, Google, xAI, and OpenRouter.
+- Model catalog: normalised slug names, `model:tier` selectors, and
+  capability-based `select()`.
+- Tiered pricing with cost tracking and budget limits.
+- Service tiers end to end (request → bill → cost).
+- Cross-environment: runs on Node, Bun, and the browser. ESM, zero runtime deps.
+
+[1.0.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ORXA / CombyCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @combycode/llm-sdk
+
+A unified, pluggable AI SDK for accessing the LLMs of every major provider —
+**Anthropic, OpenAI, Google, xAI, and OpenRouter** — through one API.
+
+- **One API, every provider.** Switch model or provider without rewriting calls.
+- **Pluggable.** Opt-in subsystems: a model catalog, cost tracking + budgets,
+  rate-limit-aware queueing, tools/agents, and an OpenAI-compatible server.
+- **Unified model catalog** — normalised slug names (`anthropic/claude-haiku-4.5`),
+  `model:tier` selectors, capability-based `select()`, tiered pricing, and cost
+  tracking.
+- **Cross-environment.** The same code runs on Node, Bun, and the browser. Zero
+  runtime dependencies, ESM.
+
+## Install
+
+```sh
+npm install @combycode/llm-sdk      # or: bun add @combycode/llm-sdk
+```
+
+Requires Node ≥ 18 or Bun ≥ 1.1.
+
+## Quickstart
+
+### Simplest path — a callable provider id
+
+```ts
+import { complete } from '@combycode/llm-sdk';
+
+const r = await complete({
+  model: 'anthropic/claude-haiku-4-5', // provider/model, sent verbatim
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  prompt: 'Say hello in one word.',
+});
+console.log(r.text);
+```
+
+### Unified names + capability selection
+
+`createEngine()` registers a default engine that the helpers use automatically —
+you only pass `engine` explicitly when you run more than one.
+
+```ts
+import { complete, createEngine, select } from '@combycode/llm-sdk';
+
+createEngine({ catalog: 'defaults', apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } });
+
+// Normalised slug → translated to the provider's callable id via the catalog.
+await complete({ model: 'anthropic/claude-haiku-4.5', prompt: 'Hi' });
+
+// Pick the cheapest model matching a capability query.
+const best = select('type:chat; vision; cheap'); // -> "provider/slug"
+await complete({ model: best!, prompt: 'Hi' });
+```
+
+### Streaming
+
+```ts
+import { createLLM } from '@combycode/llm-sdk';
+
+const llm = createLLM({ model: 'openai/gpt-5.4-nano', apiKey: process.env.OPENAI_API_KEY });
+for await (const ev of llm.stream('Count to 5.')) {
+  if (ev.type === 'text') process.stdout.write(ev.text);
+}
+```
+
+## Documentation
+
+Full guide pages covering all export groups:
+
+- **[docs/guide/](./docs/guide/README.md)** -- index of all guide pages
+  - [Network Engine](./docs/guide/network.md)
+  - [LLM Client + complete / stream](./docs/guide/llm-client.md)
+  - [Agent Loop + delegate / chain / consolidate](./docs/guide/agent-loop.md)
+  - [Tools (defineTool)](./docs/guide/tools.md)
+  - [Tokens + Embeddings](./docs/guide/tokens-embeddings.md)
+  - [Cost Tracking + estimate()](./docs/guide/cost.md)
+  - [Observability / Telemetry](./docs/guide/telemetry.md)
+  - [Media / Files / Batch](./docs/guide/media-files-batch.md)
+  - [MCP (Model Context Protocol)](./docs/guide/mcp.md)
+  - [Context Guard + Permissions + Persistence + Cache](./docs/guide/context-guard.md)
+  - [OpenAI-Compatible Server](./docs/guide/server.md)
+  - [Agent Patterns](./docs/guide/agent-patterns.md)
+  - [Moderation](./docs/guide/moderation.md)
+  - [Retrieval (RAG)](./docs/guide/retrieval.md)
+  - [Approval and Checkpoints](./docs/guide/approval-and-checkpoints.md)
+  - [Realtime (Live)](./docs/guide/realtime.md)
+
+MCP subsystem design: [docs/design/mcp.md](./docs/design/mcp.md)
+
+## Development
+
+```sh
+bun install
+bun test          # unit tests
+bun run typecheck # tsc --noEmit
+bun run lint      # biome
+bun run build     # dist/ (node + browser builds + types)
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/agent/approval-types.d.ts

@@ -0,0 +1,49 @@
+/** HITL (Human-in-the-Loop) approval types.
+ *
+ *  ApprovalRequest  — sent to the approve() callback when a tool call needs human sign-off.
+ *  ApprovalDecision — returned by the approver to tell the loop what to do next.
+ *  PendingToolCall  — serializable record stored in AgentLoopSnapshot while approval is awaited. */
+import type { TraceContext } from '../network/types';
+/** Sent to the `approve` callback when a tool call needs human approval. */
+export interface ApprovalRequest {
+    /** Unique ID of the tool call (from the LLM response). */
+    callId: string;
+    /** Name of the tool being called. */
+    toolName: string;
+    /** Arguments the model wants to pass to the tool. */
+    arguments: Record<string, unknown>;
+    /** Human-readable reason why approval is required (from the matching permission rule). */
+    reason?: string;
+    /** Step index within the run. */
+    step: number;
+    /** Run identity: sessionId = agentId (ConversationHistory id),
+     *  requestId = runId for this .complete()/.stream() invocation,
+     *  callId = this tool call's id (same as ApprovalRequest.callId). */
+    trace: TraceContext;
+}
+/** Returned by the approver to direct the loop. */
+export interface ApprovalDecision {
+    /** 'approve' — execute the tool normally.
+     *  'deny'    — block the tool; the model receives a denial message.
+     *  'skip'    — skip silently; the model receives a skip message. */
+    decision: 'approve' | 'deny' | 'skip';
+    /** When set, inject this string as the tool result instead of executing. */
+    overrideResult?: string;
+    /** Optional note logged in the tool report. */
+    note?: string;
+}
+/** Serializable record of a pending approval stored in AgentLoopSnapshot. */
+export interface PendingToolCall {
+    /** Unique ID of the tool call. */
+    callId: string;
+    /** Name of the tool. */
+    toolName: string;
+    /** Arguments the model wanted to pass. */
+    arguments: Record<string, unknown>;
+    /** Step index within the run. */
+    step: number;
+    /** ISO timestamp (ms since epoch) when the approval was requested. */
+    requestedAt: number;
+    /** Run ID of the suspended run. */
+    runId: string;
+}

package/dist/agent/context-registry/layers.d.ts

@@ -0,0 +1,39 @@
+/** Well-known system layer names + priorities used by SDK subsystems.
+ *
+ *  AgentLoop, ContextGuard, memory tools and other writers all contribute
+ *  layers to a conversation's `history.registry`. Their relative priority
+ *  determines the rendered order of the system prompt the LLM sees.
+ *
+ *  Lower priority renders earlier (closer to the top of the system prompt).
+ *  Stable prefix layers go first so prompt-cache hits are maximized; dynamic
+ *  contributors (memory, facts) come after. */
+import type { ContextRegistry } from './registry';
+/** Role / persona / behavior. Stable per-conversation. Lowest priority so
+ *  cache prefixes start here. */
+export declare const LAYER_AGENTLOOP_SYSTEM = "agentloop.system";
+/** Run-scenario context the AgentLoop was constructed with (e.g. background
+ *  for the current task). Stable per-run; rendered after system. */
+export declare const LAYER_AGENTLOOP_CONTEXT = "agentloop.context";
+/** Legacy ConversationHistory.system setter — kept for backward compat with
+ *  pre-registry callers. */
+export declare const LAYER_LEGACY_SYSTEM = "_legacy_system";
+/** Memory layer for free-form notes / scratch (long-lived, low churn). */
+export declare const LAYER_MEMORY = "memory";
+/** Conversational facts surfaced from the user/assistant pair. Updated turn-
+ *  to-turn so it lands later in render order to keep earlier prefix stable. */
+export declare const LAYER_CHAT_FACTS = "chat.facts";
+/** Worker-side: examples log distilled from prior tool calls. */
+export declare const LAYER_EXECUTOR_TOOL_EXAMPLES = "executor.tool-examples";
+/** ContextGuard's compaction summary layer (replaces compacted message ranges). */
+export declare const LAYER_CONTEXT_GUARD_SUMMARY = "context-guard.summary";
+export declare const PRIORITY_AGENTLOOP_SYSTEM = 10;
+export declare const PRIORITY_LEGACY_SYSTEM = 50;
+export declare const PRIORITY_AGENTLOOP_CONTEXT = 100;
+export declare const PRIORITY_MEMORY = 200;
+export declare const PRIORITY_CHAT_FACTS = 250;
+export declare const PRIORITY_EXECUTOR_TOOL_EXAMPLES = 280;
+export declare const PRIORITY_CONTEXT_GUARD_SUMMARY = 300;
+/** Set the AgentLoop's persona/system layer on a registry (or remove if blank). */
+export declare function writeAgentLoopSystem(registry: ContextRegistry, text: string | undefined, owner: string): void;
+/** Set the AgentLoop's run-scenario context layer (or remove if blank). */
+export declare function writeAgentLoopContext(registry: ContextRegistry, text: string | undefined, owner: string): void;

package/dist/agent/context-registry/registry-internal.d.ts

@@ -0,0 +1,14 @@
+/** ContextRegistry rendering helpers — layer filtering, sorting, and text
+ *  flattening. Pure functions split out of registry.ts to keep the class file
+ *  focused on the registry behavior. */
+import type { ContentPart } from '../../llm/types/messages';
+import type { ContextLayer, RenderOptions } from './types';
+export interface CollectedEntry {
+    layer: ContextLayer;
+    source: string;
+}
+export declare function passesFilter(layer: ContextLayer, opts: RenderOptions): boolean;
+export declare function sortLayers(a: CollectedEntry, b: CollectedEntry): number;
+export declare function layerToText(layer: ContextLayer): string;
+export declare function concatContent(a: string | ContentPart[], b: string | ContentPart[]): string | ContentPart[];
+export declare function cryptoRandomShort(): string;

package/dist/agent/context-registry/registry.d.ts

@@ -0,0 +1,104 @@
+/** ContextRegistry — layered, observable, composable context store.
+ *
+ *  Lives at three conceptual scopes (all use the same class, distinguished
+ *  only by their parent chain): orchestrator-global, module-level, and
+ *  conversation-level. Composed render walks the parent chain; child layers
+ *  override parents by default, or merge additively via layer.mergeParent.
+ *
+ *  Events bubble from parent to children — subscribers on child registries
+ *  see all effective changes without wiring to parents manually. */
+import type { ContentPart } from '../../llm/types/messages';
+import type { ContextLayer, ContextRegistryConfig, RegistryEventHandler, RegistrySnapshot, RenderOptions, RenderResult, SetLayerOptions, SizeChangeHandler } from './types';
+export declare class ContextRegistry {
+    readonly id: string;
+    private readonly defaultOwner;
+    private readonly separator;
+    private readonly counter;
+    private readonly layers;
+    private readonly exactSubs;
+    private readonly prefixSubs;
+    private readonly wildcardSubs;
+    private readonly sizeSubs;
+    private _parent;
+    private parentUnsub;
+    constructor(config?: ContextRegistryConfig);
+    get parent(): ContextRegistry | null;
+    /** Attach or detach a parent registry. Throws on cycle. Re-wires bubbling. */
+    setParent(parent: ContextRegistry | null): void;
+    private wouldCreateCycle;
+    /** Set or replace a layer. Bumps version. Emits 'set' (if new) or 'update'. */
+    set(name: string, content: string | ContentPart[], opts?: SetLayerOptions): ContextLayer;
+    /** Modify a layer in place via a function.
+     *  - fn receives the current layer (or undefined if absent)
+     *  - fn may return: new content (string | ContentPart[]) OR a full layer shape
+     *  - Missing fields inherit from previous layer. */
+    patch(name: string, fn: (prev: ContextLayer | undefined) => string | ContentPart[] | ContextLayer): ContextLayer;
+    /** Lookup by name. Does NOT walk parent chain. Use render() for composed views. */
+    get(name: string): ContextLayer | undefined;
+    has(name: string): boolean;
+    /** Remove a layer. Returns true if something was removed. */
+    remove(name: string): boolean;
+    /** List layers, optionally filtered. Does NOT walk parent. */
+    list(filter?: {
+        tag?: string;
+        tags?: string[];
+        owner?: string;
+    }): ContextLayer[];
+    /** All layer names in this registry (not parent). */
+    names(): string[];
+    /** Compose layers into a rendered result.
+     *
+     *  - If includeParent !== false AND a parent exists, parent's layers are
+     *    collected first; then THIS registry's layers overlay on top.
+     *  - Same-named collision: child replaces parent (default) OR merges
+     *    (if child layer.mergeParent === true).
+     *  - Sort: priority ascending → updatedAt ascending → name ascending. */
+    render(opts?: RenderOptions): RenderResult;
+    /** Convenience: render().flat. */
+    flat(opts?: RenderOptions): string;
+    /** Internal recursive collector — merges parent chain, applies filters. */
+    private collectForRender;
+    /** Total character count of rendered output (with given options). */
+    sizeChars(opts?: RenderOptions): number;
+    /** Estimated token count. Uses injected TokenCounter when available,
+     *  otherwise a 4-chars/token heuristic. */
+    sizeTokens(ctx?: {
+        provider?: string;
+        model?: string;
+    }, opts?: RenderOptions): number;
+    /** Local (this-registry-only) char count — used for sizeBefore/sizeAfter
+     *  on emitted events. Does NOT walk parent chain. */
+    private sizeCharsLocal;
+    /** Subscribe to layer events. Pattern matches layer name:
+     *  - exact: 'facts'
+     *  - prefix: 'memory.*'
+     *  - wildcard: '*' (all events, including bubbled from parent)
+     *  Returns unsubscribe. */
+    subscribe(pattern: string, handler: RegistryEventHandler): () => void;
+    /** Subscribe to every event (equivalent to subscribe('*', ...)). */
+    onChange(handler: RegistryEventHandler): () => void;
+    /** Subscribe to size changes. Fires whenever a layer changes and produces
+     *  a non-zero delta. Delta reflects the EMITTING registry's own size change
+     *  — subscribers on composed/child registries should recompute their own
+     *  effective size if precise composed-size tracking is required. */
+    onSizeChange(handler: SizeChangeHandler): () => void;
+    /** Internal: subscribe to all events — used by children to bubble parent
+     *  events. Separate from public subscribe('*') so internal bookkeeping
+     *  doesn't mix with user state. */
+    private subscribeInternalWildcard;
+    /** Emit an event originating from THIS registry. */
+    private fireEvent;
+    /** Emit a bubbled event (originated in an ancestor). We re-publish to our
+     *  subscribers, preserving the original event.registry for traceability. */
+    private fireBubbledEvent;
+    private dispatchToSubscribers;
+    /** Serialize to a JSON-safe snapshot. Parent is NOT serialized — caller
+     *  re-attaches via setParent() after fromSnapshot. */
+    snapshot(): RegistrySnapshot;
+    /** Reconstruct from a snapshot. Events are NOT emitted for initial restore. */
+    static fromSnapshot(snap: RegistrySnapshot, config?: ContextRegistryConfig): ContextRegistry;
+    /** Total handlers across all subscription types. For test leak detection. */
+    get handlerCount(): number;
+    /** Detach from parent and clear all subscribers. Idempotent. */
+    clear(): void;
+}

package/dist/agent/context-registry/types.d.ts

@@ -0,0 +1,110 @@
+/** ContextRegistry types — layered, observable, composable context storage. */
+import type { ContentPart } from '../../llm/types/messages';
+import type { TokenCounter } from '../types';
+import type { ContextRegistry as ContextRegistryClass } from './registry';
+/** A named, versioned slice of context. Each mutation bumps `version`. */
+export interface ContextLayer {
+    /** Unique within a single registry. Also the subscribe() pattern target. */
+    name: string;
+    /** Free-form content. Strings are most common; ContentPart[] supports multi-modal
+     *  and structured hints (tool calls / results). Rendering flattens to text. */
+    content: string | ContentPart[];
+    /** Sort key when rendering. Lower renders earlier. Default 100. */
+    priority: number;
+    /** Free-form grouping tags. Render filters by tag. */
+    tags: string[];
+    /** Who wrote this last. Useful for audit and per-owner filtering. */
+    owner?: string;
+    /** Monotonic — bumps on every set/patch. */
+    version: number;
+    createdAt: number;
+    updatedAt: number;
+    /** When true AND a parent registry has a same-named layer, composed render
+     *  concatenates parent content BEFORE this layer's content instead of
+     *  replacing. Used for additive layers (facts, memory). Default: false. */
+    mergeParent?: boolean;
+    /** Owner-supplied arbitrary data. Not serialized further. */
+    metadata?: Record<string, unknown>;
+}
+/** Registry construction config. */
+export interface ContextRegistryConfig {
+    /** Stable ID. Auto-generated if absent. */
+    id?: string;
+    /** Parent registry — registry inherits layers from parent when rendering.
+     *  Child can override same-named layers OR merge them via `mergeParent`. */
+    parent?: ContextRegistryClass;
+    /** Token counter for sizeTokens() method. */
+    counter?: TokenCounter;
+    /** Default owner tag for mutations that don't specify one. */
+    defaultOwner?: string;
+    /** Separator between rendered parts in .flat output. Default '\n\n'. */
+    separator?: string;
+}
+/** Partial fields for set/patch — missing fields inherit from existing layer
+ *  (if any) or use defaults. */
+export interface SetLayerOptions {
+    priority?: number;
+    tags?: string[];
+    owner?: string;
+    mergeParent?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Render filter + formatting options. */
+export interface RenderOptions {
+    /** Only include layers whose name is in this list. */
+    include?: string[];
+    /** Skip layers whose name is in this list. */
+    exclude?: string[];
+    /** Only include layers that have this tag. */
+    tag?: string;
+    /** Only include layers that have AT LEAST ONE of these tags. */
+    tags?: string[];
+    /** Only include layers with this owner. */
+    ownerFilter?: string;
+    /** Separator between parts when producing .flat. */
+    separator?: string;
+    /** When false, skip parent chain — render only this registry's layers.
+     *  Default: true (compose parent chain). */
+    includeParent?: boolean;
+}
+/** One entry in the rendered output. */
+export interface RenderedPart {
+    name: string;
+    content: string;
+    priority: number;
+    tags: string[];
+    owner?: string;
+    /** ID of the registry this layer was sourced from (this registry or a parent).
+     *  Crucial for debugging cascades. */
+    registry: string;
+}
+/** Structured result of render(). .flat is the string for immediate use. */
+export interface RenderResult {
+    parts: RenderedPart[];
+    flat: string;
+    totalChars: number;
+    rendered: number;
+}
+/** Change event fired on set/update/remove. Also bubbles from parents. */
+export interface ContextRegistryEvent {
+    type: 'set' | 'update' | 'remove';
+    name: string;
+    previous?: ContextLayer;
+    current?: ContextLayer;
+    /** ID of the registry that originated this change (not the one forwarding). */
+    registry: string;
+    /** Total chars of the emitting registry BEFORE the change. */
+    sizeBefore: number;
+    /** Total chars of the emitting registry AFTER the change. */
+    sizeAfter: number;
+    timestamp: number;
+}
+export type RegistryEventHandler = (event: ContextRegistryEvent) => void;
+export type SizeChangeHandler = (totalChars: number, delta: number) => void;
+/** Persistence snapshot. Does NOT serialize parent — that's a runtime relationship. */
+export interface RegistrySnapshot {
+    v: 1;
+    id: string;
+    layers: ContextLayer[];
+    separator: string;
+}

package/dist/agent/guardrail-types.d.ts

@@ -0,0 +1,58 @@
+/** Guardrail types — input/output validators with tripwire halt.
+ *  Extracted per the library rule: types in *-types.ts, never inline. */
+import type { Message } from '../llm/types/messages';
+import type { CompletionResponse } from '../llm/types/response';
+import type { TraceContext } from '../network/types';
+/** Guardrail passed — proceed normally. */
+export interface GuardrailPass {
+    pass: true;
+}
+/** Guardrail tripped — halt the run. */
+export interface GuardrailTrip {
+    pass: false;
+    /** When true the loop MUST halt immediately (hard stop). */
+    tripwire: true;
+    /** Human-readable explanation surfaced in the response and hooks. */
+    reason: string;
+    /** Optional severity label for observability routing. */
+    severity?: 'low' | 'medium' | 'high';
+}
+export type GuardrailDecision = GuardrailPass | GuardrailTrip;
+/** Context given to an input guardrail (before the LLM call). */
+export interface InputGuardrailContext {
+    kind: 'input';
+    /** Run trace: sessionId = agentId (ConversationHistory id),
+     *  requestId = runId for this .complete()/.stream() invocation. */
+    trace: TraceContext;
+    step: number;
+    messages: Message[];
+    system?: string;
+}
+/** Context given to an output guardrail (after a step's response is produced). */
+export interface OutputGuardrailContext {
+    kind: 'output';
+    /** Run trace: sessionId = agentId (ConversationHistory id),
+     *  requestId = runId for this .complete()/.stream() invocation. */
+    trace: TraceContext;
+    step: number;
+    response: CompletionResponse;
+}
+export type GuardrailCheckContext = InputGuardrailContext | OutputGuardrailContext;
+export interface Guardrail {
+    /** Unique label shown in hooks and error messages. */
+    name: string;
+    /** Whether this runs before ('input') or after ('output') the LLM call. */
+    kind: 'input' | 'output';
+    /** Return a decision; throw only for unexpected infrastructure errors. */
+    check(ctx: GuardrailCheckContext): Promise<GuardrailDecision>;
+}
+export interface GuardrailTriggeredContext {
+    runId: string;
+    agentId: string;
+    step: number;
+    guardrailName: string;
+    kind: 'input' | 'output';
+    reason: string;
+    severity?: 'low' | 'medium' | 'high';
+    trace?: TraceContext;
+}

package/dist/agent/history-types.d.ts

@@ -0,0 +1,40 @@
+/** ConversationHistory types: entries, config, and serialized snapshots. */
+import type { Message } from '../llm/types/messages';
+import type { Usage } from '../llm/types/response';
+import type { RegistrySnapshot } from './context-registry/types';
+import type { TokenCounter } from './types';
+export interface HistoryEntry {
+    index: number;
+    message: Message;
+    timestamp: number;
+    model?: string;
+    usage?: Usage;
+    latencyMs?: number;
+    tokenEstimate?: number;
+}
+export interface ConversationHistoryConfig {
+    id?: string;
+    /** Optional token counter. If absent, falls back to length/4 heuristic. */
+    counter?: TokenCounter;
+    /** Provider/model hint for counter strategy. */
+    provider?: string;
+    model?: string;
+    /** Which ContextGuard strategy should apply to this conversation.
+     *  - string: strategy name, matched against the guard's strategies map.
+     *  - false: opt out of context-guarding entirely for this conversation.
+     *  - undefined: use the guard's defaultStrategy.
+     *  Stored in metadata.contextStrategy; readable/writable at runtime. */
+    strategy?: string | false;
+}
+export interface HistorySnapshot {
+    id: string;
+    entries: HistoryEntry[];
+    /** Legacy field — preserved for backward compat with existing snapshots.
+     *  When both `system` and `registry` are present, `registry` wins on restore. */
+    system?: string;
+    /** Layered context state (system prompt, facts, memory, ...). */
+    registry?: RegistrySnapshot;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}