@a5c-ai/krate 5.0.1-staging.04a3db697

package/src/agent-memory-import.js

@@ -0,0 +1,327 @@
+/**
+ * Agent Memory Import & Snapshot — Slice 2.3c
+ *
+ * Provides:
+ *  - parseJournalForImport: parse a babysitter .a5c journal into a summary-only import payload
+ *  - validateMemoryImport: validate an AgentRunMemoryImport spec
+ *  - createMemorySnapshot: create a dispatch-time memory snapshot pinning record refs
+ *  - validateMemorySnapshot: validate an AgentMemorySnapshot
+ *  - validateOntology: validate an AgentMemoryOntology spec
+ *  - getOntologyNodeKinds: return nodeKinds array from an ontology spec
+ *  - getOntologyEdgeKinds: return edgeKinds array from an ontology spec
+ *
+ * Boundary: agent-memory-import
+ * - owns: journal parsing, summary extraction, snapshot creation, ontology validation
+ * - delegatesTo: (none — pure data transformation)
+ * - mustNotOwn: persistence, HTTP routing, Kubernetes resources, secret handling, git operations
+ */
+
+import { randomBytes } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Journal parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a babysitter .a5c journal array into a summary-only import payload.
+ * Returns structural metadata only — no raw task content, no arbitrary effect payloads.
+ *
+ * @param {Array} journal - Array of journal event objects
+ * @returns {{ summary: object, keyEvents: Array, effectSummary: object }}
+ */
+export function parseJournalForImport(journal) {
+  if (!Array.isArray(journal) || journal.length === 0) {
+    return {
+      summary: {
+        runId: null,
+        processId: null,
+        eventCount: 0,
+        durationMs: 0,
+        runStatus: null,
+      },
+      keyEvents: [],
+      effectSummary: {
+        successCount: 0,
+        failureCount: 0,
+        effectKinds: [],
+      },
+    };
+  }
+
+  // Extract run metadata from run_start event
+  const runStart = journal.find(e => e.type === 'run_start');
+  const runEnd = journal.find(e => e.type === 'run_end');
+
+  const runId = runStart?.runId ?? null;
+  const processId = runStart?.processId ?? null;
+  const runStatus = runEnd?.status ?? null;
+
+  // Compute duration from timestamps
+  let durationMs = 0;
+  if (runStart?.timestamp && runEnd?.timestamp) {
+    const startMs = Date.parse(runStart.timestamp);
+    const endMs = Date.parse(runEnd.timestamp);
+    if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+      durationMs = endMs - startMs;
+    }
+  }
+
+  // Extract key events (structural, no raw content)
+  const keyEvents = [];
+  let successCount = 0;
+  let failureCount = 0;
+  const effectKindSet = new Set();
+
+  for (const event of journal) {
+    switch (event.type) {
+      case 'run_start':
+        keyEvents.push({
+          type: 'run_start',
+          runId: event.runId ?? null,
+          processId: event.processId ?? null,
+          timestamp: event.timestamp ?? null,
+        });
+        break;
+
+      case 'task_completed': {
+        const keyEvent = {
+          type: 'task_completed',
+          taskId: event.taskId ?? null,
+          title: event.title ?? null,
+          status: event.status ?? null,
+          timestamp: event.timestamp ?? null,
+        };
+        // Strip raw effect to summary-only (kind + result only)
+        if (event.effect && typeof event.effect === 'object') {
+          keyEvent.effect = {
+            kind: event.effect.kind ?? null,
+            result: event.effect.result ?? null,
+          };
+          if (event.effect.kind) effectKindSet.add(event.effect.kind);
+          if (event.effect.result === 'success') successCount++;
+          else if (event.effect.result === 'failure') failureCount++;
+        } else if (event.status === 'success') {
+          successCount++;
+        } else if (event.status === 'failure') {
+          failureCount++;
+        }
+        keyEvents.push(keyEvent);
+        break;
+      }
+
+      case 'breakpoint':
+        keyEvents.push({
+          type: 'breakpoint',
+          reason: event.reason ?? null,
+          timestamp: event.timestamp ?? null,
+        });
+        break;
+
+      case 'run_end':
+        keyEvents.push({
+          type: 'run_end',
+          status: event.status ?? null,
+          timestamp: event.timestamp ?? null,
+        });
+        break;
+
+      default:
+        // Include other event types with only structural metadata
+        keyEvents.push({
+          type: event.type,
+          timestamp: event.timestamp ?? null,
+        });
+        break;
+    }
+  }
+
+  return {
+    summary: {
+      runId,
+      processId,
+      eventCount: journal.length,
+      durationMs,
+      runStatus,
+    },
+    keyEvents,
+    effectSummary: {
+      successCount,
+      failureCount,
+      effectKinds: Array.from(effectKindSet),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateMemoryImport
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AgentRunMemoryImport spec.
+ *
+ * @param {object} importSpec
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateMemoryImport(importSpec) {
+  const errors = [];
+
+  if (!importSpec || typeof importSpec !== 'object') {
+    return { valid: false, errors: ['importSpec must be a non-null object'] };
+  }
+
+  if (!importSpec.name || typeof importSpec.name !== 'string' || importSpec.name.trim() === '') {
+    errors.push('name is required and must be a non-empty string');
+  }
+
+  if (!importSpec.organizationRef || typeof importSpec.organizationRef !== 'string' || importSpec.organizationRef.trim() === '') {
+    errors.push('organizationRef is required and must be a non-empty string');
+  }
+
+  if (!importSpec.runId || typeof importSpec.runId !== 'string' || importSpec.runId.trim() === '') {
+    errors.push('runId is required and must be a non-empty string');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// createMemorySnapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a dispatch-time memory snapshot pinning record refs.
+ *
+ * @param {object} params
+ * @param {string} params.sessionRef        - The agent session reference (required)
+ * @param {string} params.organizationRef   - Organization reference
+ * @param {Array}  params.recordRefs        - Array of record reference strings
+ * @param {object} [params.queryCriteria]   - Optional query criteria used to select records
+ * @returns {object} snapshot
+ */
+export function createMemorySnapshot({ sessionRef, organizationRef, recordRefs = [], queryCriteria }) {
+  const snapshotId = `snap-${randomBytes(8).toString('hex')}`;
+  const createdAt = new Date().toISOString();
+
+  const snapshot = {
+    snapshotId,
+    sessionRef: sessionRef ?? null,
+    organizationRef: organizationRef ?? null,
+    recordRefs: Array.isArray(recordRefs) ? [...recordRefs] : [],
+    createdAt,
+  };
+
+  if (queryCriteria !== undefined && queryCriteria !== null) {
+    snapshot.queryCriteria = { ...queryCriteria };
+  }
+
+  return snapshot;
+}
+
+// ---------------------------------------------------------------------------
+// validateMemorySnapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AgentMemorySnapshot object.
+ *
+ * @param {object} snapshot
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateMemorySnapshot(snapshot) {
+  const errors = [];
+
+  if (!snapshot || typeof snapshot !== 'object') {
+    return { valid: false, errors: ['snapshot must be a non-null object'] };
+  }
+
+  if (!snapshot.snapshotId || typeof snapshot.snapshotId !== 'string' || snapshot.snapshotId.trim() === '') {
+    errors.push('snapshotId is required and must be a non-empty string');
+  }
+
+  if (!snapshot.sessionRef || typeof snapshot.sessionRef !== 'string' || snapshot.sessionRef.trim() === '') {
+    errors.push('sessionRef is required and must be a non-empty string');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// validateOntology (standalone)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AgentMemoryOntology spec.
+ *
+ * @param {object} ontologySpec
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateOntology(ontologySpec) {
+  const errors = [];
+
+  if (!ontologySpec || typeof ontologySpec !== 'object') {
+    return { valid: false, errors: ['ontologySpec must be a non-null object'] };
+  }
+
+  if (!ontologySpec.name || typeof ontologySpec.name !== 'string' || ontologySpec.name.trim() === '') {
+    errors.push('name is required and must be a non-empty string');
+  }
+
+  if (!ontologySpec.organizationRef || typeof ontologySpec.organizationRef !== 'string' || ontologySpec.organizationRef.trim() === '') {
+    errors.push('organizationRef is required and must be a non-empty string');
+  }
+
+  // nodeKinds must be a non-empty array
+  const nodeKinds = ontologySpec.nodeKinds;
+  if (!Array.isArray(nodeKinds) || nodeKinds.length === 0) {
+    errors.push('nodeKinds must be a non-empty array');
+  } else {
+    // Check for duplicate nodeKind names
+    const seen = new Set();
+    for (const nk of nodeKinds) {
+      const kindName = nk?.name;
+      if (kindName !== undefined && kindName !== null) {
+        if (seen.has(kindName)) {
+          errors.push(`Duplicate nodeKind name: "${kindName}"`);
+        } else {
+          seen.add(kindName);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// getOntologyNodeKinds
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the nodeKinds array from an ontology spec.
+ *
+ * @param {object} ontologySpec
+ * @returns {Array}
+ */
+export function getOntologyNodeKinds(ontologySpec) {
+  if (!ontologySpec || !Array.isArray(ontologySpec.nodeKinds)) {
+    return [];
+  }
+  return [...ontologySpec.nodeKinds];
+}
+
+// ---------------------------------------------------------------------------
+// getOntologyEdgeKinds
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the edgeKinds array from an ontology spec.
+ *
+ * @param {object} ontologySpec
+ * @returns {Array}
+ */
+export function getOntologyEdgeKinds(ontologySpec) {
+  if (!ontologySpec || !Array.isArray(ontologySpec.edgeKinds)) {
+    return [];
+  }
+  return [...ontologySpec.edgeKinds];
+}

package/src/agent-memory-query.js

@@ -0,0 +1,292 @@
+/**
+ * Agent Memory Query Engine
+ *
+ * Standalone query engine for in-memory graph traversal and document grep.
+ * No external dependencies — operates purely on plain JS data structures.
+ *
+ * Boundary: agent-memory-query
+ * - owns: graph traversal, relevance scoring, text grep, context extraction, combined query execution
+ * - delegatesTo: (none — pure data transformation)
+ * - mustNotOwn: persistence, HTTP routing, Kubernetes resources, secret handling
+ */
+
+export const AGENT_MEMORY_QUERY_BOUNDARY = {
+  role: 'agent-memory-query',
+  scope: 'In-memory graph traversal and full-text grep query execution for agent memory documents',
+  owns: ['graph traversal', 'nodeKind filtering', 'edge following', 'relevance scoring', 'full-text grep', 'context extraction', 'combined query execution'],
+  delegatesTo: [],
+  mustNotOwn: ['persistence', 'HTTP routing', 'Kubernetes resources', 'secret handling'],
+};
+
+const VALID_MODES = ['graph-only', 'grep-only', 'graph-and-grep'];
+
+// ---------------------------------------------------------------------------
+// Graph query
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a graph query over a set of records.
+ *
+ * @param {object} params
+ * @param {Array}  params.records   - Array of graph records. Each record has { id, nodeKind, attributes, edges }.
+ * @param {Array}  [params.edges]   - Optional flat edges array { source, target, kind }. If provided these
+ *                                    supplement per-record edges during traversal.
+ * @param {string} params.query     - Search text (required, must be non-empty).
+ * @param {Array}  [params.kinds]   - nodeKind filter. Empty array means "no filter".
+ * @param {number} [params.depth]   - Edge-follow depth (default 1).
+ * @returns {{ matches: Array, totalMatches: number }}
+ */
+export function queryGraph({ records = [], edges = [], query, kinds = [], depth = 1 }) {
+  if (query === undefined || query === null) {
+    throw new Error('queryGraph: query text is required');
+  }
+  if (typeof query !== 'string' || query.trim() === '') {
+    throw new Error('queryGraph: query text must be a non-empty string');
+  }
+
+  // Build adjacency index from flat edges + per-record edges
+  const adjacency = buildAdjacency(records, edges);
+
+  // Filter by nodeKind
+  let candidates = records;
+  if (kinds.length > 0) {
+    candidates = candidates.filter(r => kinds.includes(r.nodeKind));
+  }
+
+  const lowerQuery = query.toLowerCase();
+  const matches = [];
+
+  for (const record of candidates) {
+    const score = scoreRecord(record, lowerQuery);
+    if (score === 0) continue;
+
+    const followedEdges = followEdges(record.id, adjacency, depth);
+
+    matches.push({
+      record: shallowClone(record),
+      score,
+      edges: followedEdges,
+    });
+  }
+
+  // Sort by descending score for deterministic output
+  matches.sort((a, b) => b.score - a.score);
+
+  return { matches, totalMatches: matches.length };
+}
+
+/**
+ * Execute a grep query over a set of documents.
+ *
+ * @param {object}   params
+ * @param {Array}    params.documents   - Array of { path: string, content: string }.
+ * @param {string}   params.query       - Search text (required, must be non-empty).
+ * @param {Array}    [params.paths]     - Optional glob-style path filters.
+ * @param {number}   [params.context]   - Number of context lines above/below each match (default 1).
+ * @param {number}   [params.maxMatches] - Maximum number of excerpts to return (default 25).
+ * @returns {{ excerpts: Array, totalMatches: number }}
+ */
+export function queryGrep({ documents = [], query, paths = [], context = 1, maxMatches = 25 }) {
+  if (query === undefined || query === null) {
+    throw new Error('queryGrep: query text is required');
+  }
+  if (typeof query !== 'string' || query.trim() === '') {
+    throw new Error('queryGrep: query text must be a non-empty string');
+  }
+
+  // Filter by path globs
+  let filtered = documents;
+  if (paths.length > 0) {
+    filtered = documents.filter(doc => paths.some(p => globMatch(p, doc.path)));
+  }
+
+  const lowerQuery = query.toLowerCase();
+  const excerpts = [];
+
+  for (const doc of filtered) {
+    if (excerpts.length >= maxMatches) break;
+
+    const lines = String(doc.content || '').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (excerpts.length >= maxMatches) break;
+
+      const lowerLine = lines[i].toLowerCase();
+      if (!lowerLine.includes(lowerQuery)) continue;
+
+      // Build highlighted line: mark matched span
+      const matchStart = lowerLine.indexOf(lowerQuery);
+      const matchEnd = matchStart + query.length;
+      const highlighted =
+        lines[i].slice(0, matchStart) +
+        '**' + lines[i].slice(matchStart, matchEnd) + '**' +
+        lines[i].slice(matchEnd);
+
+      // Context lines
+      const ctxStart = Math.max(0, i - context);
+      const ctxEnd = Math.min(lines.length - 1, i + context);
+      const contextLines = lines.slice(ctxStart, ctxEnd + 1);
+
+      excerpts.push({
+        path: doc.path,
+        lineNumber: i + 1,
+        line: lines[i],
+        highlighted,
+        context: contextLines.join('\n'),
+        contextStart: ctxStart + 1,
+        contextEnd: ctxEnd + 1,
+      });
+    }
+  }
+
+  return { excerpts, totalMatches: excerpts.length };
+}
+
+/**
+ * Execute a combined query (graph + grep or either alone).
+ *
+ * @param {object}  params
+ * @param {string}  params.query        - Search text (required).
+ * @param {string}  [params.mode]       - 'graph-and-grep' | 'graph-only' | 'grep-only' (default 'graph-and-grep').
+ * @param {Array}   [params.records]    - Graph records.
+ * @param {Array}   [params.edges]      - Flat edge list.
+ * @param {Array}   [params.documents]  - Grep documents.
+ * @param {object}  [params.graphOptions] - Passed to queryGraph: { kinds, depth }.
+ * @param {object}  [params.grepOptions]  - Passed to queryGrep: { paths, context, maxMatches }.
+ * @returns {{ graph: object|null, grep: object|null, stats: object }}
+ */
+export function queryMemory({
+  query,
+  mode = 'graph-and-grep',
+  records = [],
+  edges = [],
+  documents = [],
+  graphOptions = {},
+  grepOptions = {},
+}) {
+  if (!VALID_MODES.includes(mode)) {
+    throw new Error(`queryMemory: invalid mode "${mode}". Must be one of: ${VALID_MODES.join(', ')}`);
+  }
+  if (query === undefined || query === null) {
+    throw new Error('queryMemory: query text is required');
+  }
+  if (typeof query !== 'string' || query.trim() === '') {
+    throw new Error('queryMemory: query text must be a non-empty string');
+  }
+
+  let graphResult = null;
+  let grepResult = null;
+
+  if (mode === 'graph-only' || mode === 'graph-and-grep') {
+    graphResult = queryGraph({
+      records,
+      edges,
+      query,
+      kinds: graphOptions.kinds || [],
+      depth: graphOptions.depth ?? 1,
+    });
+  }
+
+  if (mode === 'grep-only' || mode === 'graph-and-grep') {
+    grepResult = queryGrep({
+      documents,
+      query,
+      paths: grepOptions.paths || [],
+      context: grepOptions.context ?? 1,
+      maxMatches: grepOptions.maxMatches ?? 25,
+    });
+  }
+
+  const graphCount = graphResult ? graphResult.totalMatches : 0;
+  const grepCount = grepResult ? grepResult.totalMatches : 0;
+  const totalMatches = graphCount + grepCount;
+
+  return {
+    graph: graphResult,
+    grep: grepResult,
+    stats: {
+      mode,
+      totalMatches,
+      graphCount,
+      grepCount,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build adjacency map: nodeId -> [{ target, kind, source }]
+ * Merges per-record edges with a flat edge list.
+ */
+function buildAdjacency(records, flatEdges) {
+  const adj = new Map();
+
+  for (const record of records) {
+    if (!adj.has(record.id)) adj.set(record.id, []);
+    for (const edge of record.edges || []) {
+      adj.get(record.id).push({ ...edge, source: record.id });
+    }
+  }
+
+  for (const edge of flatEdges) {
+    const src = edge.source;
+    if (!adj.has(src)) adj.set(src, []);
+    adj.get(src).push({ ...edge });
+  }
+
+  return adj;
+}
+
+/**
+ * Follow edges from a start node up to `maxDepth` hops.
+ * Returns a flat array of edge objects encountered.
+ */
+function followEdges(startId, adjacency, maxDepth) {
+  if (maxDepth <= 0) return [];
+
+  const visited = new Set([startId]);
+  const collected = [];
+  let frontier = [startId];
+
+  for (let d = 0; d < maxDepth; d++) {
+    const nextFrontier = [];
+    for (const nodeId of frontier) {
+      for (const edge of adjacency.get(nodeId) || []) {
+        if (visited.has(edge.target)) continue;
+        visited.add(edge.target);
+        collected.push({ ...edge });
+        nextFrontier.push(edge.target);
+      }
+    }
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+  }
+
+  return collected;
+}
+
+/**
+ * Score a record against a lowercase query string.
+ * Returns 0 (no match), 1 (attribute match), or 2 (id match).
+ */
+function scoreRecord(record, lowerQuery) {
+  const id = String(record.id || '').toLowerCase();
+  const attrs = JSON.stringify(record.attributes || {}).toLowerCase();
+
+  if (id.includes(lowerQuery)) return 2;
+  if (attrs.includes(lowerQuery)) return 1;
+  return 0;
+}
+
+/** Minimal shallow clone to avoid mutation of inputs */
+function shallowClone(obj) {
+  return Object.assign(Object.create(null), obj);
+}
+
+/** Simple glob match: * matches any sequence of characters */
+function globMatch(pattern, path) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`).test(path);
+}