@nandansai08/personal-ai 0.8.0 → 0.9.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 PersonalAI Contributors
+Copyright (c) 2026 PersonalAI Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -37,6 +37,7 @@ See [docs/PROVIDERS.md](docs/PROVIDERS.md) for API key links, recommended models
 - **4 agent profiles** — `assistant`, `coder`, `researcher`, `tutor`; each overrides system prompt, model, and tool priority
 - **Persistent memory** — SQLite-backed long-term memory; facts, preferences, context, and episodic entries survive restarts
 - **6 built-in tools** — web search (Serper → Brave → DuckDuckGo), notes, tasks, calculator, file reader, memory save
+- **Plugin system** — drop a folder with `plugin.json` + `index.js` into `plugins/` to add tools and hooks; sandboxed, hot-reloadable, no build step ([docs](docs/PLUGINS.md))
 - **Streaming output** — token-by-token display with animated spinner and tool call progress indicators
 - **Hot-reload config** — edit `persona.yaml` or `profiles.yaml` while running; changes apply to the next message
 - **Observability** — every action emits typed events; daily log files at `~/.personal-ai/logs/`
@@ -404,9 +405,10 @@ Set `PORT=8080` in `.env` to change the port. `autoPort: true` in `.claude/launc
 | v0.6 | Done | Web UI — Express + WebSocket streaming chat in browser |
 | v0.7 | Done | Setup wizard, `/cost` tracking, model-pin for all providers, friendly errors, session save |
 | v0.8 | Done | Security hardening, semantic memory (local embeddings via Ollama), session save/load, npm packaging |
-| v0.9 | Planned | MCP support — connect any MCP server over stdio |
-| v1.0 | Planned | Plugin system — weather, GitHub, calendar plugins |
-| v1.1 | Planned | Voice — STT + TTS + wake word |
+| v0.9 | Done | Plugin system — local tools + hooks, sandboxed, hot-reload ([docs/PLUGINS.md](docs/PLUGINS.md)) |
+| v1.0 | Planned | MCP support — connect any MCP server over stdio |
+| v1.1 | Planned | Local document RAG — point the existing embeddings at your files |
+| v1.2 | Planned | Voice — STT + TTS + wake word |
 
 ---
 

package/dist/bootstrap.js

@@ -12,6 +12,7 @@ import { tasksTool } from './tools/tasks.js';
 import { calculatorTool } from './tools/calculator.js';
 import { fileReaderTool } from './tools/file-reader.js';
 import { createMemoryTool } from './tools/memory-tool.js';
+import { createPluginManager } from './plugins/manager.js';
 /** Load persona + profiles, initialise provider + tools. Never throws. */
 export async function createAppCore(configDir) {
     const persona = loadPersona(path.join(configDir, 'persona.yaml'));
@@ -29,7 +30,19 @@ export async function createAppCore(configDir) {
     // silently to keyword search if Ollama or the model is unavailable.
     memory.setEmbedder(createOllamaEmbedder());
     registerDefaultTools(memory);
-    return { ok: true, core: { provider, profileManager, memory, persona } };
+    // Plugins: local extensions (custom tools + hooks). MCP remains the path
+    // for external integrations. A failing plugin never blocks startup.
+    const plugins = createPluginManager(toolRegistry, path.join(configDir, '..'));
+    const loaded = await plugins.loadAll();
+    toolRegistry.setObserver(plugins.hooks);
+    memory.setOnStored(m => { void plugins.hooks.memoryStored(m); });
+    if (loaded > 0) {
+        for (const p of plugins.list().filter(r => r.status === 'healthy')) {
+            console.log(`✓ Plugin: ${p.manifest.name} loaded`);
+        }
+        console.log(`\n${loaded} plugin${loaded === 1 ? '' : 's'} active\n`);
+    }
+    return { ok: true, core: { provider, profileManager, memory, persona, plugins } };
 }
 function registerDefaultTools(memory) {
     toolRegistry.register(webSearchTool);

package/dist/core/assistant.js

@@ -31,6 +31,7 @@ export class AssistantEngine {
     profileManager;
     context;
     modelManager;
+    promptHooks;
     constructor(opts) {
         this.provider = opts.provider;
         this.getSystemPrompt = opts.getSystemPrompt;
@@ -39,6 +40,7 @@ export class AssistantEngine {
         this.profileManager = opts.profileManager;
         this.context = opts.context;
         this.modelManager = opts.modelManager;
+        this.promptHooks = opts.promptHooks;
     }
     async *chat(userMessage, options) {
         // Explicit memory intent ("remember …") — save the normalized fact and
@@ -77,7 +79,9 @@ export class AssistantEngine {
         const toolsSection = (this.registry && this.registry.count() > 0 && isGemma)
             ? this.registry.formatForPrompt()
             : '';
-        const systemPrompt = this.getSystemPrompt(memories, toolsSection);
+        let systemPrompt = this.getSystemPrompt(memories, toolsSection);
+        if (this.promptHooks)
+            systemPrompt = await this.promptHooks.beforePrompt(systemPrompt);
         const nativeTools = (this.registry && !isGemma && this.provider.supportsToolUse)
             ? this.registry.formatNative()
             : undefined;
@@ -125,8 +129,12 @@ export class AssistantEngine {
                 if (assistantText) {
                     // Strip XML tool-call blocks that some models output as text instead of function calls
                     const TOOL_XML_RE = /<(memory|web_search|notes|tasks|calculator|file_reader|tool)>[\s\S]*?(<\/\1>|<\/args>)/g;
-                    const cleanText = assistantText.replace(TOOL_XML_RE, '').trim();
-                    this.context?.addAssistant(cleanText || assistantText);
+                    let cleanText = assistantText.replace(TOOL_XML_RE, '').trim() || assistantText;
+                    // Plugin afterResponse transforms apply to the stored response;
+                    // streamed text has already been displayed.
+                    if (this.promptHooks)
+                        cleanText = await this.promptHooks.afterResponse(cleanText);
+                    this.context?.addAssistant(cleanText);
                     this._saveMemoryCandidates(userMessage);
                 }
                 if (doneChunk)

package/dist/index.js

@@ -10,7 +10,6 @@ import { watchPersona, watchProfiles } from './persona/loader.js';
 import { buildSystemPrompt, isGemma3Model } from './persona/system-prompt.js';
 import { startCLI } from './ui/cli.js';
 import { needsSetup, runSetupWizard } from './ui/setup.js';
-import { createWebServer, getServerUrl } from './ui/web/server.js';
 import { ModelManager, defaultModelsConfig } from './core/model-manager.js';
 import { eventBus } from './core/events.js';
 import { logger } from './core/logger.js';
@@ -31,6 +30,11 @@ function resolveEnvPath() {
     return path.join(os.homedir(), '.personal-ai', '.env');
 }
 async function main() {
+    if (process.argv.includes('--version') || process.argv.includes('-v')) {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+        console.log(`personal-ai v${pkg.version}`);
+        return;
+    }
     const envPath = resolveEnvPath();
     const { config } = await import('dotenv');
     config({ path: envPath });
@@ -45,7 +49,7 @@ async function main() {
         console.error(`Failed to initialize provider: ${boot.error}`);
         process.exit(1);
     }
-    const { provider, profileManager, memory, persona } = boot.core;
+    const { provider, profileManager, memory, persona, plugins } = boot.core;
     const context = new ConversationContext();
     let currentPersona = persona;
     // Hot-reload config files
@@ -58,12 +62,15 @@ async function main() {
     const engine = new AssistantEngine({
         provider, getSystemPrompt, memory,
         registry: toolRegistry, profileManager, context, modelManager,
+        promptHooks: plugins.hooks,
     });
+    void plugins.hooks.sessionStarted();
     process.on('SIGINT', () => {
         eventBus.emit('session_ended', {
             messageCount: context.messageCount,
             toolCallCount: context.getToolCallCount(),
         });
+        void plugins.hooks.sessionEnded();
         memory.close();
         console.log('\nBye.');
         process.exit(0);
@@ -72,6 +79,8 @@ async function main() {
     let webPort;
     let webToken;
     const startWebFn = async () => {
+        // Lazy import — keeps express/ws/cors out of CLI startup entirely
+        const { createWebServer, getServerUrl } = await import('./ui/web/server.js');
         if (!webServer) {
             const preferred = parseInt(process.env['PORT'] ?? '3000', 10);
             const result = await createWebServer({
@@ -80,6 +89,7 @@ async function main() {
                 profileManager,
                 registry: toolRegistry,
                 modelManager,
+                plugins,
                 personaPath: path.join(CONFIG, 'persona.yaml'),
                 port: preferred,
             });
@@ -93,6 +103,6 @@ async function main() {
         const { createProvider } = await import('./providers/factory.js');
         return createProvider();
     };
-    await startCLI(provider, engine, context, memory, profileManager, toolRegistry, modelManager, startWebFn, reloadProvider, envPath);
+    await startCLI(provider, engine, context, memory, profileManager, toolRegistry, modelManager, startWebFn, reloadProvider, envPath, plugins);
 }
 main().catch(err => { console.error(err); process.exit(1); });

package/dist/memory/long-term.js

@@ -33,6 +33,7 @@ export class LongTermMemory {
     db;
     vectors;
     embedder;
+    onStored;
     constructor(dbPath = DB_PATH) {
         if (!fs.existsSync(DB_DIR))
             fs.mkdirSync(DB_DIR, { recursive: true });
@@ -48,6 +49,10 @@ export class LongTermMemory {
     setEmbedder(embedder) {
         this.embedder = embedder;
     }
+    /** Observer invoked with the full Memory after each new save (plugin memoryStored hook). */
+    setOnStored(cb) {
+        this.onStored = cb;
+    }
     migrate() {
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS memories (
@@ -92,7 +97,9 @@ export class LongTermMemory {
         eventBus.emit('memory_saved', { type: input.type, importance });
         logger.debug('memory', `saved [${input.type}] importance=${importance}: ${input.content.slice(0, 60)}`);
         const row = this.db.prepare('SELECT * FROM memories WHERE id = ?').get(id);
-        return rowToMemory(row);
+        const saved = rowToMemory(row);
+        this.onStored?.(saved);
+        return saved;
     }
     /**
      * Tokenized LIKE search: splits the query into words and ranks rows by how

package/dist/plugins/hooks.js

@@ -0,0 +1,91 @@
+// MIT License — personal-ai
+// Hook runner: aggregates hooks across loaded plugins and runs them inside
+// the sandbox. A failing hook logs, bumps the plugin's failure count, and
+// the chain continues — plugins never break the assistant.
+import { sandboxed } from './sandbox.js';
+export class HookRunner {
+    entries = [];
+    register(record) {
+        if (record.plugin?.hooks)
+            this.entries.push({ record, hooks: record.plugin.hooks });
+    }
+    unregister(name) {
+        this.entries = this.entries.filter(e => e.record.manifest.name !== name);
+    }
+    count() {
+        return this.entries.length;
+    }
+    /** Chain: each plugin may transform the prompt; failures keep the previous value. */
+    async beforePrompt(prompt) {
+        let current = prompt;
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.beforePrompt)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'beforePrompt', () => hooks.beforePrompt(current));
+            if (r.ok && typeof r.value === 'string')
+                current = r.value;
+            else
+                record.failureCount++;
+        }
+        return current;
+    }
+    /** Chain: each plugin may transform the response; failures keep the previous value. */
+    async afterResponse(response) {
+        let current = response;
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.afterResponse)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'afterResponse', () => hooks.afterResponse(current));
+            if (r.ok && typeof r.value === 'string')
+                current = r.value;
+            else
+                record.failureCount++;
+        }
+        return current;
+    }
+    async beforeToolCall(toolName, args) {
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.beforeToolCall)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'beforeToolCall', () => hooks.beforeToolCall(toolName, args));
+            if (!r.ok)
+                record.failureCount++;
+        }
+    }
+    async afterToolCall(toolName, result) {
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.afterToolCall)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'afterToolCall', () => hooks.afterToolCall(toolName, result));
+            if (!r.ok)
+                record.failureCount++;
+        }
+    }
+    async memoryStored(memory) {
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.memoryStored)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'memoryStored', () => hooks.memoryStored(memory));
+            if (!r.ok)
+                record.failureCount++;
+        }
+    }
+    async sessionStarted() {
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.sessionStarted)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'sessionStarted', () => hooks.sessionStarted());
+            if (!r.ok)
+                record.failureCount++;
+        }
+    }
+    async sessionEnded() {
+        for (const { record, hooks } of this.entries) {
+            if (!hooks.sessionEnded)
+                continue;
+            const r = await sandboxed(record.manifest.name, 'sessionEnded', () => hooks.sessionEnded());
+            if (!r.ok)
+                record.failureCount++;
+        }
+    }
+}

package/dist/plugins/loader.js

@@ -1,3 +1,104 @@
 // MIT License — personal-ai
-// Stub — implemented in M8
-export {};
+// Plugin discovery: scan plugin directories, read + validate manifests,
+// import entry modules. Invalid plugins are rejected with a reason and
+// never crash startup.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { pathToFileURL } from 'node:url';
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const VERSION_RE = /^\d+\.\d+\.\d+/;
+/** Validate a parsed plugin.json object. */
+export function validateManifest(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return { ok: false, error: 'manifest is not an object' };
+    const m = raw;
+    if (typeof m['name'] !== 'string' || !NAME_RE.test(m['name'])) {
+        return { ok: false, error: `invalid name (kebab-case required): ${String(m['name'])}` };
+    }
+    if (typeof m['version'] !== 'string' || !VERSION_RE.test(m['version'])) {
+        return { ok: false, error: `invalid version (semver required): ${String(m['version'])}` };
+    }
+    if (typeof m['description'] !== 'string' || m['description'].length === 0) {
+        return { ok: false, error: 'description required' };
+    }
+    if (typeof m['main'] !== 'string' || !/\.(js|mjs|cjs)$/.test(m['main'])) {
+        return { ok: false, error: `main must point to a .js module: ${String(m['main'])}` };
+    }
+    if (m['main'].includes('..')) {
+        return { ok: false, error: 'main must not escape the plugin directory' };
+    }
+    if (typeof m['enabled'] !== 'boolean') {
+        return { ok: false, error: 'enabled must be a boolean' };
+    }
+    return {
+        ok: true,
+        manifest: {
+            name: m['name'], version: m['version'], description: m['description'],
+            main: m['main'], enabled: m['enabled'],
+        },
+    };
+}
+/** Directories scanned for plugins, in order. Override with PLUGINS_DIR. */
+export function pluginDirs(packageRoot) {
+    const override = process.env['PLUGINS_DIR'];
+    if (override)
+        return [path.resolve(override)];
+    return [
+        path.join(packageRoot, 'plugins'),
+        path.join(os.homedir(), '.personal-ai', 'plugins'),
+    ];
+}
+/** Scan plugin directories for subdirs containing plugin.json. */
+export function discoverPlugins(roots) {
+    const found = [];
+    const seen = new Set();
+    for (const root of roots) {
+        if (!fs.existsSync(root))
+            continue;
+        for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = path.join(root, entry.name);
+            const manifestPath = path.join(dir, 'plugin.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            let result;
+            try {
+                result = validateManifest(JSON.parse(fs.readFileSync(manifestPath, 'utf8')));
+            }
+            catch (err) {
+                result = { ok: false, error: `plugin.json parse error: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            // First occurrence of a name wins (package plugins shadow home-dir ones)
+            if (result.ok) {
+                if (seen.has(result.manifest.name))
+                    continue;
+                seen.add(result.manifest.name);
+            }
+            found.push({ dir, result });
+        }
+    }
+    return found;
+}
+/**
+ * Import a plugin's entry module. Accepts `export default plugin` or
+ * `export const plugin`. Returns an error string instead of throwing.
+ */
+export async function importPlugin(dir, manifest) {
+    const entry = path.resolve(dir, manifest.main);
+    if (!fs.existsSync(entry))
+        return { ok: false, error: `entry not found: ${manifest.main}` };
+    try {
+        // Cache-bust so reload() picks up edited plugin code
+        const mod = await import(`${pathToFileURL(entry).href}?t=${Date.now()}`);
+        const plugin = mod.default ?? mod.plugin;
+        if (!plugin || typeof plugin.name !== 'string') {
+            return { ok: false, error: 'module must export a PersonalAIPlugin as default or `plugin`' };
+        }
+        return { ok: true, plugin };
+    }
+    catch (err) {
+        return { ok: false, error: `import failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/dist/plugins/manager.js

@@ -0,0 +1,155 @@
+// MIT License — personal-ai
+// PluginManager — lifecycle orchestration. Discovers plugins, loads enabled
+// ones, registers their tools into the shared ToolRegistry and their hooks
+// into the HookRunner. A failing plugin is reported and skipped; the
+// assistant always keeps running.
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../core/logger.js';
+import { discoverPlugins, importPlugin, pluginDirs } from './loader.js';
+import { PluginRegistry } from './registry.js';
+import { HookRunner } from './hooks.js';
+import { sandboxed, LIFECYCLE_TIMEOUT_MS } from './sandbox.js';
+export class PluginManager {
+    toolRegistry;
+    roots;
+    registry = new PluginRegistry();
+    hooks = new HookRunner();
+    constructor(toolRegistry, roots) {
+        this.toolRegistry = toolRegistry;
+        this.roots = roots;
+    }
+    /** Discover and load every enabled plugin. Returns loaded count. */
+    async loadAll() {
+        let loaded = 0;
+        for (const { dir, result } of discoverPlugins(this.roots)) {
+            if (!result.ok) {
+                logger.warn('plugins', `rejected ${path.basename(dir)}: ${result.error}`);
+                continue;
+            }
+            const record = {
+                manifest: result.manifest, dir,
+                status: result.manifest.enabled ? 'failed' : 'disabled',
+                toolCount: 0, hookCount: 0, failureCount: 0,
+            };
+            this.registry.set(record);
+            if (!result.manifest.enabled)
+                continue;
+            if (await this.activate(record))
+                loaded++;
+        }
+        return loaded;
+    }
+    /** Load (or re-activate) one plugin by name. */
+    async load(name) {
+        const record = this.registry.get(name);
+        if (!record)
+            return undefined;
+        await this.activate(record);
+        return record;
+    }
+    /** Unload one plugin: shutdown, remove tools + hooks. */
+    async unload(name) {
+        const record = this.registry.get(name);
+        if (!record || !record.plugin)
+            return false;
+        if (record.plugin.shutdown) {
+            await sandboxed(name, 'shutdown', () => record.plugin.shutdown(), LIFECYCLE_TIMEOUT_MS);
+        }
+        for (const tool of record.plugin.tools ?? []) {
+            this.toolRegistry.unregister(tool.definition.name);
+        }
+        this.hooks.unregister(name);
+        record.plugin = undefined;
+        record.status = 'disabled';
+        record.toolCount = 0;
+        record.hookCount = 0;
+        return true;
+    }
+    /** Reload one plugin from disk (picks up code + manifest changes). */
+    async reload(name) {
+        const record = this.registry.get(name);
+        if (!record)
+            return undefined;
+        await this.unload(name);
+        // Re-read manifest in case enabled/version changed
+        try {
+            const manifestPath = path.join(record.dir, 'plugin.json');
+            const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            record.manifest = raw;
+        }
+        catch { /* keep previous manifest */ }
+        if (record.manifest.enabled)
+            await this.activate(record);
+        return record;
+    }
+    /** Enable/disable persists to plugin.json so the state survives restarts. */
+    async setEnabled(name, enabled) {
+        const record = this.registry.get(name);
+        if (!record)
+            return undefined;
+        record.manifest.enabled = enabled;
+        try {
+            fs.writeFileSync(path.join(record.dir, 'plugin.json'), JSON.stringify(record.manifest, null, 2) + '\n');
+        }
+        catch (err) {
+            logger.warn('plugins', `could not persist enabled state for ${name}: ${String(err)}`);
+        }
+        if (enabled)
+            await this.activate(record);
+        else
+            await this.unload(name);
+        return record;
+    }
+    list() {
+        return this.registry.list();
+    }
+    health() {
+        return this.registry.list().map(r => ({
+            name: r.manifest.name,
+            version: r.manifest.version,
+            status: r.failureCount > 0 && r.status === 'healthy' ? `healthy (${r.failureCount} hook failures)` : r.status,
+            tools: r.toolCount,
+            hooks: r.hookCount,
+            failures: r.failureCount,
+            ...(r.error ? { error: r.error } : {}),
+        }));
+    }
+    async activate(record) {
+        const start = Date.now();
+        const name = record.manifest.name;
+        const imported = await importPlugin(record.dir, record.manifest);
+        if (!imported.ok) {
+            record.status = 'failed';
+            record.error = imported.error;
+            logger.warn('plugins', `⚠ Plugin ${name} failed: ${imported.error}`);
+            return false;
+        }
+        const plugin = imported.plugin;
+        if (plugin.initialize) {
+            const init = await sandboxed(name, 'initialize', () => plugin.initialize(), LIFECYCLE_TIMEOUT_MS);
+            if (!init.ok) {
+                record.status = 'failed';
+                record.error = `initialize: ${init.error}`;
+                logger.warn('plugins', `⚠ Plugin ${name} failed: ${record.error}`);
+                return false;
+            }
+        }
+        for (const tool of plugin.tools ?? []) {
+            this.toolRegistry.register(tool);
+        }
+        record.plugin = plugin;
+        record.toolCount = plugin.tools?.length ?? 0;
+        record.hookCount = plugin.hooks ? Object.keys(plugin.hooks).length : 0;
+        record.status = 'healthy';
+        record.error = undefined;
+        record.loadMs = Date.now() - start;
+        this.hooks.register(record);
+        logger.debug('plugins', `loaded ${name} v${record.manifest.version} (${record.toolCount} tools, ${record.hookCount} hooks, ${record.loadMs}ms)`);
+        return true;
+    }
+}
+/** Construct a manager scanning the default plugin directories. */
+export function createPluginManager(toolRegistry, packageRoot) {
+    return new PluginManager(toolRegistry, pluginDirs(packageRoot));
+}

package/dist/plugins/registry.js

@@ -0,0 +1,25 @@
+// MIT License — personal-ai
+// Plugin record store — tracks every discovered plugin and its state.
+// Kept separate from the tool registry: tools are capabilities, plugin
+// records are lifecycle/health bookkeeping.
+export class PluginRegistry {
+    records = new Map();
+    set(record) {
+        this.records.set(record.manifest.name, record);
+    }
+    get(name) {
+        return this.records.get(name);
+    }
+    delete(name) {
+        return this.records.delete(name);
+    }
+    list() {
+        return [...this.records.values()];
+    }
+    byStatus(status) {
+        return this.list().filter(r => r.status === status);
+    }
+    count() {
+        return this.records.size;
+    }
+}

package/dist/plugins/sandbox.js

@@ -0,0 +1,31 @@
+// MIT License — personal-ai
+// Error boundary for plugin code: plugins must never crash PersonalAI.
+// Every plugin call is wrapped in a timeout and a catch; failures are
+// returned as values.
+import { logger } from '../core/logger.js';
+export const HOOK_TIMEOUT_MS = 2_000;
+export const LIFECYCLE_TIMEOUT_MS = 5_000;
+/**
+ * Run a plugin-supplied async function with a timeout and error boundary.
+ * Never throws. Timeouts and exceptions come back as `{ ok: false }`.
+ */
+export async function sandboxed(pluginName, what, fn, timeoutMs = HOOK_TIMEOUT_MS) {
+    let timer;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+            timer.unref?.();
+        });
+        const value = await Promise.race([fn(), timeout]);
+        return { ok: true, value };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logger.warn('plugins', `${pluginName}.${what} failed: ${error}`);
+        return { ok: false, error };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/plugins/types.js

@@ -0,0 +1,4 @@
+// MIT License — personal-ai
+// Plugin system types. Plugins extend PersonalAI locally (custom tools,
+// hooks); MCP remains the integration path for external services.
+export {};

package/dist/tools/registry.js

@@ -3,6 +3,11 @@ import { eventBus } from '../core/events.js';
 export class ToolRegistry {
     tools = new Map();
     confirmHandler;
+    observer;
+    /** Install a tool-call observer (plugin hooks). Failures inside it must be handled by the observer. */
+    setObserver(observer) {
+        this.observer = observer;
+    }
     /**
      * Install a confirmation handler for tools marked requiresConfirmation.
      * Without a handler such tools run unconfirmed (legacy behavior) — the CLI
@@ -15,6 +20,10 @@ export class ToolRegistry {
     register(tool) {
         this.tools.set(tool.definition.name, tool);
     }
+    /** Remove a tool (used when a plugin is unloaded). */
+    unregister(name) {
+        return this.tools.delete(name);
+    }
     /** Returns true if tool exists. */
     has(name) {
         return this.tools.has(name);
@@ -49,11 +58,15 @@ export class ToolRegistry {
                 return { success: false, data: null, error: `User denied ${name} call` };
             }
         }
+        if (this.observer)
+            await this.observer.beforeToolCall(name, args);
         try {
             const result = await tool.execute(args);
             const durationMs = Date.now() - start;
             eventBus.emit('tool_called', { name, args, durationMs });
             eventBus.emit('tool_result', { name, success: result.success, resultSize: JSON.stringify(result.data).length });
+            if (this.observer)
+                await this.observer.afterToolCall(name, result.data);
             return result;
         }
         catch (err) {

package/dist/ui/cli.js

@@ -3,6 +3,7 @@ import readline from 'node:readline';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { logger } from '../core/logger.js';
 import { eventBus } from '../core/events.js';
@@ -13,9 +14,19 @@ export { inferProvider, makeToolXmlStripper, patchEnvFile, friendlyError, create
 function modelEnvKeyFor(provider) {
     return PROVIDER_META[provider]?.modelEnvKey;
 }
+function readVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '';
+    }
+    catch {
+        return '';
+    }
+}
 const BANNER = `
 ${chalk.cyan('╔═══════════════════════════════════════╗')}
-${chalk.cyan('║')}  ${chalk.bold('PersonalAI')} ${chalk.dim('v0.7.0')}                   ${chalk.cyan('║')}
+${chalk.cyan('║')}  ${chalk.bold('PersonalAI')} ${chalk.dim(`v${readVersion()}`.padEnd(8))}                 ${chalk.cyan('║')}
 ${chalk.cyan('║')}  ${chalk.dim('Local-first. Any model.')}              ${chalk.cyan('║')}
 ${chalk.cyan('╚═══════════════════════════════════════╝')}
 `;
@@ -45,6 +56,10 @@ const HELP = `
   ${chalk.cyan('/research')}              Switch to researcher profile
   ${chalk.cyan('/tutor')}                 Switch to tutor profile
   ${chalk.cyan('/tools')}                 List registered tools
+  ${chalk.cyan('/plugins')}               List plugins and status
+  ${chalk.cyan('/plugins reload')} [name] Reload plugins from disk
+  ${chalk.cyan('/plugins enable')} <name> Enable a plugin (persists)
+  ${chalk.cyan('/plugins disable')} <name> Disable a plugin (persists)
   ${chalk.cyan('/save')} [name]           Save conversation to a named session
   ${chalk.cyan('/load')} [name]           Restore a saved session (no name = list)
   ${chalk.cyan('/cost')}                  Show session token usage and estimated cost
@@ -290,6 +305,51 @@ async function handleModelCmd(parts, modelManager, engine, providerName, envPath
     console.log(chalk.green(`✓ Pinned to ${modelManager.getCurrentModel()}`));
     return;
 }
+async function handlePluginsCmd(parts, plugins) {
+    const sub = parts[1]?.toLowerCase();
+    if (!sub || sub === 'list' || sub === 'health') {
+        const rows = plugins.health();
+        if (rows.length === 0) {
+            console.log(chalk.dim('No plugins installed. Drop one into plugins/ or ~/.personal-ai/plugins/.'));
+            return;
+        }
+        const nameW = Math.max(16, ...rows.map(r => r.name.length + 2));
+        console.log(chalk.bold(`\n${'Plugin'.padEnd(nameW)}Status`));
+        console.log(chalk.dim('-'.repeat(nameW + 24)));
+        for (const r of rows) {
+            const color = r.status.startsWith('healthy') ? chalk.green : r.status === 'disabled' ? chalk.dim : chalk.red;
+            console.log(`${r.name.padEnd(nameW)}${color(r.status)}${sub === 'health' ? chalk.dim(`  v${r.version}  tools:${r.tools} hooks:${r.hooks}${r.error ? `  ${r.error}` : ''}`) : ''}`);
+        }
+        console.log();
+        return;
+    }
+    if (sub === 'reload') {
+        const name = parts[2];
+        if (name) {
+            const r = await plugins.reload(name);
+            console.log(r ? chalk.green(`✓ Reloaded ${name} (${r.status})`) : chalk.yellow(`Plugin "${name}" not found`));
+        }
+        else {
+            for (const p of plugins.list())
+                await plugins.reload(p.manifest.name);
+            console.log(chalk.green(`✓ Reloaded ${plugins.list().length} plugin(s)`));
+        }
+        return;
+    }
+    if (sub === 'enable' || sub === 'disable') {
+        const name = parts[2];
+        if (!name) {
+            console.log(chalk.yellow(`Usage: /plugins ${sub} <name>`));
+            return;
+        }
+        const r = await plugins.setEnabled(name, sub === 'enable');
+        console.log(r
+            ? chalk.green(`✓ ${name} ${sub}d (${r.status})`)
+            : chalk.yellow(`Plugin "${name}" not found`));
+        return;
+    }
+    console.log(chalk.yellow('Usage: /plugins [list|health|reload [name]|enable <name>|disable <name>]'));
+}
 const SESSIONS_DIR = path.join(os.homedir(), '.personal-ai', 'sessions');
 function sessionPath(name) {
     const safe = name.replace(/[^\w-]/g, '_');
@@ -347,9 +407,16 @@ function handleLoadCmd(parts, context) {
         console.log(chalk.red(`Session "${name}" not found. Run /load to list.`));
     }
 }
-async function handleCommand(parts, provider, context, memory, profileManager, registry, modelManager, startWeb, getCost) {
+async function handleCommand(parts, provider, context, memory, profileManager, registry, modelManager, startWeb, getCost, plugins) {
     const cmd = parts[0]?.toLowerCase();
     switch (cmd) {
+        case '/plugins':
+            if (!plugins) {
+                console.log(chalk.yellow('Plugins not available.'));
+                break;
+            }
+            await handlePluginsCmd(parts, plugins);
+            break;
         case '/exit':
             console.log(chalk.dim('Goodbye.'));
             process.exit(0);
@@ -466,7 +533,7 @@ async function handleCommand(parts, provider, context, memory, profileManager, r
             console.log(chalk.yellow(`Unknown command: ${cmd}. Type /help.`));
     }
 }
-export async function startCLI(provider, engine, context, memory, profileManager, registry, modelManager, startWeb, reloadProvider, envPath) {
+export async function startCLI(provider, engine, context, memory, profileManager, registry, modelManager, startWeb, reloadProvider, envPath, plugins) {
     let activeProvider = provider;
     console.log(BANNER);
     if (activeProvider.healthCheck) {
@@ -577,7 +644,7 @@ export async function startCLI(provider, engine, context, memory, profileManager
             return;
         }
         if (input.startsWith('/')) {
-            await handleCommand(input.split(' '), activeProvider, context, memory, profileManager, registry, modelManager, startWeb, getCost);
+            await handleCommand(input.split(' '), activeProvider, context, memory, profileManager, registry, modelManager, startWeb, getCost, plugins);
             refreshPrompt();
             return;
         }

package/dist/ui/web/client/index.html

@@ -1149,12 +1149,29 @@ html, body { height: 100%; background: var(--bg); color: var(--text); font-famil
   }
   const AUTH_TOKEN = sessionStorage.getItem('pai_token') || '';
 
+  // Auth-failure banner: a bookmarked URL without ?token= means every API
+  // call 401s and panels silently stay empty — tell the user what to do.
+  let authBannerShown = false;
+  function showAuthBanner() {
+    if (authBannerShown) return;
+    authBannerShown = true;
+    const b = document.createElement('div');
+    b.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:9999;background:#7f1d1d;color:#fff;' +
+      'padding:10px 16px;font:13px system-ui;text-align:center';
+    b.textContent = 'Session token missing or expired. Restart PersonalAI (or run /web in the CLI) and open the printed URL — it contains your access token.';
+    document.body.prepend(b);
+  }
+
   const _fetch = window.fetch.bind(window);
   window.fetch = function(input, init) {
     const url = typeof input === 'string' ? input : input.url;
     if (url.startsWith('/api')) {
       init = init || {};
       init.headers = Object.assign({}, init.headers, { 'Authorization': 'Bearer ' + AUTH_TOKEN });
+      return _fetch(input, init).then(res => {
+        if (res.status === 401) showAuthBanner();
+        return res;
+      });
     }
     return _fetch(input, init);
   };

package/dist/ui/web/server.js

@@ -25,7 +25,7 @@ function findFreePort(start) {
     });
 }
 export async function createWebServer(opts) {
-    const { provider, memory, profileManager, registry, modelManager, personaPath } = opts;
+    const { provider, memory, profileManager, registry, modelManager, plugins, personaPath } = opts;
     const preferred = opts.port ?? parseInt(process.env['PORT'] ?? '3000', 10);
     const PORT = await findFreePort(preferred);
     // Security: per-session bearer token. Required on every /api request and WS
@@ -195,6 +195,10 @@ export async function createWebServer(opts) {
                 : [],
         });
     });
+    // Read-only plugin visibility (Settings → Plugins)
+    app.get('/api/plugins', (_req, res) => {
+        res.json(plugins ? plugins.health() : []);
+    });
     app.get('/api/system', (_req, res) => {
         const totalMem = os.totalmem();
         const freeMem = os.freemem();

package/dist/web.js

@@ -18,7 +18,7 @@ async function main() {
         console.error(`Failed to initialize provider: ${boot.error}`);
         process.exit(1);
     }
-    const { provider, profileManager, memory } = boot.core;
+    const { provider, profileManager, memory, plugins } = boot.core;
     watchProfiles(path.join(CONFIG, 'profiles.yaml'), p => profileManager.reload(p));
     // Web UI: two-model routing — qwen2.5:14b for tools/logic, gemma3:12b for chat/research/tutor
     const defaultModel = process.env['OLLAMA_MODEL'] ?? 'qwen2.5:14b';
@@ -47,6 +47,7 @@ async function main() {
         profileManager,
         registry: toolRegistry,
         modelManager,
+        plugins,
         personaPath: path.join(CONFIG, 'persona.yaml'),
         port: preferred,
     });

package/docs/PLUGINS.md

@@ -0,0 +1,130 @@
+# Plugin System
+
+Plugins extend PersonalAI **locally**: custom tools, prompt/response hooks,
+and lifecycle handlers — without modifying core code.
+
+**Plugins vs MCP:** plugins are for local custom extensions, community
+extensions, and user-defined tools. MCP (M9 roadmap) is for external
+integrations, remote tools, and third-party services. If your extension
+talks to an external service, build an MCP server instead.
+
+## Quick start
+
+```
+plugins/
+└── my-plugin/
+    ├── plugin.json
+    ├── index.js
+    └── README.md
+```
+
+Plugin directories are scanned from:
+1. `<package root>/plugins/`
+2. `~/.personal-ai/plugins/`
+3. `PLUGINS_DIR` env var (overrides both)
+
+`plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What it does",
+  "main": "./index.js",
+  "enabled": true
+}
+```
+
+All five fields are required. `name` must be kebab-case; `main` must be a
+`.js` ESM module inside the plugin directory. Invalid manifests are rejected
+with a logged reason and never crash startup.
+
+`index.js` (plain ESM JavaScript — no build step):
+
+```js
+/** @type {import('../../src/plugins/types.js').PersonalAIPlugin} */
+const plugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  description: 'What it does',
+
+  tools: [{
+    definition: {
+      name: 'my_tool',
+      description: 'What the model sees',
+      parameters: { type: 'object', properties: {} },
+    },
+    async execute(args) {
+      return { success: true, data: 'result' }
+    },
+  }],
+
+  hooks: {
+    async beforePrompt(prompt) { return prompt },
+    async afterResponse(response) { return response },
+    async beforeToolCall(name, args) {},
+    async afterToolCall(name, result) {},
+    async memoryStored(memory) {},
+    async sessionStarted() {},
+    async sessionEnded() {},
+  },
+
+  async initialize() {},
+  async shutdown() {},
+}
+
+export default plugin
+```
+
+## Lifecycle
+
+1. Startup scans plugin directories and validates each `plugin.json`.
+2. Enabled plugins are imported; `initialize()` runs (5 s timeout).
+3. Tools register into the shared tool registry — they appear in `/tools`
+   and are callable by the assistant immediately.
+4. Hooks register into the hook runner.
+5. On `/plugins disable <name>` or shutdown, `shutdown()` runs and the
+   plugin's tools/hooks are removed.
+
+## Hooks
+
+| Hook | When | Contract |
+|---|---|---|
+| `beforePrompt` | before each model call | return the (possibly modified) system prompt |
+| `afterResponse` | after the response completes | return the (possibly modified) text — applies to stored context; streamed text is already displayed |
+| `beforeToolCall` | before a tool executes | observe only |
+| `afterToolCall` | after a tool returns | observe only |
+| `memoryStored` | when a memory is saved | observe only |
+| `sessionStarted` / `sessionEnded` | CLI session boundaries | observe only |
+
+Hooks run inside a sandbox: **2-second timeout**, errors caught and logged.
+A failing hook keeps the previous value in transform chains and bumps the
+plugin's failure count (visible in `/plugins health`). Plugins can degrade —
+they can never take the assistant down.
+
+## CLI
+
+```
+/plugins                  list plugins and status
+/plugins health           status + versions, tool/hook counts, failures
+/plugins reload [name]    reload from disk (picks up code changes)
+/plugins enable <name>    enable + persist to plugin.json
+/plugins disable <name>   disable + persist to plugin.json
+```
+
+The web UI exposes the same data read-only at `GET /api/plugins`.
+
+## Best practices
+
+- One concern per plugin; keep tools small and return errors as values
+  (`{ success: false, error }`) — never throw.
+- Tools that touch the filesystem or network should set
+  `requiresConfirmation: true` so the CLI confirm gate applies.
+- Keep hooks fast — anything over 2 s is cut off.
+- Don't mutate the prompt destructively in `beforePrompt`; append.
+- Ship a README per plugin (see `plugins/hello-world/`).
+
+## Examples
+
+- `plugins/hello-world/` — tool + beforePrompt hook
+- `plugins/timestamp/` — minimal single-tool plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nandansai08/personal-ai",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Personal AI assistant — any model, local or cloud",
   "type": "module",
   "scripts": {
@@ -55,7 +55,9 @@
     "dist",
     "bin",
     "config",
-    ".env.example"
+    ".env.example",
+    "plugins",
+    "docs/PLUGINS.md"
   ],
   "repository": {
     "type": "git",
@@ -64,5 +66,18 @@
   "homepage": "https://github.com/Nandansai08/personal-ai#readme",
   "bugs": {
     "url": "https://github.com/Nandansai08/personal-ai/issues"
-  }
+  },
+  "keywords": [
+    "ai",
+    "assistant",
+    "local-first",
+    "ollama",
+    "llm",
+    "chatgpt",
+    "claude",
+    "cli",
+    "memory",
+    "semantic-search",
+    "privacy"
+  ]
 }

package/plugins/hello-world/README.md

@@ -0,0 +1,14 @@
+# hello-world
+
+Minimal example plugin. Registers one tool (`hello_world`) and one hook
+(`beforePrompt`) that appends a marker line to the system prompt.
+
+Use it as the template for your own plugins — see `docs/PLUGINS.md`.
+
+```
+> use the hello_world tool to greet Nandan
+  ⟳ hello_world… ✓
+Hello, Nandan — from the hello-world plugin!
+```
+
+Disable with `/plugins disable hello-world`.

package/plugins/hello-world/index.js

@@ -0,0 +1,37 @@
+// MIT License — personal-ai
+// Example plugin. Plain ESM JavaScript — no build step required.
+
+/** @type {import('../../src/plugins/types.js').PersonalAIPlugin} */
+const plugin = {
+  name: 'hello-world',
+  version: '1.0.0',
+  description: 'Example plugin — greeting tool and a beforePrompt hook',
+
+  tools: [
+    {
+      definition: {
+        name: 'hello_world',
+        description: 'Returns a greeting from the hello-world plugin.',
+        parameters: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'Who to greet (optional)' },
+          },
+        },
+      },
+      async execute(args) {
+        const who = (args && typeof args === 'object' && 'name' in args && args.name) || 'world'
+        return { success: true, data: `Hello, ${who} — from the hello-world plugin!` }
+      },
+    },
+  ],
+
+  hooks: {
+    // Demonstrates a prompt hook: appends one line to the system prompt.
+    async beforePrompt(prompt) {
+      return prompt + '\n(hello-world plugin is active)'
+    },
+  },
+}
+
+export default plugin

package/plugins/hello-world/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "hello-world",
+  "version": "1.0.0",
+  "description": "Example plugin — greeting tool and a beforePrompt hook",
+  "main": "./index.js",
+  "enabled": true
+}

package/plugins/timestamp/README.md

@@ -0,0 +1,4 @@
+# timestamp
+
+Registers `current_timestamp` — returns the current ISO 8601 timestamp.
+Useful as the smallest possible real plugin: one tool, no hooks.

package/plugins/timestamp/index.js

@@ -0,0 +1,24 @@
+// MIT License — personal-ai
+// Timestamp plugin — exposes the current time as a tool.
+
+/** @type {import('../../src/plugins/types.js').PersonalAIPlugin} */
+const plugin = {
+  name: 'timestamp',
+  version: '1.0.0',
+  description: 'Current ISO timestamp tool',
+
+  tools: [
+    {
+      definition: {
+        name: 'current_timestamp',
+        description: 'Returns the current date and time as an ISO 8601 string.',
+        parameters: { type: 'object', properties: {} },
+      },
+      async execute() {
+        return { success: true, data: new Date().toISOString() }
+      },
+    },
+  ],
+}
+
+export default plugin

package/plugins/timestamp/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "timestamp",
+  "version": "1.0.0",
+  "description": "Current ISO timestamp tool",
+  "main": "./index.js",
+  "enabled": true
+}

package/dist/plugins/interface.js

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

package/dist/voice/stt.js

@@ -1,3 +0,0 @@
-// MIT License — personal-ai
-// Stub — implemented in M11
-export {};

package/dist/voice/tts.js

@@ -1,3 +0,0 @@
-// MIT License — personal-ai
-// Stub — implemented in M11
-export {};