@nandansai08/personal-ai 0.8.0

package/dist/providers/ollama.js

@@ -0,0 +1,265 @@
+// MIT License — personal-ai
+import { eventBus } from '../core/events.js';
+import { logger } from '../core/logger.js';
+import { readStreamLines } from './utils.js';
+function parseOllamaError(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.error === 'string')
+            return parsed.error;
+    }
+    catch { /* not JSON, use raw */ }
+    return raw;
+}
+const NATIVE_TOOL_PREFIXES = [
+    'qwen2.5:', 'qwen2.5-coder:', 'llama3.1:', 'llama3.2:', 'mistral-nemo:', 'mistral:',
+];
+function isNativeToolModel(model) {
+    return NATIVE_TOOL_PREFIXES.some(p => model.startsWith(p));
+}
+function xmlToolInstructions(tools) {
+    const defs = tools
+        .map(t => `  ${t.name}: ${t.description}\n  params: ${JSON.stringify(t.parameters)}`)
+        .join('\n\n');
+    return [
+        'To call a tool output ONLY:',
+        '<tool>tool_name</tool>',
+        '<args>{"key": "value"}</args>',
+        '',
+        'Available tools:',
+        defs,
+    ].join('\n');
+}
+function* parseXmlChunks(content) {
+    const re = /<tool>([\s\S]*?)<\/tool>\s*<args>([\s\S]*?)<\/args>/g;
+    let last = 0;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        if (match.index > last)
+            yield { type: 'text', delta: content.slice(last, match.index) };
+        const name = (match[1] ?? '').trim();
+        const argsRaw = (match[2] ?? '').trim();
+        let args = {};
+        try {
+            args = JSON.parse(argsRaw);
+        }
+        catch {
+            args = { raw: argsRaw };
+        }
+        yield { type: 'tool_call', id: `xml_${Date.now()}`, name, arguments: args };
+        last = re.lastIndex;
+    }
+    if (last < content.length)
+        yield { type: 'text', delta: content.slice(last) };
+}
+function buildMessages(request, useXml) {
+    const messages = [];
+    if (request.systemPrompt) {
+        let sys = request.systemPrompt;
+        if (useXml && request.tools)
+            sys += '\n\n' + xmlToolInstructions(request.tools);
+        messages.push({ role: 'system', content: sys });
+    }
+    else if (useXml && request.tools) {
+        messages.push({ role: 'system', content: xmlToolInstructions(request.tools) });
+    }
+    for (const m of request.messages) {
+        messages.push({ role: m.role, content: m.content, ...(m.name ? { name: m.name } : {}) });
+    }
+    return messages;
+}
+function* processStreamChunk(chunk, useXml) {
+    const msg = chunk.message;
+    if (!msg)
+        return;
+    if (msg.tool_calls?.length) {
+        for (const tc of msg.tool_calls) {
+            const name = tc.function?.name ?? tc['name'] ?? '';
+            let args = tc.function?.arguments ?? {};
+            // Ollama sometimes returns arguments as a JSON string
+            if (typeof args === 'string') {
+                try {
+                    args = JSON.parse(args);
+                }
+                catch {
+                    args = { raw: args };
+                }
+            }
+            yield { type: 'tool_call', id: `tc_${Date.now()}`, name, arguments: args };
+        }
+    }
+    else if (msg.content) {
+        if (useXml) {
+            yield* parseXmlChunks(msg.content);
+        }
+        else {
+            yield { type: 'text', delta: msg.content };
+        }
+    }
+}
+async function* readNdjsonStream(body, useXml) {
+    for await (const line of readStreamLines(body)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.done) {
+            const d = parsed;
+            yield { usage: { input: d.prompt_eval_count ?? 0, output: d.eval_count ?? 0 } };
+        }
+        else {
+            yield* processStreamChunk(parsed, useXml);
+        }
+    }
+}
+export class OllamaProvider {
+    name = 'ollama';
+    supportsStreaming = true;
+    model;
+    supportsToolUse;
+    baseUrl;
+    defaultModel;
+    numCtx;
+    numPredict;
+    temperature;
+    constructor() {
+        this.baseUrl = process.env['OLLAMA_BASE_URL'] ?? 'http://localhost:11434';
+        this.defaultModel = process.env['OLLAMA_MODEL'] ?? 'qwen2.5:14b';
+        this.model = this.defaultModel;
+        // 8192 default: 2048 silently truncates the system prompt once history
+        // grows past a few messages. Lower via OLLAMA_NUM_CTX on RAM-tight machines.
+        this.numCtx = parseInt(process.env['OLLAMA_NUM_CTX'] ?? '8192', 10);
+        this.numPredict = parseInt(process.env['OLLAMA_NUM_PREDICT'] ?? '512', 10);
+        this.temperature = parseFloat(process.env['OLLAMA_TEMPERATURE'] ?? '0.7');
+        this.supportsToolUse = isNativeToolModel(this.model);
+    }
+    // fallow-ignore-next-line unused-class-member
+    setModel(model) {
+        this.model = model;
+        this.supportsToolUse = isNativeToolModel(model);
+    }
+    async *chat(request) {
+        const startMs = Date.now();
+        // request.model is authoritative — avoids mutating shared provider state
+        // when multiple sessions (CLI + web) use the same instance concurrently
+        const model = request.model ?? this.model;
+        const useNative = isNativeToolModel(model) && (request.tools?.length ?? 0) > 0;
+        const useXml = !useNative && (request.tools?.length ?? 0) > 0;
+        const body = {
+            model,
+            messages: buildMessages(request, useXml),
+            stream: true,
+            keep_alive: -1,
+            options: { num_ctx: this.numCtx, num_predict: this.numPredict, temperature: request.temperature ?? this.temperature },
+        };
+        if (useNative && request.tools) {
+            body['tools'] = request.tools.map(t => ({
+                type: 'function',
+                function: { name: t.name, description: t.description, parameters: t.parameters },
+            }));
+        }
+        let response;
+        try {
+            response = await fetch(`${this.baseUrl}/api/chat`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            yield { type: 'error', message: `Ollama connection failed: ${err instanceof Error ? err.message : String(err)}` };
+            return;
+        }
+        if (!response.ok) {
+            const errText = await response.text();
+            const errMsg = parseOllamaError(errText);
+            // Model not pulled — fall back to default and retry once
+            if (response.status === 404 && errText.includes('not found') && body['model'] !== this.defaultModel) {
+                const missing = String(body['model']);
+                logger.warn('ollama', `model "${missing}" not found, falling back to "${this.defaultModel}" (run: ollama pull ${missing})`);
+                yield { type: 'model_switch', from: missing, to: this.defaultModel };
+                body['model'] = this.defaultModel;
+                try {
+                    response = await fetch(`${this.baseUrl}/api/chat`, {
+                        method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+                    });
+                }
+                catch (err) {
+                    yield { type: 'error', message: `Ollama connection failed: ${err instanceof Error ? err.message : String(err)}` };
+                    return;
+                }
+                if (!response.ok) {
+                    yield { type: 'error', message: parseOllamaError(await response.text()) };
+                    return;
+                }
+            }
+            else {
+                yield { type: 'error', message: errMsg };
+                return;
+            }
+        }
+        if (!response.body) {
+            yield { type: 'error', message: 'No response body' };
+            return;
+        }
+        let usage;
+        for await (const item of readNdjsonStream(response.body, useXml)) {
+            if ('usage' in item) {
+                usage = item.usage;
+                continue;
+            }
+            yield item;
+        }
+        const latencyMs = Date.now() - startMs;
+        eventBus.emit('provider_latency', { provider: 'ollama', model: String(body['model']), latencyMs });
+        if (usage)
+            eventBus.emit('tokens_used', { input: usage.input, output: usage.output, provider: 'ollama' });
+        yield { type: 'done', usage };
+    }
+    async healthCheck() {
+        const start = Date.now();
+        try {
+            const res = await fetch(`${this.baseUrl}/api/tags`);
+            const latencyMs = Date.now() - start;
+            if (!res.ok)
+                return { ok: false, latencyMs, model: this.model, error: `HTTP ${res.status}` };
+            eventBus.emit('session_started', { provider: 'ollama', model: this.model });
+            return { ok: true, latencyMs, model: this.model };
+        }
+        catch (err) {
+            return { ok: false, latencyMs: Date.now() - start, model: this.model, error: String(err) };
+        }
+    }
+    async warmUp(model) {
+        const target = model ?? this.model;
+        try {
+            await fetch(`${this.baseUrl}/api/generate`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model: target, prompt: '', keep_alive: -1 }),
+            });
+            logger.debug('ollama', `warmed up ${target}`);
+        }
+        catch { /* non-fatal */ }
+    }
+    async listModels() {
+        try {
+            const res = await fetch(`${this.baseUrl}/api/tags`);
+            if (!res.ok)
+                return [];
+            const data = await res.json();
+            return (data.models ?? []).map(m => ({
+                id: m.name, name: m.name, supportsTools: isNativeToolModel(m.name),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/providers/openai-compatible.js

@@ -0,0 +1,110 @@
+// MIT License — personal-ai
+import OpenAI from 'openai';
+import { eventBus } from '../core/events.js';
+import { logger } from '../core/logger.js';
+import { buildOAIMessages, flushToolCalls, runHealthCheck } from './utils.js';
+function toOAITools(tools) {
+    return tools.map(t => ({
+        type: 'function',
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+    }));
+}
+function processOAIChunk(chunk, toolNames, toolArgs) {
+    const choice = chunk.choices[0];
+    const yields = [];
+    if (!choice)
+        return { yields };
+    const delta = choice.delta;
+    if (delta.content)
+        yields.push({ type: 'text', delta: delta.content });
+    for (const tc of delta.tool_calls ?? []) {
+        const idx = String(tc.index);
+        if (tc.function?.name)
+            toolNames[idx] = (toolNames[idx] ?? '') + tc.function.name;
+        if (tc.function?.arguments)
+            toolArgs[idx] = (toolArgs[idx] ?? '') + tc.function.arguments;
+    }
+    if (choice.finish_reason === 'tool_calls')
+        yields.push(...flushToolCalls(toolNames, toolArgs, 'tc'));
+    return {
+        yields,
+        inputTokens: chunk.usage?.prompt_tokens,
+        outputTokens: chunk.usage?.completion_tokens,
+    };
+}
+/**
+ * Abstract base for all OpenAI-compatible providers (OpenAI, Groq, LMStudio, Together).
+ * Subclasses set name, baseURL, defaultModel, supportsToolUse.
+ */
+export class OpenAICompatibleProvider {
+    supportsStreaming = true;
+    model;
+    client;
+    temperature;
+    constructor(apiKey, baseURL, model, temperature = 0.7) {
+        this.model = model;
+        this.temperature = temperature;
+        this.client = new OpenAI({ apiKey, baseURL });
+    }
+    async *chat(request) {
+        const startMs = Date.now();
+        const messages = buildOAIMessages(request.messages, request.systemPrompt);
+        const params = {
+            model: request.model ?? this.model,
+            messages,
+            temperature: request.temperature ?? this.temperature,
+            stream: true,
+        };
+        if (request.tools?.length && this.supportsToolUse) {
+            params.tools = toOAITools(request.tools);
+        }
+        if (request.maxTokens)
+            params.max_tokens = request.maxTokens;
+        let stream;
+        try {
+            stream = await this.client.chat.completions.create(params);
+        }
+        catch (err) {
+            yield { type: 'error', message: `${this.name} request failed: ${String(err)}` };
+            return;
+        }
+        let inputTokens = 0;
+        let outputTokens = 0;
+        const toolArgs = {};
+        const toolNames = {};
+        try {
+            for await (const chunk of stream) {
+                const result = processOAIChunk(chunk, toolNames, toolArgs);
+                for (const c of result.yields)
+                    yield c;
+                if (result.inputTokens !== undefined)
+                    inputTokens = result.inputTokens;
+                if (result.outputTokens !== undefined)
+                    outputTokens = result.outputTokens;
+            }
+        }
+        catch (err) {
+            yield { type: 'error', message: `${this.name} stream error: ${String(err)}` };
+            return;
+        }
+        const latencyMs = Date.now() - startMs;
+        eventBus.emit('provider_latency', { provider: this.name, model: this.model, latencyMs });
+        if (inputTokens || outputTokens) {
+            eventBus.emit('tokens_used', { input: inputTokens, output: outputTokens, provider: this.name });
+        }
+        logger.debug(this.name, `done in ${latencyMs}ms`);
+        yield { type: 'done', usage: { input: inputTokens, output: outputTokens } };
+    }
+    async healthCheck() {
+        return runHealthCheck(this.model, () => this.client.models.list().then(() => undefined));
+    }
+    async listModels() {
+        try {
+            const res = await this.client.models.list();
+            return res.data.map(m => ({ id: m.id, name: m.id }));
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/providers/openai.js

@@ -0,0 +1,14 @@
+// MIT License — personal-ai
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// fallow-ignore-next-line unused-export
+export class OpenAIProvider extends OpenAICompatibleProvider {
+    name = 'openai';
+    supportsToolUse = true;
+    constructor() {
+        const key = process.env['OPENAI_API_KEY'] ?? '';
+        const base = process.env['OPENAI_BASE_URL'];
+        const model = process.env['OPENAI_MODEL'] ?? 'gpt-4o-mini';
+        const temp = parseFloat(process.env['OPENAI_TEMPERATURE'] ?? '0.7');
+        super(key, base, model, temp);
+    }
+}

package/dist/providers/together.js

@@ -0,0 +1,14 @@
+// MIT License — personal-ai
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+const TOGETHER_BASE_URL = 'https://api.together.xyz/v1';
+// fallow-ignore-next-line unused-export
+export class TogetherProvider extends OpenAICompatibleProvider {
+    name = 'together';
+    supportsToolUse = false;
+    constructor() {
+        const key = process.env['TOGETHER_API_KEY'] ?? '';
+        const model = process.env['TOGETHER_MODEL'] ?? 'meta-llama/Llama-3.3-70B-Instruct-Turbo';
+        const temp = parseFloat(process.env['TOGETHER_TEMPERATURE'] ?? '0.7');
+        super(key, TOGETHER_BASE_URL, model, temp);
+    }
+}

package/dist/providers/utils.js

@@ -0,0 +1,57 @@
+/** Convert internal Message[] to OpenAI-compatible message array. */
+export function buildOAIMessages(messages, systemPrompt) {
+    const out = [];
+    if (systemPrompt)
+        out.push({ role: 'system', content: systemPrompt });
+    for (const m of messages) {
+        if (m.role === 'system')
+            continue;
+        out.push({
+            role: m.role,
+            content: m.content,
+            ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
+        });
+    }
+    return out;
+}
+/** Yield each newline-delimited text line from a ReadableStream. */
+export async function* readStreamLines(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+        for (const line of lines)
+            yield line;
+    }
+}
+/** Wrap a provider health-check probe in the standard start/try/catch/return envelope. */
+export async function runHealthCheck(model, probe) {
+    const start = Date.now();
+    try {
+        await probe();
+        return { ok: true, latencyMs: Date.now() - start, model };
+    }
+    catch (err) {
+        return { ok: false, latencyMs: Date.now() - start, model, error: String(err) };
+    }
+}
+/** Flush accumulated streaming tool-call chunks into ChatChunk events. */
+export function flushToolCalls(toolNames, toolArgs, idPrefix) {
+    return Object.entries(toolNames).map(([idx, name]) => {
+        const argsRaw = toolArgs[idx] ?? '{}';
+        let args = {};
+        try {
+            args = JSON.parse(argsRaw);
+        }
+        catch {
+            args = { raw: argsRaw };
+        }
+        return { type: 'tool_call', id: `${idPrefix}_${idx}_${Date.now()}`, name, arguments: args };
+    });
+}

package/dist/tools/calculator.js

@@ -0,0 +1,44 @@
+// MIT License — personal-ai
+const ALLOWED = /^[\d\s+\-*/%.()e,Ee]+$/;
+/**
+ * Safe expression evaluator. Only allows numeric chars + basic operators.
+ * No eval of arbitrary code.
+ */
+function safeEval(expr) {
+    const cleaned = expr.replace(/\s/g, '');
+    if (!ALLOWED.test(cleaned)) {
+        throw new Error(`Invalid characters in expression: ${expr}`);
+    }
+    // Use Function constructor with numeric-only whitelist validated above
+    const result = new Function(`"use strict"; return (${cleaned})`)();
+    if (typeof result !== 'number' || !isFinite(result)) {
+        throw new Error(`Expression did not evaluate to a finite number: ${expr}`);
+    }
+    return result;
+}
+export const calculatorTool = {
+    definition: {
+        name: 'calculator',
+        description: 'Evaluate math expression.',
+        parameters: {
+            type: 'object',
+            properties: {
+                expression: { type: 'string', description: 'e.g. "(2+3)*4"' },
+            },
+            required: ['expression'],
+        },
+    },
+    async execute(args) {
+        const a = args;
+        const expression = String(a['expression'] ?? '').trim();
+        if (!expression)
+            return { success: false, data: null, error: 'expression required' };
+        try {
+            const result = safeEval(expression);
+            return { success: true, data: { expression, result } };
+        }
+        catch (err) {
+            return { success: false, data: null, error: String(err) };
+        }
+    },
+};

package/dist/tools/file-reader.js

@@ -0,0 +1,101 @@
+// MIT License — personal-ai
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const MAX_BYTES = 100_000; // 100 KB read limit
+// Security: filenames that must never be readable by the model, regardless of
+// location — credentials, keys, and shell history are prime prompt-injection
+// exfiltration targets.
+const DENIED_NAMES = /^(\.env(\..*)?|id_rsa.*|id_ed25519.*|id_ecdsa.*|.*\.pem|.*\.key|credentials(\..*)?|\.netrc|\.npmrc|\.bash_history|\.zsh_history)$/i;
+const DENIED_DIRS = ['.ssh', '.gnupg', '.aws', '.azure', '.kube', '.docker'];
+/** Resolve path, expanding ~. */
+function resolveSafe(filePath) {
+    return path.resolve(filePath.startsWith('~')
+        ? filePath.replace('~', os.homedir())
+        : filePath);
+}
+/**
+ * Security gate: deny sensitive files and directories. Allow-list roots are
+ * configurable via FILE_READER_ROOTS (comma-separated); defaults to home dir
+ * and current working directory.
+ */
+function checkAccess(resolved) {
+    const base = path.basename(resolved);
+    if (DENIED_NAMES.test(base)) {
+        return `Access denied: ${base} may contain credentials`;
+    }
+    const segments = resolved.split(/[\\/]/);
+    for (const dir of DENIED_DIRS) {
+        if (segments.includes(dir))
+            return `Access denied: ${dir} directory is protected`;
+    }
+    const rootsEnv = process.env['FILE_READER_ROOTS'];
+    const roots = rootsEnv
+        ? rootsEnv.split(',').map(r => path.resolve(r.trim()))
+        : [os.homedir(), process.cwd()];
+    const inRoot = roots.some(root => {
+        const rel = path.relative(root, resolved);
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    });
+    if (!inRoot) {
+        return `Access denied: path outside allowed roots (${roots.join(', ')}). Set FILE_READER_ROOTS in .env to extend.`;
+    }
+    return null;
+}
+export const fileReaderTool = {
+    requiresConfirmation: true,
+    definition: {
+        name: 'file_reader',
+        description: 'Read local text file, max 100KB.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path (absolute or ~)' },
+                encoding: { type: 'string', description: 'File encoding (default utf-8)' },
+                lines: { type: 'number', description: 'Max lines to read (default: all)' },
+            },
+            required: ['path'],
+        },
+    },
+    async execute(args) {
+        const a = args;
+        const filePath = String(a['path'] ?? '').trim();
+        if (!filePath)
+            return { success: false, data: null, error: 'path required' };
+        const resolved = resolveSafe(filePath);
+        const denied = checkAccess(resolved);
+        if (denied)
+            return { success: false, data: null, error: denied };
+        if (!fs.existsSync(resolved)) {
+            return { success: false, data: null, error: `File not found: ${resolved}` };
+        }
+        // Re-check the real path — a symlink inside an allowed root must not
+        // escape to a denied location.
+        const real = fs.realpathSync(resolved);
+        if (real !== resolved) {
+            const deniedReal = checkAccess(real);
+            if (deniedReal)
+                return { success: false, data: null, error: deniedReal };
+        }
+        const stat = fs.statSync(resolved);
+        if (!stat.isFile()) {
+            return { success: false, data: null, error: `Not a file: ${resolved}` };
+        }
+        if (stat.size > MAX_BYTES) {
+            return { success: false, data: null, error: `File too large (${stat.size} bytes, max ${MAX_BYTES})` };
+        }
+        try {
+            const encoding = a['encoding'] ?? 'utf-8';
+            const raw = fs.readFileSync(resolved, encoding);
+            const maxLines = a['lines'] ? Number(a['lines']) : undefined;
+            const content = maxLines ? raw.split('\n').slice(0, maxLines).join('\n') : raw;
+            return {
+                success: true,
+                data: { path: resolved, size: stat.size, content },
+            };
+        }
+        catch (err) {
+            return { success: false, data: null, error: `Read error: ${String(err)}` };
+        }
+    },
+};

package/dist/tools/memory-tool.js

@@ -0,0 +1,58 @@
+// MIT License — personal-ai
+/**
+ * Creates the memory tool bound to a LongTermMemory instance.
+ * Kept as a factory so the tool shares the same DB connection as the assistant.
+ */
+export function createMemoryTool(memory) {
+    return {
+        definition: {
+            name: 'memory',
+            description: 'Save, search, or retrieve memories about the user. Use to remember important facts, preferences, and context.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    action: { type: 'string', description: 'save | search | list | stats', enum: ['save', 'search', 'list', 'stats'] },
+                    content: { type: 'string', description: 'Memory content (for save)' },
+                    type: { type: 'string', description: 'fact | preference | context | episodic | education | career | project | personal', enum: ['fact', 'preference', 'context', 'episodic', 'education', 'career', 'project', 'personal'] },
+                    query: { type: 'string', description: 'Search query (for search)' },
+                    limit: { type: 'number', description: 'Max results (for search/list, default 8)' },
+                    importance: { type: 'number', description: 'Importance 1-10 (for save, default 5)' },
+                },
+                required: ['action'],
+            },
+        },
+        async execute(args) {
+            const a = args;
+            const action = String(a['action'] ?? '').trim();
+            switch (action) {
+                case 'save': {
+                    const content = String(a['content'] ?? '').trim();
+                    if (!content)
+                        return { success: false, data: null, error: 'content required' };
+                    const type = a['type'] ?? 'fact';
+                    const importance = Math.min(10, Math.max(1, Number(a['importance'] ?? 5)));
+                    const saved = memory.save({ content, type, importance });
+                    return { success: true, data: saved };
+                }
+                case 'search': {
+                    const query = String(a['query'] ?? '').trim();
+                    if (!query)
+                        return { success: false, data: null, error: 'query required' };
+                    const limit = Number(a['limit'] ?? 8);
+                    const results = memory.search(query, limit);
+                    return { success: true, data: results };
+                }
+                case 'list': {
+                    const limit = Number(a['limit'] ?? 10);
+                    const results = memory.getRecent(limit);
+                    return { success: true, data: results };
+                }
+                case 'stats': {
+                    return { success: true, data: memory.getStats() };
+                }
+                default:
+                    return { success: false, data: null, error: `Unknown action: ${action}` };
+            }
+        },
+    };
+}