@roj-ai/sdk 0.1.1 → 0.1.4

package/dist/core/llm/snapshot-fetch.js

@@ -0,0 +1,122 @@
+/**
+ * Snapshot-caching fetch wrapper for integration tests.
+ *
+ * On first run (or when request changes), makes a real HTTP call and saves
+ * the request+response pair to a JSON snapshot file. On subsequent runs
+ * with the same request, returns the cached response without making a call.
+ *
+ * Usage:
+ *   const fetch = createSnapshotFetch(snapshotsDir)
+ *   const provider = new AnthropicProvider({ ..., fetch })
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Deterministic hash of a request (URL + method + body).
+ * Headers are excluded because auth headers change between runs.
+ */
+function hashRequest(url, method, body) {
+    const hash = createHash('sha256');
+    hash.update(method);
+    hash.update(url);
+    hash.update(stableStringify(JSON.parse(body)));
+    return hash.digest('hex').slice(0, 16);
+}
+/**
+ * JSON.stringify with sorted keys for deterministic output.
+ */
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val && typeof val === 'object' && !Array.isArray(val)) {
+            return Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return val;
+    });
+}
+/**
+ * Strip sensitive headers (auth) from a headers object for snapshot storage.
+ */
+function sanitizeHeaders(headers) {
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+        const lower = key.toLowerCase();
+        if (lower === 'authorization' || lower === 'x-api-key')
+            continue;
+        result[key] = value;
+    }
+    return result;
+}
+export function createSnapshotFetch(snapshotsDir, testName) {
+    const snapshotPath = join(snapshotsDir, `${testName}.json`);
+    return async (input, init) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+        const method = init?.method ?? 'GET';
+        const body = typeof init?.body === 'string' ? init.body : '';
+        const currentHash = hashRequest(url, method, body);
+        // Try loading existing snapshot
+        let snapshot = null;
+        try {
+            const content = await readFile(snapshotPath, 'utf-8');
+            snapshot = JSON.parse(content);
+        }
+        catch {
+            // No snapshot yet
+        }
+        // If snapshot exists and hash matches, return cached response
+        if (snapshot && snapshot.requestHash === currentHash) {
+            return new Response(JSON.stringify(snapshot.response.body), {
+                status: snapshot.response.status,
+                headers: snapshot.response.headers,
+            });
+        }
+        // Make real request
+        const response = await globalThis.fetch(input, init);
+        const responseBody = await response.json();
+        // Extract response headers
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        // Extract request headers
+        const requestHeaders = {};
+        if (init?.headers) {
+            if (init.headers instanceof Headers) {
+                init.headers.forEach((value, key) => {
+                    requestHeaders[key] = value;
+                });
+            }
+            else if (Array.isArray(init.headers)) {
+                for (const [key, value] of init.headers) {
+                    requestHeaders[key] = value;
+                }
+            }
+            else {
+                Object.assign(requestHeaders, init.headers);
+            }
+        }
+        // Save snapshot
+        const entry = {
+            requestHash: currentHash,
+            request: {
+                url,
+                method,
+                headers: sanitizeHeaders(requestHeaders),
+                body: body ? JSON.parse(body) : null,
+            },
+            response: {
+                status: response.status,
+                headers: sanitizeHeaders(responseHeaders),
+                body: responseBody,
+            },
+        };
+        await mkdir(snapshotsDir, { recursive: true });
+        await writeFile(snapshotPath, JSON.stringify(entry, null, '\t'));
+        // Return a new Response from the parsed body (original was consumed)
+        return new Response(JSON.stringify(responseBody), {
+            status: response.status,
+            headers: responseHeaders,
+        });
+    };
+}
+//# sourceMappingURL=snapshot-fetch.js.map

package/dist/core/llm/snapshot-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-fetch.js","sourceRoot":"","sources":["../../../src/core/llm/snapshot-fetch.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/snapshot-middleware.js

@@ -0,0 +1,142 @@
+/**
+ * Snapshot-caching LLM middleware for e2e tests.
+ *
+ * Works at the InferenceRequest/InferenceResponse boundary (not HTTP). On a
+ * request hit, returns the cached response without calling the downstream
+ * provider. On a miss, forwards the request, records the response, writes
+ * one snapshot file per request hash.
+ *
+ * Unlike the lower-level `snapshot-fetch` (which writes one file per testName
+ * and overwrites on each call), this middleware keys by request hash — so a
+ * single multi-turn test records N independent snapshots.
+ *
+ * Usage:
+ *   startStandaloneServer({
+ *     presets: [myPreset],
+ *     llmMiddleware: [createSnapshotLLMMiddleware({ snapshotsDir: '...' })],
+ *   })
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Err, Ok } from '../../lib/utils/result.js';
+/**
+ * Replace all UUIDs in a string with a `__UUID__` placeholder.
+ */
+export function stripUuids(text) {
+    return text.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '__UUID__');
+}
+/**
+ * Replace dynamically assigned TCP ports (e.g. `port 46140`, `:46140`) with
+ * a `__PORT__` placeholder. Dev services in roj pick free ports at runtime,
+ * which otherwise bust the snapshot key on every run.
+ */
+export function stripEphemeralPorts(text) {
+    return text
+        .replace(/port\s+(\d{4,5})\b/gi, 'port __PORT__')
+        .replace(/:(1[0-9]{4}|[2-6][0-9]{4})\b/g, ':__PORT__');
+}
+/**
+ * Compose multiple text stripping functions.
+ */
+export function composeStrippers(...fns) {
+    return (text) => fns.reduce((acc, fn) => fn(acc), text);
+}
+/**
+ * Build a `normalize` hook that applies a text-level stripper to the system
+ * prompt and all string-form message content / text parts.
+ */
+export function normalizeWith(stripper) {
+    return (request) => ({
+        ...request,
+        systemPrompt: stripper(request.systemPrompt),
+        messages: request.messages.map((m) => {
+            if (typeof m.content === 'string') {
+                return { ...m, content: stripper(m.content) };
+            }
+            if (Array.isArray(m.content)) {
+                return {
+                    ...m,
+                    content: m.content.map((part) => part.type === 'text' ? { ...part, text: stripper(part.text) } : part),
+                };
+            }
+            return m;
+        }),
+    });
+}
+/**
+ * A `normalize` implementation that strips UUIDs from the request text.
+ * Use `normalizeStripRuntime` if dev service ports also leak into prompts.
+ */
+export const normalizeStripUuids = normalizeWith(stripUuids);
+/**
+ * `normalize` implementation for typical e2e runs: strips UUIDs and
+ * dynamically-assigned ports. Covers the usual suspects; add your own with
+ * `normalizeWith(composeStrippers(...))` for more.
+ */
+export const normalizeStripRuntime = normalizeWith(composeStrippers(stripUuids, stripEphemeralPorts));
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val && typeof val === 'object' && !Array.isArray(val)) {
+            return Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return val;
+    });
+}
+/**
+ * Build a stable digest of the request. Strips:
+ *   - tool `input`/`execute` functions + Zod schemas (reduced to name/description)
+ *   - conversation-metadata fields on messages (`timestamp`, `isError`,
+ *     `toolName`, `sourceMessageIds`) — not forwarded to the LLM, so they
+ *     shouldn't bust the snapshot key either.
+ */
+function stripMessageMetadata(message) {
+    if (!message || typeof message !== 'object')
+        return message;
+    const { timestamp: _t, isError: _e, toolName: _n, sourceMessageIds: _s, ...rest } = message;
+    return rest;
+}
+function buildDigest(request) {
+    return {
+        model: String(request.model),
+        systemPrompt: request.systemPrompt,
+        messages: request.messages.map(stripMessageMetadata),
+        tools: request.tools?.map((t) => ({ name: t.name, description: t.description })),
+        maxTokens: request.maxTokens,
+        temperature: request.temperature,
+        stopSequences: request.stopSequences,
+        openrouter: request.openrouter,
+        anthropic: request.anthropic,
+    };
+}
+function hashDigest(digest) {
+    return createHash('sha256').update(stableStringify(digest)).digest('hex').slice(0, 16);
+}
+export function createSnapshotLLMMiddleware(options) {
+    const mode = options.mode ?? 'auto';
+    mkdirSync(options.snapshotsDir, { recursive: true });
+    return async (request, context, next) => {
+        const forHashing = options.normalize ? options.normalize(request) : request;
+        const digest = buildDigest(forHashing);
+        const hash = hashDigest(digest);
+        const filePath = join(options.snapshotsDir, `${hash}.json`);
+        const hasSnapshot = existsSync(filePath);
+        if (mode !== 'record' && hasSnapshot) {
+            const entry = JSON.parse(readFileSync(filePath, 'utf-8'));
+            return Ok(entry.response);
+        }
+        if (mode === 'replay') {
+            return Err({
+                type: 'invalid_request',
+                message: `Snapshot not found (replay mode): ${hash}. Set mode to 'auto' or 'record' and provide API keys to record.`,
+            });
+        }
+        const result = await next(request, context);
+        if (result.ok) {
+            const entry = { request: digest, response: result.value };
+            writeFileSync(filePath, JSON.stringify(entry, null, '\t'));
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=snapshot-middleware.js.map

package/dist/core/llm/snapshot-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-middleware.js","sourceRoot":"","sources":["../../../src/core/llm/snapshot-middleware.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/snapshot-middleware.test.js

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isErr, isOk } from '../../lib/utils/result.js';
+import { applyMiddleware } from './middleware.js';
+import { MockLLMProvider } from './mock.js';
+import { ModelId } from './schema.js';
+import { createSnapshotLLMMiddleware } from './snapshot-middleware.js';
+describe('SnapshotLLMMiddleware', () => {
+    let dir;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'roj-snap-'));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    const request = (overrides = {}) => ({
+        model: ModelId('test-model'),
+        systemPrompt: 'You are a test assistant.',
+        messages: [{ role: 'user', content: 'Hello' }],
+        ...overrides,
+    });
+    const fixedResponse = {
+        content: 'Recorded response',
+        toolCalls: [],
+        finishReason: 'stop',
+        metrics: MockLLMProvider.defaultMetrics(),
+    };
+    test('records on miss and replays on hit without calling next', async () => {
+        const downstream = new MockLLMProvider(() => fixedResponse);
+        const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })]);
+        const first = await wrapped.inference(request());
+        expect(isOk(first)).toBe(true);
+        expect(downstream.getCallCount()).toBe(1);
+        // Snapshot file created
+        const files = readdirSync(dir);
+        expect(files.length).toBe(1);
+        expect(files[0]).toMatch(/^[0-9a-f]{16}\.json$/);
+        // Replay — downstream NOT called again
+        const second = await wrapped.inference(request());
+        expect(isOk(second)).toBe(true);
+        if (isOk(second)) {
+            expect(second.value.content).toBe('Recorded response');
+        }
+        expect(downstream.getCallCount()).toBe(1);
+    });
+    test('distinct requests produce distinct snapshot files', async () => {
+        const downstream = new MockLLMProvider(() => fixedResponse);
+        const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })]);
+        await wrapped.inference(request({ messages: [{ role: 'user', content: 'A' }] }));
+        await wrapped.inference(request({ messages: [{ role: 'user', content: 'B' }] }));
+        expect(readdirSync(dir).length).toBe(2);
+        expect(downstream.getCallCount()).toBe(2);
+    });
+    test('hash is stable across key-order differences', async () => {
+        const downstream = new MockLLMProvider(() => fixedResponse);
+        const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })]);
+        // Two requests identical in content but constructed with different key order
+        await wrapped.inference({
+            model: ModelId('m'),
+            systemPrompt: 's',
+            messages: [{ role: 'user', content: 'x' }],
+            temperature: 0.5,
+            maxTokens: 100,
+        });
+        await wrapped.inference({
+            maxTokens: 100,
+            temperature: 0.5,
+            messages: [{ role: 'user', content: 'x' }],
+            systemPrompt: 's',
+            model: ModelId('m'),
+        });
+        // Same hash → single snapshot file → downstream called once
+        expect(readdirSync(dir).length).toBe(1);
+        expect(downstream.getCallCount()).toBe(1);
+    });
+    test('replay mode errors on miss', async () => {
+        const downstream = new MockLLMProvider(() => fixedResponse);
+        const wrapped = applyMiddleware(downstream, [
+            createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'replay' }),
+        ]);
+        const result = await wrapped.inference(request());
+        expect(isErr(result)).toBe(true);
+        if (isErr(result)) {
+            expect(result.error.type).toBe('invalid_request');
+            expect(result.error.message).toContain('Snapshot not found');
+        }
+        expect(downstream.getCallCount()).toBe(0);
+    });
+    test('replay mode serves existing snapshot', async () => {
+        // Pre-seed a snapshot by running once in auto mode
+        const downstream1 = new MockLLMProvider(() => fixedResponse);
+        const recording = applyMiddleware(downstream1, [createSnapshotLLMMiddleware({ snapshotsDir: dir })]);
+        await recording.inference(request());
+        // Now a replay-only chain must hit it
+        const downstream2 = new MockLLMProvider(() => {
+            throw new Error('should not be called');
+        });
+        const replaying = applyMiddleware(downstream2, [
+            createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'replay' }),
+        ]);
+        const result = await replaying.inference(request());
+        expect(isOk(result)).toBe(true);
+        if (isOk(result)) {
+            expect(result.value.content).toBe('Recorded response');
+        }
+    });
+    test('record mode overwrites existing snapshot', async () => {
+        // Seed with response A
+        const downstream1 = new MockLLMProvider(() => ({ ...fixedResponse, content: 'A' }));
+        const first = applyMiddleware(downstream1, [createSnapshotLLMMiddleware({ snapshotsDir: dir })]);
+        await first.inference(request());
+        // Force re-record with response B
+        const downstream2 = new MockLLMProvider(() => ({ ...fixedResponse, content: 'B' }));
+        const second = applyMiddleware(downstream2, [
+            createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'record' }),
+        ]);
+        await second.inference(request());
+        // Read back
+        const downstream3 = new MockLLMProvider(() => {
+            throw new Error('should not be called');
+        });
+        const third = applyMiddleware(downstream3, [
+            createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'replay' }),
+        ]);
+        const result = await third.inference(request());
+        expect(isOk(result)).toBe(true);
+        if (isOk(result)) {
+            expect(result.value.content).toBe('B');
+        }
+    });
+    test('does not persist error responses', async () => {
+        const downstream = new MockLLMProvider(() => {
+            const err = { type: 'rate_limit', message: 'throttled' };
+            throw err;
+        });
+        const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })]);
+        const result = await wrapped.inference(request());
+        expect(isErr(result)).toBe(true);
+        expect(readdirSync(dir).length).toBe(0);
+    });
+});
+//# sourceMappingURL=snapshot-middleware.test.js.map

package/dist/core/llm/snapshot-middleware.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-middleware.test.js","sourceRoot":"","sources":["../../../src/core/llm/snapshot-middleware.test.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/state.js

@@ -0,0 +1,48 @@
+import z4 from 'zod/v4';
+import { agentIdSchema } from '../../core/agents';
+import { createEventsFactory } from '../../core/events/types';
+import { toolCallIdSchema } from '../../core/tools/schema';
+import { messageIdSchema } from '../../plugins/mailbox/schema';
+import { llmCallIdSchema } from './schema';
+// ============================================================================
+// LLM events
+// ============================================================================
+export const llmEvents = createEventsFactory({
+    events: {
+        inference_started: z4.object({
+            agentId: agentIdSchema,
+            messages: z4.array(z4.custom()),
+            consumedMessageIds: z4.array(messageIdSchema),
+        }),
+        inference_completed: z4.object({
+            agentId: agentIdSchema,
+            consumedMessageIds: z4.array(messageIdSchema),
+            response: z4.object({
+                content: z4.string().nullable(),
+                toolCalls: z4.array(z4.object({
+                    id: toolCallIdSchema,
+                    name: z4.string(),
+                    input: z4.unknown(),
+                })),
+            }),
+            metrics: z4.object({
+                promptTokens: z4.number(),
+                completionTokens: z4.number(),
+                totalTokens: z4.number(),
+                latencyMs: z4.number(),
+                model: z4.string(),
+                provider: z4.string().optional(),
+                cost: z4.number().optional(),
+                cachedTokens: z4.number().optional(),
+                cacheWriteTokens: z4.number().optional(),
+            }),
+            llmCallId: llmCallIdSchema.optional(),
+        }),
+        inference_failed: z4.object({
+            agentId: agentIdSchema,
+            error: z4.string(),
+            llmCallId: llmCallIdSchema.optional(),
+        }),
+    },
+});
+//# sourceMappingURL=state.js.map

package/dist/core/llm/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/llm/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,QAAQ,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAwC1C,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,MAAM,CAAC,MAAM,SAAS,GAAG,mBAAmB,CAAC;IAC5C,MAAM,EAAE;QACP,iBAAiB,EAAE,EAAE,CAAC,MAAM,CAAC;YAC5B,OAAO,EAAE,aAAa;YACtB,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAc,CAAC;YAC3C,kBAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC;SAC7C,CAAC;QACF,mBAAmB,EAAE,EAAE,CAAC,MAAM,CAAC;YAC9B,OAAO,EAAE,aAAa;YACtB,kBAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC;YAC7C,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC;gBACnB,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC/B,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC;oBAC7B,EAAE,EAAE,gBAAgB;oBACpB,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE;oBACjB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE;iBACnB,CAAC,CAAC;aACH,CAAC;YACF,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC;gBAClB,YAAY,EAAE,EAAE,CAAC,MAAM,EAAE;gBACzB,gBAAgB,EAAE,EAAE,CAAC,MAAM,EAAE;gBAC7B,WAAW,EAAE,EAAE,CAAC,MAAM,EAAE;gBACxB,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE;gBACtB,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE;gBAClB,QAAQ,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAChC,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC5B,YAAY,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBACpC,gBAAgB,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;aACxC,CAAC;YACF,SAAS,EAAE,eAAe,CAAC,QAAQ,EAAE;SACrC,CAAC;QACF,gBAAgB,EAAE,EAAE,CAAC,MAAM,CAAC;YAC3B,OAAO,EAAE,aAAa;YACtB,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE;YAClB,SAAS,EAAE,eAAe,CAAC,QAAQ,EAAE;SACrC,CAAC;KACF;CACD,CAAC,CAAA"}

package/dist/core/llm/tokens.js

@@ -0,0 +1,40 @@
+/**
+ * Token estimation utilities using tokenx library.
+ * Provides ~95-98% accuracy compared to full tokenizers.
+ */
+import { estimateTokenCount, sliceByTokens } from 'tokenx';
+/**
+ * Estimate token count for a text string.
+ * Uses tokenx library for better accuracy than simple char/4 heuristic.
+ */
+export function estimateTokens(text) {
+    return estimateTokenCount(text);
+}
+/**
+ * Truncate text to fit within a token budget.
+ * Returns null if text is already within budget.
+ * Uses 80/20 head/tail split via sliceByTokens.
+ */
+export function truncateByTokens(text, maxTokens) {
+    const originalTokens = estimateTokenCount(text);
+    // 5% tolerance to avoid truncating near the boundary
+    if (originalTokens <= maxTokens * 1.05)
+        return null;
+    const headBudget = Math.floor(maxTokens * 0.8);
+    const tailBudget = maxTokens - headBudget;
+    const head = sliceByTokens(text, 0, headBudget);
+    const tail = sliceByTokens(text, -tailBudget);
+    const content = `${head}\n\n[... truncated — ~${originalTokens} tokens total ...]\n\n${tail}`;
+    return { content, originalTokens };
+}
+/**
+ * Estimate total tokens for an array of messages.
+ * Includes ~4 tokens overhead per message for role/formatting.
+ */
+export function estimateMessagesTokens(messages) {
+    return messages.reduce((sum, msg) => {
+        const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+        return sum + estimateTokens(content) + 4; // 4 tokens overhead per message
+    }, 0);
+}
+//# sourceMappingURL=tokens.js.map

package/dist/core/llm/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../../src/core/llm/tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAE1D;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAA;AAChC,CAAC;AAmBD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IAC/D,MAAM,cAAc,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;IAC/C,qDAAqD;IACrD,IAAI,cAAc,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,IAAI,CAAA;IAEnD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,CAAA;IAC9C,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;IACzC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC,CAAA;IAC/C,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,CAAA;IAE7C,MAAM,OAAO,GAAG,GAAG,IAAI,yBAAyB,cAAc,yBAAyB,IAAI,EAAE,CAAA;IAC7F,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAA;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAkC;IACxE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACnC,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC3F,OAAO,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA,CAAC,gCAAgC;IAC1E,CAAC,EAAE,CAAC,CAAC,CAAA;AACN,CAAC"}