agent-common 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [1.0.0] - 2026-04-07
+
+Initial release of `agent-common`. Extracted shared scaffolding from `agent-comm`, `agent-tasks`, `agent-knowledge`, and `agent-discover`:
+
+- `createDb` + migration runner (`storage/database.ts`)
+- FTS5 helpers (`storage/fts.ts`)
+- REST router builder (`transport/rest.ts`)
+- WebSocket server with fingerprint-based delta polling (`transport/ws.ts`)
+- MCP JSON-RPC dispatcher (`transport/mcp.ts`)
+- `EventBus` (`domain/events.ts`)
+- `CleanupService` base class (`domain/cleanup.ts`)
+- `startDashboard` with port leader-election (`dashboard.ts`)
+- `readPackageMeta` (`package-meta.ts`)

package/LICENSE

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

package/README.md

@@ -0,0 +1,23 @@
+# agent-common
+
+Shared foundation for `agent-*` MCP servers (`agent-comm`, `agent-tasks`, `agent-knowledge`, `agent-discover`).
+
+## What it provides
+
+- **storage** — better-sqlite3 wrapper with WAL pragmas, transaction helper, migration runner
+- **transport/rest** — node:http router with `:param` matching, JSON helper, CORS preflight, body reader, static file serving
+- **transport/ws** — WebSocket server with full-state-on-connect, DB-fingerprint polling for cross-process delta updates, ping/pong heartbeat, max-connection cap
+- **transport/mcp** — JSON-RPC over stdio, tool dispatcher, `ToolDefinition` type
+- **domain/events** — typed in-process EventBus with wildcard subscribers
+- **domain/cleanup** — base `CleanupService` with retention timer, startup reset hook
+- **dashboard** — auto-start with port leader-election (graceful skip if port in use)
+- **package-meta** — runtime read of `name` + `version` from a consumer's `package.json`
+- **fts** — FTS5 virtual table + trigger boilerplate, search helper with LIKE fallback
+
+## Who uses it
+
+Internal: the four `agent-*` MCP servers. The package is host-agnostic — no `~/.claude` paths or Claude-specific config baked in.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/dashboard.d.ts

@@ -0,0 +1,29 @@
+import { type Server } from 'http';
+import type { IncomingMessage, ServerResponse } from 'http';
+export interface DashboardServer {
+    httpServer: Server;
+    port: number;
+    close(): void;
+}
+export interface DashboardOptions {
+    port: number;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+    /** Optional callback after the HTTP server is listening, to attach a WebSocket. */
+    onListen?: (httpServer: Server) => {
+        close(): void;
+    } | void;
+    /** Banner string written to stderr on successful start. Defaults to dashboard URL. */
+    banner?: (port: number) => string;
+}
+/**
+ * Start a dashboard HTTP server. Resolves to a `DashboardServer` on success.
+ * Rejects with an error whose `code === 'EADDRINUSE'` when the port is taken.
+ */
+export declare function startDashboard(opts: DashboardOptions): Promise<DashboardServer>;
+/**
+ * Try to start a dashboard, but resolve to `null` (rather than rejecting) if the
+ * port is already taken. Use this from MCP entrypoints where multiple processes
+ * may race to bind the same port.
+ */
+export declare function tryStartDashboard(opts: DashboardOptions): Promise<DashboardServer | null>;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AASA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,mFAAmF;IACnF,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK;QAAE,KAAK,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4C/E;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAY/F"}

package/dist/dashboard.js

@@ -0,0 +1,71 @@
+// =============================================================================
+// agent-kit — Dashboard auto-start
+//
+// Starts an HTTP+WebSocket server on a fixed port using leader-election:
+// the first process to bind wins; subsequent processes get EADDRINUSE and
+// gracefully skip (the existing dashboard is already serving). This lets
+// every MCP client process call `startDashboard()` without coordination.
+// =============================================================================
+import { createServer } from 'http';
+/**
+ * Start a dashboard HTTP server. Resolves to a `DashboardServer` on success.
+ * Rejects with an error whose `code === 'EADDRINUSE'` when the port is taken.
+ */
+export function startDashboard(opts) {
+    return new Promise((resolve, reject) => {
+        const httpServer = createServer((req, res) => {
+            Promise.resolve(opts.handler(req, res)).catch((err) => {
+                process.stderr.write('[agent-kit] Dashboard handler error: ' +
+                    (err instanceof Error ? err.message : String(err)) +
+                    '\n');
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end('Internal server error');
+                }
+            });
+        });
+        let attached;
+        httpServer.on('error', (err) => {
+            reject(err);
+        });
+        httpServer.listen(opts.port, () => {
+            try {
+                attached = opts.onListen?.(httpServer);
+            }
+            catch (err) {
+                process.stderr.write('[agent-kit] Dashboard onListen error: ' +
+                    (err instanceof Error ? err.message : String(err)) +
+                    '\n');
+            }
+            const banner = opts.banner ? opts.banner(opts.port) : `dashboard: http://localhost:${opts.port}`;
+            process.stderr.write(banner + '\n');
+            resolve({
+                httpServer,
+                port: opts.port,
+                close() {
+                    if (attached)
+                        attached.close();
+                    httpServer.close();
+                },
+            });
+        });
+    });
+}
+/**
+ * Try to start a dashboard, but resolve to `null` (rather than rejecting) if the
+ * port is already taken. Use this from MCP entrypoints where multiple processes
+ * may race to bind the same port.
+ */
+export async function tryStartDashboard(opts) {
+    try {
+        return await startDashboard(opts);
+    }
+    catch (err) {
+        if (err.code === 'EADDRINUSE') {
+            process.stderr.write(`[agent-kit] Dashboard port ${opts.port} in use — another instance is serving.\n`);
+            return null;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,mCAAmC;AACnC,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,yEAAyE;AACzE,yEAAyE;AACzE,gFAAgF;AAEhF,OAAO,EAAE,YAAY,EAAe,MAAM,MAAM,CAAC;AAkBjD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAsB;IACnD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YAC3C,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uCAAuC;oBACrC,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAClD,IAAI,CACP,CAAC;gBACF,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;oBACrB,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;oBACnB,GAAG,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,IAAI,QAAkC,CAAC;QAEvC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;YACpD,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE;YAChC,IAAI,CAAC;gBACH,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wCAAwC;oBACtC,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAClD,IAAI,CACP,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,+BAA+B,IAAI,CAAC,IAAI,EAAE,CAAC;YACjG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;YACpC,OAAO,CAAC;gBACN,UAAU;gBACV,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK;oBACH,IAAI,QAAQ;wBAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;oBAC/B,UAAU,CAAC,KAAK,EAAE,CAAC;gBACrB,CAAC;aACF,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAsB;IAC5D,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8BAA8B,IAAI,CAAC,IAAI,0CAA0C,CAClF,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/domain/cleanup.d.ts

@@ -0,0 +1,30 @@
+import type { Db } from '../storage/database.js';
+export interface CleanupOptions {
+    /** Retention period in days for the consumer's main rows. Default: 7. */
+    retentionDays?: number;
+    /** Interval at which `run()` is invoked. Default: 1 hour. */
+    intervalMs?: number;
+    /** If true, calls `resetOnStartup()` and `run()` immediately on construction. */
+    autoStart?: boolean;
+}
+export declare abstract class CleanupService<S extends Record<string, number> = Record<string, number>> {
+    protected readonly db: Db;
+    protected readonly retentionDays: number;
+    protected readonly intervalMs: number;
+    private timer;
+    constructor(db: Db, options?: CleanupOptions);
+    /**
+     * Override to delete stale rows. Called on startup, on the timer, and
+     * via the public `purgeAll()` entry point.
+     */
+    abstract run(): S;
+    /**
+     * Override to fix up state on server start (e.g. mark agents offline).
+     * Default no-op.
+     */
+    resetOnStartup(): void;
+    purgeAll(): S;
+    startTimer(): void;
+    stopTimer(): void;
+}
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/domain/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/domain/cleanup.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,wBAAwB,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,8BAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAM1F,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE;IAL3B,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IACzC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IACtC,OAAO,CAAC,KAAK,CAA+C;gBAGvC,EAAE,EAAE,EAAE,EACzB,OAAO,GAAE,cAAmB;IAW9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,IAAI,CAAC;IAEjB;;;OAGG;IACH,cAAc,IAAI,IAAI;IAItB,QAAQ,IAAI,CAAC;IAIb,UAAU,IAAI,IAAI;IAiBlB,SAAS,IAAI,IAAI;CAMlB"}

package/dist/domain/cleanup.js

@@ -0,0 +1,54 @@
+// =============================================================================
+// agent-kit — Cleanup service base
+//
+// Provides timer scheduling and a startup-reset hook. Consumers extend
+// `CleanupService` and override `run()` to delete their own stale rows.
+// =============================================================================
+export class CleanupService {
+    db;
+    retentionDays;
+    intervalMs;
+    timer = null;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.retentionDays = options.retentionDays ?? 7;
+        this.intervalMs = options.intervalMs ?? 60 * 60 * 1000;
+        if (options.autoStart !== false) {
+            this.resetOnStartup();
+            this.startTimer();
+        }
+    }
+    /**
+     * Override to fix up state on server start (e.g. mark agents offline).
+     * Default no-op.
+     */
+    resetOnStartup() {
+        /* override in consumer */
+    }
+    purgeAll() {
+        return this.run();
+    }
+    startTimer() {
+        if (this.timer)
+            return;
+        this.run();
+        this.timer = setInterval(() => {
+            try {
+                this.run();
+            }
+            catch (err) {
+                process.stderr.write('[agent-kit] Cleanup timer error: ' +
+                    (err instanceof Error ? err.message : String(err)) +
+                    '\n');
+            }
+        }, this.intervalMs);
+        this.timer.unref();
+    }
+    stopTimer() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/domain/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/domain/cleanup.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,mCAAmC;AACnC,EAAE;AACF,uEAAuE;AACvE,wEAAwE;AACxE,gFAAgF;AAahF,MAAM,OAAgB,cAAc;IAMb;IALF,aAAa,CAAS;IACtB,UAAU,CAAS;IAC9B,KAAK,GAA0C,IAAI,CAAC;IAE5D,YACqB,EAAM,EACzB,UAA0B,EAAE;QADT,OAAE,GAAF,EAAE,CAAI;QAGzB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAEvD,IAAI,OAAO,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAQD;;;OAGG;IACH,cAAc;QACZ,0BAA0B;IAC5B,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,UAAU;QACR,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC;gBACH,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mCAAmC;oBACjC,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAClD,IAAI,CACP,CAAC;YACJ,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,SAAS;QACP,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/domain/events.d.ts

@@ -0,0 +1,13 @@
+export interface BusEvent<T extends string = string> {
+    type: T;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+export type EventHandler<T extends string = string> = (event: BusEvent<T>) => void;
+export declare class EventBus<T extends string = string> {
+    private readonly listeners;
+    emit(type: T, data?: Record<string, unknown>): void;
+    on(type: T | '*', handler: EventHandler<T>): () => void;
+    removeAll(): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/domain/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACjD,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEnF,qBAAa,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IAEtE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IA0CvD,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAYvD,SAAS,IAAI,IAAI;CAGlB"}

package/dist/domain/events.js

@@ -0,0 +1,61 @@
+// =============================================================================
+// agent-kit — Event bus
+//
+// In-process pub/sub with wildcard subscribers. Consumer-defined event types
+// are passed as a generic parameter for type safety.
+// =============================================================================
+export class EventBus {
+    listeners = new Map();
+    emit(type, data = {}) {
+        const event = {
+            type,
+            timestamp: new Date().toISOString(),
+            data,
+        };
+        const specific = this.listeners.get(type);
+        if (specific) {
+            for (const handler of specific) {
+                try {
+                    handler(event);
+                }
+                catch (err) {
+                    process.stderr.write('[agent-kit] Event listener error (' +
+                        type +
+                        '): ' +
+                        (err instanceof Error ? err.message : String(err)) +
+                        '\n');
+                }
+            }
+        }
+        const wildcards = this.listeners.get('*');
+        if (wildcards) {
+            for (const handler of wildcards) {
+                try {
+                    handler(event);
+                }
+                catch (err) {
+                    process.stderr.write('[agent-kit] Wildcard listener error (' +
+                        type +
+                        '): ' +
+                        (err instanceof Error ? err.message : String(err)) +
+                        '\n');
+                }
+            }
+        }
+    }
+    on(type, handler) {
+        let set = this.listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(type, set);
+        }
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    removeAll() {
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/domain/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wBAAwB;AACxB,EAAE;AACF,6EAA6E;AAC7E,qDAAqD;AACrD,gFAAgF;AAUhF,MAAM,OAAO,QAAQ;IACF,SAAS,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEtE,IAAI,CAAC,IAAO,EAAE,OAAgC,EAAE;QAC9C,MAAM,KAAK,GAAgB;YACzB,IAAI;YACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,IAAI;SACL,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,oCAAoC;wBAClC,IAAI;wBACJ,KAAK;wBACL,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;wBAClD,IAAI,CACP,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;gBAChC,IAAI,CAAC;oBACH,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uCAAuC;wBACrC,IAAI;wBACJ,KAAK;wBACL,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;wBAClD,IAAI,CACP,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,EAAE,CAAC,IAAa,EAAE,OAAwB;QACxC,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjB,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC,CAAC;IACJ,CAAC;IAED,SAAS;QACP,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './types.js';
+export * from './storage/database.js';
+export * from './storage/fts.js';
+export * from './transport/rest.js';
+export * from './transport/ws.js';
+export * from './transport/mcp.js';
+export * from './domain/events.js';
+export * from './domain/cleanup.js';
+export * from './dashboard.js';
+export * from './package-meta.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// =============================================================================
+// agent-kit — Public API
+// =============================================================================
+export * from './types.js';
+export * from './storage/database.js';
+export * from './storage/fts.js';
+export * from './transport/rest.js';
+export * from './transport/ws.js';
+export * from './transport/mcp.js';
+export * from './domain/events.js';
+export * from './domain/cleanup.js';
+export * from './dashboard.js';
+export * from './package-meta.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC"}

package/dist/package-meta.d.ts

@@ -0,0 +1,22 @@
+export interface PackageMeta {
+    name: string;
+    version: string;
+}
+export interface ReadPackageMetaOptions {
+    /** import.meta.url of the calling file. Required when running as ESM. */
+    importMetaUrl?: string;
+    /** Override absolute path to a package.json. Wins over importMetaUrl. */
+    packageJsonPath?: string;
+    /** Fallback name if package.json is missing or unreadable. */
+    fallbackName?: string;
+    /** Fallback version if package.json is missing or unreadable. */
+    fallbackVersion?: string;
+}
+/**
+ * Read `name` + `version` from a package.json. Resolution order:
+ *   1. options.packageJsonPath (absolute)
+ *   2. options.importMetaUrl → ../package.json (relative to caller)
+ *   3. fallback values
+ */
+export declare function readPackageMeta(options?: ReadPackageMetaOptions): PackageMeta;
+//# sourceMappingURL=package-meta.d.ts.map

package/dist/package-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-meta.d.ts","sourceRoot":"","sources":["../src/package-meta.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,WAAW,CA8BjF"}

package/dist/package-meta.js

@@ -0,0 +1,48 @@
+// =============================================================================
+// agent-kit — Read package.json metadata at runtime
+//
+// Consumers call this from a known location (typically `dist/<file>.js`) so
+// that the relative `..` path resolves to their package.json. The result is
+// cached per-path so repeated calls are cheap.
+// =============================================================================
+import { readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+const cache = new Map();
+/**
+ * Read `name` + `version` from a package.json. Resolution order:
+ *   1. options.packageJsonPath (absolute)
+ *   2. options.importMetaUrl → ../package.json (relative to caller)
+ *   3. fallback values
+ */
+export function readPackageMeta(options = {}) {
+    const fallback = {
+        name: options.fallbackName ?? 'unknown',
+        version: options.fallbackVersion ?? '0.0.0',
+    };
+    let path = options.packageJsonPath;
+    if (!path && options.importMetaUrl) {
+        const callerDir = dirname(fileURLToPath(options.importMetaUrl));
+        path = resolve(join(callerDir, '..', 'package.json'));
+    }
+    if (!path)
+        return fallback;
+    const cached = cache.get(path);
+    if (cached)
+        return cached;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const pkg = JSON.parse(raw);
+        const meta = {
+            name: typeof pkg.name === 'string' ? pkg.name : fallback.name,
+            version: typeof pkg.version === 'string' ? pkg.version : fallback.version,
+        };
+        cache.set(path, meta);
+        return meta;
+    }
+    catch {
+        cache.set(path, fallback);
+        return fallback;
+    }
+}
+//# sourceMappingURL=package-meta.js.map

package/dist/package-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-meta.js","sourceRoot":"","sources":["../src/package-meta.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,+CAA+C;AAC/C,gFAAgF;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAOpC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;AAa7C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,QAAQ,GAAgB;QAC5B,IAAI,EAAE,OAAO,CAAC,YAAY,IAAI,SAAS;QACvC,OAAO,EAAE,OAAO,CAAC,eAAe,IAAI,OAAO;KAC5C,CAAC;IAEF,IAAI,IAAI,GAAuB,OAAO,CAAC,eAAe,CAAC;IACvD,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAChE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAE3B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwC,CAAC;QACnE,MAAM,IAAI,GAAgB;YACxB,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI;YAC7D,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO;SAC1E,CAAC;QACF,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1B,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/storage/database.d.ts

@@ -0,0 +1,27 @@
+import Database from 'better-sqlite3';
+export interface Db {
+    readonly raw: Database.Database;
+    run(sql: string, params?: unknown[]): Database.RunResult;
+    queryAll<T>(sql: string, params?: unknown[]): T[];
+    queryOne<T>(sql: string, params?: unknown[]): T | null;
+    transaction<T>(fn: () => T): T;
+    close(): void;
+}
+export interface Migration {
+    /** 1-based version number; migrations run in ascending order. */
+    version: number;
+    /** Idempotent SQL or programmatic step. */
+    up: (raw: Database.Database) => void;
+}
+export interface DbOptions {
+    /** Use ':memory:' for tests, or an absolute file path. */
+    path: string;
+    /** Migrations to apply on open. */
+    migrations?: Migration[];
+    /** Enable verbose logging to stderr. */
+    verbose?: boolean;
+}
+export declare function createDb(options: DbOptions): Db;
+export declare function runMigrations(raw: Database.Database, migrations: Migration[]): void;
+export declare function getSchemaVersion(raw: Database.Database): number;
+//# sourceMappingURL=database.d.ts.map

package/dist/storage/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/storage/database.ts"],"names":[],"mappings":"AAQA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,MAAM,WAAW,EAAE;IACjB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC;IACzD,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;IAClD,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IACvD,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,EAAE,CAwC/C;AAMD,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,IAAI,CAyBnF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAK/D"}

package/dist/storage/database.js

@@ -0,0 +1,73 @@
+// =============================================================================
+// agent-kit — Storage layer
+//
+// Generic better-sqlite3 wrapper with WAL pragmas, transactions, and a
+// version-based migration runner. Consumers supply their own migrations and
+// resolve their own DB path.
+// =============================================================================
+import Database from 'better-sqlite3';
+export function createDb(options) {
+    const raw = new Database(options.path, {
+        verbose: options.verbose ? (msg) => process.stderr.write(`[sql] ${msg}\n`) : undefined,
+    });
+    raw.pragma('journal_mode = WAL');
+    raw.pragma('busy_timeout = 5000');
+    raw.pragma('synchronous = NORMAL');
+    raw.pragma('foreign_keys = ON');
+    if (options.migrations && options.migrations.length > 0) {
+        runMigrations(raw, options.migrations);
+    }
+    return {
+        raw,
+        run(sql, params) {
+            const stmt = raw.prepare(sql);
+            return params?.length ? stmt.run(...params) : stmt.run();
+        },
+        queryAll(sql, params) {
+            const stmt = raw.prepare(sql);
+            return (params?.length ? stmt.all(...params) : stmt.all());
+        },
+        queryOne(sql, params) {
+            const stmt = raw.prepare(sql);
+            const row = params?.length ? stmt.get(...params) : stmt.get();
+            return row ?? null;
+        },
+        transaction(fn) {
+            return raw.transaction(fn)();
+        },
+        close() {
+            try {
+                raw.close();
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Migration runner
+// ---------------------------------------------------------------------------
+export function runMigrations(raw, migrations) {
+    raw.exec(`
+    CREATE TABLE IF NOT EXISTS _meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+    const row = raw.prepare(`SELECT value FROM _meta WHERE key = 'schema_version'`).get();
+    const currentVersion = row ? parseInt(row.value, 10) : 0;
+    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    const target = sorted.length > 0 ? sorted[sorted.length - 1].version : 0;
+    for (const m of sorted) {
+        if (m.version > currentVersion) {
+            m.up(raw);
+        }
+    }
+    raw.prepare(`INSERT OR REPLACE INTO _meta (key, value) VALUES ('schema_version', ?)`).run(String(target));
+}
+export function getSchemaVersion(raw) {
+    const row = raw.prepare(`SELECT value FROM _meta WHERE key = 'schema_version'`).get();
+    return row ? parseInt(row.value, 10) : 0;
+}
+//# sourceMappingURL=database.js.map

package/dist/storage/database.js.map

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

package/dist/storage/fts.d.ts

@@ -0,0 +1,27 @@
+import type { Db } from './database.js';
+export interface FtsOptions {
+    /** Name of the FTS5 virtual table to create (e.g. "messages_fts"). */
+    ftsTable: string;
+    /** Name of the content table the FTS index mirrors (e.g. "messages"). */
+    contentTable: string;
+    /** Column name in the content table to index (e.g. "content"). */
+    column: string;
+}
+/** Create an FTS5 virtual table + insert/update/delete triggers idempotently. */
+export declare function createFtsTable(db: Db, opts: FtsOptions): void;
+export interface FtsSearchOptions {
+    ftsTable: string;
+    contentTable: string;
+    column: string;
+    query: string;
+    limit?: number;
+    /** Optional extra WHERE clause appended after the FTS join. */
+    extraWhere?: string;
+    extraParams?: unknown[];
+}
+/**
+ * FTS5 MATCH search with LIKE fallback. Returns matching content rows.
+ * If the FTS query parses incorrectly, falls back to a LIKE wildcard scan.
+ */
+export declare function ftsSearch<T>(db: Db, opts: FtsSearchOptions): T[];
+//# sourceMappingURL=fts.d.ts.map

package/dist/storage/fts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../../src/storage/fts.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,eAAe,CAAC;AAExC,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAsB7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,gBAAgB,GAAG,CAAC,EAAE,CA0BhE"}