@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/core/interface.js

@@ -0,0 +1,629 @@
+'use strict';
+
+function formatDate(value, fallback = '?') {
+  if (!value) return fallback;
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? fallback : parsed.toISOString().slice(0, 10);
+}
+
+function compactRows(rows = []) {
+  return rows.filter(row => row && row.value !== undefined && row.value !== null && row.value !== '');
+}
+
+function renderValue(value) {
+  if (Array.isArray(value)) return value.join(', ');
+  return String(value);
+}
+
+function renderRow(row, indent = '') {
+  if (!row.label) return `${indent}${renderValue(row.value)}`;
+  return `${indent}${row.label}: ${renderValue(row.value)}`;
+}
+
+function arrayPath(value) {
+  return Array.isArray(value) ? value.filter(Boolean) : [];
+}
+
+function hasProjectScope(stats = {}) {
+  const path = arrayPath(stats.serving?.activeScopePath);
+  if (path.length > 1) return true;
+  const key = stats.serving?.activeScopeKey;
+  return !!(key && key !== 'global');
+}
+
+function hasSavedContent(stats = {}) {
+  if (stats.backendKind === 'local' || stats.backendProfile === 'starter' || stats.degraded) {
+    return (stats.sessionTotal || 0) > 0;
+  }
+  return (stats.sessionTotal || 0) > 0 || (stats.summaries || 0) > 0 || (stats.turnEmbeddings || 0) > 0;
+}
+
+function buildReadinessProductStatus(stats = {}) {
+  const starter = stats.backendKind === 'local' || stats.backendProfile === 'starter' || stats.degraded;
+  const savedContent = hasSavedContent(stats);
+  const pendingTotal = stats.pendingSessions?.total || 0;
+  const fullMemorySupported = !starter && stats.memoryRecords?.available !== false;
+  const fullMemoryEnabled = fullMemorySupported && (stats.serving?.mode || 'legacy') === 'curated';
+  const fullMemoryLinked = fullMemoryEnabled && hasProjectScope(stats);
+  const activeFullMemoryRows = fullMemorySupported ? (stats.memoryRecords?.active || 0) : 0;
+  const fullMemoryReady = fullMemoryLinked && activeFullMemoryRows > 0;
+  const fullMemoryEmpty = fullMemoryLinked && activeFullMemoryRows === 0;
+
+  let code = 'online_memory_ready';
+  let level = 'ready';
+  let headline = 'Online. Memory is ready.';
+  const available = ['Aquifer is online'];
+  const attention = [];
+  let action = 'No action required.';
+
+  if (starter) {
+    if (savedContent) {
+      code = 'online_starter_saved_content';
+      level = 'limited';
+      headline = 'Online. Saved local content is available. Complete memory requires full storage.';
+      available.push('Saved local content is available');
+      attention.push('Complete memory requires full storage.');
+      action = 'Use full storage when complete memory is needed.';
+    } else {
+      code = 'online_starter_empty';
+      level = 'empty';
+      headline = 'Online. No saved content is available yet.';
+      attention.push('Save content, or use full storage for complete memory.');
+      action = 'Save content to start building memory.';
+    }
+  } else if (!savedContent && !fullMemoryReady) {
+    code = 'online_empty';
+    level = 'empty';
+    headline = 'Online. No saved content is available yet.';
+    attention.push('No saved content is available yet.');
+    action = 'Save content to start building memory.';
+  } else {
+    if (savedContent) available.push('Saved content is available');
+    if (fullMemoryReady) available.push('Memory is available');
+
+    if (!fullMemoryEnabled) {
+      code = savedContent ? 'online_saved_content_memory_preparing' : 'online_memory_preparing';
+      level = 'limited';
+      headline = savedContent
+        ? 'Online. Saved content is available. Memory is still getting ready.'
+        : 'Online. Memory is still getting ready.';
+      attention.push('Memory is still getting ready.');
+      action = 'Finish preparing memory.';
+    } else if (!fullMemoryLinked) {
+      code = 'online_saved_content_memory_not_linked';
+      level = 'limited';
+      headline = 'Online. Saved content is available. Memory is not linked to this app yet.';
+      attention.push('Memory is not linked to this app yet.');
+      action = 'Link this app to memory.';
+    } else if (fullMemoryEmpty) {
+      code = 'online_saved_content_memory_empty';
+      level = 'limited';
+      headline = 'Online. Saved content is available. Memory is not available yet.';
+      attention.push('No memory is available yet.');
+      action = 'Finish preparing memory.';
+    }
+
+    if (fullMemoryReady) {
+      code = pendingTotal > 0 ? 'online_memory_with_saved_content_preparing' : 'online_memory_ready';
+      level = pendingTotal > 0 ? 'limited' : 'ready';
+      headline = pendingTotal > 0
+        ? 'Online. Memory is ready. Some saved content is still being prepared.'
+        : 'Online. Memory is ready.';
+      if (pendingTotal > 0) {
+        attention.push('Some saved content is still being prepared.');
+        action = 'Let Aquifer finish preparing saved content.';
+      }
+    }
+  }
+
+  const capabilities = {
+    service: 'online',
+    savedContent: savedContent ? (starter ? 'local_available' : 'available') : 'empty',
+    memory: starter
+      ? 'requires_full_storage'
+      : fullMemoryReady
+        ? 'available'
+        : !fullMemoryEnabled
+          ? 'preparing'
+          : !fullMemoryLinked
+            ? 'not_linked'
+            : fullMemoryEmpty
+              ? 'empty'
+              : 'preparing',
+    savedContentPreparation: pendingTotal > 0 ? 'preparing' : 'ready',
+  };
+
+  return {
+    kind: 'aquifer_status',
+    code,
+    level,
+    headline,
+    available,
+    attention: [...new Set(attention)],
+    action,
+    capabilities,
+  };
+}
+
+function buildReadinessSurface(stats = {}, context = {}) {
+  const productStatus = buildReadinessProductStatus(stats);
+  const nextActions = productStatus.action === 'No action required.'
+    ? []
+    : [productStatus.action];
+  return {
+    status: productStatus.level === 'ready'
+      ? 'ready'
+      : productStatus.level === 'empty'
+        ? 'empty'
+        : 'partial',
+    summary: productStatus.headline,
+    answer: productStatus.headline,
+    works: productStatus.available.slice(),
+    needs: productStatus.attention.slice(),
+    nextStep: productStatus.action,
+    checks: Array.isArray(context.checks) ? context.checks : [],
+    nextActions,
+    productStatus,
+  };
+}
+
+function numericCount(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function buildBacklogProductStatus(input = {}) {
+  const statusCounts = input.statusCounts && typeof input.statusCounts === 'object'
+    ? input.statusCounts
+    : {};
+  const pending = numericCount(statusCounts.pending ?? input.pending);
+  const failed = numericCount(statusCounts.failed ?? input.failed);
+  const explicitTotal = input.total === undefined ? null : numericCount(input.total);
+  const total = explicitTotal === null ? pending + failed : explicitTotal;
+
+  let code = 'clear';
+  let level = 'ready';
+  let headline = 'All saved content is ready.';
+  let action = 'No action required.';
+
+  if (total > 0 && pending > 0 && failed > 0) {
+    code = 'mixed_attention';
+    level = 'attention';
+    headline = 'Some saved content is still being prepared.';
+    action = 'Finish preparing saved content, then review items with errors.';
+  } else if (total > 0 && failed > 0) {
+    code = 'needs_review';
+    level = 'attention';
+    headline = 'Some saved content needs review.';
+    action = 'Review items with errors before retrying or closing them.';
+  } else if (total > 0) {
+    code = 'recoverable';
+    level = 'limited';
+    headline = 'Some saved content is still being prepared.';
+    action = 'Let Aquifer finish preparing saved content.';
+  }
+
+  return {
+    kind: 'saved_content_status',
+    code,
+    level,
+    headline,
+    action,
+    counts: {
+      total,
+      pending,
+      failed,
+    },
+  };
+}
+
+function renderPresentation(presentation = {}) {
+  const lines = [];
+  for (const row of compactRows(presentation.summaryRows || [])) {
+    lines.push(renderRow(row));
+  }
+
+  for (const warning of presentation.warnings || []) {
+    if (!warning.diagnosticsOnly) lines.push(`Warning: ${warning.text}`);
+  }
+
+  for (const section of presentation.diagnosticSections || []) {
+    const rows = compactRows(section.rows || []);
+    if (rows.length === 0) continue;
+    if (lines.length > 0) lines.push('');
+    lines.push(`${section.title}:`);
+    for (const row of rows) {
+      lines.push(renderRow(row, section.indentRows === false ? '' : '  '));
+    }
+  }
+
+  for (const warning of presentation.warnings || []) {
+    if (warning.diagnosticsOnly) lines.push(`Warning: ${warning.text}`);
+  }
+
+  return lines.join('\n');
+}
+
+function readinessAction(readiness = {}) {
+  if (readiness.nextStep) return readiness.nextStep;
+  if (Array.isArray(readiness.nextActions) && readiness.nextActions.length > 0) {
+    return readiness.nextActions.slice(0, 2).join(' ');
+  }
+  return 'No action required.';
+}
+
+function buildStatsPresentation(stats = {}, opts = {}) {
+  const diagnostics = opts.diagnostics === true;
+  const readiness = stats.readiness?.productStatus
+    ? stats.readiness
+    : buildReadinessSurface(stats, { checks: stats.readiness?.checks || [] });
+  const productStatus = readiness.productStatus || buildReadinessProductStatus(stats);
+  const presentation = {
+    kind: 'memory_stats',
+    summaryRows: compactRows([
+      {
+        id: 'status',
+        label: 'Aquifer status',
+        value: productStatus.headline || readiness.summary || readiness.answer || 'unavailable.',
+      },
+      {
+        id: 'available',
+        label: 'Available',
+        value: Array.isArray(productStatus.available) && productStatus.available.length > 0 ? productStatus.available : null,
+      },
+      {
+        id: 'attention',
+        label: 'Attention',
+        value: Array.isArray(productStatus.attention) && productStatus.attention.length > 0 ? productStatus.attention : null,
+      },
+      {
+        id: 'action',
+        label: 'Action',
+        value: productStatus.action || readinessAction(readiness),
+      },
+    ]),
+    diagnosticSections: [],
+    warnings: [],
+  };
+
+  if (!diagnostics) return presentation;
+
+  const sessionRows = compactRows([
+    { id: 'backend', label: 'Backend', value: `${stats.backendKind || 'unknown'} (${stats.backendProfile || 'unknown'})` },
+    { id: 'serving_mode', label: 'Serving mode', value: stats.serving?.mode || 'legacy' },
+    { id: 'active_scope', label: 'Active scope', value: stats.serving?.activeScopePath?.join(' > ') || stats.serving?.activeScopeKey || 'none' },
+    { id: 'sessions', label: 'Sessions', value: `${stats.sessionTotal ?? 0}${formatSessionStatuses(stats.sessions || {})}` },
+    stats.pendingSessions?.available
+      ? { id: 'actionable_pending', label: 'Actionable pending/failed', value: stats.pendingSessions.total ?? 0 }
+      : null,
+    { id: 'summaries', label: 'Summaries', value: stats.summaries ?? 0 },
+    { id: 'turn_embeddings', label: 'Turn embeddings', value: stats.turnEmbeddings ?? 0 },
+    { id: 'entities', label: 'Entities', value: stats.entities ?? 0 },
+  ]);
+
+  if (stats.memoryRecords) {
+    sessionRows.push(
+      {
+        id: 'memory_records',
+        label: 'Memory records',
+        value: `${stats.memoryRecords.total ?? 0} (${stats.memoryRecords.active ?? 0} active, ${stats.memoryRecords.visibleInRecall ?? 0} recall-visible, ${stats.memoryRecords.visibleInBootstrap ?? 0} bootstrap-visible)`,
+      }
+    );
+    if (stats.memoryRecords.latest) {
+      sessionRows.push({
+        id: 'memory_record_range',
+        label: 'Memory record range',
+        value: `${formatDate(stats.memoryRecords.earliest)}..${formatDate(stats.memoryRecords.latest)}`,
+      });
+    }
+  }
+
+  if (stats.sessionFinalizations?.available) {
+    const statusText = Object.entries(stats.sessionFinalizations.statuses || {})
+      .map(([status, count]) => `${status}: ${count}`)
+      .join(', ') || 'none';
+    sessionRows.push({
+      id: 'session_finalizations',
+      label: 'Session finalizations',
+      value: `${stats.sessionFinalizations.total ?? 0} (${statusText})`,
+    });
+    if (stats.sessionFinalizations.latestFinalizedAt) {
+      sessionRows.push({
+        id: 'latest_finalization',
+        label: 'Latest finalization',
+        value: formatDate(stats.sessionFinalizations.latestFinalizedAt),
+      });
+    }
+  }
+
+  if (stats.earliest) {
+    sessionRows.push({
+      id: 'range',
+      label: 'Range',
+      value: `${formatDate(stats.earliest)}..${formatDate(stats.latest)}`,
+    });
+  }
+
+  presentation.diagnosticSections.push({
+    id: 'storage',
+    title: 'Diagnostics',
+    rows: sessionRows,
+  });
+
+  if ((stats.serving?.mode || 'legacy') !== 'curated') {
+    presentation.warnings.push({
+      id: 'legacy_serving',
+      diagnosticsOnly: true,
+      text: 'legacy serving returns session/evidence material; configure curated serving with an active scope for current-memory status.',
+    });
+  }
+
+  return presentation;
+}
+
+function buildStatsEnvelope(stats = {}, opts = {}) {
+  const diagnostics = opts.diagnostics === true;
+  const readiness = stats.readiness?.productStatus
+    ? stats.readiness
+    : buildReadinessSurface(stats, { checks: stats.readiness?.checks || [] });
+  const productStatus = readiness.productStatus || buildReadinessProductStatus(stats);
+  const presentation = buildStatsPresentation(stats, { diagnostics });
+  const envelope = {
+    kind: 'memory_stats',
+    productStatus,
+    readiness: {
+      status: readiness.status,
+      summary: readiness.summary,
+      answer: readiness.answer,
+      works: Array.isArray(readiness.works) ? readiness.works.slice() : [],
+      needs: Array.isArray(readiness.needs) ? readiness.needs.slice() : [],
+      nextStep: readiness.nextStep || readinessAction(readiness),
+      nextActions: Array.isArray(readiness.nextActions) ? readiness.nextActions.slice() : [],
+      productStatus,
+    },
+    summaryRows: presentation.summaryRows,
+  };
+
+  if (diagnostics) {
+    envelope.diagnostics = {
+      raw: stats,
+      sections: presentation.diagnosticSections,
+      warnings: presentation.warnings,
+    };
+  }
+
+  return envelope;
+}
+
+function formatSessionStatuses(statuses = {}) {
+  const entries = Object.entries(statuses);
+  if (entries.length === 0) return '';
+  return ` (${entries.map(([status, count]) => `${status}: ${count}`).join(', ')})`;
+}
+
+function pendingSummary(report = {}) {
+  if (report.publicStatus?.headline) return report.publicStatus.headline;
+  if (report.summary) return report.summary;
+  return buildBacklogProductStatus(report).headline;
+}
+
+function pendingAction(report = {}) {
+  if (report.publicStatus?.action) return report.publicStatus.action;
+  if (report.nextStep) return report.nextStep;
+  return buildBacklogProductStatus(report).action;
+}
+
+function planRow(plan = {}) {
+  if (!plan.action || plan.action === 'inspect') return null;
+  return {
+    id: 'plan',
+    label: 'Plan',
+    value: `${plan.action} allowed=${plan.allowed ?? 0} blocked=${plan.blocked ?? 0} dry-run`,
+  };
+}
+
+function buildBacklogPresentation(report = {}, opts = {}) {
+  const diagnostics = opts.diagnostics === true;
+  const includePlan = opts.includePlan === true;
+  const presentation = {
+    kind: 'memory_pending',
+    summaryRows: compactRows([
+      { id: 'status', label: 'Saved content status', value: pendingSummary(report) },
+      { id: 'action', label: 'Action', value: pendingAction(report) },
+      includePlan ? planRow(report.plan || {}) : null,
+    ]),
+    diagnosticSections: [],
+    warnings: [],
+  };
+
+  if (!diagnostics) return presentation;
+
+  const detailRows = [
+    { id: 'actionable_backlog', label: 'Actionable backlog', value: report.total ?? 0 },
+  ];
+  const filters = report.filters || {};
+  if (filters.source || filters.agentId || filters.statuses?.length) {
+    detailRows.push({
+      id: 'filters',
+      label: 'Filters',
+      value: `source=${filters.source || '*'} agent=${filters.agentId || '*'} status=${(filters.statuses || []).join(',') || '*'}`,
+    });
+  }
+  presentation.diagnosticSections.push({
+    id: 'backlog',
+    title: 'Diagnostics',
+    rows: detailRows,
+  });
+
+  if (report.terminalFiltering === false) {
+    presentation.warnings.push({
+      id: 'terminal_filtering_unavailable',
+      diagnosticsOnly: true,
+      text: 'session_finalizations table is unavailable; terminal finalization filtering was not applied.',
+    });
+  }
+
+  const groups = Array.isArray(report.groups) ? report.groups : [];
+  if (groups.length > 0) {
+    presentation.diagnosticSections.push({
+      id: 'buckets',
+      title: 'Buckets',
+      rows: groups.map(group => ({
+        id: `${group.source}:${group.agentId}:${group.status}`,
+        value: `${group.source}/${group.agentId} [${group.status}] count=${group.count} range=${formatDate(group.earliest)}..${formatDate(group.latest)} users=${group.userCount} messages=${group.msgCount}`,
+      })),
+    });
+  }
+
+  const guidance = Array.isArray(report.guidance) ? report.guidance : [];
+  if (guidance.length > 0) {
+    presentation.diagnosticSections.push({
+      id: 'guidance',
+      title: 'Guidance',
+      rows: guidance.map(item => ({
+        id: item.status,
+        value: `${item.status}: prefer ${item.recommendedAction}; ${item.reason}`,
+      })),
+    });
+  }
+
+  const samples = Array.isArray(report.samples) ? report.samples : [];
+  if (samples.length > 0) {
+    presentation.diagnosticSections.push({
+      id: 'samples',
+      title: 'Samples',
+      rows: samples.slice(0, 10).map(row => {
+        const suffix = row.processingError ? ` error=${String(row.processingError).slice(0, 80)}` : '';
+        return {
+          id: row.sessionId,
+          value: `${row.sessionId} source=${row.source} agent=${row.agentId} status=${row.status} started=${formatDate(row.startedAt)}${suffix}`,
+        };
+      }),
+    });
+  }
+
+  if (includePlan && report.plan?.action && report.plan.action !== 'inspect') {
+    const rows = (report.plan.notes || []).map((note, index) => ({
+      id: `note_${index}`,
+      value: note,
+    }));
+    if (rows.length > 0) {
+      presentation.diagnosticSections.push({
+        id: 'plan_notes',
+        title: 'Plan notes',
+        rows,
+      });
+    }
+  }
+
+  return presentation;
+}
+
+function buildBacklogEnvelope(report = {}, opts = {}) {
+  const diagnostics = opts.diagnostics === true;
+  const includePlan = opts.includePlan === true;
+  const publicStatus = report.publicStatus || buildBacklogProductStatus(report);
+  const presentation = buildBacklogPresentation(report, { diagnostics, includePlan });
+  const envelope = {
+    kind: 'memory_pending',
+    publicStatus,
+    productStatus: publicStatus,
+    summaryRows: presentation.summaryRows,
+  };
+
+  if (includePlan && report.plan?.action && report.plan.action !== 'inspect') {
+    envelope.plan = {
+      action: report.plan.action,
+      dryRunOnly: report.plan.dryRunOnly !== false,
+      allowed: report.plan.allowed ?? 0,
+      blocked: report.plan.blocked ?? 0,
+    };
+  }
+
+  if (diagnostics) {
+    envelope.diagnostics = {
+      raw: report,
+      sections: presentation.diagnosticSections,
+      warnings: presentation.warnings,
+    };
+  }
+
+  return envelope;
+}
+
+function buildPendingRowsPresentation(rows = [], opts = {}) {
+  const diagnostics = opts.diagnostics === true;
+  const total = rows.length;
+  const statusCounts = {};
+  for (const row of rows) {
+    const status = row?.processing_status;
+    if (!status) continue;
+    statusCounts[status] = (statusCounts[status] || 0) + 1;
+  }
+  const publicStatus = buildBacklogProductStatus({ total, statusCounts });
+  const presentation = {
+    kind: 'memory_pending',
+    summaryRows: [
+      {
+        id: 'status',
+        label: 'Saved content status',
+        value: publicStatus.headline,
+      },
+      {
+        id: 'action',
+        label: 'Action',
+        value: publicStatus.action,
+      },
+    ],
+    diagnosticSections: [],
+    warnings: [],
+  };
+
+  if (!diagnostics) return presentation;
+
+  presentation.diagnosticSections.push({
+    id: 'backlog',
+    title: 'Diagnostics',
+    rows: [{ id: 'actionable_backlog', label: 'Actionable backlog', value: total }],
+  });
+  if (total > 0) {
+    presentation.diagnosticSections.push({
+      id: 'samples',
+      title: 'Samples',
+      rows: rows.slice(0, 10).map(row => ({
+        id: row.session_id,
+        value: `${row.session_id} source=${row.source || 'api'} agent=${row.agent_id} status=${row.processing_status}`,
+      })),
+    });
+  }
+
+  return presentation;
+}
+
+function formatMemoryStatsInterface(stats = {}, opts = {}) {
+  return renderPresentation(buildStatsPresentation(stats, opts));
+}
+
+function formatPendingWorkInterface(report = {}, opts = {}) {
+  return renderPresentation(buildBacklogPresentation(report, opts));
+}
+
+function formatPendingRowsInterface(rows = [], opts = {}) {
+  return renderPresentation(buildPendingRowsPresentation(rows, opts));
+}
+
+module.exports = {
+  buildBacklogEnvelope,
+  buildBacklogPresentation,
+  buildBacklogProductStatus,
+  buildPendingRowsPresentation,
+  buildReadinessProductStatus,
+  buildReadinessSurface,
+  buildStatsEnvelope,
+  buildStatsPresentation,
+  formatDate,
+  formatMemoryStatsInterface,
+  formatPendingRowsInterface,
+  formatPendingWorkInterface,
+  renderPresentation,
+};

package/core/mcp-manifest.js

@@ -137,6 +137,8 @@ const MCP_TOOL_MANIFEST = Object.freeze([
         source: { type: 'string', description: 'Filter by source (e.g., gateway, cc)' },
         dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
         dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+        host: { type: 'string', description: 'Audit boundary host filter' },
+        sessionId: { type: 'string', description: 'Audit boundary session ID filter' },
         entities: { type: 'array', items: { type: 'string' }, description: 'Entity names to match' },
         entityMode: { type: 'string', enum: ['any', 'all'], description: '"any" (default, boost) or "all" hard filter' },
         mode: { type: 'string', enum: ['fts', 'hybrid', 'vector'], description: 'Legacy evidence recall mode' },
@@ -179,21 +181,27 @@ const MCP_TOOL_MANIFEST = Object.freeze([
   },
   {
     name: 'memory_stats',
-    description: 'Return storage statistics for the Aquifer memory store, serving mode, current-memory record coverage, and session date range.',
+    description: 'Return current operational Aquifer product status. For user-facing status/readiness/health requests, treat this tool result as the answer boundary: report the service state, availability, attention, and action. Do not merge repository, package, release, local-development, project-ledger, log, source-search, or historical-memory detail unless the user explicitly asks for diagnostic/development detail. Set diagnostics=true for raw storage counters.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
-      properties: {},
+      properties: {
+        diagnostics: { type: 'boolean', description: 'Include raw storage counters and serving diagnostics. Default false.' },
+      },
     },
   },
   {
     name: 'memory_pending',
-    description: 'List sessions with pending or failed processing status.',
+    description: 'Return current saved-content preparation status. Use this as the operational backlog/readiness surface after product status when the user needs preparation state or review action. Do not merge repository, package, release, local-development, project-ledger, log, source-search, or historical-memory detail unless the user explicitly asks for diagnostic/development detail. Set diagnostics=true for grouped actionable pending or failed sessions.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
       properties: {
         limit: { type: 'integer', minimum: 1, maximum: 200, description: 'Max results (default 20)' },
+        source: { type: 'string', description: 'Filter by source' },
+        agentId: { type: 'string', description: 'Filter by agent ID' },
+        status: { type: 'string', enum: ['pending', 'failed'], description: 'Filter by processing status' },
+        diagnostics: { type: 'boolean', description: 'Include source/agent/status buckets, guidance, and samples. Default false.' },
       },
     },
   },