@a5c-ai/krate 5.0.1-staging.660d2b90f → 5.0.1-staging.69cb593ea

package/src/agent-memory-controller.js

@@ -0,0 +1,357 @@
+import { createHash } from 'node:crypto';
+import { createResource, clone } from './resource-model.js';
+import { queryGraph, queryGrep, queryMemory } from './agent-memory-query.js';
+
+export const AGENT_MEMORY_CONTROLLER_BOUNDARY = {
+  role: 'agent-memory-controller',
+  scope: 'Company Brain memory management — search, snapshots, redaction, imports, time-travel',
+  owns: ['memory search', 'snapshot pinning', 'redaction scanning', 'import lifecycle', 'ontology validation'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['git operations', 'secret values', 'Agent Mux sessions']
+};
+
+// Redaction patterns (same as agent-context-bundles)
+const REDACTION_PATTERNS = [
+  { kind: 'secret-key', pattern: /(?:API_KEY|API_SECRET|SECRET_KEY|ACCESS_KEY|PRIVATE_KEY|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)\s*[=:]\s*['"]?([^\s'"}{,\]]+)/gi },
+  { kind: 'provider-token', pattern: /\b(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36,}|gho_[a-zA-Z0-9]{36,}|glpat-[a-zA-Z0-9\-_]{20,}|xoxb-[a-zA-Z0-9\-]+|xoxp-[a-zA-Z0-9\-]+)\b/g },
+  { kind: 'bearer-token', pattern: /Bearer\s+[a-zA-Z0-9\-._~+\/]+=*/gi },
+  { kind: 'private-key', pattern: /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----/g },
+  { kind: 'base64-credential', pattern: /\b[A-Za-z0-9+\/]{40,}={0,2}\b/g },
+];
+
+function sha256(data) {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+const IMPORT_PHASES = ['Pending', 'Collecting', 'Redacting', 'Normalizing', 'Validating', 'AwaitingReview'];
+
+export function createAgentMemoryController(options = {}) {
+  return {
+    role: 'agent-memory-controller',
+
+    createMemorySnapshot({ memoryRepository, requestedRef, resolvedCommit, queryManifest, selectedRecords, selectedDocuments, ontologyDigest, namespace = 'default', organizationRef = 'default' }) {
+      const queryManifestDigest = sha256(JSON.stringify(queryManifest || {}));
+      const selectedRecordsDigest = sha256(JSON.stringify(selectedRecords || []));
+      const selectedDocumentsDigest = sha256(JSON.stringify(selectedDocuments || []));
+
+      const now = new Date().toISOString();
+      const snapshotName = `memsnapshot-${sha256(memoryRepository + resolvedCommit + now).slice(0, 12)}`;
+
+      const snapshot = createResource('AgentMemorySnapshot', { name: snapshotName, namespace }, {
+        organizationRef,
+        memoryRepository,
+        requestedRef,
+        resolvedCommit,
+        queryManifestDigest,
+        selectedRecordsDigest,
+        selectedDocumentsDigest,
+        ontologyDigest: ontologyDigest || '',
+        recordCount: (selectedRecords || []).length,
+        documentCount: (selectedDocuments || []).length,
+      });
+      snapshot.status = { phase: 'Pinned', createdAt: now };
+
+      return snapshot;
+    },
+
+    queryMemory({ snapshotRef, requester, query, records = [], documents = [], namespace = 'default', organizationRef = 'default' }) {
+      const modes = query.modes || ['graph-and-grep'];
+      const results = { graph: null, grep: null };
+
+      if (modes.includes('graph-only') || modes.includes('graph-and-grep')) {
+        results.graph = this.searchGraph({
+          records,
+          kinds: query.graph?.kinds || [],
+          edgeDepth: query.graph?.edgeDepth ?? 2,
+          query: query.text || '',
+        });
+      }
+
+      if (modes.includes('grep-only') || modes.includes('graph-and-grep')) {
+        results.grep = this.searchGrep({
+          documents,
+          paths: query.grep?.paths || [],
+          pattern: query.text || '',
+          maxMatches: query.grep?.maxMatches ?? 25,
+        });
+      }
+
+      const now = new Date().toISOString();
+      const queryName = `memquery-${sha256(snapshotRef + requester + now).slice(0, 12)}`;
+
+      const queryResource = createResource('AgentMemoryQuery', { name: queryName, namespace }, {
+        organizationRef,
+        snapshotRef,
+        requester,
+        query: clone(query),
+        resultDigest: sha256(JSON.stringify(results)),
+      });
+      queryResource.status = { phase: 'Completed', executedAt: now };
+
+      return { queryResource, results };
+    },
+
+    /**
+     * Execute a memory search using the real query engine (agent-memory-query.js).
+     *
+     * @param {object}  params
+     * @param {string}  params.query        - Search text (required, non-empty).
+     * @param {string}  [params.mode]       - 'graph-only' | 'grep-only' | 'graph-and-grep' (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 }}
+     */
+    queryAgentMemory({ query, mode = 'graph-and-grep', records = [], edges = [], documents = [], graphOptions = {}, grepOptions = {} }) {
+      return queryMemory({ query, mode, records, edges, documents, graphOptions, grepOptions });
+    },
+
+    searchGraph({ records, edges = [], kinds = [], edgeDepth = 2, query = '' }) {
+      // Empty query: return all records matching kinds filter with score=1 (no text match)
+      if (!query || query.trim() === '') {
+        let candidates = records;
+        if (kinds.length > 0) {
+          candidates = candidates.filter(r => kinds.includes(r.nodeKind));
+        }
+        const matches = candidates.map(record => ({
+          record: clone(record),
+          score: 1,
+          edges: this._collectEdges(record, records, edgeDepth),
+        }));
+        return { matches, totalMatches: matches.length };
+      }
+
+      // Non-empty query: delegate to the real query engine
+      return queryGraph({
+        records,
+        edges,
+        query,
+        kinds,
+        depth: edgeDepth,
+      });
+    },
+
+    _collectEdges(startRecord, allRecords, maxDepth) {
+      if (maxDepth <= 0 || !startRecord.edges || startRecord.edges.length === 0) return [];
+
+      const visited = new Set([startRecord.id]);
+      const collectedEdges = [];
+      let frontier = [startRecord];
+
+      for (let depth = 0; depth < maxDepth; depth++) {
+        const nextFrontier = [];
+        for (const record of frontier) {
+          for (const edge of (record.edges || [])) {
+            if (visited.has(edge.target)) continue;
+            visited.add(edge.target);
+            collectedEdges.push(clone(edge));
+            const targetRecord = allRecords.find(r => r.id === edge.target);
+            if (targetRecord) nextFrontier.push(targetRecord);
+          }
+        }
+        frontier = nextFrontier;
+        if (frontier.length === 0) break;
+      }
+
+      return collectedEdges;
+    },
+
+    searchGrep({ documents, paths = [], pattern = '', maxMatches = 25 }) {
+      // Empty pattern: return empty (no-op, preserves backward-compatible behavior)
+      if (!pattern || pattern.trim() === '') {
+        return { excerpts: [], totalMatches: 0 };
+      }
+
+      // Delegate to the real query engine, mapping pattern -> query
+      return queryGrep({
+        documents,
+        query: pattern,
+        paths,
+        maxMatches,
+      });
+    },
+
+    resolveTimeTravel({ mode = 'current', requestedRef, requestedTime, commits = [] }) {
+      const now = new Date().toISOString();
+
+      if (mode === 'current') {
+        const latest = commits[0] || null;
+        return {
+          resolvedCommit: latest?.sha || latest?.id || null,
+          resolvedAt: now,
+          mode: 'current',
+          staleBy: null,
+        };
+      }
+
+      if (mode === 'explicit-ref') {
+        return {
+          resolvedCommit: requestedRef,
+          resolvedAt: now,
+          mode: 'explicit-ref',
+          staleBy: null,
+        };
+      }
+
+      if (mode === 'ref-at-time') {
+        const targetTime = new Date(requestedTime).getTime();
+        let best = null;
+        for (const commit of commits) {
+          const commitTime = new Date(commit.timestamp || commit.date).getTime();
+          if (commitTime <= targetTime) {
+            if (!best || commitTime > new Date(best.timestamp || best.date).getTime()) {
+              best = commit;
+            }
+          }
+        }
+        const resolvedCommit = best?.sha || best?.id || null;
+        const staleBy = best ? (targetTime - new Date(best.timestamp || best.date).getTime()) : null;
+        return {
+          resolvedCommit,
+          resolvedAt: now,
+          mode: 'ref-at-time',
+          staleBy,
+        };
+      }
+
+      if (mode === 'snapshot-tag') {
+        return {
+          resolvedCommit: requestedRef,
+          resolvedAt: now,
+          mode: 'snapshot-tag',
+          staleBy: null,
+        };
+      }
+
+      return { resolvedCommit: null, resolvedAt: now, mode, staleBy: null };
+    },
+
+    createImport({ organizationRef, memoryRepository, source, include, validationPolicy, namespace = 'default' }) {
+      const now = new Date().toISOString();
+      const importName = `memimport-${sha256(memoryRepository + source + now).slice(0, 12)}`;
+
+      const importResource = createResource('AgentRunMemoryImport', { name: importName, namespace }, {
+        organizationRef,
+        memoryRepository,
+        source,
+        include: clone(include),
+        validationPolicy: validationPolicy || 'none',
+      });
+      importResource.status = { phase: 'Pending', createdAt: now };
+
+      return importResource;
+    },
+
+    processImport({ importResource, content }) {
+      const updated = clone(importResource);
+      const currentPhase = updated.status?.phase || 'Pending';
+      const now = new Date().toISOString();
+
+      const currentIndex = IMPORT_PHASES.indexOf(currentPhase);
+      if (currentIndex < 0 || currentIndex >= IMPORT_PHASES.length - 1) {
+        return updated;
+      }
+
+      const nextPhase = IMPORT_PHASES[currentIndex + 1];
+
+      // Apply phase-specific logic
+      if (nextPhase === 'Redacting') {
+        const scan = this.scanForRedaction(content || '');
+        updated.status.redactionScan = {
+          clean: scan.clean,
+          redactionCount: scan.redactionCount,
+          redactionsByKind: clone(scan.redactionsByKind),
+        };
+      }
+
+      updated.status.phase = nextPhase;
+      updated.status.lastTransitionAt = now;
+
+      return updated;
+    },
+
+    scanForRedaction(content) {
+      if (typeof content !== 'string' || content.length === 0) {
+        return { clean: true, redactedContent: content || '', redactionCount: 0, redactionsByKind: {} };
+      }
+
+      let redacted = content;
+      const redactionsByKind = {};
+      let redactionCount = 0;
+
+      for (const { kind, pattern } of REDACTION_PATTERNS) {
+        const fresh = new RegExp(pattern.source, pattern.flags);
+        redacted = redacted.replace(fresh, (match) => {
+          redactionsByKind[kind] = (redactionsByKind[kind] || 0) + 1;
+          redactionCount++;
+          return `[REDACTED:${kind}]`;
+        });
+      }
+
+      return {
+        clean: redactionCount === 0,
+        redactedContent: redacted,
+        redactionCount,
+        redactionsByKind,
+      };
+    },
+
+    validateOntology({ records, ontology }) {
+      const errors = [];
+      const requiredFields = ontology.requiredFields || {};
+      const allowedEdgeKinds = ontology.allowedEdgeKinds || [];
+
+      for (const record of records) {
+        const kind = record.nodeKind;
+        const fields = requiredFields[kind] || [];
+
+        for (const field of fields) {
+          const value = record.attributes?.[field];
+          if (value === undefined || value === null || value === '') {
+            errors.push({
+              record: record.id,
+              field,
+              message: `Missing required field '${field}' for nodeKind '${kind}'`,
+            });
+          }
+        }
+
+        // Check edge kinds
+        for (const edge of (record.edges || [])) {
+          if (allowedEdgeKinds.length > 0 && !allowedEdgeKinds.includes(edge.kind)) {
+            errors.push({
+              record: record.id,
+              field: `edge.kind`,
+              message: `Edge kind '${edge.kind}' is not in allowedEdgeKinds`,
+            });
+          }
+        }
+      }
+
+      return { valid: errors.length === 0, errors };
+    },
+
+    createMemoryUpdate({ memoryRepository, sourceRun, changes, namespace = 'default', organizationRef = 'default' }) {
+      const now = new Date().toISOString();
+      const updateName = `memupdate-${sha256(memoryRepository + sourceRun + now).slice(0, 12)}`;
+
+      const update = createResource('AgentMemoryUpdate', { name: updateName, namespace }, {
+        organizationRef,
+        memoryRepository,
+        sourceRun,
+        changes: clone(changes),
+      });
+      update.status = { phase: 'Pending', createdAt: now };
+
+      return update;
+    },
+  };
+}
+
+function globMatch(pattern, path) {
+  // Simple glob: convert * to regex .*
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`).test(path);
+}

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];
+}