@combycode/llm-sdk 1.0.0-rc.0

package/dist/plugins/batch/types.d.ts

@@ -0,0 +1,54 @@
+/** Batch types — strategy, provider adapter contract, pending job shape.
+ *
+ *  All BatchProviderAdapter HTTP calls flow through an injected EngineFetch
+ *  (NetworkEngine queue) — adapters do not hold their own fetch fn. The
+ *  Batcher class threads `engine.fetch` into adapter methods on every call,
+ *  so rate-limit, retry, and observability hooks apply uniformly. */
+import type { EngineFetch } from '../../network/types';
+export interface BatchStrategy {
+    collectionWindowMs: number;
+    minBatchSize: number;
+    maxBatchSize: number;
+    shouldBatch(ctx: {
+        provider: string;
+        markedRequestorsCount: number;
+        pendingCount: number;
+    }): boolean;
+    estimateFirstPoll(batchSize: number): number;
+    pollIntervalMs: number;
+}
+export interface BatchProviderAdapter {
+    readonly name: string;
+    submit(requests: BatchRequest[], fetch: EngineFetch): Promise<string>;
+    getStatus(batchId: string, fetch: EngineFetch): Promise<BatchStatus>;
+    getResults(batchId: string, fetch: EngineFetch): Promise<BatchResult[]>;
+    cancel(batchId: string, fetch: EngineFetch): Promise<void>;
+}
+export interface BatchRequest {
+    customId: string;
+    body: Record<string, unknown>;
+}
+export interface BatchStatus {
+    id: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'expired' | 'cancelled';
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+}
+export interface BatchResult {
+    customId: string;
+    success: boolean;
+    response: unknown | null;
+    error: string | null;
+}
+export interface PendingBatchJob {
+    batchId: string;
+    provider: string;
+    createdAt: number;
+    requests: Array<{
+        customId: string;
+        conversationId: string;
+        clientId: string;
+    }>;
+}

package/dist/plugins/cache/cache.d.ts

@@ -0,0 +1,50 @@
+/** Cache — semantic-keyed response cache.
+ *
+ *  Lives at the network layer. Caller (LLMClient via RequestContext, or any
+ *  application) supplies:
+ *    - `cacheName`: namespace ("default", "user-${userId}", "shared", ...)
+ *    - `cacheKey`:  content key (typically a content hash computed by LLMClient)
+ *
+ *  Storage key composition: `cache:{cacheName}:{cacheKey}`.
+ *
+ *  The cache is content-agnostic. It does not compute keys itself — that's
+ *  semantic. The cache itself does not subscribe to a hook bus; NetworkEngine
+ *  owns the bus wiring and emits the relevant cache events.
+ *
+ *  TTL: per-entry, with default at construction. Expired entries are
+ *  detected on `get()` and dropped lazily. */
+import type { CacheStore } from './types';
+export interface CachePluginConfig {
+    store: CacheStore;
+    /** Default TTL in ms applied to entries when caller does not specify one.
+     *  Use Number.POSITIVE_INFINITY for "never expire". */
+    ttlMs?: number;
+    /** Namespace fallback when caller passes `set(undefined, ...)`. Default: 'default'. */
+    defaultName?: string;
+}
+export interface InvalidateScope {
+    /** Keep only entries whose cacheName matches this exact namespace. */
+    cacheName?: string;
+    /** Sub-pattern within a name. Currently a string prefix on cacheKey. */
+    keyPrefix?: string;
+}
+export declare class Cache {
+    private readonly store;
+    private readonly defaultTtl;
+    private readonly defaultName;
+    constructor(config: CachePluginConfig);
+    /** Look up a cached response by (cacheName, cacheKey). Null if missing or expired. */
+    get<T = unknown>(cacheName: string | undefined, cacheKey: string): Promise<T | null>;
+    /** Store a response under (cacheName, cacheKey). Overwrites any existing entry. */
+    set<T = unknown>(cacheName: string | undefined, cacheKey: string, body: T, options?: {
+        ttlMs?: number;
+    }): Promise<void>;
+    /** Remove a single entry. */
+    delete(cacheName: string | undefined, cacheKey: string): Promise<void>;
+    /** Drop entries matching scope. Empty scope clears everything cache-managed.
+     *  Returns the number of entries removed. */
+    invalidate(scope?: InvalidateScope): Promise<number>;
+    /** Drop all entries (cache-managed and otherwise) from the store.
+     *  Compare with `invalidate({})` which only removes cache-prefixed entries. */
+    clear(): Promise<void>;
+}

package/dist/plugins/cache/file-store.d.ts

@@ -0,0 +1,15 @@
+/** FileCacheStore — persists CacheEntries as JSON files via FilePersistence.
+ *  Survives process restart. */
+import type { CacheEntry, CacheStore } from './types';
+export interface FileCacheStoreConfig {
+    dir: string;
+}
+export declare class FileCacheStore implements CacheStore {
+    private readonly store;
+    constructor(config: FileCacheStoreConfig);
+    get<T = unknown>(storageKey: string): Promise<CacheEntry<T> | null>;
+    set<T = unknown>(storageKey: string, entry: CacheEntry<T>): Promise<void>;
+    delete(storageKey: string): Promise<void>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(): Promise<void>;
+}

package/dist/plugins/cache/memory-store.d.ts

@@ -0,0 +1,10 @@
+/** MemoryCacheStore — in-process Map-backed CacheStore. Lost on restart. */
+import type { CacheEntry, CacheStore } from './types';
+export declare class MemoryCacheStore implements CacheStore {
+    private map;
+    get<T = unknown>(storageKey: string): Promise<CacheEntry<T> | null>;
+    set<T = unknown>(storageKey: string, entry: CacheEntry<T>): Promise<void>;
+    delete(storageKey: string): Promise<void>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(): Promise<void>;
+}

package/dist/plugins/cache/types.d.ts

@@ -0,0 +1,28 @@
+/** Cache types — store interface + entry shape.
+ *
+ *  The Cache plugin stores arbitrary response bodies under (cacheName, cacheKey)
+ *  pairs. The semantic layer decides what makes "the same request" by computing
+ *  the `cacheKey`; the cache itself is content-agnostic. */
+export interface CacheEntry<T = unknown> {
+    /** Stored payload — typically a provider's raw response body. */
+    body: T;
+    /** ms-epoch when written. */
+    storedAt: number;
+    /** TTL in ms. Stores prune lazily on get. */
+    ttlMs: number;
+    /** Cache namespace this entry belongs to. Used by `invalidate(cacheName)`. */
+    cacheName: string;
+}
+/** Storage backend. Implementations: MemoryCacheStore, FileCacheStore. */
+export interface CacheStore {
+    /** Get an entry by full storage key. Null if missing or expired. */
+    get<T = unknown>(storageKey: string): Promise<CacheEntry<T> | null>;
+    /** Write an entry. */
+    set<T = unknown>(storageKey: string, entry: CacheEntry<T>): Promise<void>;
+    /** Drop a specific entry. */
+    delete(storageKey: string): Promise<void>;
+    /** List all keys, optionally filtered by prefix. */
+    keys(prefix?: string): Promise<string[]>;
+    /** Drop everything. */
+    clear(): Promise<void>;
+}

package/dist/plugins/configuration/configuration.d.ts

@@ -0,0 +1,71 @@
+/** ConfigurationPlugin — open-shape settings registry keyed by `configName`.
+ *
+ *  Stores arbitrary configuration bundles. Consumers (rate limiter, retry,
+ *  cache TTL, custom plugins) read their own typed slice off each entry by
+ *  convention. The registry itself is opaque about content.
+ *
+ *  Lookup order at consumer time (e.g. NetworkEngine creating a queue):
+ *    1. Lookup by `configName`.
+ *    2. Fallback to a parent name via `extend()` chain (handled internally).
+ *    3. If nothing registered: consumer applies its own hard-coded defaults.
+ *
+ *  Snapshot semantics: when a queue is created, it captures its slice from
+ *  the current config. Subsequent `set()` calls do NOT affect existing queues.
+ *  Live updates are deferred (see report 016 §open-questions).
+ *
+ *  Persistence: optional. When a `Persistence` is supplied, `load()` and
+ *  `save()` round-trip the registry through it under the key `__configurations`.
+ *  The registry does not auto-save; callers do.
+ */
+import type { Persistence } from '../persistence/types';
+/** Per-name settings bundle. Values are opaque. */
+export type ConfigurationEntry = Record<string, unknown>;
+/** What `serialize()` emits / `deserialize()` accepts. */
+export interface SerializedConfigurations {
+    version: 1;
+    entries: Record<string, ConfigurationEntry>;
+    /** Parent chain: child name → parent name. */
+    parents: Record<string, string>;
+}
+export interface ConfigurationPluginConfig {
+    /** Optional storage. When given, `load()` / `save()` use it. */
+    persistence?: Persistence;
+    /** Storage key under which the registry is persisted. Defaults to `__configurations`. */
+    storageKey?: string;
+    /** Initial entries seeded at construction. */
+    initial?: Record<string, ConfigurationEntry>;
+}
+export declare class ConfigurationPlugin {
+    private readonly entries;
+    private readonly parents;
+    private readonly persistence?;
+    private readonly storageKey;
+    constructor(config?: ConfigurationPluginConfig);
+    /** Register or replace settings for a name. Throws if `name` is empty.
+     *  Defensive deep clone: caller's nested objects can be mutated freely
+     *  after `set()` without affecting the stored copy. */
+    set(name: string, settings: ConfigurationEntry): void;
+    /** Look up resolved settings for a name. Walks the parent chain (child overrides
+     *  parent). Returns null if the name (and any ancestor) is unknown. */
+    get(name: string): ConfigurationEntry | null;
+    /** Create a derived configuration that inherits from `baseName`.
+     *  The derived entry stores ONLY the overrides; `get(newName)` merges
+     *  them with the base. */
+    extend(baseName: string, newName: string, overrides: ConfigurationEntry): void;
+    /** Whether a name is registered (directly or via parent chain). */
+    has(name: string): boolean;
+    /** Remove a name. If others extend from it, they remain but `get()` on them
+     *  returns null when their full chain becomes broken. */
+    delete(name: string): void;
+    /** All registered names. */
+    names(): string[];
+    /** Snapshot the registry. */
+    serialize(): SerializedConfigurations;
+    /** Replace the registry from a snapshot. */
+    deserialize(data: SerializedConfigurations): void;
+    /** Load from configured persistence. No-op if no persistence attached.
+     *  Returns true if data was loaded; false if storage was empty. */
+    load(): Promise<boolean>;
+    /** Save to configured persistence. Throws if no persistence attached. */
+    save(): Promise<void>;
+}

package/dist/plugins/context-guard/facts.d.ts

@@ -0,0 +1,14 @@
+/** ExtractedFact — universal fact shape used by ContextGuard's strategies.
+ *  Producers (fact-extract tools, memory tools, custom extractors) emit facts
+ *  in this shape; consumers (renderFactsLayer, snapshots) read them. */
+export declare const FACT_CATEGORIES: readonly ["name", "date", "time", "path", "url", "email", "phone", "address", "amount", "number", "identifier", "other"];
+export type FactCategory = (typeof FACT_CATEGORIES)[number];
+export interface ExtractedFact {
+    /** Short descriptive label. Lowercase, snake_or_dotted notation. */
+    key: string;
+    /** Fact value — verbatim from source for verifiability. */
+    value: string;
+    category: FactCategory;
+    /** Optional surrounding context for ambiguous values. */
+    span?: string;
+}

package/dist/plugins/context-guard/guard.d.ts

@@ -0,0 +1,27 @@
+/** ContextGuard — stateless engine that routes onContextMeasure events to
+ *  per-conversation strategies. */
+import type { ContextGuardConfig } from './types';
+export declare class ContextGuard {
+    private readonly hooks;
+    private readonly measurer;
+    private readonly contextTools;
+    private readonly strategies;
+    private readonly defaultStrategy;
+    private readonly onUnknownStrategy;
+    private readonly maxRetries;
+    private readonly criticalFloor;
+    private readonly triggerCache;
+    private readonly warnedUnknownStrategies;
+    private unsubscribe;
+    constructor(config: ContextGuardConfig);
+    destroy(): void;
+    private wire;
+    private handleMeasure;
+    private resolveStrategy;
+    private resolveStrategyName;
+    private getSortedTriggers;
+    private readState;
+    private writeState;
+    private readStrategyState;
+    private writeStrategyState;
+}

package/dist/plugins/context-guard/strategies/layered.d.ts

@@ -0,0 +1,24 @@
+/** LayeredStrategy — three-zone compaction policy.
+ *
+ *  Zones: recent (verbatim) / middle (per-segment summary) / old (fact-only).
+ *  Escalation by trigger level: healthy/pressure/urgent/critical. */
+import type { ContextStrategy, ReactContext, StrategyDecision, TriggerLevel } from '../types';
+export interface LayeredStrategyConfig {
+    recentCount?: number;
+    middleSummaryChars?: number;
+    oldSummaryChars?: number;
+    jumpEscalateDelta?: number;
+    declineCeiling?: number;
+    triggers?: TriggerLevel[];
+}
+export declare class LayeredStrategy implements ContextStrategy {
+    readonly triggers: TriggerLevel[];
+    private readonly cfg;
+    constructor(config?: LayeredStrategyConfig);
+    react(ctx: ReactContext): Promise<StrategyDecision>;
+    private compactOldLayer;
+    private compactOldAndMiddle;
+    private compactAll;
+    private compactAggressive;
+    private applyJumpEscalation;
+}

package/dist/plugins/context-guard/strategies/truncate.d.ts

@@ -0,0 +1,19 @@
+/** TruncateStrategy — cheapest possible compaction.
+ *
+ *  Drops the oldest messages when usage crosses a threshold. NO LLM calls,
+ *  NO fact extraction, NO summarization. Use for prototypes, smoke tests,
+ *  and conversations where losing old context is acceptable. */
+import type { ContextStrategy, ReactContext, StrategyDecision, TriggerLevel } from '../types';
+export interface TruncateStrategyConfig {
+    keepRecent?: number;
+    triggers?: TriggerLevel[];
+    declineCeiling?: number;
+}
+export declare class TruncateStrategy implements ContextStrategy {
+    readonly name: "truncate";
+    readonly triggers: TriggerLevel[];
+    private readonly keepRecent;
+    private readonly declineCeiling;
+    constructor(config?: TruncateStrategyConfig);
+    react(ctx: ReactContext): Promise<StrategyDecision>;
+}

package/dist/plugins/context-guard/tools.d.ts

@@ -0,0 +1,50 @@
+/** StrategyToolsImpl — plumbing the guard provides to each strategy.
+ *  Wraps history mutation, token measurement, summarize/fact-extract calls,
+ *  and fact injection so policy code stays short. */
+import type { Message } from '../../llm/types/messages';
+import type { TokenCounter } from '../../agent/types';
+import type { ConversationHistory } from '../../agent/history';
+import type { HistoryEntry } from '../../agent/history-types';
+import type { ContextRegistry } from '../../agent/context-registry/registry';
+import type { ExtractedFact } from './facts';
+import type { ContextTools, FactInjectionSite, StrategyTools } from './types';
+export interface StrategyToolsDeps {
+    history: ConversationHistory;
+    /** Active messages array — mutated in place when replaceRange/dropOldest
+     *  fire so the current request reflects the compaction. */
+    activeMessages: Message[];
+    counter: TokenCounter;
+    contextTools: ContextTools;
+    provider: string;
+    model: string;
+}
+export declare class StrategyToolsImpl implements StrategyTools {
+    private readonly deps;
+    constructor(deps: StrategyToolsDeps);
+    get historyLength(): number;
+    segment(opts?: {
+        recentCount?: number;
+        timeWindow?: number;
+    }): {
+        recent: HistoryEntry[];
+        middle: HistoryEntry[];
+        old: HistoryEntry[];
+    };
+    measure(items: readonly HistoryEntry[] | Message[]): number;
+    extractFacts(entries: readonly HistoryEntry[], categories?: string[]): Promise<ExtractedFact[]>;
+    summarize(entries: readonly HistoryEntry[], maxLength: number, focus?: string): Promise<string>;
+    replaceRange(from: number, to: number, replacement: Message): void;
+    dropOldest(n: number): void;
+    injectFacts(facts: ExtractedFact[], site: FactInjectionSite): void;
+    private concatContent;
+    private contentToPlainText;
+    private prependText;
+}
+export declare function renderFactsBlock(facts: ExtractedFact[], opts?: {
+    bareBlock?: boolean;
+}): string;
+export declare function renderFactsLayer(facts: ExtractedFact[]): string;
+export declare function readFactsLayer(registry: ContextRegistry): ExtractedFact[] | null;
+export declare function parseFactsBlock(system: string): ExtractedFact[];
+export declare function writeFactsBlock(system: string, facts: ExtractedFact[]): string;
+export declare function renderPriorFactsForExtraction(facts: ExtractedFact[]): string;

package/dist/plugins/context-guard/types.d.ts

@@ -0,0 +1,110 @@
+/** ContextGuard types — strategy interface, decisions, trigger ladder. */
+import type { Message } from '../../llm/types/messages';
+import type { HookBus } from '../../bus/hook-bus';
+import type { HistoryEntry } from '../../agent/history-types';
+import type { ContextMeasurer } from '../context-measurer/measurer';
+import type { ExtractedFact } from './facts';
+/** One step of the trigger ladder. */
+export interface TriggerLevel {
+    level: string;
+    at: number;
+}
+/** Pluggable adapter for the LLM-driven helpers a strategy may need.
+ *  Default impl is a no-op (TruncateStrategy works without it). Layered
+ *  strategy benefits from real summarize/extractFacts (e.g. backed by an
+ *  agent or a built-in tool registry). */
+export interface ContextTools {
+    summarize(content: string, maxLength: number, focus?: string): Promise<string>;
+    extractFacts(content: string, categories?: string[]): Promise<ExtractedFact[]>;
+}
+/** Default no-op tools — returns empty summary and no facts. Sufficient for
+ *  TruncateStrategy and tests. */
+export declare class NoopContextTools implements ContextTools {
+    summarize(): Promise<string>;
+    extractFacts(): Promise<ExtractedFact[]>;
+}
+/** Adapter that delegates ContextTools to an InternalToolRunner.
+ *  - summarize → runs `orxa:summarize@1.0.0` and returns its `summary` field.
+ *  - extractFacts → runs `orxa:fact-extract@1.0.0` when present in the
+ *    registry, else returns []. (fact-extract ships in extensions/, not core.)
+ */
+export declare class RunnerContextTools implements ContextTools {
+    private readonly deps;
+    constructor(deps: {
+        runner: {
+            run<T>(toolId: string, input: unknown): Promise<T>;
+            registry: {
+                get(toolId: string): Promise<unknown>;
+            };
+        };
+        summarizeId?: string;
+        factExtractId?: string;
+    });
+    summarize(content: string, maxLength: number, focus?: string): Promise<string>;
+    extractFacts(content: string, categories?: string[]): Promise<ExtractedFact[]>;
+}
+export interface ReactContext {
+    level: string;
+    percentage: number;
+    current: number;
+    window: number | null;
+    delta: number;
+    provider: string;
+    model: string;
+    attempt: number;
+    tools: StrategyTools;
+    state: Record<string, unknown>;
+}
+export type StrategyDecision = {
+    action: 'none';
+} | {
+    action: 'compacted';
+    note?: string;
+} | {
+    action: 'warn';
+    message: string;
+} | {
+    action: 'decline';
+    reason: string;
+};
+export interface ContextStrategy {
+    readonly triggers: TriggerLevel[];
+    react(ctx: ReactContext): StrategyDecision | Promise<StrategyDecision>;
+}
+export type FactInjectionSite = 'system-append' | 'first-user-prefix';
+export interface StrategyTools {
+    segment(opts?: {
+        recentCount?: number;
+        timeWindow?: number;
+    }): {
+        recent: HistoryEntry[];
+        middle: HistoryEntry[];
+        old: HistoryEntry[];
+    };
+    measure(items: readonly HistoryEntry[] | Message[]): number;
+    extractFacts(entries: readonly HistoryEntry[], categories?: string[]): Promise<ExtractedFact[]>;
+    summarize(entries: readonly HistoryEntry[], maxLength: number, focus?: string): Promise<string>;
+    replaceRange(from: number, to: number, replacement: Message): void;
+    dropOldest(n: number): void;
+    injectFacts(facts: ExtractedFact[], site: FactInjectionSite): void;
+    readonly historyLength: number;
+}
+export type UnknownStrategyPolicy = 'skip' | 'fallback-default' | 'throw';
+export interface ContextGuardConfig {
+    hooks: HookBus;
+    measurer: ContextMeasurer;
+    /** Pluggable summarize / fact-extract backend. Defaults to a no-op
+     *  (sufficient for TruncateStrategy; LayeredStrategy needs a real one). */
+    contextTools?: ContextTools;
+    strategies: Record<string, ContextStrategy>;
+    defaultStrategy: string;
+    onUnknownStrategy?: UnknownStrategyPolicy;
+    maxCompactRetries?: number;
+    criticalFloor?: number;
+}
+export interface GuardConversationState {
+    v: 1;
+    lastLevelIdx: number;
+    lastCurrent: number;
+    strategyState?: Record<string, Record<string, unknown>>;
+}

package/dist/plugins/context-measurer/calibration/store.d.ts

@@ -0,0 +1,19 @@
+/** PersistenceCalibrationStore — EMA-backed persistence of token rates. */
+import type { ContentClass } from '../../../agent/types';
+import type { Persistence } from '../../persistence/types';
+import type { CalibrationStore, CalibrationEntry, CalibrationConfig } from '../types';
+export declare class PersistenceCalibrationStore implements CalibrationStore {
+    private readonly persistence;
+    private config;
+    constructor(persistence: Persistence, config?: Partial<CalibrationConfig>);
+    get(provider: string, model: string, contentClass?: ContentClass): Promise<CalibrationEntry | null>;
+    update(input: Omit<CalibrationEntry, 'lastUpdated' | 'confidence'>): Promise<CalibrationEntry>;
+    list(opts?: {
+        provider?: string;
+        model?: string;
+    }): Promise<CalibrationEntry[]>;
+    reset(opts?: {
+        provider?: string;
+        model?: string;
+    }): Promise<void>;
+}

package/dist/plugins/context-measurer/counter/count-api.d.ts

@@ -0,0 +1,41 @@
+/** Count API adapter — exact token counting via provider endpoints. */
+import type { Message } from '../../../llm/types/messages';
+import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+import type { FetchFn } from '../../../network/types';
+import type { ModelCatalog } from '../../model-catalog/catalog';
+/** Anthropic count endpoint: POST /v1/messages/count_tokens */
+export declare class AnthropicCountApi {
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly baseURL;
+    constructor(apiKey: string, fetchFn?: FetchFn, baseURL?: string);
+    countMessages(model: string, messages: Array<{
+        role: string;
+        content: unknown;
+    }>, system?: string): Promise<number>;
+    countText(model: string, text: string): Promise<number>;
+}
+/** Google count endpoint: POST /v1beta/models/{model}:countTokens */
+export declare class GoogleCountApi {
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly baseURL;
+    constructor(apiKey: string, fetchFn?: FetchFn, baseURL?: string);
+    countText(model: string, text: string): Promise<number>;
+}
+/** TokenCounter backed by Anthropic/Google count APIs. Falls back to heuristic
+ *  for fast estimates and unknown providers. */
+export declare class CountApiCounter implements TokenCounter {
+    private readonly providers;
+    private heuristic;
+    constructor(catalog: ModelCatalog | null, providers?: {
+        anthropic?: AnthropicCountApi;
+        google?: GoogleCountApi;
+    });
+    estimate(text: string, ctx?: TokenCountContext): number;
+    estimateMessage(msg: Message, ctx?: TokenCountContext): number;
+    measure(text: string, ctx?: TokenCountContext): Promise<number>;
+    measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    learn(input: LearnInput): void;
+    private apiFor;
+}

package/dist/plugins/context-measurer/counter/heuristic.d.ts

@@ -0,0 +1,25 @@
+/** Heuristic token counter — chars-per-token with optional calibration. */
+import type { Message } from '../../../llm/types/messages';
+import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { CalibrationStore } from '../types';
+/** Count chars across a message's content parts. */
+export declare function messageChars(msg: Message): number;
+export declare class HeuristicCounter implements TokenCounter {
+    private readonly catalog;
+    private readonly calibrationStore;
+    private readonly cache;
+    constructor(catalog: ModelCatalog | null, calibrationStore?: CalibrationStore | null);
+    estimate(text: string, ctx?: TokenCountContext): number;
+    estimateMessage(msg: Message, ctx?: TokenCountContext): number;
+    measure(text: string, ctx?: TokenCountContext): Promise<number>;
+    measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    learn(input: LearnInput): void;
+    /** Pre-warm the sync cache from the calibration store. */
+    warmCache(): Promise<void>;
+    private rateSync;
+    private rate;
+    private catalogDefault;
+    private cacheKey;
+    private cacheKeyFor;
+}

package/dist/plugins/context-measurer/counter/hybrid.d.ts

@@ -0,0 +1,33 @@
+/** HybridTokenCounter — selects strategy per model based on catalog config. */
+import type { Message } from '../../../llm/types/messages';
+import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { CalibrationStore } from '../types';
+export interface HybridCounterConfig {
+    catalog?: ModelCatalog;
+    calibrationStore?: CalibrationStore;
+    countApiKeys?: {
+        anthropic?: string;
+        google?: string;
+    };
+}
+/**
+ * HybridTokenCounter routes based on catalog's tokenizer.strategy:
+ *   'tiktoken'  → TiktokenCounter (exact for OpenAI)
+ *   'count_api' → CountApiCounter (exact via provider endpoint for Anthropic/Google)
+ *   'heuristic' → HeuristicCounter (calibration-aware fallback)
+ */
+export declare class HybridTokenCounter implements TokenCounter {
+    private heuristic;
+    private tiktoken;
+    private countApi;
+    private readonly _config;
+    constructor(config: HybridCounterConfig);
+    warmCache(): Promise<void>;
+    estimate(text: string, ctx?: TokenCountContext): number;
+    estimateMessage(msg: Message, ctx?: TokenCountContext): number;
+    measure(text: string, ctx?: TokenCountContext): Promise<number>;
+    measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    learn(input: LearnInput): void;
+    private strategyFor;
+}

package/dist/plugins/context-measurer/counter/tiktoken.d.ts

@@ -0,0 +1,13 @@
+/** Tiktoken adapter — exact tokenization for OpenAI models. */
+import type { Message } from '../../../llm/types/messages';
+import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+export declare class TiktokenCounter implements TokenCounter {
+    private encodings;
+    estimate(text: string, ctx?: TokenCountContext): number;
+    estimateMessage(msg: Message, ctx?: TokenCountContext): number;
+    measure(text: string, ctx?: TokenCountContext): Promise<number>;
+    measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    learn(_input: LearnInput): void;
+    private encodingFor;
+    private getEncoder;
+}