@hamak/ai-agent-backend 0.7.1

package/dist/agent-routes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Express route factory for the agent (ticket §10 PR2). Mounts a small REST +
+ * SSE surface backed by a server-side `AgentService` (hosted provider + durable
+ * memory). Mirrors the `event-channel-backend` route/SSE conventions.
+ *
+ *   POST   /chat                      → SSE: `token` deltas, then `turn-end`
+ *   GET    /conversations?agent=      → ConversationSummary[]
+ *   DELETE /conversations/:id?agent=  → { ok: true }
+ *
+ * `express` is an optional peer; this module is only imported by hosts that
+ * have it. Types are structural so it doesn't hard-import express.
+ */
+import type { AgentService } from '@hamak/ai-agent';
+import type { HooksBus } from './hooks-bus.js';
+import type { HttpServerChannel } from './http-server-channel.js';
+interface Req {
+    body: any;
+    query: Record<string, unknown>;
+    params: Record<string, string>;
+    on(event: 'close', cb: () => void): void;
+}
+interface Res {
+    setHeader(name: string, value: string): void;
+    write(chunk: string): void;
+    end(): void;
+    status(code: number): Res;
+    json(body: unknown): void;
+    flushHeaders?(): void;
+}
+interface RouterLike {
+    post(path: string, handler: (req: Req, res: Res) => void): void;
+    get(path: string, handler: (req: Req, res: Res) => void): void;
+    delete(path: string, handler: (req: Req, res: Res) => void): void;
+}
+export interface AgentRoutesConfig {
+    service: AgentService;
+    /** The same bus the service emits on; the SSE handler relays `ai:token`. */
+    hooks: HooksBus;
+    /** Factory for a fresh router, e.g. `() => express.Router()`. */
+    router: () => RouterLike;
+    /** Split-loop channel (§4): mounts GET/POST `/channel` when provided. */
+    channel?: HttpServerChannel;
+}
+export declare function createAgentRoutes(config: AgentRoutesConfig): RouterLike;
+export {};
+//# sourceMappingURL=agent-routes.d.ts.map

package/dist/agent-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-routes.d.ts","sourceRoot":"","sources":["../src/agent-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,UAAU,GAAG;IACX,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC1C;AACD,UAAU,GAAG;IACX,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,IAAI,IAAI,CAAC;IACZ,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,IAAI,IAAI,CAAC;CACvB;AACD,UAAU,UAAU;IAClB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAAC;IAChE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,4EAA4E;IAC5E,KAAK,EAAE,QAAQ,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,UAAU,CAAC;IACzB,yEAAyE;IACzE,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAWD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,UAAU,CAoFvE"}

package/dist/agent-routes.js

@@ -0,0 +1,93 @@
+/**
+ * Express route factory for the agent (ticket §10 PR2). Mounts a small REST +
+ * SSE surface backed by a server-side `AgentService` (hosted provider + durable
+ * memory). Mirrors the `event-channel-backend` route/SSE conventions.
+ *
+ *   POST   /chat                      → SSE: `token` deltas, then `turn-end`
+ *   GET    /conversations?agent=      → ConversationSummary[]
+ *   DELETE /conversations/:id?agent=  → { ok: true }
+ *
+ * `express` is an optional peer; this module is only imported by hosts that
+ * have it. Types are structural so it doesn't hard-import express.
+ */
+import { randomUUID } from 'node:crypto';
+function sse(res, event, data) {
+    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+function agentName(req) {
+    const a = req.query.agent;
+    return typeof a === 'string' ? a : undefined;
+}
+export function createAgentRoutes(config) {
+    const { service, hooks } = config;
+    const router = config.router();
+    router.post('/chat', (req, res) => {
+        const { input, sessionId, agent } = (req.body ?? {});
+        if (typeof input !== 'string' || input.length === 0) {
+            res.status(400).json({ error: 'input (string) is required' });
+            return;
+        }
+        // Pin the session up front so we can scope the token stream to this turn.
+        const sid = sessionId ?? randomUUID();
+        res.setHeader('content-type', 'text/event-stream');
+        res.setHeader('cache-control', 'no-cache');
+        res.setHeader('connection', 'keep-alive');
+        res.flushHeaders?.();
+        sse(res, 'session', { sessionId: sid });
+        const onToken = (payload) => {
+            if (payload?.sessionId === sid) {
+                sse(res, 'token', payload);
+            }
+        };
+        hooks.on('ai:token', onToken);
+        let done = false;
+        const cleanup = () => {
+            if (done)
+                return;
+            done = true;
+            hooks.off('ai:token', onToken);
+        };
+        req.on('close', cleanup);
+        service
+            .askStream(agent, input, { sessionId: sid })
+            .then((result) => {
+            sse(res, 'turn-end', result);
+            cleanup();
+            res.end();
+        })
+            .catch((err) => {
+            sse(res, 'error', { error: String(err) });
+            cleanup();
+            res.end();
+        });
+    });
+    router.get('/conversations', (req, res) => {
+        service
+            .listConversations(agentName(req))
+            .then((list) => res.json(list))
+            .catch((err) => res.status(500).json({ error: String(err) }));
+    });
+    router.delete('/conversations/:id', (req, res) => {
+        service
+            .reset(agentName(req), req.params.id)
+            .then(() => res.json({ ok: true }))
+            .catch((err) => res.status(500).json({ error: String(err) }));
+    });
+    // Split-loop duplex channel (§4): SSE down + POST up.
+    const channel = config.channel;
+    if (channel) {
+        router.get('/channel', (req, res) => {
+            res.setHeader('content-type', 'text/event-stream');
+            res.setHeader('cache-control', 'no-cache');
+            res.setHeader('connection', 'keep-alive');
+            res.flushHeaders?.();
+            channel.addClient(res);
+            req.on('close', () => channel.removeClient(res));
+        });
+        router.post('/channel', (req, res) => {
+            channel.ingest(req.body);
+            res.json({ ok: true });
+        });
+    }
+    return router;
+}

package/dist/anthropic-provider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Anthropic provider — hosted Claude models via the Messages API (ticket §3,
+ * topology B: runs backend-side so the API key never reaches a browser).
+ *
+ * Uses `fetch` directly to match the sibling `OllamaProvider` and to avoid
+ * adding an SDK dependency the workspace doesn't otherwise carry; swapping to
+ * `@anthropic-ai/sdk` later is a drop-in behind this same `IAgentProvider`.
+ *
+ * Wire format (POST https://api.anthropic.com/v1/messages):
+ *   headers: x-api-key, anthropic-version: 2023-06-01, content-type: json
+ *   body:    { model, max_tokens, system?, messages, stream }
+ *   stream:  SSE — message_start (usage.input_tokens),
+ *            content_block_delta/text_delta (delta.text),
+ *            message_delta (usage.output_tokens), message_stop.
+ *
+ * Note: Opus 4.8 / 4.7 reject `temperature`/`top_p` (400), so `temperature` is
+ * sent only when explicitly configured. Default model: claude-opus-4-8.
+ */
+import type { AgentEvent, AgentMessage, AgentResult, CompleteOpts, IAgentProvider } from '@hamak/ai-agent';
+export interface AnthropicProviderConfig {
+    /** API key; falls back to `process.env.ANTHROPIC_API_KEY`. */
+    apiKey?: string;
+    /** Override the base URL (proxies, gateways). */
+    baseURL?: string;
+    /** Override the provider id (default `anthropic`). */
+    id?: string;
+    /** Custom fetch (tests inject this); defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class AnthropicProvider implements IAgentProvider {
+    readonly id: string;
+    private readonly apiKey;
+    private readonly url;
+    private readonly fetchImpl;
+    constructor(config?: AnthropicProviderConfig);
+    private headers;
+    private body;
+    complete(messages: AgentMessage[], opts: CompleteOpts): Promise<AgentResult>;
+    stream(messages: AgentMessage[], opts: CompleteOpts): AsyncIterable<AgentEvent>;
+}
+//# sourceMappingURL=anthropic-provider.d.ts.map

package/dist/anthropic-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-provider.d.ts","sourceRoot":"","sources":["../src/anthropic-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACf,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA4BD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,MAAM,GAAE,uBAA4B;IAahD,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,IAAI;IAYN,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAgC3E,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,UAAU,CAAC;CA+CvF"}

package/dist/anthropic-provider.js

@@ -0,0 +1,162 @@
+/**
+ * Anthropic provider — hosted Claude models via the Messages API (ticket §3,
+ * topology B: runs backend-side so the API key never reaches a browser).
+ *
+ * Uses `fetch` directly to match the sibling `OllamaProvider` and to avoid
+ * adding an SDK dependency the workspace doesn't otherwise carry; swapping to
+ * `@anthropic-ai/sdk` later is a drop-in behind this same `IAgentProvider`.
+ *
+ * Wire format (POST https://api.anthropic.com/v1/messages):
+ *   headers: x-api-key, anthropic-version: 2023-06-01, content-type: json
+ *   body:    { model, max_tokens, system?, messages, stream }
+ *   stream:  SSE — message_start (usage.input_tokens),
+ *            content_block_delta/text_delta (delta.text),
+ *            message_delta (usage.output_tokens), message_stop.
+ *
+ * Note: Opus 4.8 / 4.7 reject `temperature`/`top_p` (400), so `temperature` is
+ * sent only when explicitly configured. Default model: claude-opus-4-8.
+ */
+const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-01';
+const DEFAULT_MAX_TOKENS = 4096;
+/** Map agent messages to Anthropic's user/assistant turns. */
+function toAnthropicMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'system')
+            continue; // system is passed separately
+        // tool results are surfaced as plain user text in this text-only skeleton
+        out.push({ role: m.role === 'assistant' ? 'assistant' : 'user', content: m.content });
+    }
+    // The Messages API requires the first turn to be `user`.
+    if (out.length > 0 && out[0].role !== 'user') {
+        out.unshift({ role: 'user', content: '(context)' });
+    }
+    return out;
+}
+let seq = 0;
+function genId() {
+    seq += 1;
+    return `msg-anthropic-${seq}`;
+}
+export class AnthropicProvider {
+    constructor(config = {}) {
+        this.id = config.id ?? 'anthropic';
+        this.apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '';
+        this.url = config.baseURL ?? ANTHROPIC_URL;
+        const resolved = config.fetchImpl ??
+            (typeof globalThis.fetch === 'function' ? globalThis.fetch.bind(globalThis) : undefined);
+        if (!resolved) {
+            throw new Error('[anthropic] no fetch implementation available');
+        }
+        this.fetchImpl = resolved;
+    }
+    headers() {
+        if (!this.apiKey) {
+            throw new Error('[anthropic] missing API key (set ANTHROPIC_API_KEY or pass apiKey)');
+        }
+        return {
+            'content-type': 'application/json',
+            'x-api-key': this.apiKey,
+            'anthropic-version': ANTHROPIC_VERSION,
+        };
+    }
+    body(messages, opts, stream) {
+        return JSON.stringify({
+            model: opts.model,
+            max_tokens: opts.maxTokens ?? DEFAULT_MAX_TOKENS,
+            ...(opts.systemPrompt ? { system: opts.systemPrompt } : {}),
+            // Only send temperature when explicitly set — Opus 4.8/4.7 reject it.
+            ...(opts.temperature != null ? { temperature: opts.temperature } : {}),
+            messages: toAnthropicMessages(messages),
+            stream,
+        });
+    }
+    async complete(messages, opts) {
+        const res = await this.fetchImpl(this.url, {
+            method: 'POST',
+            headers: this.headers(),
+            body: this.body(messages, opts, false),
+            signal: opts.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`[anthropic] ${res.status} ${res.statusText}: ${await safeText(res)}`);
+        }
+        const json = (await res.json());
+        const content = (json.content ?? [])
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('');
+        return {
+            message: {
+                id: genId(),
+                role: 'assistant',
+                content,
+                createdAt: new Date().toISOString(),
+            },
+            usage: {
+                inputTokens: json.usage?.input_tokens ?? 0,
+                outputTokens: json.usage?.output_tokens ?? 0,
+            },
+        };
+    }
+    async *stream(messages, opts) {
+        const res = await this.fetchImpl(this.url, {
+            method: 'POST',
+            headers: this.headers(),
+            body: this.body(messages, opts, true),
+            signal: opts.signal,
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`[anthropic] ${res.status} ${res.statusText}: ${await safeText(res)}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let inputTokens = 0;
+        let outputTokens = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let nl;
+                while ((nl = buffer.indexOf('\n')) !== -1) {
+                    const line = buffer.slice(0, nl).trim();
+                    buffer = buffer.slice(nl + 1);
+                    if (!line.startsWith('data:'))
+                        continue; // skip `event:` and blanks
+                    const payload = line.slice(5).trim();
+                    if (!payload || payload === '[DONE]')
+                        continue;
+                    const evt = JSON.parse(payload);
+                    if (evt.type === 'message_start') {
+                        inputTokens = evt.message?.usage?.input_tokens ?? inputTokens;
+                    }
+                    else if (evt.type === 'content_block_delta' && evt.delta?.type === 'text_delta') {
+                        if (evt.delta.text)
+                            yield { type: 'text-delta', delta: evt.delta.text };
+                    }
+                    else if (evt.type === 'message_delta') {
+                        outputTokens = evt.usage?.output_tokens ?? outputTokens;
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const usage = { inputTokens, outputTokens };
+        yield { type: 'usage', usage };
+        yield { type: 'done', usage };
+    }
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}

package/dist/create-agent-backend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Convenience wiring for a server-side agent: registers the Anthropic provider,
+ * a durable `FileAgentMemory`, an `AgentService`, and a hooks bus the SSE route
+ * relays from. Hosts that prefer the microkernel can wire these pieces by hand;
+ * this helper covers the common Express-server case.
+ */
+import { AgentService, Registry, RemoteToolBridge, type AgentPluginConfig, type IAgentProvider, type IAgentTool } from '@hamak/ai-agent';
+import { type AnthropicProviderConfig } from './anthropic-provider.js';
+import { FileAgentMemory } from './file-agent-memory.js';
+import { type HooksBus } from './hooks-bus.js';
+import { HttpServerChannel } from './http-server-channel.js';
+export interface AgentBackendConfig {
+    /** Agent definitions (provider id should match a registered provider). */
+    agents: AgentPluginConfig;
+    /** Directory for durable conversation files. */
+    memoryRoot: string;
+    /** Anthropic provider options (apiKey, baseURL). */
+    anthropic?: AnthropicProviderConfig;
+    /** Extra providers to register beyond the built-in Anthropic one. */
+    providers?: IAgentProvider[];
+    /** Backend-side tools. */
+    tools?: IAgentTool[];
+}
+export interface AgentBackend {
+    service: AgentService;
+    hooks: HooksBus;
+    memory: FileAgentMemory;
+    providers: Registry<IAgentProvider>;
+    tools: Registry<IAgentTool>;
+    /** Split-loop channel — pass to `createAgentRoutes({ channel })` (§4). */
+    channel: HttpServerChannel;
+    bridge: RemoteToolBridge;
+}
+export declare function createAgentBackend(config: AgentBackendConfig): AgentBackend;
+//# sourceMappingURL=create-agent-backend.d.ts.map

package/dist/create-agent-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-agent-backend.d.ts","sourceRoot":"","sources":["../src/create-agent-backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAqB,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACpC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CA8B3E"}

package/dist/create-agent-backend.js

@@ -0,0 +1,39 @@
+/**
+ * Convenience wiring for a server-side agent: registers the Anthropic provider,
+ * a durable `FileAgentMemory`, an `AgentService`, and a hooks bus the SSE route
+ * relays from. Hosts that prefer the microkernel can wire these pieces by hand;
+ * this helper covers the common Express-server case.
+ */
+import { AgentService, Registry, RemoteToolBridge, } from '@hamak/ai-agent';
+import { AnthropicProvider } from './anthropic-provider.js';
+import { FileAgentMemory } from './file-agent-memory.js';
+import { createHooksBus } from './hooks-bus.js';
+import { HttpServerChannel } from './http-server-channel.js';
+export function createAgentBackend(config) {
+    const providers = new Registry();
+    providers.register(new AnthropicProvider(config.anthropic));
+    for (const p of config.providers ?? [])
+        providers.register(p);
+    const tools = new Registry();
+    for (const t of config.tools ?? [])
+        tools.register(t);
+    const memory = new FileAgentMemory(config.memoryRoot);
+    const hooks = createHooksBus();
+    // Split-loop: a backend channel + bridge so the loop can call frontend tools.
+    const channel = new HttpServerChannel();
+    const bridge = new RemoteToolBridge({ channel });
+    bridge.start();
+    const service = new AgentService({
+        config: config.agents,
+        providers,
+        tools,
+        memory,
+        frontend: {
+            specs: () => bridge.specs(),
+            has: (n) => bridge.has(n),
+            run: (call, sessionId) => bridge.run(call, sessionId),
+        },
+    });
+    service.setHooks(hooks);
+    return { service, hooks, memory, providers, tools, channel, bridge };
+}

package/dist/file-agent-memory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Durable file-system conversation memory (ticket §3: backend "durable /
+ * cross-device / audit" source of truth). One JSON file per conversation under
+ * `<root>/<agentId>/<sessionId>.json`, so it survives server restarts.
+ *
+ * This is the backend analogue of the frontend's `StoreFsMemory` — same
+ * `IAgentMemory` contract, different substrate (node `fs` vs the virtual store).
+ */
+import type { AgentMessage, Conversation, ConversationSummary } from '@hamak/ai-agent';
+import type { IAgentMemory } from '@hamak/ai-agent/spi';
+export declare class FileAgentMemory implements IAgentMemory {
+    private readonly root;
+    constructor(root: string);
+    private dir;
+    private file;
+    get(agentId: string, sessionId: string): Promise<Conversation | null>;
+    load(agentId: string, sessionId: string): Promise<AgentMessage[]>;
+    private write;
+    append(agentId: string, sessionId: string, message: AgentMessage): Promise<void>;
+    update(agentId: string, sessionId: string, messageId: string, changes: Partial<Pick<AgentMessage, 'content' | 'toolCalls'>>): Promise<void>;
+    patch(agentId: string, sessionId: string, changes: Partial<Pick<Conversation, 'title' | 'pinned' | 'systemPrompt'>>): Promise<void>;
+    reset(agentId: string, sessionId: string): Promise<void>;
+    list(agentId: string): Promise<ConversationSummary[]>;
+}
+//# sourceMappingURL=file-agent-memory.d.ts.map

package/dist/file-agent-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-agent-memory.d.ts","sourceRoot":"","sources":["../src/file-agent-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAoBxD,qBAAa,eAAgB,YAAW,YAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAEzC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,IAAI;IAIN,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAUrE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAIzD,KAAK;IAKb,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhF,MAAM,CACV,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,GAC5D,OAAO,CAAC,IAAI,CAAC;IAUV,KAAK,CACT,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,QAAQ,GAAG,cAAc,CAAC,CAAC,GACxE,OAAO,CAAC,IAAI,CAAC;IAMV,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;CAuB5D"}

package/dist/file-agent-memory.js

@@ -0,0 +1,124 @@
+/**
+ * Durable file-system conversation memory (ticket §3: backend "durable /
+ * cross-device / audit" source of truth). One JSON file per conversation under
+ * `<root>/<agentId>/<sessionId>.json`, so it survives server restarts.
+ *
+ * This is the backend analogue of the frontend's `StoreFsMemory` — same
+ * `IAgentMemory` contract, different substrate (node `fs` vs the virtual store).
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { CONVERSATION_SCHEMA_VERSION } from '@hamak/ai-agent';
+function nowIso() {
+    return new Date().toISOString();
+}
+function deriveTitle(text) {
+    const trimmed = text.trim().replace(/\s+/g, ' ');
+    if (!trimmed)
+        return 'New conversation';
+    return trimmed.length > 60 ? `${trimmed.slice(0, 57)}…` : trimmed;
+}
+/** Reject path segments that could escape the root. */
+function safeSegment(seg) {
+    if (!seg || seg.includes('/') || seg.includes('\\') || seg.includes('..')) {
+        throw new Error(`[ai-agent-backend] unsafe path segment: ${seg}`);
+    }
+    return seg;
+}
+export class FileAgentMemory {
+    constructor(root) {
+        this.root = root;
+    }
+    dir(agentId) {
+        return path.join(this.root, safeSegment(agentId));
+    }
+    file(agentId, sessionId) {
+        return path.join(this.dir(agentId), `${safeSegment(sessionId)}.json`);
+    }
+    async get(agentId, sessionId) {
+        try {
+            const raw = await fs.readFile(this.file(agentId, sessionId), 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async load(agentId, sessionId) {
+        return (await this.get(agentId, sessionId))?.messages ?? [];
+    }
+    async write(agentId, sessionId, conv) {
+        await fs.mkdir(this.dir(agentId), { recursive: true });
+        await fs.writeFile(this.file(agentId, sessionId), JSON.stringify(conv, null, 2), 'utf8');
+    }
+    async append(agentId, sessionId, message) {
+        const now = nowIso();
+        const existing = await this.get(agentId, sessionId);
+        if (existing) {
+            existing.messages.push(message);
+            existing.updatedAt = now;
+            if (existing.title === '' && message.role === 'user') {
+                existing.title = deriveTitle(message.content);
+            }
+            await this.write(agentId, sessionId, existing);
+            return;
+        }
+        await this.write(agentId, sessionId, {
+            schemaVersion: CONVERSATION_SCHEMA_VERSION,
+            id: sessionId,
+            title: message.role === 'user' ? deriveTitle(message.content) : '',
+            messages: [message],
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    async update(agentId, sessionId, messageId, changes) {
+        const existing = await this.get(agentId, sessionId);
+        if (!existing)
+            return;
+        const idx = existing.messages.findIndex((m) => m.id === messageId);
+        if (idx === -1)
+            return;
+        existing.messages[idx] = { ...existing.messages[idx], ...changes };
+        existing.updatedAt = nowIso();
+        await this.write(agentId, sessionId, existing);
+    }
+    async patch(agentId, sessionId, changes) {
+        const existing = await this.get(agentId, sessionId);
+        if (!existing)
+            return;
+        await this.write(agentId, sessionId, { ...existing, ...changes, updatedAt: nowIso() });
+    }
+    async reset(agentId, sessionId) {
+        await fs.rm(this.file(agentId, sessionId), { force: true });
+    }
+    async list(agentId) {
+        let names;
+        try {
+            names = await fs.readdir(this.dir(agentId));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const out = [];
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            const conv = await this.get(agentId, name.slice(0, -'.json'.length));
+            if (!conv)
+                continue;
+            out.push({
+                id: conv.id,
+                title: conv.title,
+                messageCount: conv.messages.length,
+                updatedAt: conv.updatedAt,
+                pinned: conv.pinned,
+            });
+        }
+        return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+}

package/dist/hooks-bus.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tiny synchronous event bus — the backend analogue of the microkernel hooks
+ * surface, so a standalone `AgentService` can emit `ai:*` events that the SSE
+ * route subscribes to.
+ */
+export interface HooksBus {
+    on(event: string, fn: (...args: unknown[]) => void): void;
+    off(event: string, fn: (...args: unknown[]) => void): void;
+    emit(event: string, ...args: unknown[]): void;
+}
+export declare function createHooksBus(): HooksBus;
+//# sourceMappingURL=hooks-bus.d.ts.map

package/dist/hooks-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-bus.d.ts","sourceRoot":"","sources":["../src/hooks-bus.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/C;AAED,wBAAgB,cAAc,IAAI,QAAQ,CAqBzC"}

package/dist/hooks-bus.js

@@ -0,0 +1,29 @@
+/**
+ * Tiny synchronous event bus — the backend analogue of the microkernel hooks
+ * surface, so a standalone `AgentService` can emit `ai:*` events that the SSE
+ * route subscribes to.
+ */
+export function createHooksBus() {
+    const map = new Map();
+    return {
+        on(event, fn) {
+            let set = map.get(event);
+            if (!set)
+                map.set(event, (set = new Set()));
+            set.add(fn);
+        },
+        off(event, fn) {
+            map.get(event)?.delete(fn);
+        },
+        emit(event, ...args) {
+            for (const fn of map.get(event) ?? []) {
+                try {
+                    fn(...args);
+                }
+                catch {
+                    /* a bad listener must not break the loop */
+                }
+            }
+        },
+    };
+}

package/dist/http-server-channel.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `HttpServerChannel` — the backend `IAgentChannel` end (ticket §4). Holds the
+ * open SSE responses (down-stream) and fans `send()` out to them; `ingest()`
+ * feeds POSTed up-envelopes to the registered handlers. The Express channel
+ * routes (see `agent-routes.ts`) drive `addClient`/`removeClient`/`ingest`.
+ */
+import type { AgentChannelEnvelope } from '@hamak/ai-agent';
+import type { IAgentChannel } from '@hamak/ai-agent/spi';
+export interface SseWritable {
+    write(chunk: string): void;
+}
+export declare class HttpServerChannel implements IAgentChannel {
+    private readonly clients;
+    private readonly handlers;
+    send(msg: AgentChannelEnvelope): void;
+    onMessage(handler: (m: AgentChannelEnvelope) => void): () => void;
+    addClient(res: SseWritable): void;
+    removeClient(res: SseWritable): void;
+    /** Called by the POST /channel route with a parsed up-envelope. */
+    ingest(msg: AgentChannelEnvelope): void;
+}
+//# sourceMappingURL=http-server-channel.d.ts.map

package/dist/http-server-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server-channel.d.ts","sourceRoot":"","sources":["../src/http-server-channel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IAEzE,IAAI,CAAC,GAAG,EAAE,oBAAoB,GAAG,IAAI;IAWrC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKjE,SAAS,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAIjC,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAIpC,mEAAmE;IACnE,MAAM,CAAC,GAAG,EAAE,oBAAoB,GAAG,IAAI;CAGxC"}

package/dist/http-server-channel.js

@@ -0,0 +1,38 @@
+/**
+ * `HttpServerChannel` — the backend `IAgentChannel` end (ticket §4). Holds the
+ * open SSE responses (down-stream) and fans `send()` out to them; `ingest()`
+ * feeds POSTed up-envelopes to the registered handlers. The Express channel
+ * routes (see `agent-routes.ts`) drive `addClient`/`removeClient`/`ingest`.
+ */
+export class HttpServerChannel {
+    constructor() {
+        this.clients = new Set();
+        this.handlers = new Set();
+    }
+    send(msg) {
+        const frame = `data: ${JSON.stringify(msg)}\n\n`;
+        for (const c of this.clients) {
+            try {
+                c.write(frame);
+            }
+            catch {
+                /* drop a broken client; close handler removes it */
+            }
+        }
+    }
+    onMessage(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    addClient(res) {
+        this.clients.add(res);
+    }
+    removeClient(res) {
+        this.clients.delete(res);
+    }
+    /** Called by the POST /channel route with a parsed up-envelope. */
+    ingest(msg) {
+        for (const h of [...this.handlers])
+            h(msg);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @hamak/ai-agent-backend — server-side pieces for the AI agent plugin.
+ *
+ * Hosted-model provider (Anthropic), durable file-backed memory, a hooks bus,
+ * and an Express agent-chat route. See `docs/README.md` and ticket §10 PR2.
+ */
+export { AnthropicProvider } from './anthropic-provider.js';
+export type { AnthropicProviderConfig } from './anthropic-provider.js';
+export { FileAgentMemory } from './file-agent-memory.js';
+export { createHooksBus } from './hooks-bus.js';
+export type { HooksBus } from './hooks-bus.js';
+export { createAgentRoutes } from './agent-routes.js';
+export type { AgentRoutesConfig } from './agent-routes.js';
+export { createAgentBackend } from './create-agent-backend.js';
+export type { AgentBackend, AgentBackendConfig } from './create-agent-backend.js';
+export { HttpServerChannel } from './http-server-channel.js';
+export type { SseWritable } from './http-server-channel.js';
+export { StdioMcpConnector, StdioMcpClient } from './stdio-mcp.js';
+export type { StdioMcpClientConfig } from './stdio-mcp.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":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @hamak/ai-agent-backend — server-side pieces for the AI agent plugin.
+ *
+ * Hosted-model provider (Anthropic), durable file-backed memory, a hooks bus,
+ * and an Express agent-chat route. See `docs/README.md` and ticket §10 PR2.
+ */
+export { AnthropicProvider } from './anthropic-provider.js';
+export { FileAgentMemory } from './file-agent-memory.js';
+export { createHooksBus } from './hooks-bus.js';
+export { createAgentRoutes } from './agent-routes.js';
+export { createAgentBackend } from './create-agent-backend.js';
+export { HttpServerChannel } from './http-server-channel.js';
+export { StdioMcpConnector, StdioMcpClient } from './stdio-mcp.js';

package/dist/stdio-mcp.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Real stdio MCP connector (ticket §11). Spawns the server subprocess and
+ * speaks newline-delimited JSON-RPC 2.0 over stdin/stdout — the MCP stdio wire
+ * format. No SDK dependency; `@modelcontextprotocol/sdk`'s `StdioClientTransport`
+ * is an equivalent drop-in behind the same `McpConnector` interface.
+ *
+ * stdio requires a process host, so this lives in the backend package.
+ */
+import type { McpServerConfig, McpToolDef } from '@hamak/ai-agent';
+import type { IMcpClient, McpConnector } from '@hamak/ai-agent/spi';
+export interface StdioMcpClientConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Per-request timeout. Default 10s. */
+    timeoutMs?: number;
+}
+export declare class StdioMcpClient implements IMcpClient {
+    private readonly proc;
+    private readonly pending;
+    private readonly clientInfo;
+    private readonly timeoutMs;
+    private rpcId;
+    private buffer;
+    private initialized;
+    private closed;
+    constructor(config: StdioMcpClientConfig);
+    private failAll;
+    private onData;
+    private rpc;
+    private ensureInitialized;
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, input: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** Connector for `transport: 'stdio'` MCP servers. */
+export declare class StdioMcpConnector implements McpConnector {
+    connect(id: string, config: McpServerConfig): Promise<IMcpClient>;
+}
+//# sourceMappingURL=stdio-mcp.d.ts.map

package/dist/stdio-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-mcp.d.ts","sourceRoot":"","sources":["../src/stdio-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIpE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,oBAAoB;IAgBxC,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,MAAM;IAuBd,OAAO,CAAC,GAAG;YAmBG,iBAAiB;IAWzB,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAYlC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B;AAED,sDAAsD;AACtD,qBAAa,iBAAkB,YAAW,YAAY;IAC9C,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;CAYxE"}

package/dist/stdio-mcp.js

@@ -0,0 +1,136 @@
+/**
+ * Real stdio MCP connector (ticket §11). Spawns the server subprocess and
+ * speaks newline-delimited JSON-RPC 2.0 over stdin/stdout — the MCP stdio wire
+ * format. No SDK dependency; `@modelcontextprotocol/sdk`'s `StdioClientTransport`
+ * is an equivalent drop-in behind the same `McpConnector` interface.
+ *
+ * stdio requires a process host, so this lives in the backend package.
+ */
+import { spawn } from 'node:child_process';
+const PROTOCOL_VERSION = '2024-11-05';
+export class StdioMcpClient {
+    constructor(config) {
+        this.pending = new Map();
+        this.rpcId = 0;
+        this.buffer = '';
+        this.initialized = false;
+        this.closed = false;
+        this.clientInfo = config.clientInfo ?? { name: '@hamak/ai-agent', version: '0' };
+        this.timeoutMs = config.timeoutMs ?? 10000;
+        this.proc = spawn(config.command, config.args ?? [], {
+            env: { ...process.env, ...config.env },
+            cwd: config.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.proc.stdout.setEncoding('utf8');
+        this.proc.stdout.on('data', (chunk) => this.onData(chunk));
+        this.proc.on('error', (err) => this.failAll(err));
+        this.proc.on('exit', () => {
+            if (!this.closed)
+                this.failAll(new Error('[mcp] server process exited'));
+        });
+    }
+    failAll(err) {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue; // ignore non-JSON (servers may log to stdout by mistake)
+            }
+            if (msg.id != null && this.pending.has(msg.id)) {
+                const p = this.pending.get(msg.id);
+                this.pending.delete(msg.id);
+                clearTimeout(p.timer);
+                if (msg.error)
+                    p.reject(new Error(`[mcp] ${msg.error.message ?? 'rpc error'}`));
+                else
+                    p.resolve(msg.result);
+            }
+        }
+    }
+    rpc(method, params, notification = false) {
+        const id = notification ? undefined : (this.rpcId += 1);
+        const payload = JSON.stringify({
+            jsonrpc: '2.0',
+            ...(notification ? {} : { id }),
+            method,
+            ...(params !== undefined ? { params } : {}),
+        });
+        this.proc.stdin.write(`${payload}\n`);
+        if (notification)
+            return Promise.resolve(undefined);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`[mcp] timeout waiting for ${method}`));
+            }, this.timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+    }
+    async ensureInitialized() {
+        if (this.initialized)
+            return;
+        await this.rpc('initialize', {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: this.clientInfo,
+        });
+        await this.rpc('notifications/initialized', undefined, true);
+        this.initialized = true;
+    }
+    async listTools() {
+        await this.ensureInitialized();
+        const result = await this.rpc('tools/list');
+        const tools = result?.tools ?? [];
+        return tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            readOnlyHint: t.annotations?.readOnlyHint,
+        }));
+    }
+    async callTool(name, input) {
+        await this.ensureInitialized();
+        return this.rpc('tools/call', { name, arguments: input ?? {} });
+    }
+    async close() {
+        this.closed = true;
+        try {
+            this.proc.stdin.end();
+        }
+        catch {
+            /* already closed */
+        }
+        this.proc.kill();
+    }
+}
+/** Connector for `transport: 'stdio'` MCP servers. */
+export class StdioMcpConnector {
+    async connect(id, config) {
+        if (config.definition.transport !== 'stdio') {
+            throw new Error(`[mcp] StdioMcpConnector only supports stdio transport (server "${id}")`);
+        }
+        return new StdioMcpClient({
+            command: config.definition.command,
+            args: config.definition.args,
+            env: config.definition.env,
+            cwd: config.definition.cwd,
+            timeoutMs: config.timeoutMs,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hamak/ai-agent-backend",
+  "version": "0.7.1",
+  "private": false,
+  "type": "module",
+  "description": "Backend for @hamak/ai-agent: hosted-model providers (Anthropic), durable memory, and an Express agent-chat route",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amah/app-framework.git",
+    "directory": "packages/ai-agent/backend/ai-agent-backend"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node ../../../../scripts/fix-esm-extensions.mjs ./dist",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@hamak/ai-agent": "*"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.17",
+    "@types/node": "^20.0.0",
+    "typescript": "~5.4.0",
+    "vitest": "^2.0.0"
+  }
+}