@alejandroroman/agent-kit 0.1.4 → 0.2.0

package/dist/llm/types.js

@@ -4,3 +4,12 @@ export function extractText(content) {
         .map((b) => b.text)
         .join("");
 }
+/** Extract text from user content (string or UserContentBlock[]) */
+export function extractUserText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+}

package/dist/logger.js

@@ -1,4 +1,5 @@
 import pino from "pino";
+import { trace } from "@opentelemetry/api";
 const root = pino({
     level: process.env.LOG_LEVEL ?? "info",
     transport: {
@@ -9,6 +10,13 @@ const root = pino({
             colorize: true,
         },
     },
+    mixin() {
+        const span = trace.getActiveSpan();
+        if (!span)
+            return {};
+        const ctx = span.spanContext();
+        return { trace_id: ctx.traceId, span_id: ctx.spanId };
+    },
 });
 export function createLogger(name) {
     return root.child({ component: name });

package/dist/media/sanitize.d.ts

@@ -0,0 +1,5 @@
+export interface SanitizedImage {
+    base64: string;
+    mediaType: string;
+}
+export declare function sanitizeImage(buffer: Buffer, claimedMimeType?: string): Promise<SanitizedImage>;

package/dist/media/sanitize.js

@@ -0,0 +1,53 @@
+import sharp from "sharp";
+const MAX_BYTES = 20 * 1024 * 1024; // 20MB — raw upload limit (sharp will resize/compress)
+const MAX_DIMENSION = 1200;
+const JPEG_QUALITY = 85;
+const SUPPORTED_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+// Magic byte signatures
+const SIGNATURES = [
+    [Buffer.from([0x89, 0x50, 0x4e, 0x47]), "image/png"],
+    [Buffer.from([0xff, 0xd8, 0xff]), "image/jpeg"],
+    [Buffer.from("GIF87a"), "image/gif"],
+    [Buffer.from("GIF89a"), "image/gif"],
+    [Buffer.from("RIFF"), "image/webp"], // RIFF....WEBP
+];
+function sniffMimeType(buffer) {
+    for (const [sig, type] of SIGNATURES) {
+        if (buffer.length >= sig.length && buffer.subarray(0, sig.length).equals(sig)) {
+            // For WEBP, also check bytes 8-12 for "WEBP"
+            if (type === "image/webp") {
+                if (buffer.length >= 12 && buffer.subarray(8, 12).toString() === "WEBP")
+                    return type;
+                continue;
+            }
+            return type;
+        }
+    }
+    return undefined;
+}
+export async function sanitizeImage(buffer, claimedMimeType) {
+    if (buffer.length > MAX_BYTES) {
+        throw new Error(`Image exceeds 20 MB size limit (${(buffer.length / 1024 / 1024).toFixed(1)} MB)`);
+    }
+    const sniffed = sniffMimeType(buffer);
+    const mediaType = sniffed ?? claimedMimeType;
+    if (!mediaType || !SUPPORTED_TYPES.has(mediaType)) {
+        throw new Error(`Unsupported image type: ${mediaType ?? "unknown"}`);
+    }
+    const meta = await sharp(buffer).metadata();
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    let output;
+    if (width > MAX_DIMENSION || height > MAX_DIMENSION) {
+        // Resize to fit within MAX_DIMENSION, preserving aspect ratio
+        // Recompress as JPEG for smaller output
+        output = await sharp(buffer)
+            .resize(MAX_DIMENSION, MAX_DIMENSION, { fit: "inside", withoutEnlargement: true })
+            .jpeg({ quality: JPEG_QUALITY })
+            .toBuffer();
+        return { base64: output.toString("base64"), mediaType: "image/jpeg" };
+    }
+    // No resize needed — return as-is
+    output = buffer;
+    return { base64: output.toString("base64"), mediaType };
+}

package/dist/multi/spawn.js

@@ -1,14 +1,33 @@
 import { runAgentLoop } from "../agent/loop.js";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { getTracer, ATTR } from "../telemetry/index.js";
 export async function spawnAgent(options) {
-    return runAgentLoop([{ role: "user", content: options.task }], {
-        model: options.model,
-        fallbacks: options.fallbacks,
-        systemPrompt: options.systemPrompt,
-        tools: options.tools,
-        maxIterations: options.maxIterations ?? 10,
-        label: options.label,
-        agentName: options.label,
-        usageStore: options.usageStore,
-        source: "spawn",
+    const tracer = getTracer("multi");
+    const span = tracer.startSpan("agent.spawn", {
+        attributes: {
+            [ATTR.SPAWN_CHILD]: options.label ?? "unknown",
+        },
     });
+    try {
+        const result = await runAgentLoop([{ role: "user", content: options.task }], {
+            model: options.model,
+            fallbacks: options.fallbacks,
+            systemPrompt: options.systemPrompt,
+            tools: options.tools,
+            maxIterations: options.maxIterations ?? 10,
+            label: options.label,
+            agentName: options.label,
+            usageStore: options.usageStore,
+            source: "spawn",
+        });
+        return result;
+    }
+    catch (err) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    finally {
+        span.end();
+    }
 }

package/dist/session/compaction.js

@@ -1,5 +1,6 @@
 import { complete } from "../llm/index.js";
 import { extractText } from "../llm/types.js";
+import { pruneImages } from "./prune-images.js";
 export function estimateTokens(message) {
     return Math.ceil(JSON.stringify(message).length / 4);
 }
@@ -13,6 +14,7 @@ export async function compactMessages(messages, model, tokenThreshold = 100_000)
     const splitPoint = Math.floor(messages.length / 2);
     const oldMessages = messages.slice(0, splitPoint);
     const recentMessages = messages.slice(splitPoint);
+    const prunedOld = pruneImages(oldMessages, 0);
     const summaryResponse = await complete(model, [{
             role: "user",
             content: "Summarize this conversation concisely. Preserve:\n" +
@@ -20,7 +22,7 @@ export async function compactMessages(messages, model, tokenThreshold = 100_000)
                 "- Important decisions made\n" +
                 "- Open tasks or TODOs\n" +
                 "- File paths and code changes discussed\n\n" +
-                JSON.stringify(oldMessages, null, 2),
+                JSON.stringify(prunedOld, null, 2),
         }]);
     const summaryText = extractText(summaryResponse.content);
     return [

package/dist/session/prune-images.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "../llm/types.js";
+/**
+ * Returns a shallow copy of messages with ImageBlocks replaced by text placeholders
+ * in user messages older than `keepLastNTurns` user turns from the end.
+ * A "turn" is defined by a user message — all messages (assistant, tool_result)
+ * between two user messages belong to the same turn as the preceding user message.
+ * Does NOT mutate the original array.
+ */
+export declare function pruneImages(messages: Message[], keepLastNTurns?: number): Message[];

package/dist/session/prune-images.js

@@ -0,0 +1,42 @@
+const IMAGE_PLACEHOLDER = {
+    type: "text",
+    text: "[image previously shared \u2014 already processed]",
+};
+/**
+ * Returns a shallow copy of messages with ImageBlocks replaced by text placeholders
+ * in user messages older than `keepLastNTurns` user turns from the end.
+ * A "turn" is defined by a user message — all messages (assistant, tool_result)
+ * between two user messages belong to the same turn as the preceding user message.
+ * Does NOT mutate the original array.
+ */
+export function pruneImages(messages, keepLastNTurns = 4) {
+    // Find the Nth user message from the end — this is the start of the kept range.
+    // Everything before it (older turns and their tool results) gets image-pruned.
+    let turnsSeen = 0;
+    let cutoff = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            turnsSeen++;
+            if (turnsSeen === keepLastNTurns) {
+                cutoff = i;
+                break;
+            }
+        }
+    }
+    if (turnsSeen < keepLastNTurns)
+        return messages; // fewer turns than threshold
+    return messages.map((msg, i) => {
+        if (i >= cutoff)
+            return msg;
+        if (msg.role === "user" || msg.role === "tool_result") {
+            if (typeof msg.content === "string")
+                return msg;
+            const hasImage = msg.content.some((b) => b.type === "image");
+            if (!hasImage)
+                return msg;
+            const pruned = msg.content.map((b) => b.type === "image" ? IMAGE_PLACEHOLDER : b);
+            return { ...msg, content: pruned };
+        }
+        return msg;
+    });
+}

package/dist/skills/activate.d.ts

@@ -1,6 +1,7 @@
 import type { Tool } from "../tools/types.js";
 import type { ToolRegistry } from "../tools/registry.js";
 import type { SkillManifest } from "./schema.js";
+import type { Logger } from "pino";
 export interface SkillActivationContext {
     manifests: SkillManifest[];
     skillsDir: string;
@@ -8,4 +9,9 @@ export interface SkillActivationContext {
     promptFragments: string[];
     activatedSkills: Set<string>;
 }
+/**
+ * Auto-activate all skills upfront so the LLM doesn't need to call activate_skill.
+ * Returns the skillsIndex string to append to the system prompt.
+ */
+export declare function preActivateSkills(ctx: SkillActivationContext, activateTool: Tool, logger?: Logger): Promise<string>;
 export declare function createActivateSkillTool(ctx: SkillActivationContext): Tool;

package/dist/skills/activate.js

@@ -1,6 +1,32 @@
 import * as fs from "fs";
 import * as path from "path";
 import { loadSkillManifest } from "./loader.js";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { getTracer, ATTR } from "../telemetry/index.js";
+/**
+ * Auto-activate all skills upfront so the LLM doesn't need to call activate_skill.
+ * Returns the skillsIndex string to append to the system prompt.
+ */
+export async function preActivateSkills(ctx, activateTool, logger) {
+    for (const manifest of ctx.manifests) {
+        try {
+            const result = await activateTool.execute({ skill_name: manifest.name });
+            if (typeof result === "string" && result.startsWith("Error")) {
+                logger?.error({ skill: manifest.name, result }, "failed to auto-activate skill");
+            }
+        }
+        catch (err) {
+            logger?.error({ err, skill: manifest.name }, "skill auto-activation threw");
+        }
+    }
+    const activatedNames = [...ctx.activatedSkills];
+    if (activatedNames.length > 0) {
+        return "\n\nThe following skills are pre-activated: "
+            + activatedNames.join(", ")
+            + ".\nTheir tools are already available — you do not need to call activate_skill.";
+    }
+    return "";
+}
 export function createActivateSkillTool(ctx) {
     return {
         name: "activate_skill",
@@ -24,39 +50,58 @@ export function createActivateSkillTool(ctx) {
             if (!manifest) {
                 return `Skill "${skillName}" is not available. Available skills: ${ctx.manifests.map((m) => m.name).join(", ")}`;
             }
-            const skillDir = path.join(ctx.skillsDir, skillName);
-            const fullManifest = loadSkillManifest(skillDir);
-            const loadedTools = [];
-            // Load prompt fragment
-            if (fullManifest.prompt) {
-                const promptPath = path.join(skillDir, fullManifest.prompt);
-                if (fs.existsSync(promptPath)) {
-                    ctx.promptFragments.push(fs.readFileSync(promptPath, "utf-8"));
+            const tracer = getTracer("skills");
+            const span = tracer.startSpan("skill.activate", {
+                attributes: {
+                    [ATTR.SKILL_NAME]: skillName,
+                },
+            });
+            try {
+                const skillDir = path.join(ctx.skillsDir, skillName);
+                const fullManifest = loadSkillManifest(skillDir);
+                const loadedTools = [];
+                // Load prompt fragment
+                if (fullManifest.prompt) {
+                    const promptPath = path.join(skillDir, fullManifest.prompt);
+                    if (fs.existsSync(promptPath)) {
+                        ctx.promptFragments.push(fs.readFileSync(promptPath, "utf-8"));
+                    }
                 }
-            }
-            // Load tools via dynamic import
-            if (fullManifest.tools) {
-                for (const toolName of fullManifest.tools) {
-                    const toolPath = path.join(skillDir, "tools", `${toolName}.ts`);
-                    if (fs.existsSync(toolPath)) {
-                        try {
-                            const mod = await import(toolPath);
-                            const tool = mod.default;
-                            ctx.toolRegistry.register(tool);
-                            loadedTools.push(tool.name);
-                        }
-                        catch (err) {
-                            return `Error loading tool "${toolName}" from skill "${skillName}": ${err instanceof Error ? err.message : String(err)}`;
+                // Load tools via dynamic import
+                if (fullManifest.tools) {
+                    for (const toolName of fullManifest.tools) {
+                        const toolPath = path.join(skillDir, "tools", `${toolName}.ts`);
+                        if (fs.existsSync(toolPath)) {
+                            try {
+                                const mod = await import(toolPath);
+                                const tool = mod.default;
+                                ctx.toolRegistry.register(tool);
+                                loadedTools.push(tool.name);
+                            }
+                            catch (err) {
+                                span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+                                span.recordException(err instanceof Error ? err : new Error(String(err)));
+                                return `Error loading tool "${toolName}" from skill "${skillName}": ${err instanceof Error ? err.message : String(err)}`;
+                            }
                         }
                     }
                 }
+                ctx.activatedSkills.add(skillName);
+                span.setAttribute(ATTR.SKILL_TOOLS_LOADED, loadedTools.length);
+                const parts = [`Skill "${skillName}" activated.`];
+                if (loadedTools.length > 0) {
+                    parts.push(`Tools now available: ${loadedTools.join(", ")}`);
+                }
+                return parts.join(" ");
+            }
+            catch (err) {
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+                span.recordException(err instanceof Error ? err : new Error(String(err)));
+                throw err;
             }
-            ctx.activatedSkills.add(skillName);
-            const parts = [`Skill "${skillName}" activated.`];
-            if (loadedTools.length > 0) {
-                parts.push(`Tools now available: ${loadedTools.join(", ")}`);
+            finally {
+                span.end();
             }
-            return parts.join(" ");
         },
     };
 }

package/dist/skills/index.d.ts

@@ -1,3 +1,3 @@
 export { SkillManifestSchema, type SkillManifest } from "./schema.js";
 export { loadSkillManifest, loadAllSkillManifests } from "./loader.js";
-export { createActivateSkillTool, type SkillActivationContext } from "./activate.js";
+export { createActivateSkillTool, preActivateSkills, type SkillActivationContext } from "./activate.js";

package/dist/skills/index.js

@@ -1,3 +1,3 @@
 export { SkillManifestSchema } from "./schema.js";
 export { loadSkillManifest, loadAllSkillManifests } from "./loader.js";
-export { createActivateSkillTool } from "./activate.js";
+export { createActivateSkillTool, preActivateSkills } from "./activate.js";

package/dist/telemetry/db.d.ts

@@ -0,0 +1,63 @@
+export interface SpanRow {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string | null;
+    name: string;
+    kind: string;
+    status: string;
+    agent?: string | null;
+    source?: string | null;
+    start_time: number;
+    end_time: number;
+    duration_ms: number;
+    attributes: string;
+    events: string;
+}
+export interface ErrorRow {
+    trace_id: string;
+    span_id: string;
+    fingerprint: string;
+    error_type?: string | null;
+    message: string;
+    stack?: string | null;
+    agent?: string | null;
+    source?: string | null;
+}
+export interface EventRow {
+    trace_id?: string | null;
+    span_id?: string | null;
+    name: string;
+    agent?: string | null;
+    body?: string;
+}
+export interface ListTracesOptions {
+    agent?: string;
+    source?: string;
+    status?: string;
+    since?: string;
+    limit?: number;
+}
+export interface RecentErrorsOptions {
+    agent?: string;
+    source?: string;
+    since?: string;
+    limit?: number;
+}
+export interface ErrorStatsOptions {
+    since?: string;
+    groupBy?: "fingerprint" | "agent";
+}
+export declare class TelemetryDb {
+    private db;
+    constructor(dbPath: string);
+    insertSpan(span: SpanRow): void;
+    insertError(error: ErrorRow): void;
+    insertEvent(event: EventRow): void;
+    getTraceSpans(traceId: string): any[];
+    listTraces(options: ListTracesOptions): any[];
+    getRecentErrors(options: RecentErrorsOptions): any[];
+    private static readonly ALLOWED_GROUP_BY;
+    getErrorStats(options: ErrorStatsOptions): any[];
+    cleanup(retentionDays: number, vacuum?: boolean): void;
+    close(): void;
+}

package/dist/telemetry/db.js

@@ -0,0 +1,193 @@
+import Database from "better-sqlite3";
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS spans (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  trace_id       TEXT NOT NULL,
+  span_id        TEXT NOT NULL,
+  parent_span_id TEXT,
+  name           TEXT NOT NULL,
+  kind           TEXT NOT NULL DEFAULT 'internal',
+  status         TEXT NOT NULL DEFAULT 'unset',
+  agent          TEXT,
+  source         TEXT,
+  start_time     INTEGER NOT NULL,
+  end_time       INTEGER NOT NULL,
+  duration_ms    REAL NOT NULL,
+  attributes     TEXT NOT NULL DEFAULT '{}',
+  events         TEXT NOT NULL DEFAULT '[]',
+  created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(trace_id, span_id)
+);
+
+CREATE TABLE IF NOT EXISTS errors (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  trace_id     TEXT NOT NULL,
+  span_id      TEXT NOT NULL,
+  fingerprint  TEXT NOT NULL,
+  error_type   TEXT,
+  message      TEXT NOT NULL,
+  stack        TEXT,
+  agent        TEXT,
+  source       TEXT,
+  created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (trace_id, span_id) REFERENCES spans(trace_id, span_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS events (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  trace_id  TEXT,
+  span_id   TEXT,
+  name      TEXT NOT NULL,
+  agent     TEXT,
+  body      TEXT NOT NULL DEFAULT '{}',
+  timestamp TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_spans_trace ON spans(trace_id);
+CREATE INDEX IF NOT EXISTS idx_spans_parent ON spans(parent_span_id);
+CREATE INDEX IF NOT EXISTS idx_spans_name_time ON spans(name, start_time);
+CREATE INDEX IF NOT EXISTS idx_spans_agent_time ON spans(agent, created_at);
+CREATE INDEX IF NOT EXISTS idx_spans_source_time ON spans(source, created_at);
+CREATE INDEX IF NOT EXISTS idx_spans_status ON spans(status, created_at);
+CREATE INDEX IF NOT EXISTS idx_errors_agent_time ON errors(agent, created_at);
+CREATE INDEX IF NOT EXISTS idx_errors_fingerprint ON errors(fingerprint, created_at);
+CREATE INDEX IF NOT EXISTS idx_errors_trace ON errors(trace_id);
+CREATE INDEX IF NOT EXISTS idx_events_time ON events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_events_agent ON events(agent, timestamp);
+CREATE INDEX IF NOT EXISTS idx_events_span ON events(span_id);
+`;
+export class TelemetryDb {
+    db;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("foreign_keys = ON");
+        this.db.exec(SCHEMA_SQL);
+    }
+    insertSpan(span) {
+        this.db
+            .prepare(`INSERT INTO spans (trace_id, span_id, parent_span_id, name, kind, status, agent, source, start_time, end_time, duration_ms, attributes, events)
+         VALUES (@trace_id, @span_id, @parent_span_id, @name, @kind, @status, @agent, @source, @start_time, @end_time, @duration_ms, @attributes, @events)`)
+            .run({
+            trace_id: span.trace_id,
+            span_id: span.span_id,
+            parent_span_id: span.parent_span_id ?? null,
+            name: span.name,
+            kind: span.kind,
+            status: span.status,
+            agent: span.agent ?? null,
+            source: span.source ?? null,
+            start_time: span.start_time,
+            end_time: span.end_time,
+            duration_ms: span.duration_ms,
+            attributes: span.attributes,
+            events: span.events,
+        });
+    }
+    insertError(error) {
+        this.db
+            .prepare(`INSERT INTO errors (trace_id, span_id, fingerprint, error_type, message, stack, agent, source)
+         VALUES (@trace_id, @span_id, @fingerprint, @error_type, @message, @stack, @agent, @source)`)
+            .run({
+            trace_id: error.trace_id,
+            span_id: error.span_id,
+            fingerprint: error.fingerprint,
+            error_type: error.error_type ?? null,
+            message: error.message,
+            stack: error.stack ?? null,
+            agent: error.agent ?? null,
+            source: error.source ?? null,
+        });
+    }
+    insertEvent(event) {
+        this.db
+            .prepare(`INSERT INTO events (trace_id, span_id, name, agent, body)
+         VALUES (@trace_id, @span_id, @name, @agent, @body)`)
+            .run({
+            trace_id: event.trace_id ?? null,
+            span_id: event.span_id ?? null,
+            name: event.name,
+            agent: event.agent ?? null,
+            body: event.body ?? "{}",
+        });
+    }
+    getTraceSpans(traceId) {
+        return this.db
+            .prepare("SELECT * FROM spans WHERE trace_id = ? ORDER BY start_time")
+            .all(traceId);
+    }
+    listTraces(options) {
+        const conditions = ["parent_span_id IS NULL"];
+        const params = [];
+        if (options.agent) {
+            conditions.push("agent = ?");
+            params.push(options.agent);
+        }
+        if (options.source) {
+            conditions.push("source = ?");
+            params.push(options.source);
+        }
+        if (options.status) {
+            conditions.push("status = ?");
+            params.push(options.status);
+        }
+        if (options.since) {
+            conditions.push("created_at >= ?");
+            params.push(options.since);
+        }
+        const limit = options.limit ?? 100;
+        const sql = `SELECT * FROM spans WHERE ${conditions.join(" AND ")} ORDER BY start_time DESC LIMIT ?`;
+        params.push(limit);
+        return this.db.prepare(sql).all(...params);
+    }
+    getRecentErrors(options) {
+        const conditions = [];
+        const params = [];
+        if (options.agent) {
+            conditions.push("agent = ?");
+            params.push(options.agent);
+        }
+        if (options.source) {
+            conditions.push("source = ?");
+            params.push(options.source);
+        }
+        if (options.since) {
+            conditions.push("created_at >= ?");
+            params.push(options.since);
+        }
+        const limit = options.limit ?? 100;
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const sql = `SELECT * FROM errors ${where} ORDER BY created_at DESC LIMIT ?`;
+        params.push(limit);
+        return this.db.prepare(sql).all(...params);
+    }
+    static ALLOWED_GROUP_BY = new Set(["fingerprint", "agent"]);
+    getErrorStats(options) {
+        const conditions = [];
+        const params = [];
+        if (options.since) {
+            conditions.push("created_at >= ?");
+            params.push(options.since);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const groupBy = options.groupBy ?? "fingerprint";
+        if (!TelemetryDb.ALLOWED_GROUP_BY.has(groupBy)) {
+            throw new Error(`Invalid groupBy: ${groupBy}`);
+        }
+        const sql = `SELECT ${groupBy}, COUNT(*) as count FROM errors ${where} GROUP BY ${groupBy} ORDER BY count DESC`;
+        return this.db.prepare(sql).all(...params);
+    }
+    cleanup(retentionDays, vacuum = false) {
+        const cutoff = `-${retentionDays} days`;
+        this.db.transaction(() => {
+            this.db.prepare("DELETE FROM events WHERE timestamp < datetime('now', ?)").run(cutoff);
+            this.db.prepare("DELETE FROM spans WHERE created_at < datetime('now', ?)").run(cutoff);
+        })();
+        if (vacuum) {
+            this.db.exec("VACUUM");
+        }
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,17 @@
+import { type Tracer } from "@opentelemetry/api";
+import { TelemetryDb } from "./db.js";
+export interface TelemetryConfig {
+    enabled?: boolean;
+    serviceName?: string;
+    otlpEndpoint?: string;
+    sentryDsn?: string;
+    dbPath?: string;
+    sampleRate?: number;
+}
+/** Get the TelemetryDb instance (available after initTelemetry with a dbPath) */
+export declare function getTelemetryDb(): TelemetryDb | undefined;
+export declare function initTelemetry(config?: TelemetryConfig): () => Promise<void>;
+export declare function getTracer(name: string): Tracer;
+export { ATTR } from "./types.js";
+export { TelemetryDb } from "./db.js";
+export { SQLiteSpanProcessor } from "./sqlite-processor.js";