agent-common

library1.1.1jsnpmunverified

Shared foundation for agent-* MCP servers (agent-comm, agent-tasks, agent-knowledge, agent-discover). Provides SQLite storage with WAL pragmas, transaction helper, and migration runner; REST transport with node:http router, JSON helper, CORS, body reader, static file serving; WebSocket server with full-state-on-connect, DB-fingerprint delta polling, ping/pong heartbeat, max-connection cap; MCP JSON-RPC over stdio with tool dispatcher; typed in-process EventBus with wildcards; CleanupService with retention timer; auto-starting dashboard with port leader-election; runtime package name+version reader; FTS5 and LIKE fallback search. Current version 1.1.1, MIT license, TypeScript types included, requires Node >=20.11.0 and peer deps better-sqlite3 >=11 and ws >=8. Internal use package, not yet stable API, no external documentation.

ai-ml devops

npm install agent-common

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AGENT-COMMON

agent-common

ai-mljavascriptv1.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createRouter

✓ import { createRouter } from 'agent-common'

✗ const { createRouter } = require('agent-common')

ESM only; package type is module. TypeScript types are bundled.

createStorage

✓ import { createStorage } from 'agent-common'

✗ import { createStorage } from 'agent-common/storage'

All exports are from the root index; subpath exports are not supported.

EventBus

✓ import { EventBus } from 'agent-common'

✗ import EventBus from 'agent-common'

EventBus is a named export, not default.

ToolDefinition

✓ import type { ToolDefinition } from 'agent-common'

✗ import { ToolDefinition } from 'agent-common'

ToolDefinition is a type, prefer type import for elision.

Creates an in-memory SQLite database with migrations, sets up a simple REST router, and demonstrates typed EventBus usage.

import { createStorage, createRouter, EventBus } from 'agent-common'; import Database from 'better-sqlite3'; const db = new Database(':memory:'); const storage = createStorage(db, { migrate: true }); const router = createRouter(); router.get('/items', async (req, res) => { const items = storage.prepare('SELECT * FROM items').all(); res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(items)); }); const bus = new EventBus<{ itemCreated: { id: number } }>(); bus.on('itemCreated', (event) => console.log('Created', event.data.id)); bus.emit('itemCreated', { id: 1 }); console.log('Quickstart done');

Debug

Known issues

breakingRequires Node.js >=20.11.0; older versions throw ERR_UNSUPPORTED_ESM_URL_SCHEME or similar.

fix

Upgrade Node.js to >=20.11.0 or use a polyfill (not recommended).

affects: <1.0.0

gotchaAll exports are from the root index; attempting to import from subpaths like 'agent-common/storage' will fail with 'MODULE_NOT_FOUND'.

fix

Import only from 'agent-common'.

affects: >=1.0.0

deprecatedThe 'Dashboard' auto-start feature uses port leader-election which may silently fail if the port is already in use.

fix

Check if dashboard is needed; override or disable via configuration if unexpected.

affects: >=1.0.0

gotchaThe package uses ESM only; require() will throw ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import() in CommonJS.

affects: >=1.0.0

gotchaTypeScript users must set moduleResolution to 'bundler' or 'node16' to resolve types correctly.

fix

Add 'moduleResolution': 'bundler' to tsconfig.json.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/agent-common/index.js from /path/to/app.js not supported.

Package is ESM-only; require() is not supported.

fix

Change to import syntax (import { ... } from 'agent-common') or use dynamic import() in CommonJS modules.

Cannot find module 'agent-common/storage' or its corresponding type declarations.

No subpath exports; all exports are from the root index.

fix

Import from 'agent-common' only: import { createStorage } from 'agent-common'.

TypeError: Database is not a constructor

Using better-sqlite3 v10 or lower which is incompatible; peer dep requires >=11.

fix

Install better-sqlite3 >=11: npm install better-sqlite3@^11

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite database access with WAL mode and transactions

wsrequiredWebSocket server for transport/ws

Agent activity

52 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/keshrath/agent-common ↗

packageagent-common ↗

homepagehttps://github.com/keshrath/agent-common#readme ↗