mcp-coordinator 0.1.0

package/dist/src/database.js

@@ -0,0 +1,194 @@
+import path from "path";
+import { mkdirSync } from "fs";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+let db;
+const SCHEMA = `
+    CREATE TABLE IF NOT EXISTS agents (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      modules TEXT DEFAULT '[]',
+      status TEXT DEFAULT 'offline',
+      registered_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      last_seen_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE TABLE IF NOT EXISTS threads (
+      id TEXT PRIMARY KEY,
+      initiator_id TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      plan TEXT,
+      target_modules TEXT DEFAULT '[]',
+      target_files TEXT DEFAULT '[]',
+      status TEXT DEFAULT 'open',
+      resolution_summary TEXT,
+      conflicts TEXT,
+      round INTEGER DEFAULT 1,
+      max_rounds INTEGER DEFAULT 4,
+      timeout_seconds INTEGER DEFAULT 600,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      resolved_at TEXT,
+      expected_respondents TEXT,
+      depends_on_files TEXT,
+      exports_affected TEXT,
+      claimed_by TEXT,
+      claimed_at TEXT,
+      FOREIGN KEY (initiator_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS thread_messages (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      agent_name TEXT,
+      type TEXT NOT NULL,
+      content TEXT NOT NULL,
+      context_snapshot TEXT,
+      in_reply_to TEXT,
+      round INTEGER NOT NULL,
+      token_estimate INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (thread_id) REFERENCES threads(id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS action_summaries (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      file_path TEXT,
+      summary TEXT NOT NULL,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE TABLE IF NOT EXISTS dependency_map (
+      module_id TEXT PRIMARY KEY,
+      depends_on TEXT DEFAULT '[]',
+      exports TEXT DEFAULT '[]',
+      owners TEXT DEFAULT '[]'
+    );
+
+    CREATE TABLE IF NOT EXISTS file_activity (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      agent_name TEXT,
+      tool_name TEXT NOT NULL,
+      file_path TEXT NOT NULL,
+      module TEXT,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_threads_status ON threads(status);
+    CREATE INDEX IF NOT EXISTS idx_threads_initiator ON threads(initiator_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_thread ON thread_messages(thread_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_agent ON thread_messages(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_summaries_agent ON action_summaries(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_summaries_session ON action_summaries(session_id);
+    CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+    CREATE INDEX IF NOT EXISTS idx_file_activity_agent ON file_activity(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_file_activity_path ON file_activity(file_path);
+
+    CREATE TABLE IF NOT EXISTS introspections (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      score INTEGER NOT NULL,
+      reasons TEXT,
+      status TEXT DEFAULT 'pending',
+      response TEXT,
+      concerned INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      responded_at TEXT,
+      FOREIGN KEY (thread_id) REFERENCES threads(id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_introspections_agent ON introspections(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_introspections_status ON introspections(status);
+
+    CREATE TABLE IF NOT EXISTS agent_activity_status (
+      agent_id TEXT PRIMARY KEY,
+      activity_status TEXT DEFAULT 'idle',
+      current_file TEXT,
+      current_thread TEXT,
+      last_activity_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS revoked_agents (
+      agent_id TEXT PRIMARY KEY,
+      revoked_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      revoked_by TEXT NOT NULL
+    );
+`;
+function createBetterSqlite3(dataDir) {
+    mkdirSync(dataDir, { recursive: true });
+    const Database = require("better-sqlite3");
+    const dbPath = path.join(dataDir, "coordinator.db");
+    const raw = new Database(dbPath);
+    raw.pragma("journal_mode = WAL");
+    raw.pragma("busy_timeout = 5000");
+    raw.pragma("foreign_keys = ON");
+    return raw;
+}
+function createBunSqlite(dataDir) {
+    mkdirSync(dataDir, { recursive: true });
+    const { Database } = require("bun:sqlite");
+    const dbPath = path.join(dataDir, "coordinator.db");
+    const raw = new Database(dbPath);
+    raw.exec("PRAGMA journal_mode = WAL");
+    raw.exec("PRAGMA busy_timeout = 5000");
+    raw.exec("PRAGMA foreign_keys = ON");
+    return raw;
+}
+export function initDatabase(dataDir) {
+    if (typeof globalThis.Bun !== "undefined") {
+        db = createBunSqlite(dataDir);
+    }
+    else {
+        db = createBetterSqlite3(dataDir);
+    }
+    db.exec(SCHEMA);
+    // Migrations for existing databases — columns may already exist
+    try {
+        db.exec("ALTER TABLE threads ADD COLUMN claimed_by TEXT");
+    }
+    catch { /* already exists */ }
+    try {
+        db.exec("ALTER TABLE threads ADD COLUMN claimed_at TEXT");
+    }
+    catch { /* already exists */ }
+    // F4: track unclaim count to poison threads that no agent manages to complete.
+    // Without this, an aborted task bounces back into the pool indefinitely and
+    // gets re-claimed by the same (or next) agent in a tight failure loop.
+    try {
+        db.exec("ALTER TABLE threads ADD COLUMN unclaim_count INTEGER DEFAULT 0");
+    }
+    catch { /* already exists */ }
+    // Directed-dispatch: a thread with `assigned_to` set is claimable only by
+    // that specific agent. NULL = anyone can claim (backwards compat with
+    // existing work-stealing). Used by lead/worker presets and sequential
+    // pipelines that need explicit hand-offs instead of first-come claims.
+    try {
+        db.exec("ALTER TABLE threads ADD COLUMN assigned_to TEXT");
+    }
+    catch { /* already exists */ }
+}
+export function getDb() {
+    if (!db)
+        throw new Error("Database not initialized. Call initDatabase first.");
+    return db;
+}
+export function closeDb() {
+    if (db)
+        db.close();
+}

package/dist/src/db-adapter.d.ts

@@ -0,0 +1,15 @@
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+export interface Statement {
+    run(...params: unknown[]): RunResult;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+export interface DatabaseAdapter {
+    prepare(sql: string): Statement;
+    exec(sql: string): void;
+    close(): void;
+    transaction<T>(fn: () => T): () => T;
+}

package/dist/src/db-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/dependency-map.d.ts

@@ -0,0 +1,7 @@
+import type { ModuleInfo, DependencyMap, BlastRadius } from "./types.js";
+export declare class DependencyMapper {
+    getMap(): DependencyMap;
+    setMap(map: DependencyMap): void;
+    getModuleInfo(moduleId: string): ModuleInfo | null;
+    getBlastRadius(moduleId: string): BlastRadius;
+}

package/dist/src/dependency-map.js

@@ -0,0 +1,76 @@
+import { getDb } from "./database.js";
+export class DependencyMapper {
+    getMap() {
+        const db = getDb();
+        const rows = db.prepare("SELECT * FROM dependency_map").all();
+        const map = {};
+        for (const row of rows) {
+            map[row.module_id] = {
+                module_id: row.module_id,
+                depends_on: JSON.parse(row.depends_on),
+                exports: JSON.parse(row.exports),
+                owners: JSON.parse(row.owners),
+            };
+        }
+        return map;
+    }
+    setMap(map) {
+        const db = getDb();
+        const stmt = db.prepare(`INSERT INTO dependency_map (module_id, depends_on, exports, owners)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(module_id) DO UPDATE SET
+         depends_on = excluded.depends_on, exports = excluded.exports, owners = excluded.owners`);
+        const tx = db.transaction(() => {
+            for (const [id, info] of Object.entries(map)) {
+                stmt.run(id, JSON.stringify(info.depends_on), JSON.stringify(info.exports), JSON.stringify(info.owners));
+            }
+        });
+        tx();
+    }
+    getModuleInfo(moduleId) {
+        const db = getDb();
+        const row = db.prepare("SELECT * FROM dependency_map WHERE module_id = ?").get(moduleId);
+        if (!row)
+            return null;
+        return {
+            module_id: row.module_id,
+            depends_on: JSON.parse(row.depends_on),
+            exports: JSON.parse(row.exports),
+            owners: JSON.parse(row.owners),
+        };
+    }
+    getBlastRadius(moduleId) {
+        const map = this.getMap();
+        const direct = [];
+        const indirect = [];
+        const visited = new Set();
+        for (const [id, info] of Object.entries(map)) {
+            if (info.depends_on.includes(moduleId))
+                direct.push(id);
+        }
+        const queue = [...direct];
+        visited.add(moduleId);
+        for (const d of direct)
+            visited.add(d);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const [id, info] of Object.entries(map)) {
+                if (!visited.has(id) && info.depends_on.includes(current)) {
+                    indirect.push(id);
+                    visited.add(id);
+                    queue.push(id);
+                }
+            }
+        }
+        const moduleInfo = map[moduleId];
+        const affectedExports = moduleInfo ? moduleInfo.exports : [];
+        const activeThreadsInRadius = [];
+        return {
+            module_id: moduleId,
+            direct_dependents: direct,
+            indirect_dependents: indirect,
+            affected_exports: affectedExports,
+            active_threads_in_radius: activeThreadsInRadius,
+        };
+    }
+}

package/dist/src/file-tracker.d.ts

@@ -0,0 +1,21 @@
+import type { FileActivity } from "./types.js";
+export declare class FileTracker {
+    log(params: {
+        session_id: string;
+        agent_id: string;
+        agent_name?: string;
+        tool_name: string;
+        file_path: string;
+    }): void;
+    getBySession(sessionId: string): FileActivity[];
+    getHotFiles(sinceMinutes?: number): {
+        file_path: string;
+        agent_count: number;
+        agents: string[];
+    }[];
+    checkFileConflict(filePath: string, agentId: string, withinMinutes?: number): {
+        conflict: boolean;
+        agents: string[];
+    };
+    fileToModule(filePath: string): string;
+}

package/dist/src/file-tracker.js

@@ -0,0 +1,44 @@
+import { getDb } from "./database.js";
+export class FileTracker {
+    log(params) {
+        const db = getDb();
+        const module = this.fileToModule(params.file_path);
+        db.prepare(`INSERT INTO file_activity (session_id, agent_id, agent_name, tool_name, file_path, module)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(params.session_id, params.agent_id, params.agent_name || null, params.tool_name, params.file_path, module);
+    }
+    getBySession(sessionId) {
+        const db = getDb();
+        return db.prepare("SELECT * FROM file_activity WHERE session_id = ? ORDER BY created_at").all(sessionId);
+    }
+    getHotFiles(sinceMinutes = 30) {
+        const db = getDb();
+        const rows = db.prepare(`SELECT file_path, COUNT(DISTINCT agent_id) as agent_count, GROUP_CONCAT(DISTINCT agent_id) as agents
+       FROM file_activity
+       WHERE created_at > datetime('now', '-' || ? || ' minutes')
+       GROUP BY file_path
+       HAVING COUNT(DISTINCT agent_id) > 1
+       ORDER BY agent_count DESC`).all(sinceMinutes);
+        return rows.map((r) => ({
+            file_path: r.file_path,
+            agent_count: r.agent_count,
+            agents: r.agents.split(","),
+        }));
+    }
+    checkFileConflict(filePath, agentId, withinMinutes = 30) {
+        const db = getDb();
+        const rows = db.prepare(`SELECT DISTINCT agent_id FROM file_activity
+       WHERE file_path = ? AND agent_id != ?
+       AND created_at > datetime('now', '-' || ? || ' minutes')`).all(filePath, agentId, withinMinutes);
+        return { conflict: rows.length > 0, agents: rows.map((r) => r.agent_id) };
+    }
+    fileToModule(filePath) {
+        // Strip leading / so "/server/src/x.ts" and "server/src/x.ts" produce the
+        // same module name. Without this, split("/") on an absolute path yields
+        // ["", "server", "src", ...] and slice(0,2) gives "/server" instead of "server/src".
+        const normalized = filePath.replace(/^\/+/, "");
+        const parts = normalized.split("/");
+        if (parts.length < 2 || parts[0] === "")
+            return "";
+        return parts.slice(0, 2).join("/");
+    }
+}

package/dist/src/impact-scorer.d.ts

@@ -0,0 +1,31 @@
+import type { AgentRegistry } from "./agent-registry.js";
+import type { FileTracker } from "./file-tracker.js";
+import type { Consultation } from "./consultation.js";
+export interface ImpactScore {
+    agent_id: string;
+    agent_name: string;
+    score: number;
+    reasons: string[];
+    reason: string;
+}
+export interface CategorizedImpact {
+    concerned: ImpactScore[];
+    gray_zone: ImpactScore[];
+    pass: ImpactScore[];
+}
+interface AnnounceParams {
+    agent_id: string;
+    target_modules: string[];
+    target_files: string[];
+    depends_on_files?: string[];
+    exports_affected?: string[];
+}
+export declare class ImpactScorer {
+    private registry;
+    private fileTracker;
+    private consultation?;
+    constructor(registry: AgentRegistry, fileTracker: FileTracker, consultation?: Consultation | undefined);
+    score(params: AnnounceParams): ImpactScore[];
+    categorize(params: AnnounceParams): CategorizedImpact;
+}
+export {};

package/dist/src/impact-scorer.js

@@ -0,0 +1,112 @@
+export class ImpactScorer {
+    registry;
+    fileTracker;
+    consultation;
+    constructor(registry, fileTracker, consultation) {
+        this.registry = registry;
+        this.fileTracker = fileTracker;
+        this.consultation = consultation;
+    }
+    score(params) {
+        const onlineAgents = this.registry
+            .listOnline()
+            .filter((a) => a.id !== params.agent_id);
+        return onlineAgents.map((agent) => {
+            const agentModules = JSON.parse(agent.modules);
+            const reasons = [];
+            let maxScore = 0;
+            // Layer 0: Announced intent overlap (checks active threads from this agent).
+            // Resolved threads older than LAYER_0_RESOLVED_WINDOW_MS are excluded —
+            // yesterday's resolved work shouldn't trigger today's scoring.
+            if (this.consultation) {
+                const LAYER_0_RESOLVED_WINDOW_MS = 30 * 60 * 1000; // 30 minutes
+                const now = Date.now();
+                // SQLite datetime('now') returns UTC without a TZ suffix. new Date(str)
+                // parses it as local time by default — causing a local-offset skew.
+                // Normalize by treating the space as T and appending Z.
+                const parseSqliteUtc = (s) => {
+                    const iso = /[Tt]/.test(s) ? s : s.replace(" ", "T");
+                    return new Date(/[zZ]|[+-]\d{2}:?\d{2}$/.test(iso) ? iso : iso + "Z").getTime();
+                };
+                const activeThreads = [
+                    ...this.consultation.listThreads({ status: "open" }),
+                    ...this.consultation.listThreads({ status: "resolving" }),
+                    ...this.consultation
+                        .listThreads({ status: "resolved" })
+                        .filter((t) => {
+                        if (!t.resolved_at)
+                            return true;
+                        const resolvedAt = parseSqliteUtc(t.resolved_at);
+                        return !isNaN(resolvedAt) && now - resolvedAt <= LAYER_0_RESOLVED_WINDOW_MS;
+                    }),
+                ].filter((t) => t.initiator_id === agent.id);
+                for (const thread of activeThreads) {
+                    const threadFiles = JSON.parse(thread.target_files || "[]");
+                    const threadDeps = JSON.parse(thread.depends_on_files || "[]");
+                    // 0a: My target_files ∩ their target_files → score 100
+                    const fileOverlap = params.target_files.filter((f) => threadFiles.includes(f));
+                    if (fileOverlap.length > 0) {
+                        maxScore = Math.max(maxScore, 100);
+                        reasons.push(`announced same file: ${fileOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
+                    }
+                    // 0b: My depends_on ∩ their target_files → score 80 (they modify what I depend on)
+                    if (params.depends_on_files) {
+                        const depOverlap = params.depends_on_files.filter((f) => threadFiles.includes(f));
+                        if (depOverlap.length > 0) {
+                            maxScore = Math.max(maxScore, 80);
+                            reasons.push(`modifies my dependency: ${depOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
+                        }
+                    }
+                    // 0c: My target_files ∩ their depends_on → score 80 (I modify what they depend on)
+                    const reverseDepOverlap = params.target_files.filter((f) => threadDeps.includes(f));
+                    if (reverseDepOverlap.length > 0) {
+                        maxScore = Math.max(maxScore, 80);
+                        reasons.push(`they depend on my target: ${reverseDepOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
+                    }
+                }
+            }
+            // Layer 1: Same file recently modified (score 100)
+            for (const targetFile of params.target_files) {
+                const conflict = this.fileTracker.checkFileConflict(targetFile, params.agent_id, 60);
+                if (conflict.agents.includes(agent.id)) {
+                    maxScore = Math.max(maxScore, 100);
+                    reasons.push(`same file: ${targetFile}`);
+                }
+            }
+            // Layer 2: Depends-on file recently modified (score 80)
+            if (params.depends_on_files) {
+                for (const depFile of params.depends_on_files) {
+                    const conflict = this.fileTracker.checkFileConflict(depFile, params.agent_id, 60);
+                    if (conflict.agents.includes(agent.id)) {
+                        maxScore = Math.max(maxScore, 80);
+                        reasons.push(`depends on: ${depFile}`);
+                    }
+                }
+            }
+            // Layer 3: Module overlap (score 30)
+            const overlapping = agentModules.filter((am) => params.target_modules.some((tm) => am === tm || am.startsWith(tm + "/") || tm.startsWith(am + "/")));
+            if (overlapping.length > 0) {
+                maxScore = Math.max(maxScore, 30);
+                reasons.push(`module overlap: ${overlapping.join(", ")}`);
+            }
+            // Layer 4 (future): Git co-change analysis
+            // Score 60 for >50% co-change ratio, 40 for >20%
+            // Requires git history analysis — not implemented in v3 prototype
+            return {
+                agent_id: agent.id,
+                agent_name: agent.name,
+                score: maxScore,
+                reasons,
+                reason: reasons[0] || "no link detected",
+            };
+        });
+    }
+    categorize(params) {
+        const scores = this.score(params);
+        return {
+            concerned: scores.filter((s) => s.score >= 90),
+            gray_zone: scores.filter((s) => s.score >= 30 && s.score < 90),
+            pass: scores.filter((s) => s.score < 30),
+        };
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { startServer, type ServerOptions } from "./serve-http.js";
+export { createServices, createMcpServer } from "./server-setup.js";

package/dist/src/index.js

@@ -0,0 +1,26 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { pathToFileURL } from "url";
+import { createServices, createMcpServer } from "./server-setup.js";
+// Re-export the public package surface for npm consumers
+export { startServer } from "./serve-http.js";
+export { createServices, createMcpServer } from "./server-setup.js";
+// STDIO entry: only run when invoked directly (not when imported).
+// Uses pathToFileURL for cross-platform correctness (handles Windows drive letters
+// + the file:///C:/... vs file://C:/... slash-count mismatch). Guards against
+// process.argv[1] being undefined (REPL, some bundlers).
+const isMainModule = process.argv[1] != null && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+    const DATA_DIR = process.env.COORDINATOR_DATA_DIR || "./data";
+    async function main() {
+        const services = createServices({ dataDir: DATA_DIR });
+        const log = services.logger;
+        const server = createMcpServer(services);
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        log.info("mcp-coordinator running on stdio (no MQTT broker in stdio mode)");
+    }
+    main().catch((err) => {
+        console.error("FATAL:", err);
+        process.exit(1);
+    });
+}

package/dist/src/introspection.d.ts

@@ -0,0 +1,24 @@
+export interface IntrospectionRecord {
+    id: string;
+    thread_id: string;
+    agent_id: string;
+    score: number;
+    reasons: string | null;
+    status: "pending" | "concerned" | "not_concerned";
+    response: string | null;
+    concerned: number;
+    created_at: string;
+    responded_at: string | null;
+}
+export declare class IntrospectionManager {
+    create(params: {
+        thread_id: string;
+        agent_id: string;
+        score: number;
+        reasons: string[];
+    }): IntrospectionRecord;
+    respond(id: string, concerned: boolean, response: string): IntrospectionRecord;
+    get(id: string): IntrospectionRecord | null;
+    getPending(agentId: string): IntrospectionRecord[];
+    getByThread(threadId: string): IntrospectionRecord[];
+}

package/dist/src/introspection.js

@@ -0,0 +1,28 @@
+import { randomUUID } from "crypto";
+import { getDb } from "./database.js";
+export class IntrospectionManager {
+    create(params) {
+        const db = getDb();
+        const id = randomUUID();
+        db.prepare(`INSERT INTO introspections (id, thread_id, agent_id, score, reasons)
+       VALUES (?, ?, ?, ?, ?)`).run(id, params.thread_id, params.agent_id, params.score, JSON.stringify(params.reasons));
+        return this.get(id);
+    }
+    respond(id, concerned, response) {
+        const db = getDb();
+        db.prepare(`UPDATE introspections SET status = ?, concerned = ?, response = ?, responded_at = ? WHERE id = ?`).run(concerned ? "concerned" : "not_concerned", concerned ? 1 : 0, response, new Date().toISOString(), id);
+        return this.get(id);
+    }
+    get(id) {
+        const db = getDb();
+        return db.prepare("SELECT * FROM introspections WHERE id = ?").get(id) || null;
+    }
+    getPending(agentId) {
+        const db = getDb();
+        return db.prepare("SELECT * FROM introspections WHERE agent_id = ? AND status = 'pending' ORDER BY created_at").all(agentId);
+    }
+    getByThread(threadId) {
+        const db = getDb();
+        return db.prepare("SELECT * FROM introspections WHERE thread_id = ? ORDER BY created_at").all(threadId);
+    }
+}

package/dist/src/logger.d.ts

@@ -0,0 +1,20 @@
+export interface Logger {
+    level: string;
+    info(obj: unknown, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: unknown, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: unknown, msg?: string): void;
+    error(msg: string): void;
+    fatal(obj: unknown, msg?: string): void;
+    fatal(msg: string): void;
+    debug(obj: unknown, msg?: string): void;
+    debug(msg: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+export interface LoggerOptions {
+    level?: string;
+    pretty?: boolean;
+}
+export declare function createLogger(options?: LoggerOptions): Logger;
+export declare const silentLogger: Logger;

package/dist/src/logger.js

@@ -0,0 +1,55 @@
+// Simple console-based logger (works everywhere, no native deps)
+function createConsoleLogger(level, bindings = {}) {
+    const levels = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50, silent: 100 };
+    const threshold = levels[level] ?? 20;
+    function log(lvl, num, args) {
+        if (num < threshold)
+            return;
+        const ts = new Date().toISOString();
+        const prefix = Object.keys(bindings).length > 0
+            ? `[${Object.values(bindings).join(":")}]`
+            : "";
+        const obj = typeof args[0] === "object" && args[0] !== null ? args[0] : {};
+        const msg = typeof args[0] === "string" ? args[0] : args[1] ?? "";
+        const data = typeof args[0] === "object" ? { ...bindings, ...obj } : bindings;
+        if (lvl === "error" || lvl === "fatal") {
+            console.error(JSON.stringify({ level: num, time: ts, ...data, msg }));
+        }
+        else {
+            console.log(JSON.stringify({ level: num, time: ts, ...data, msg }));
+        }
+    }
+    return {
+        level,
+        info: (...args) => log("info", 20, args),
+        warn: (...args) => log("warn", 30, args),
+        error: (...args) => log("error", 40, args),
+        fatal: (...args) => log("fatal", 50, args),
+        debug: (...args) => log("debug", 10, args),
+        child: (b) => createConsoleLogger(level, { ...bindings, ...b }),
+    };
+}
+// Pino-based logger (dev mode, richer output)
+function createPinoLogger(level) {
+    const pino = require("pino");
+    const isDev = process.env.NODE_ENV === "development";
+    const transport = isDev
+        ? { target: "pino-pretty", options: { colorize: true, translateTime: "SYS:HH:mm:ss" } }
+        : undefined;
+    return pino({ level, transport });
+}
+export function createLogger(options) {
+    const level = options?.level || process.env.LOG_LEVEL || "info";
+    // Use console logger in Bun compiled binary (pino uses thread-stream which breaks)
+    if (typeof globalThis.Bun !== "undefined") {
+        return createConsoleLogger(level);
+    }
+    // Use pino in Node.js (dev/test)
+    try {
+        return createPinoLogger(level);
+    }
+    catch {
+        return createConsoleLogger(level);
+    }
+}
+export const silentLogger = createConsoleLogger("silent");