@bahulam/code 0.1.20 → 0.1.22

package/src/plugins/manifest.mjs

@@ -35,6 +35,12 @@ function normalizePathList(value) {
   return [];
 }
 
+function normalizeStringList(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();
@@ -119,6 +125,7 @@ function normalizeAgentDef(agentDef, pluginName, pluginDir) {
       || ''
     ),
     tools: inlineTools.length ? inlineTools : normalizeToolNames(fileTools),
+    aliases: normalizeStringList(agentDef.aliases || metadata.aliases || fileConfig.aliases || agent.aliases),
     model: agentDef.model || agent.model || fileConfig.model || null,
     models: agentDef.models || agent.models || fileConfig.models || undefined,
     max_tokens: agentDef.max_tokens || agent.max_tokens || fileConfig.max_tokens || undefined,
@@ -156,6 +163,190 @@ function loadAgentPath(agentPath, pluginDir, pluginName, label) {
   }
 }
 
+// Identifiers that are safe to interpolate into DDL. Manifests are
+// plugin-author controlled, but a typo (or a malicious registry entry)
+// must never be able to escape the quoted identifier and inject SQL.
+const SAFE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+
+// SQLite type affinities. Anything else collapses to TEXT so a bad
+// manifest degrades into a working table instead of a failed CREATE.
+const SQL_TYPES = new Set(['INTEGER', 'TEXT', 'REAL', 'BLOB', 'NUMERIC']);
+
+function normalizeSqlType(value) {
+  const raw = String(value || '').trim().toUpperCase();
+  if (!raw) return 'TEXT';
+  // Accept the common aliases rather than rejecting an otherwise-fine manifest.
+  if (raw === 'INT' || raw === 'BIGINT') return 'INTEGER';
+  if (raw === 'BOOL' || raw === 'BOOLEAN') return 'INTEGER';
+  if (raw === 'FLOAT' || raw === 'DOUBLE') return 'REAL';
+  if (raw === 'STRING' || raw === 'VARCHAR' || raw === 'DATETIME' || raw === 'TIMESTAMP' || raw === 'JSON') return 'TEXT';
+  return SQL_TYPES.has(raw) ? raw : 'TEXT';
+}
+
+/**
+ * Normalize `config.state` — the manifest-declared state schema plus the
+ * agent-visibility contract for that state.
+ *
+ * Every plugin already gets a SQLite sidecar for free (the `kv` and
+ * `records` tables). This block is how a plugin graduates from "a tool
+ * that remembers a cursor" to "a local app that owns its own domain
+ * tables" (questions + answers + progress for a tutor, documents for a
+ * study aid, and so on).
+ *
+ * Three parts, matching the three visibility tiers:
+ *
+ *   tables          DDL applied idempotently whenever the plugin's state
+ *                   DB is opened. Existing columns are never dropped;
+ *                   new columns are added with ALTER TABLE so a version
+ *                   bump never costs the user their data.
+ *   context_always  Small, high-signal slices injected into the agent
+ *                   context every turn (current lesson, progress).
+ *   context_tools   Read-only tools auto-generated for the agent to call
+ *                   on demand for the larger data (list questions).
+ *
+ * Anything not declared here stays reachable only from the plugin's own
+ * handlers via `state.query()` — the third tier.
+ *
+ * @param {object|null|undefined} value raw `config.state`
+ * @returns {{tables: object[], context_always: object[], context_tools: object[]}}
+ */
+function normalizeState(value) {
+  const empty = { tables: [], context_always: [], context_tools: [] };
+  if (!value || typeof value !== 'object') return empty;
+
+  const tables = [];
+  for (const rawTable of (Array.isArray(value.tables) ? value.tables : [])) {
+    if (!rawTable || typeof rawTable !== 'object') continue;
+    const name = String(rawTable.name || '').trim();
+    if (!SAFE_IDENT_RE.test(name)) {
+      console.warn(`Skipping state table with unsafe or missing name: ${JSON.stringify(rawTable.name)}`);
+      continue;
+    }
+
+    const columns = [];
+    const columnNames = new Set();
+    for (const rawCol of (Array.isArray(rawTable.columns) ? rawTable.columns : [])) {
+      if (!rawCol || typeof rawCol !== 'object') continue;
+      const colName = String(rawCol.name || '').trim();
+      if (!SAFE_IDENT_RE.test(colName)) {
+        console.warn(`Skipping column with unsafe or missing name in table ${name}: ${JSON.stringify(rawCol.name)}`);
+        continue;
+      }
+      if (columnNames.has(colName)) continue;
+      columnNames.add(colName);
+
+      // `references` is free-form in the manifest, so validate the shape
+      // strictly before it reaches a CREATE TABLE string.
+      const references = String(rawCol.references || '').trim();
+      const safeReferences = /^[A-Za-z_][A-Za-z0-9_]{0,63}\s*\(\s*[A-Za-z_][A-Za-z0-9_]{0,63}\s*\)$/.test(references)
+        ? references.replace(/\s+/g, '')
+        : null;
+      if (references && !safeReferences) {
+        console.warn(`Ignoring malformed references "${references}" on ${name}.${colName}`);
+      }
+
+      const primary = rawCol.primary === true || rawCol.primary_key === true || rawCol.primaryKey === true;
+      const type = normalizeSqlType(rawCol.type);
+      columns.push({
+        name: colName,
+        type,
+        primary,
+        // SQLite only allows AUTOINCREMENT on INTEGER PRIMARY KEY.
+        autoincrement: (rawCol.autoincrement === true || rawCol.auto_increment === true)
+          && primary && type === 'INTEGER',
+        not_null: rawCol.not_null === true || rawCol.notNull === true,
+        default: rawCol.default === undefined || rawCol.default === null ? null : String(rawCol.default),
+        references: safeReferences,
+      });
+    }
+    if (!columns.length) {
+      console.warn(`Skipping state table ${name}: no usable columns`);
+      continue;
+    }
+
+    const indexes = [];
+    for (const rawIndex of (Array.isArray(rawTable.indexes) ? rawTable.indexes : [])) {
+      if (!rawIndex || typeof rawIndex !== 'object') continue;
+      const source = Array.isArray(rawIndex.columns) ? rawIndex.columns
+        : (rawIndex.column ? [rawIndex.column] : []);
+      const indexColumns = source
+        .map(c => String(c || '').trim())
+        .filter(c => SAFE_IDENT_RE.test(c) && columnNames.has(c));
+      if (indexColumns.length) {
+        indexes.push({ columns: indexColumns, unique: rawIndex.unique === true });
+      }
+    }
+
+    tables.push({ name, columns, indexes });
+  }
+
+  const tableNames = new Set(tables.map(t => t.name));
+
+  // Tier 1 — injected every turn. Accept a bare string as a kv key so the
+  // common case stays a one-liner in YAML.
+  const contextAlways = [];
+  for (const rawEntry of (Array.isArray(value.context_always) ? value.context_always : [])) {
+    if (typeof rawEntry === 'string') {
+      const key = rawEntry.trim();
+      if (key) contextAlways.push({ kind: 'kv', key });
+      continue;
+    }
+    if (!rawEntry || typeof rawEntry !== 'object') continue;
+    const stream = String(rawEntry.stream || '').trim();
+    if (stream) {
+      const limit = Number(rawEntry.limit);
+      contextAlways.push({
+        kind: 'records',
+        stream,
+        limit: Number.isFinite(limit) && limit > 0 ? Math.min(Math.trunc(limit), 50) : 5,
+      });
+      continue;
+    }
+    const key = String(rawEntry.kv_key || rawEntry.key || '').trim();
+    if (key) contextAlways.push({ kind: 'kv', key });
+  }
+
+  // Tier 2 — auto-generated read-only tools.
+  const contextTools = [];
+  for (const rawTool of (Array.isArray(value.context_tools) ? value.context_tools : [])) {
+    if (!rawTool || typeof rawTool !== 'object') continue;
+    const name = String(rawTool.name || '').trim();
+    if (!SAFE_IDENT_RE.test(name)) {
+      console.warn(`Skipping context tool with unsafe or missing name: ${JSON.stringify(rawTool.name)}`);
+      continue;
+    }
+    const table = String(rawTool.table || '').trim();
+    if (!tableNames.has(table)) {
+      console.warn(`Skipping context tool ${name}: table "${table}" is not declared in config.state.tables`);
+      continue;
+    }
+    const parameters = rawTool.parameters && typeof rawTool.parameters === 'object'
+      ? rawTool.parameters
+      : { type: 'object', properties: {} };
+    // Bind order for a positional `where` clause. Defaults to the declared
+    // property order so the simple case needs no extra YAML — minus
+    // `limit`, which the CLI consumes itself and must never be bound into
+    // the WHERE clause.
+    const declaredParams = Array.isArray(rawTool.params)
+      ? rawTool.params.map(p => String(p || '').trim()).filter(p => SAFE_IDENT_RE.test(p))
+      : Object.keys(parameters.properties || {}).filter(p => p !== 'limit');
+    const limit = Number(rawTool.limit);
+    contextTools.push({
+      name,
+      table,
+      description: String(rawTool.description || `List rows from ${table}`),
+      parameters,
+      // Plugin-authored SQL, same trust model as state.query(): the author
+      // owns the clause, the CLI binds the values.
+      where: String(rawTool.where || '').trim(),
+      params: declaredParams,
+      limit: Number.isFinite(limit) && limit > 0 ? Math.min(Math.trunc(limit), 500) : 50,
+    });
+  }
+
+  return { tables, context_always: contextAlways, context_tools: contextTools };
+}
+
 /**
  * Parse a plugin manifest from YAML text.
  * @param {string} yamlText - Raw YAML content
@@ -214,7 +405,7 @@ export function normalizeManifest(raw, source = '') {
   }
 
   const meta = raw.metadata || raw.meta || {};
-  const config = raw.config || raw.plugin || {};
+  const config = raw.config || raw.plugin || raw.spec || {};
   const name = meta.name || config.name || '';
   if (!name) {
     if (process.env.DEBUG) {
@@ -308,6 +499,7 @@ export function normalizeManifest(raw, source = '') {
   // config for the local plugin without editing mcp.json.
   const mcpServers = _readMcpServers(config.mcpServers, source);
   const composes = normalizeComposes(config.composes);
+  const state = normalizeState(config.state);
 
   return {
     apiVersion,
@@ -327,6 +519,7 @@ export function normalizeManifest(raw, source = '') {
       views,
       mcpServers,
       composes,
+      state,
     },
     source,
     _dir: source ? path.dirname(source) : '',
@@ -408,6 +601,19 @@ export function validatePluginManifest(manifest) {
     for (const agent of (manifest.config.agents || [])) {
       if (!agent.slug && !agent.name) errors.push('Agent missing slug or name');
     }
+
+    // State declarations that silently vanished during normalization are
+    // exactly the kind of thing an author wants to hear about at validate
+    // time rather than discover at runtime.
+    const state = manifest.config.state;
+    if (state) {
+      const declaredTables = new Set((state.tables || []).map(t => t.name));
+      for (const tool of (state.context_tools || [])) {
+        if (!declaredTables.has(tool.table)) {
+          errors.push(`State context tool "${tool.name}" references undeclared table "${tool.table}"`);
+        }
+      }
+    }
   }
 
   return {

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

@@ -19,6 +19,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { execSync } from 'node:child_process';
+import { load as yamlLoad } from 'js-yaml';
 
 export const REQUIREMENTS_FILE = '.bahulam-requirements.json';
 
@@ -168,6 +169,7 @@ function analyzeFile(text, rel, findings) {
     if (!name) continue;
     // Ignore Node.js / OS-level env vars users don't set for a plugin.
     if (['NODE_ENV', 'PATH', 'HOME', 'USER', 'PWD', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'TMP', 'TEMP'].includes(name)) continue;
+    if (/_PREFLIGHT$/.test(name)) continue;
     const existing = findings.envVars.get(name) || { name, seen_in: new Set(), credential: false };
     existing.seen_in.add(rel);
     if (CREDENTIAL_SUFFIXES.some(s => name.endsWith(s))) existing.credential = true;
@@ -278,6 +280,70 @@ function extractSkillsFiles(pluginDir) {
   return skills;
 }
 
+function readManifestRequirements(pluginDir) {
+  for (const name of ['plugin.yaml', 'plugin.yml']) {
+    const filePath = path.join(pluginDir, name);
+    if (!fs.existsSync(filePath)) continue;
+    try {
+      const doc = yamlLoad(fs.readFileSync(filePath, 'utf-8')) || {};
+      const reqs = doc.config?.requirements;
+      return reqs && typeof reqs === 'object' ? reqs : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function normalizeManifestRequirementList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string') return [value];
+  if (typeof value === 'object') return Object.entries(value).map(([name, detail]) => (
+    detail && typeof detail === 'object' ? { name, ...detail } : { name, reason: String(detail || '') }
+  ));
+  return [];
+}
+
+function mergeManifestRequirements(shape, manifestRequirements) {
+  if (!manifestRequirements) return shape;
+
+  const binaries = new Map((shape.system_binaries || []).map(b => [b.name, b]));
+  for (const raw of normalizeManifestRequirementList(manifestRequirements.system)) {
+    const name = typeof raw === 'string' ? raw : raw?.name;
+    const clean = String(name || '').trim();
+    if (!clean) continue;
+    const existing = binaries.get(clean) || { name: clean, install_hints: INSTALL_HINTS[clean] || null, seen_in: [] };
+    existing.install_hints = raw.install_hints || raw.installHints || existing.install_hints || INSTALL_HINTS[clean] || null;
+    existing.version = raw.version || existing.version || null;
+    existing.reason = raw.reason || existing.reason || 'Declared by plugin manifest.';
+    existing.optional = raw.optional === true || existing.optional === true;
+    existing.seen_in = [...new Set([...(existing.seen_in || []), 'plugin.yaml:config.requirements.system'])].slice(0, 5);
+    binaries.set(clean, existing);
+  }
+  shape.system_binaries = [...binaries.values()].sort((a, b) => a.name.localeCompare(b.name));
+
+  const envVars = new Map((shape.env_vars || []).map(v => [v.name, v]));
+  for (const raw of normalizeManifestRequirementList(manifestRequirements.env)) {
+    const name = typeof raw === 'string' ? raw : raw?.name;
+    const clean = String(name || '').trim();
+    if (!clean) continue;
+    const existing = envVars.get(clean) || { name: clean, seen_in: [], credential: false };
+    existing.credential = raw.credential === true || existing.credential || CREDENTIAL_SUFFIXES.some(s => clean.endsWith(s));
+    existing.optional = raw.optional === true || existing.optional === true;
+    existing.reason = raw.reason || existing.reason || 'Declared by plugin manifest.';
+    existing.seen_in = [...new Set([...(existing.seen_in || []), 'plugin.yaml:config.requirements.env'])].slice(0, 5);
+    envVars.set(clean, existing);
+  }
+  shape.env_vars = [...envVars.values()].sort((a, b) => a.name.localeCompare(b.name));
+
+  const files = normalizeManifestRequirementList(manifestRequirements.filesystem);
+  if (files.length) {
+    shape.filesystem = files.map(item => typeof item === 'string' ? { path: item } : item).filter(Boolean);
+  }
+  return shape;
+}
+
 function extractToolConstraints(discoveredTools) {
   const out = {};
   for (const tool of discoveredTools || []) {
@@ -377,6 +443,7 @@ export function analyzeRequirements(pluginDir, { discoveredTools = null } = {})
     skills_available: skills,
     tool_constraints: toolConstraints,
   };
+  mergeManifestRequirements(shape, readManifestRequirements(pluginDir));
 
   try {
     fs.writeFileSync(path.join(pluginDir, REQUIREMENTS_FILE), JSON.stringify(shape, null, 2));
@@ -462,4 +529,3 @@ export function checkRequirementsAgainstHost(reqs) {
 
   return results;
 }
-

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

@@ -81,6 +81,91 @@ function truncate(s, n) {
   return str.slice(0, n - 1) + '…';
 }
 
+function renderStandardRequirements(requirements) {
+  const lines = ['  requirements:'];
+  const bins = requirements?.system_binaries || [];
+  lines.push('    system:');
+  if (bins.length) {
+    for (const b of bins) {
+      lines.push(`      - name: ${yamlString(b.name)}`);
+      lines.push(`        reason: Required by composed pi tool runtime.`);
+      if (b.install_hints) {
+        lines.push('        install_hints:');
+        if (b.install_hints.darwin) lines.push(`          darwin: ${yamlString(b.install_hints.darwin)}`);
+        if (b.install_hints.linux) lines.push(`          linux: ${yamlString(b.install_hints.linux)}`);
+      }
+    }
+  } else {
+    lines.push('      []');
+  }
+
+  const envVars = requirements?.env_vars || [];
+  lines.push('    env:');
+  if (envVars.length) {
+    for (const v of envVars) {
+      lines.push(`      - name: ${yamlString(v.name)}`);
+      lines.push(`        credential: ${v.credential ? 'true' : 'false'}`);
+      lines.push(`        optional: true`);
+      lines.push(`        reason: Read by composed pi package when that feature is used.`);
+    }
+  } else {
+    lines.push('      []');
+  }
+
+  lines.push('    filesystem:');
+  lines.push('      - path: .bahulam/plugin-state');
+  lines.push('        access: read_write');
+  lines.push('        reason: Stores durable notebook records and reports for this generated pack.');
+  return lines;
+}
+
+function renderStandardState(slug) {
+  return [
+    '  state:',
+    '    tables:',
+    '      - name: items',
+    '        columns:',
+    '          - { name: id, type: INTEGER, primary: true, autoincrement: true }',
+    '          - { name: title, type: TEXT, not_null: true }',
+    '          - { name: source, type: TEXT, not_null: true, default: "\'\'" }',
+    '          - { name: notes, type: TEXT, not_null: true, default: "\'\'" }',
+    '          - { name: topic, type: TEXT, not_null: true, default: "\'\'" }',
+    '          - { name: created_at, type: TEXT, not_null: true }',
+    '          - { name: updated_at, type: TEXT, not_null: true }',
+    '        indexes:',
+    '          - { columns: [topic] }',
+    '',
+    '      - name: reports',
+    '        columns:',
+    '          - { name: id, type: INTEGER, primary: true, autoincrement: true }',
+    '          - { name: title, type: TEXT, not_null: true }',
+    '          - { name: summary, type: TEXT, not_null: true }',
+    '          - { name: item_count, type: INTEGER, not_null: true, default: "0" }',
+    '          - { name: created_at, type: TEXT, not_null: true }',
+    '',
+    '    context_always:',
+    `      - { stream: ${slug}_activity, limit: 5 }`,
+    '',
+    '    context_tools:',
+    '      - name: list_saved_items',
+    '        table: items',
+    '        description: List durable notebook items saved by this plugin.',
+    '        parameters:',
+    '          type: object',
+    '          properties:',
+    '            limit: { type: integer, description: "Max rows to return." }',
+    '',
+    '      - name: list_saved_reports',
+    '        table: reports',
+    '        description: List generated outcome reports.',
+    '        parameters:',
+    '          type: object',
+    '          properties:',
+    '            limit: { type: integer, description: "Max rows to return." }',
+    '',
+  ];
+}
+
 /**
  * Compose the "Requirements & constraints" block from the analyzer's
  * findings. Injected into the generated agent's system prompt so the
@@ -185,7 +270,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, hasState, hasWorkspace }) {
+function renderManifest({ slug, packageName, versionRange, namespace, exposeTools, hasState, hasWorkspace, requirements }) {
   const versionSpec = versionRange ? `${packageName}@${versionRange}` : packageName;
   const tools = hasState ? [
     '  tools:',
@@ -223,6 +308,17 @@ function renderManifest({ slug, packageName, versionRange, namespace, exposeTool
     '          id: { type: integer, description: "Item id (from list_items)" }',
     '        required: [id]',
     '',
+    '    - name: build_report',
+    '      description: Build a durable outcome report from saved notebook items.',
+    `      tool: ./tools/build-report.mjs`,
+    '      parameters:',
+    '        type: object',
+    '        properties:',
+    '          title: { type: string, description: "Report title." }',
+    '          topic: { type: string, description: "Optional topic filter." }',
+    '          summary: { type: string, description: "Optional agent-authored summary." }',
+    '        required: [title]',
+    '',
   ] : ['  tools: []', ''];
 
   const composesBlock = [
@@ -254,17 +350,22 @@ function renderManifest({ slug, packageName, versionRange, namespace, exposeTool
     `    Edit tools/, workspace/, and this manifest to customize.`,
     '',
     'config:',
+    ...renderStandardRequirements(requirements),
+    '',
+    ...(hasState ? renderStandardState(slug) : []),
     ...tools,
     ...composesBlock,
     '  workspace: ./config/workspace.yaml',
+    '  agents_from: ./config/agents/',
     '',
     ...workspaceBlock,
   ].join('\n');
 }
 
-function renderAgentFile({ namespace, exposeTools, agentSlug, agentDescription, hasState, systemPrompt }) {
+function renderAgentFile({ namespace, exposeTools, agentSlug, agentAliases = [], agentDescription, hasState, systemPrompt }) {
   const agentToolRefs = [
     ...(hasState ? ['save_item', 'list_items', 'drop_item'] : []),
+    ...(hasState ? ['build_report'] : []),
     ...exposeTools.map(t => `${namespace}${COMPOSED_TOOL_SEPARATOR}${t}`),
   ];
 
@@ -276,6 +377,7 @@ function renderAgentFile({ namespace, exposeTools, agentSlug, agentDescription,
     'metadata:',
     `  slug: ${agentSlug}`,
     `  name: ${yamlString(agentSlug.replace(/-/g, ' '))}`,
+    ...(agentAliases.length ? ['  aliases:', ...agentAliases.map(alias => `    - ${yamlString(alias)}`)] : []),
     '  role: specialist',
     '  description: >',
     `    ${agentDescription}`,
@@ -288,6 +390,29 @@ function renderAgentFile({ namespace, exposeTools, agentSlug, agentDescription,
   ].join('\n');
 }
 
+function renderReviewerAgent({ slug, hasState }) {
+  const tools = hasState ? ['list_items', 'build_report'] : [];
+  return [
+    'apiVersion: agent.framework/v1',
+    'kind: SubAgent',
+    'metadata:',
+    '  slug: outcome-reviewer',
+    '  name: Outcome Reviewer',
+    '  role: reviewer',
+    '  description: >',
+    `    Reviews ${slug} outputs, checks whether saved evidence is enough, and prepares a concise handoff report.`,
+    'agent:',
+    '  can_be_delegated_to: true',
+    '  system_prompt: |',
+    `    You are the Outcome Reviewer for ${slug}.`,
+    '    Inspect saved items and tool outputs, identify missing evidence, and produce a compact handoff.',
+    '    If state tools are available, call list_items first and build_report when the outcome is ready.',
+    'tools:',
+    ...tools.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.
@@ -307,6 +432,17 @@ export async function call(args = {}, options = {}) {
     topic: String(args.topic || '').trim(),
     at: new Date().toISOString(),
   };
+  if (typeof state.query === 'function') {
+    const info = state.query('INSERT INTO items (title, source, notes, topic, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)', [
+      item.title, item.source, item.notes, item.topic, item.at, item.at,
+    ]);
+    if (typeof state.append === 'function') state.append('items', item);
+    return {
+      success: true,
+      output: \`Saved item #\${info?.lastInsertRowid || ''}: \${title}\`,
+      item: { ...item, id: info?.lastInsertRowid },
+    };
+  }
   const record = state.append('items', item);
   return {
     success: true,
@@ -325,6 +461,17 @@ export async function call(args = {}, options = {}) {
 
   const topic = String(args.topic || '').trim().toLowerCase();
   const limit = Math.max(1, Math.min(500, Number(args.limit) || 50));
+  if (typeof state.query === 'function') {
+    const rows = topic
+      ? state.query('SELECT * FROM items WHERE lower(topic) = ? ORDER BY id DESC LIMIT ?', [topic, limit])
+      : state.query('SELECT * FROM items ORDER BY id DESC LIMIT ?', [limit]);
+    const summary = rows.map(r => \`#\${r.id} · \${r.title || ''}\${r.topic ? ' (' + r.topic + ')' : ''}\`).join('\\n');
+    return {
+      success: true,
+      output: rows.length ? summary : (topic ? \`No items for topic '\${topic}'\` : 'No items yet'),
+      items: rows,
+    };
+  }
   const rows = state.list('items', { limit, order: 'desc' }) || [];
   const filtered = topic
     ? rows.filter(r => String(r.payload?.topic || '').toLowerCase() === topic)
@@ -349,7 +496,14 @@ export async function call(args = {}, options = {}) {
   const state = options.state ? await options.state : null;
   if (!state) return { success: false, output: 'Shared blackboard unavailable' };
 
-  const info = state.db.prepare('DELETE FROM records WHERE stream = ? AND id = ?').run('items', id);
+  let info = null;
+  if (typeof state.query === 'function') {
+    info = state.query('DELETE FROM items WHERE id = ?', [id]);
+  } else if (state.db?.prepare) {
+    info = state.db.prepare('DELETE FROM records WHERE stream = ? AND id = ?').run('items', id);
+  } else {
+    return { success: false, output: 'delete is unavailable in this state adapter' };
+  }
   return {
     success: info.changes > 0,
     output: info.changes > 0 ? \`Dropped item #\${id}\` : \`No item with id \${id}\`,
@@ -357,6 +511,50 @@ export async function call(args = {}, options = {}) {
 }
 `;
 
+const BUILD_REPORT_TOOL = `/**
+ * build_report — create a concise durable report from saved notebook items.
+ */
+export async function call(args = {}, options = {}) {
+  const title = String(args.title || '').trim();
+  if (!title) return { success: false, output: 'title is required' };
+  const topic = String(args.topic || '').trim().toLowerCase();
+  const state = options.state ? await options.state : null;
+  if (!state) return { success: false, output: 'Shared blackboard unavailable' };
+
+  let items = [];
+  if (typeof state.query === 'function') {
+    items = topic
+      ? state.query('SELECT * FROM items WHERE lower(topic) = ? ORDER BY id DESC LIMIT 100', [topic])
+      : state.query('SELECT * FROM items ORDER BY id DESC LIMIT 100');
+  } else {
+    const rows = state.list('items', { limit: 100, order: 'desc' }) || [];
+    items = rows.map(r => ({ id: r.id, ...(r.payload || {}), created_at: r.created_at }))
+      .filter(r => !topic || String(r.topic || '').toLowerCase() === topic);
+  }
+  const summary = String(args.summary || '').trim() || (
+    items.length
+      ? \`Report from \${items.length} saved item\${items.length === 1 ? '' : 's'}.\`
+      : 'No saved items available yet.'
+  );
+  const createdAt = new Date().toISOString();
+  let reportId = null;
+  if (typeof state.query === 'function') {
+    const info = state.query('INSERT INTO reports (title, summary, item_count, created_at) VALUES (?, ?, ?, ?)', [
+      title, summary, items.length, createdAt,
+    ]);
+    reportId = info?.lastInsertRowid || null;
+  }
+  if (typeof state.append === 'function') {
+    const record = state.append('reports', { title, summary, item_count: items.length, topic, created_at: createdAt });
+    reportId ||= record?.id || null;
+  }
+  return {
+    success: true,
+    output: { id: reportId, title, summary, item_count: items.length, topic: topic || null, items },
+  };
+}
+`;
+
 function renderPanel(slug, packageName, composedToolNames) {
   const example = composedToolNames[0] || 'example_tool';
   return `<!doctype html>
@@ -523,7 +721,8 @@ export function scaffoldPiPack({
   }
   fs.mkdirSync(dest, { recursive: true });
 
-  const agentSlug = `${namespace}-specialist`;
+  const agentSlug = slug;
+  const agentAliases = [`${namespace}-specialist`].filter(alias => alias !== agentSlug);
   const agentDescription = truncate(
     `Specialist agent for ${packageName}. Composes ${toolNames.length} tool${toolNames.length === 1 ? '' : 's'} exposed as ${namespace}${COMPOSED_TOOL_SEPARATOR}*.`,
     240,
@@ -547,19 +746,24 @@ export function scaffoldPiPack({
     exposeTools: toolNames,
     hasState: state,
     hasWorkspace: workspace,
+    requirements,
   });
   fs.writeFileSync(path.join(dest, 'plugin.yaml'), manifest);
 
   const configDir = path.join(dest, 'config');
   fs.mkdirSync(configDir, { recursive: true });
+  const agentsDir = path.join(configDir, 'agents');
+  fs.mkdirSync(agentsDir, { recursive: true });
   fs.writeFileSync(path.join(configDir, 'workspace.yaml'), renderAgentFile({
     namespace,
     exposeTools: toolNames,
     agentSlug,
+    agentAliases,
     agentDescription,
     hasState: state,
     systemPrompt,
   }));
+  fs.writeFileSync(path.join(agentsDir, 'outcome-reviewer.yaml'), renderReviewerAgent({ slug, hasState: state }));
 
   if (state) {
     const toolsDir = path.join(dest, 'tools');
@@ -567,6 +771,7 @@ export function scaffoldPiPack({
     fs.writeFileSync(path.join(toolsDir, 'save-item.mjs'), SAVE_ITEM_TOOL);
     fs.writeFileSync(path.join(toolsDir, 'list-items.mjs'), LIST_ITEMS_TOOL);
     fs.writeFileSync(path.join(toolsDir, 'drop-item.mjs'), DROP_ITEM_TOOL);
+    fs.writeFileSync(path.join(toolsDir, 'build-report.mjs'), BUILD_REPORT_TOOL);
   }
 
   if (workspace) {