@bahulam/code 0.1.16 → 0.1.17

package/src/plugins/manifest.mjs

@@ -27,6 +27,37 @@ function normalizeToolNames(value) {
   }).filter(Boolean);
 }
 
+function normalizePathList(value) {
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  if (Array.isArray(value)) {
+    return value.map(item => String(item || '').trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function addAgent(agents, seen, agent) {
+  if (!agent?.slug) return;
+  const key = String(agent.slug).trim().toLowerCase();
+  if (!key || seen.has(key)) return;
+  seen.add(key);
+  agents.push(agent);
+}
+
+function normalizeViews(value) {
+  return Array.isArray(value) ? value.filter(view => view && typeof view === 'object') : [];
+}
+
+function normalizeWorkspaceDeclaration(value) {
+  if (typeof value === 'string' && value.trim()) {
+    return { agentPath: value.trim(), views: [] };
+  }
+  if (value && typeof value === 'object') {
+    const agentPath = String(value.agent || value.file || value.source || '').trim();
+    return { agentPath, views: normalizeViews(value.views) };
+  }
+  return { agentPath: '', views: [] };
+}
+
 function loadAgentFile(agentDef, pluginDir) {
   const file = String(agentDef.file || agentDef.handler || '').trim();
   if (!file || !pluginDir) return {};
@@ -45,21 +76,36 @@ function loadAgentFile(agentDef, pluginDir) {
 }
 
 function normalizeAgentDef(agentDef, pluginName, pluginDir) {
-  const fileConfig = loadAgentFile(agentDef, pluginDir);
+  const loadedConfig = loadAgentFile(agentDef, pluginDir);
+  const hasLoadedConfig = loadedConfig && Object.keys(loadedConfig).length > 0;
+  const fileConfig = hasLoadedConfig ? loadedConfig : (agentDef || {});
   const metadata = fileConfig.metadata || fileConfig.meta || {};
-  const agent = fileConfig.agent || fileConfig.spec?.agent || {};
+  const agent = fileConfig.agent || fileConfig.config?.agent || {};
   const fileTools = (
     fileConfig.tools
-    || fileConfig.spec?.tools
+    || fileConfig.config?.tools
     || agent.tools
     || []
   );
   const inlineTools = normalizeToolNames(agentDef.tools);
+  const slug = (
+    agentDef.slug
+    || metadata.slug
+    || fileConfig.slug
+    || agent.slug
+    || agentDef.id
+    || metadata.name
+    || fileConfig.name
+    || agentDef.name
+    || metadata.role
+    || fileConfig.role
+    || ''
+  );
 
   return {
-    slug: agentDef.slug || metadata.slug || fileConfig.slug || metadata.name || fileConfig.name || agentDef.name || '',
-    name: agentDef.name || metadata.name || fileConfig.name || agentDef.slug || '',
-    description: agentDef.description || metadata.description || fileConfig.description || '',
+    slug,
+    name: agentDef.name || metadata.name || fileConfig.name || agent.name || slug || '',
+    description: agentDef.description || metadata.description || fileConfig.description || agent.description || '',
     role: agentDef.role || metadata.role || fileConfig.role || 'specialist',
     system_prompt: (
       agentDef.system_prompt
@@ -77,12 +123,39 @@ function normalizeAgentDef(agentDef, pluginName, pluginDir) {
     models: agentDef.models || agent.models || fileConfig.models || undefined,
     max_tokens: agentDef.max_tokens || agent.max_tokens || fileConfig.max_tokens || undefined,
     max_iterations: agentDef.max_iterations || agent.max_iterations || fileConfig.max_iterations || undefined,
+    disallowed_tools: metadata.disallowedTools || metadata.disallowed_tools || fileConfig.disallowedTools || fileConfig.disallowed_tools || [],
+    can_delegate: agentDef.can_delegate ?? agent.can_delegate ?? fileConfig.can_delegate ?? false,
+    can_be_delegated_to: agentDef.can_be_delegated_to ?? agent.can_be_delegated_to ?? fileConfig.can_be_delegated_to ?? true,
+    apiVersion: fileConfig.apiVersion || fileConfig.api_version || undefined,
+    kind: fileConfig.kind || undefined,
     file: agentDef.file || agentDef.handler || '',
     source: `plugin:${pluginName}`,
     source_scope: 'plugin',
   };
 }
 
+function loadAgentPath(agentPath, pluginDir, pluginName, label) {
+  if (!agentPath || !pluginDir) return null;
+  const fullPath = path.resolve(pluginDir, agentPath);
+  try {
+    if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) return null;
+    const agentDef = parseYaml(fs.readFileSync(fullPath, 'utf-8'));
+    if (!agentDef || typeof agentDef !== 'object') {
+      console.warn(`Skipping ${label} ${fullPath}: not a mapping`);
+      return null;
+    }
+    const agent = normalizeAgentDef(agentDef, pluginName, pluginDir);
+    if (!agent.slug) {
+      console.warn(`Skipping ${label} ${fullPath}: no slug`);
+      return null;
+    }
+    return agent;
+  } catch (err) {
+    console.warn(`Failed to load ${label} ${fullPath}: ${err.message}`);
+    return null;
+  }
+}
+
 /**
  * Parse a plugin manifest from YAML text.
  * @param {string} yamlText - Raw YAML content
@@ -141,8 +214,8 @@ export function normalizeManifest(raw, source = '') {
   }
 
   const meta = raw.metadata || raw.meta || {};
-  const spec = raw.spec || raw.plugin || {};
-  const name = meta.name || spec.name || '';
+  const config = raw.config || raw.plugin || {};
+  const name = meta.name || config.name || '';
   if (!name) {
     if (process.env.DEBUG) {
       console.warn(`Plugin manifest missing name: ${source}`);
@@ -152,15 +225,62 @@ export function normalizeManifest(raw, source = '') {
 
   // Normalize agents
   const agents = [];
+  const agentSlugs = new Set();
   const pluginDir = source ? path.dirname(source) : '';
-  for (const agentDef of (spec.agents || [])) {
-    const agent = normalizeAgentDef(agentDef, name, pluginDir);
-    if (agent.slug) agents.push(agent);
+  for (const agentDef of (config.agents || [])) {
+    addAgent(agents, agentSlugs, normalizeAgentDef(agentDef, name, pluginDir));
+  }
+  const workspaceDecl = normalizeWorkspaceDeclaration(config.workspace);
+  if (workspaceDecl.agentPath) {
+    const workspaceAgent = loadAgentPath(workspaceDecl.agentPath, pluginDir, name, 'workspace');
+    if (workspaceAgent) {
+      workspaceAgent.entry_agent = true;
+      addAgent(agents, agentSlugs, workspaceAgent);
+    }
+  }
+  // Optional authoring convenience: `config.agents_from: <dir|string[]>`.
+  // This is for delegated sub-agents. The primary/entry agent should
+  // live at `config.workspace: ./config/workspace.yaml`.
+  const agentsFrom = normalizePathList(config.agents_from);
+  for (const agentsFromPath of agentsFrom) {
+    if (!pluginDir) continue;
+    const agentsDir = path.resolve(pluginDir, agentsFromPath);
+    try {
+      if (fs.existsSync(agentsDir) && fs.statSync(agentsDir).isDirectory()) {
+        const files = fs.readdirSync(agentsDir)
+          .filter(f => /\.(ya?ml)$/i.test(f))
+          .sort();
+        for (const f of files) {
+          const filePath = path.join(agentsDir, f);
+          let agentDef;
+          try {
+            agentDef = parseYaml(fs.readFileSync(filePath, 'utf-8'));
+          } catch (err) {
+            console.warn(`Failed to parse plugin agent file ${filePath}: ${err.message}`);
+            continue;
+          }
+          if (!agentDef || typeof agentDef !== 'object') {
+            console.warn(`Skipping plugin agent file ${filePath}: not a mapping`);
+            continue;
+          }
+          const agent = normalizeAgentDef(agentDef, name, pluginDir);
+          if (!agent.slug) {
+            console.warn(`Skipping plugin agent file ${filePath}: no slug`);
+            continue;
+          }
+          addAgent(agents, agentSlugs, agent);
+        }
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Failed to load agents_from ${agentsDir}: ${err.message}`);
+      }
+    }
   }
 
   // Normalize tools
   const tools = [];
-  for (const toolDef of (spec.tools || [])) {
+  for (const toolDef of (config.tools || [])) {
     const tool = {
       name: toolDef.name || '',
       description: toolDef.description || '',
@@ -171,11 +291,12 @@ export function normalizeManifest(raw, source = '') {
     if (tool.name) tools.push(tool);
   }
 
-  // Normalize workspace
-  const workspace = spec.workspace || {};
-  if (workspace.views && !Array.isArray(workspace.views)) {
-    workspace.views = [];
-  }
+  // Normalize browser workspace views. New manifests use `config.views`.
+  // Older installed manifests with `config.workspace.views` still render.
+  const views = [
+    ...workspaceDecl.views,
+    ...normalizeViews(config.views),
+  ];
 
   // Normalize MCP servers — the Plugin=MCP+UX story. Two sources are
   // merged so authors can either:
@@ -185,8 +306,8 @@ export function normalizeManifest(raw, source = '') {
   //       transfers with zero edits)
   // Inline wins on name collision so authors can override a portable
   // config for the local plugin without editing mcp.json.
-  const mcpServers = _readMcpServers(spec.mcpServers, source);
-  const composes = normalizeComposes(spec.composes);
+  const mcpServers = _readMcpServers(config.mcpServers, source);
+  const composes = normalizeComposes(config.composes);
 
   return {
     apiVersion,
@@ -198,10 +319,12 @@ export function normalizeManifest(raw, source = '') {
       author: meta.author || '',
       repository: meta.repository || '',
     },
-    spec: {
+    config: {
       tools,
       agents,
-      workspace,
+      ...(agentsFrom.length ? { agents_from: agentsFrom } : {}),
+      workspace: workspaceDecl.agentPath,
+      views,
       mcpServers,
       composes,
     },
@@ -277,12 +400,12 @@ export function validatePluginManifest(manifest) {
     errors.push('Plugin metadata.name is required');
   }
 
-  if (manifest.spec) {
-    for (const tool of (manifest.spec.tools || [])) {
+  if (manifest.config) {
+    for (const tool of (manifest.config.tools || [])) {
       if (!tool.name) errors.push('Tool missing name');
       if (!tool.tool) errors.push(`Tool "${tool.name || '(unnamed)'}" missing tool module path (tool: ./tools/<name>.mjs)`);
     }
-    for (const agent of (manifest.spec.agents || [])) {
+    for (const agent of (manifest.config.agents || [])) {
       if (!agent.slug && !agent.name) errors.push('Agent missing slug or name');
     }
   }

package/src/plugins/npm-install.mjs

@@ -77,11 +77,22 @@ function migratePeersForPi(pkgPath) {
   let pkg = {};
   try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')); } catch { return {}; }
   const peers = pkg.peerDependencies || {};
-  if (!Object.keys(peers).length) return pkg;
   const merged = { ...(pkg.dependencies || {}) };
+  let changed = false;
   for (const [name, range] of Object.entries(peers)) {
-    if (!merged[name]) merged[name] = range === '*' ? 'latest' : range;
+    if (!merged[name]) {
+      merged[name] = range === '*' ? 'latest' : range;
+      changed = true;
+    }
   }
+  // Some current pi packages import the Pi server runtime transitively
+  // through @earendil-works/pi-coding-agent without declaring it. Materialize
+  // it here so discovery can import the extension and capture tools.
+  if (merged['@earendil-works/pi-coding-agent'] && !merged['@earendil-works/pi-server']) {
+    merged['@earendil-works/pi-server'] = 'latest';
+    changed = true;
+  }
+  if (!changed && !Object.keys(peers).length) return pkg;
   const rewritten = { ...pkg, dependencies: merged };
   delete rewritten.peerDependencies;
   fs.writeFileSync(pkgPath, JSON.stringify(rewritten, null, 2));

package/src/plugins/pi-compat/scaffold.mjs

@@ -185,7 +185,7 @@ function generatePrompt(packageName, namespace, toolNames, hasState, requirement
  * (quoted keys, over-escaping); a small emitter here yields a diff-
  * friendly manifest the user can edit.
  */
-function renderManifest({ slug, packageName, versionRange, namespace, exposeTools, agentSlug, agentDescription, hasState, hasWorkspace, systemPrompt }) {
+function renderManifest({ slug, packageName, versionRange, namespace, exposeTools, hasState, hasWorkspace }) {
   const versionSpec = versionRange ? `${packageName}@${versionRange}` : packageName;
   const tools = hasState ? [
     '  tools:',
@@ -235,30 +235,11 @@ function renderManifest({ slug, packageName, versionRange, namespace, exposeTool
     '',
   ];
 
-  const agentToolRefs = [
-    ...(hasState ? ['save_item', 'list_items', 'drop_item'] : []),
-    ...exposeTools.map(t => `${namespace}${COMPOSED_TOOL_SEPARATOR}${t}`),
-  ];
-
-  const agentBlock = [
-    '  agents:',
-    `    - slug: ${agentSlug}`,
-    `      name: ${yamlString(agentSlug.replace(/-/g, ' '))}`,
-    '      role: specialist',
-    '      description: >',
-    `        ${agentDescription}`,
-    '      tools:',
-    ...agentToolRefs.map(t => `        - ${t}`),
-    `      system_prompt: ${yamlBlock(systemPrompt, 8)}`,
-    '',
-  ];
-
   const workspaceBlock = hasWorkspace ? [
-    '  workspace:',
-    '    views:',
-    '      - type: panel',
-    `        name: ${yamlString(slug.replace(/-/g, ' '))}`,
-    '        source: ./workspace/panel.html',
+    '  views:',
+    '    - type: panel',
+    `      name: ${yamlString(slug.replace(/-/g, ' '))}`,
+    '      source: ./workspace/panel.html',
     '',
   ] : [];
 
@@ -272,14 +253,41 @@ function renderManifest({ slug, packageName, versionRange, namespace, exposeTool
     `    Auto-scaffolded pack composing pi:${packageName}.`,
     `    Edit tools/, workspace/, and this manifest to customize.`,
     '',
-    'spec:',
+    'config:',
     ...tools,
     ...composesBlock,
-    ...agentBlock,
+    '  workspace: ./config/workspace.yaml',
+    '',
     ...workspaceBlock,
   ].join('\n');
 }
 
+function renderAgentFile({ namespace, exposeTools, agentSlug, agentDescription, hasState, systemPrompt }) {
+  const agentToolRefs = [
+    ...(hasState ? ['save_item', 'list_items', 'drop_item'] : []),
+    ...exposeTools.map(t => `${namespace}${COMPOSED_TOOL_SEPARATOR}${t}`),
+  ];
+
+  return [
+    '# config/workspace.yaml — entry agent loaded when plugin.yaml declares',
+    '# config.workspace: ./config/workspace.yaml.',
+    'apiVersion: agent.framework/v1',
+    'kind: SingleAgent',
+    'metadata:',
+    `  slug: ${agentSlug}`,
+    `  name: ${yamlString(agentSlug.replace(/-/g, ' '))}`,
+    '  role: specialist',
+    '  description: >',
+    `    ${agentDescription}`,
+    'agent:',
+    '  max_iterations: 10',
+    `  system_prompt: ${yamlBlock(systemPrompt, 4)}`,
+    'tools:',
+    ...agentToolRefs.map(t => `  - ${t}`),
+    '',
+  ].join('\n');
+}
+
 const SAVE_ITEM_TOOL = `/**
  * save_item — persist a single item to the pack's notebook.
  * Append-style records so a topic can accumulate many entries over time.
@@ -537,14 +545,22 @@ export function scaffoldPiPack({
     versionRange,
     namespace,
     exposeTools: toolNames,
-    agentSlug,
-    agentDescription,
     hasState: state,
     hasWorkspace: workspace,
-    systemPrompt,
   });
   fs.writeFileSync(path.join(dest, 'plugin.yaml'), manifest);
 
+  const configDir = path.join(dest, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(path.join(configDir, 'workspace.yaml'), renderAgentFile({
+    namespace,
+    exposeTools: toolNames,
+    agentSlug,
+    agentDescription,
+    hasState: state,
+    systemPrompt,
+  }));
+
   if (state) {
     const toolsDir = path.join(dest, 'tools');
     fs.mkdirSync(toolsDir, { recursive: true });

package/src/plugins/preflight.mjs

@@ -18,11 +18,11 @@
  */
 
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
 import { composedToolName, validateCompose } from './pi-compose.mjs';
+import { bahulamHome } from '../core/paths.mjs';
 
 const TOOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
 const AGENT_SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
@@ -84,12 +84,21 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     warnings.push(`metadata.name "${name}" should be lowercase kebab-case for registry compatibility`);
   }
 
-  const tools = manifest.spec?.tools || [];
-  const agents = manifest.spec?.agents || [];
-  const views = manifest.spec?.workspace?.views || [];
-  const mcpServers = manifest.spec?.mcpServers || {};
+  const tools = manifest.config?.tools || [];
+  const agents = manifest.config?.agents || [];
+  const workspacePath = manifest.config?.workspace || '';
+  const views = manifest.config?.views || [];
+  const mcpServers = manifest.config?.mcpServers || {};
   const mcpServerNames = new Set(Object.keys(mcpServers));
-  const composes = manifest.spec?.composes || [];
+  const composes = manifest.config?.composes || [];
+
+  if (workspacePath) {
+    const full = path.resolve(pluginDir, workspacePath);
+    const inside = full === pluginDir || full.startsWith(pluginDir + path.sep);
+    if (!inside) errors.push(`Workspace entry agent path escapes the plugin directory: ${workspacePath}`);
+    else if (!fs.existsSync(full)) errors.push(`Workspace entry agent not found: ${workspacePath}`);
+    else if (!fs.statSync(full).isFile()) errors.push(`Workspace entry agent is not a file: ${workspacePath}`);
+  }
 
   // MCP server sanity — every server should have EITHER command (stdio)
   // OR url (remote). Anything else is meaningless config.
@@ -240,7 +249,7 @@ export function existingInstalledNames(cwd = process.cwd()) {
   const names = [];
   for (const dir of [
     path.join(cwd, '.bahulam', 'plugins'),
-    path.join(os.homedir(), '.bahulam', 'plugins'),
+    path.join(bahulamHome(), 'plugins'),
   ]) {
     if (!fs.existsSync(dir)) continue;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {

package/src/plugins/registry.mjs

@@ -7,13 +7,13 @@
 
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
 import { expandComposedTools } from './pi-compose.mjs';
+import { bahulamHome } from '../core/paths.mjs';
 
 const DEFAULT_PLUGIN_DIRS = () => [
   path.join(process.cwd(), '.bahulam', 'plugins'),
-  path.join(os.homedir(), '.bahulam', 'plugins'),
+  path.join(bahulamHome(), 'plugins'),
 ];
 
 export class PluginRegistry {
@@ -153,7 +153,7 @@ export class PluginRegistry {
   listTools() {
     const tools = [];
     for (const plugin of this.plugins.values()) {
-      for (const tool of (plugin.spec?.tools || [])) {
+      for (const tool of (plugin.config?.tools || [])) {
         tools.push({
           ...tool,
           _plugin_name: plugin.metadata?.name,
@@ -163,7 +163,7 @@ export class PluginRegistry {
       tools.push(...expandComposedTools(
         plugin.metadata?.name || '',
         plugin._dir,
-        plugin.spec?.composes || [],
+        plugin.config?.composes || [],
       ));
     }
     return tools;
@@ -183,7 +183,7 @@ export class PluginRegistry {
   listMcpServers() {
     const out = [];
     for (const plugin of this.plugins.values()) {
-      const servers = plugin.spec?.mcpServers || {};
+      const servers = plugin.config?.mcpServers || {};
       const pluginName = plugin.metadata?.name || '';
       for (const [name, config] of Object.entries(servers)) {
         if (config && typeof config === 'object') {
@@ -201,7 +201,7 @@ export class PluginRegistry {
   listAgents() {
     const agents = [];
     for (const plugin of this.plugins.values()) {
-      for (const agent of (plugin.spec?.agents || [])) {
+      for (const agent of (plugin.config?.agents || [])) {
         agents.push({
           ...agent,
           _plugin_name: plugin.metadata?.name,

package/src/plugins/state.mjs

@@ -33,7 +33,10 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { DatabaseSync } from 'node:sqlite';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+let DatabaseSync = null;
 
 // Silence the single "SQLite is an experimental feature" warning that
 // node:sqlite emits at first import. Users would see it on every plugin
@@ -49,6 +52,14 @@ import { DatabaseSync } from 'node:sqlite';
   };
 }
 
+if (process.env.BAHULAM_PLUGIN_STATE_BACKEND !== 'json') {
+  try {
+    ({ DatabaseSync } = require('node:sqlite'));
+  } catch {
+    DatabaseSync = null;
+  }
+}
+
 const DATA_ROOT = () => path.join(os.homedir(), '.bahulam', 'data');
 const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
 const DEBOUNCE_MS = 50;
@@ -58,6 +69,134 @@ const DEBOUNCE_MS = 50;
 // for the lifetime of the CLI; explicit close() is available for tests.
 const _handles = new Map(); // pluginName -> { db, dir, path }
 
+class JsonStatement {
+  constructor(db, sql) {
+    this.db = db;
+    this.sql = String(sql || '').trim().replace(/\s+/g, ' ').toUpperCase();
+  }
+
+  get(...args) {
+    if (this.sql === 'SELECT VALUE FROM KV WHERE KEY = ?') {
+      const key = String(args[0]);
+      return this.db.store.kv[key] ? { value: this.db.store.kv[key].value } : undefined;
+    }
+    throw new Error('Raw SELECT is only available with native node:sqlite');
+  }
+
+  all(...args) {
+    if (this.sql === 'SELECT KEY FROM KV ORDER BY KEY') {
+      return Object.keys(this.db.store.kv).sort().map(key => ({ key }));
+    }
+    if (this.sql === 'SELECT ID, PAYLOAD, CREATED_AT FROM RECORDS WHERE STREAM = ? ORDER BY ID ASC LIMIT ?') {
+      return this.db.records(String(args[0]), Number(args[1]), 'asc');
+    }
+    if (this.sql === 'SELECT ID, PAYLOAD, CREATED_AT FROM RECORDS WHERE STREAM = ? ORDER BY ID DESC LIMIT ?') {
+      return this.db.records(String(args[0]), Number(args[1]), 'desc');
+    }
+    if (this.sql === 'SELECT COUNT(*) AS N FROM RECORDS WHERE STREAM = ?') {
+      return [{ n: this.db.store.records.filter(row => row.stream === String(args[0])).length }];
+    }
+    throw new Error('Raw SELECT is only available with native node:sqlite');
+  }
+
+  run(...args) {
+    if (this.sql.startsWith('INSERT INTO KV(')) {
+      const [key, value, updated_at] = args;
+      this.db.store.kv[String(key)] = { value: String(value), updated_at: String(updated_at) };
+      this.db.save();
+      return { changes: 1, lastInsertRowid: 0 };
+    }
+    if (this.sql === 'DELETE FROM KV WHERE KEY = ?') {
+      const key = String(args[0]);
+      const existed = Object.prototype.hasOwnProperty.call(this.db.store.kv, key);
+      if (existed) {
+        delete this.db.store.kv[key];
+        this.db.save();
+      }
+      return { changes: existed ? 1 : 0, lastInsertRowid: 0 };
+    }
+    if (this.sql === 'INSERT INTO RECORDS(STREAM, PAYLOAD, CREATED_AT) VALUES(?, ?, ?)') {
+      const row = {
+        id: this.db.store.nextRecordId++,
+        stream: String(args[0]),
+        payload: String(args[1]),
+        created_at: String(args[2]),
+      };
+      this.db.store.records.push(row);
+      this.db.save();
+      return { changes: 1, lastInsertRowid: row.id };
+    }
+    if (this.sql === 'DELETE FROM RECORDS WHERE STREAM = ?') {
+      const stream = String(args[0]);
+      const before = this.db.store.records.length;
+      this.db.store.records = this.db.store.records.filter(row => row.stream !== stream);
+      const changes = before - this.db.store.records.length;
+      if (changes) this.db.save();
+      return { changes, lastInsertRowid: 0 };
+    }
+    if (this.sql === 'DELETE FROM RECORDS WHERE STREAM = ? AND ID = ?') {
+      const stream = String(args[0]);
+      const id = Number(args[1]);
+      const before = this.db.store.records.length;
+      this.db.store.records = this.db.store.records.filter(row => !(row.stream === stream && row.id === id));
+      const changes = before - this.db.store.records.length;
+      if (changes) this.db.save();
+      return { changes, lastInsertRowid: 0 };
+    }
+    throw new Error('Raw DML is only available with native node:sqlite');
+  }
+}
+
+class JsonStateDb {
+  constructor(dbPath) {
+    this.path = dbPath;
+    this.store = {
+      kv: {},
+      records: [],
+      nextRecordId: 1,
+    };
+    try {
+      if (fs.existsSync(dbPath)) {
+        const parsed = JSON.parse(fs.readFileSync(dbPath, 'utf-8'));
+        if (parsed && typeof parsed === 'object') {
+          this.store = {
+            kv: parsed.kv && typeof parsed.kv === 'object' ? parsed.kv : {},
+            records: Array.isArray(parsed.records) ? parsed.records : [],
+            nextRecordId: Number(parsed.nextRecordId) || 1,
+          };
+        }
+      } else {
+        this.save();
+      }
+    } catch {
+      this.save();
+    }
+  }
+
+  exec() {}
+
+  prepare(sql) {
+    return new JsonStatement(this, sql);
+  }
+
+  records(stream, limit, order) {
+    const cap = Math.max(1, Math.min(10000, Math.floor(limit) || 50));
+    const rows = this.store.records
+      .filter(row => row.stream === stream)
+      .sort((a, b) => order === 'asc' ? a.id - b.id : b.id - a.id)
+      .slice(0, cap);
+    return rows.map(row => ({ id: row.id, payload: row.payload, created_at: row.created_at }));
+  }
+
+  save() {
+    fs.writeFileSync(this.path, JSON.stringify(this.store, null, 2));
+  }
+
+  close() {
+    this.save();
+  }
+}
+
 function pluginDataDir(pluginName) {
   if (!PLUGIN_NAME_RE.test(pluginName)) {
     throw new Error(`invalid plugin name for state dir: ${pluginName}`);
@@ -71,7 +210,7 @@ function openDb(pluginName) {
   if (_handles.has(pluginName)) return _handles.get(pluginName);
   const dir = pluginDataDir(pluginName);
   const dbPath = path.join(dir, 'state.db');
-  const db = new DatabaseSync(dbPath);
+  const db = DatabaseSync ? new DatabaseSync(dbPath) : new JsonStateDb(dbPath);
   // WAL: multiple readers, one writer; robust against concurrent view+agent.
   db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA synchronous = NORMAL');