agentflow-core 0.7.0 → 0.8.0

package/dist/index.js

@@ -23,12 +23,655 @@ import {
   stitchTrace,
   toAsciiTree,
   toTimeline
-} from "./chunk-5PRHVYYD.js";
+} from "./chunk-6X5HU5LB.js";
 import {
   graphToJson,
   loadGraph
 } from "./chunk-DY7YHFIB.js";
 
+// src/process-mining.ts
+function getPathSignature(graph) {
+  const root = graph.nodes.get(graph.rootNodeId);
+  if (!root) return "";
+  const parts = [];
+  function walk(node) {
+    parts.push(`${node.type}:${node.name}`);
+    const childNodes = [];
+    for (const childId of node.children) {
+      const child = graph.nodes.get(childId);
+      if (child) childNodes.push(child);
+    }
+    childNodes.sort((a, b) => {
+      const keyA = `${a.type}:${a.name}`;
+      const keyB = `${b.type}:${b.name}`;
+      return keyA.localeCompare(keyB);
+    });
+    for (const child of childNodes) {
+      walk(child);
+    }
+  }
+  walk(root);
+  return parts.join("\u2192");
+}
+function stepKey(node) {
+  return `${node.type}:${node.name}`;
+}
+function discoverProcess(graphs) {
+  if (graphs.length === 0) {
+    throw new Error("discoverProcess requires at least one graph");
+  }
+  const steps = /* @__PURE__ */ new Set();
+  const transitionCounts = /* @__PURE__ */ new Map();
+  const outgoingCounts = /* @__PURE__ */ new Map();
+  for (const graph of graphs) {
+    for (const node of graph.nodes.values()) {
+      const parentKey = stepKey(node);
+      steps.add(parentKey);
+      for (const childId of node.children) {
+        const child = graph.nodes.get(childId);
+        if (!child) continue;
+        const childKey = stepKey(child);
+        const tKey = `${parentKey}\0${childKey}`;
+        transitionCounts.set(tKey, (transitionCounts.get(tKey) ?? 0) + 1);
+        outgoingCounts.set(parentKey, (outgoingCounts.get(parentKey) ?? 0) + 1);
+      }
+    }
+  }
+  const transitions = [];
+  for (const [tKey, count] of transitionCounts) {
+    const [from, to] = tKey.split("\0");
+    const outgoing = outgoingCounts.get(from) ?? count;
+    transitions.push({
+      from,
+      to,
+      count,
+      probability: count / outgoing
+    });
+  }
+  transitions.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+  return {
+    steps: [...steps].sort(),
+    transitions,
+    totalGraphs: graphs.length,
+    agentId: graphs[0].agentId
+  };
+}
+function findVariants(graphs) {
+  if (graphs.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const graph of graphs) {
+    const sig = getPathSignature(graph);
+    const group = groups.get(sig) ?? [];
+    group.push(graph);
+    groups.set(sig, group);
+  }
+  const total = graphs.length;
+  const variants = [];
+  for (const [pathSignature, groupGraphs] of groups) {
+    variants.push({
+      pathSignature,
+      count: groupGraphs.length,
+      percentage: groupGraphs.length / total * 100,
+      graphIds: groupGraphs.map((g) => g.id),
+      exampleGraph: groupGraphs[0]
+    });
+  }
+  variants.sort((a, b) => {
+    const freqDiff = b.count - a.count;
+    if (freqDiff !== 0) return freqDiff;
+    return a.pathSignature.localeCompare(b.pathSignature);
+  });
+  return variants;
+}
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  const index = p / 100 * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sorted[lower];
+  const weight = index - lower;
+  return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+function getBottlenecks(graphs) {
+  if (graphs.length === 0) return [];
+  const now = Date.now();
+  const stats = /* @__PURE__ */ new Map();
+  for (const graph of graphs) {
+    for (const node of graph.nodes.values()) {
+      const key = `${node.type}:${node.name}`;
+      const entry = stats.get(key) ?? { durations: [], nodeType: node.type, nodeName: node.name };
+      const end = node.endTime ?? now;
+      entry.durations.push(end - node.startTime);
+      stats.set(key, entry);
+    }
+  }
+  const total = graphs.length;
+  const bottlenecks = [];
+  for (const [, entry] of stats) {
+    const sorted = [...entry.durations].sort((a, b) => a - b);
+    bottlenecks.push({
+      nodeName: entry.nodeName,
+      nodeType: entry.nodeType,
+      occurrences: sorted.length,
+      durations: {
+        median: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        p99: percentile(sorted, 99),
+        min: sorted[0],
+        max: sorted[sorted.length - 1]
+      },
+      percentOfGraphs: sorted.length / total * 100
+    });
+  }
+  bottlenecks.sort((a, b) => b.durations.p95 - a.durations.p95);
+  return bottlenecks;
+}
+function extractGraphTransitions(graph) {
+  const transitions = /* @__PURE__ */ new Set();
+  for (const node of graph.nodes.values()) {
+    const parentKey = stepKey(node);
+    for (const childId of node.children) {
+      const child = graph.nodes.get(childId);
+      if (!child) continue;
+      transitions.add(`${parentKey}\0${stepKey(child)}`);
+    }
+  }
+  return transitions;
+}
+function checkConformance(graph, model) {
+  const graphTransitions = extractGraphTransitions(graph);
+  const deviations = [];
+  const modelLookup = /* @__PURE__ */ new Map();
+  for (const t of model.transitions) {
+    modelLookup.set(`${t.from}\0${t.to}`, t);
+  }
+  let totalChecks = 0;
+  let deviationCount = 0;
+  for (const tKey of graphTransitions) {
+    totalChecks++;
+    const [from, to] = tKey.split("\0");
+    const modelTransition = modelLookup.get(tKey);
+    if (!modelTransition) {
+      deviationCount++;
+      deviations.push({
+        type: "unexpected-transition",
+        from,
+        to,
+        message: `Unexpected transition ${from} \u2192 ${to} (not in process model)`
+      });
+    } else if (modelTransition.probability < 0.1) {
+      deviationCount++;
+      deviations.push({
+        type: "low-frequency-path",
+        from,
+        to,
+        message: `Low-frequency path ${from} \u2192 ${to} (model probability: ${(modelTransition.probability * 100).toFixed(1)}%)`,
+        modelProbability: modelTransition.probability
+      });
+    }
+  }
+  const graphSteps = /* @__PURE__ */ new Set();
+  for (const node of graph.nodes.values()) {
+    graphSteps.add(stepKey(node));
+  }
+  for (const t of model.transitions) {
+    if (t.probability > 0.5) {
+      const tKey = `${t.from}\0${t.to}`;
+      if (graphSteps.has(t.from) && !graphTransitions.has(tKey)) {
+        totalChecks++;
+        deviationCount++;
+        deviations.push({
+          type: "missing-transition",
+          from: t.from,
+          to: t.to,
+          message: `Missing expected transition ${t.from} \u2192 ${t.to} (model probability: ${(t.probability * 100).toFixed(1)}%)`,
+          modelProbability: t.probability
+        });
+      }
+    }
+  }
+  const conformanceScore = totalChecks === 0 ? 1 : (totalChecks - deviationCount) / totalChecks;
+  return {
+    conformanceScore,
+    isConforming: deviations.length === 0,
+    deviations
+  };
+}
+
+// src/event-emitter.ts
+var SCHEMA_VERSION = 1;
+function createExecutionEvent(graph, options) {
+  const duration = graph.endTime !== null ? graph.endTime - graph.startTime : Date.now() - graph.startTime;
+  let failurePoint;
+  if (graph.status === "failed") {
+    let candidate;
+    for (const node of graph.nodes.values()) {
+      if (node.status === "failed" || node.status === "timeout") {
+        const errorMeta = node.metadata.error;
+        const fp = {
+          nodeId: node.id,
+          nodeName: node.name,
+          nodeType: node.type,
+          error: typeof errorMeta === "string" ? errorMeta : void 0
+        };
+        if (node.id !== graph.rootNodeId) {
+          failurePoint = fp;
+          break;
+        }
+        if (!candidate) candidate = fp;
+      }
+    }
+    if (!failurePoint) failurePoint = candidate;
+  }
+  return {
+    eventType: graph.status === "failed" ? "execution.failed" : "execution.completed",
+    graphId: graph.id,
+    agentId: graph.agentId,
+    timestamp: Date.now(),
+    schemaVersion: SCHEMA_VERSION,
+    status: graph.status,
+    duration,
+    nodeCount: graph.nodes.size,
+    pathSignature: getPathSignature(graph),
+    ...failurePoint ? { failurePoint } : {},
+    ...options?.processContext ? { processContext: options.processContext } : {},
+    ...options?.semantic ? { semantic: options.semantic } : {},
+    violations: options?.violations ?? []
+  };
+}
+function createPatternEvent(agentId, model, variants, bottlenecks) {
+  return {
+    eventType: "pattern.discovered",
+    agentId,
+    timestamp: Date.now(),
+    schemaVersion: SCHEMA_VERSION,
+    pattern: {
+      totalGraphs: model.totalGraphs,
+      variantCount: variants.length,
+      topVariants: variants.slice(0, 5).map((v) => ({
+        pathSignature: v.pathSignature,
+        count: v.count,
+        percentage: v.percentage
+      })),
+      topBottlenecks: bottlenecks.slice(0, 5).map((b) => ({
+        nodeName: b.nodeName,
+        nodeType: b.nodeType,
+        p95: b.durations.p95
+      })),
+      processModel: model
+    }
+  };
+}
+function createEventEmitter(config) {
+  const writers = config?.writers ?? [];
+  const knowledgeStore = config?.knowledgeStore;
+  const onError = config?.onError ?? (() => {
+  });
+  const subscribers = /* @__PURE__ */ new Set();
+  return {
+    async emit(event) {
+      if (knowledgeStore) {
+        try {
+          knowledgeStore.append(event);
+        } catch (err) {
+          onError(err);
+        }
+      }
+      for (const writer of writers) {
+        try {
+          await writer.writeEvent(event);
+        } catch (err) {
+          onError(err);
+        }
+      }
+      for (const listener of subscribers) {
+        try {
+          listener(event);
+        } catch (err) {
+          onError(err);
+        }
+      }
+    },
+    subscribe(listener) {
+      subscribers.add(listener);
+      return () => {
+        subscribers.delete(listener);
+      };
+    }
+  };
+}
+
+// src/prompt-builder.ts
+var ROLE = "You are analyzing execution data for an AI agent system. Provide clear, actionable analysis based on the data below.";
+function fmtDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  return `${(ms / 1e3).toFixed(1)}s`;
+}
+function fmtTime(ts) {
+  return new Date(ts).toISOString();
+}
+function durationStats(durations) {
+  if (durations.length === 0) return { avg: 0, p50: 0, p95: 0, min: 0, max: 0 };
+  const sorted = [...durations].sort((a, b) => a - b);
+  const sum = sorted.reduce((a, b) => a + b, 0);
+  return {
+    avg: Math.round(sum / sorted.length),
+    p50: sorted[Math.floor(sorted.length * 0.5)] ?? 0,
+    p95: sorted[Math.floor(sorted.length * 0.95)] ?? 0,
+    min: sorted[0] ?? 0,
+    max: sorted[sorted.length - 1] ?? 0
+  };
+}
+function buildFailureAnalysisPrompt(events, profile) {
+  const stats = durationStats(profile.recentDurations);
+  const failureDetails = events.map((e, i) => {
+    const lines = [
+      `Failure ${i + 1}:`,
+      `  Time: ${fmtTime(e.timestamp)}`,
+      `  Duration: ${fmtDuration(e.duration)}`,
+      `  Path: ${e.pathSignature}`
+    ];
+    if (e.failurePoint) {
+      lines.push(`  Failed at: ${e.failurePoint.nodeName} (${e.failurePoint.nodeType})`);
+      if (e.failurePoint.error) lines.push(`  Error: ${e.failurePoint.error}`);
+    }
+    if (e.violations.length > 0) {
+      lines.push(`  Violations: ${e.violations.map((v) => v.message).join("; ")}`);
+    }
+    return lines.join("\n");
+  }).join("\n\n");
+  return `${ROLE}
+
+## Agent Profile
+- Agent: ${profile.agentId}
+- Total runs: ${profile.totalRuns}
+- Failure rate: ${(profile.failureRate * 100).toFixed(1)}% (${profile.failureCount} failures / ${profile.totalRuns} total)
+- Avg duration: ${fmtDuration(stats.avg)} (p50: ${fmtDuration(stats.p50)}, p95: ${fmtDuration(stats.p95)})
+- Known bottlenecks: ${profile.knownBottlenecks.length > 0 ? profile.knownBottlenecks.join(", ") : "none"}
+- Last conformance score: ${profile.lastConformanceScore ?? "N/A"}
+
+## Recent Failures (${events.length})
+
+${failureDetails}
+
+## Question
+Analyze these failures. What patterns do you see? What is the most likely root cause? Are these related or independent failures?`;
+}
+function buildAnomalyExplanationPrompt(event, profile) {
+  const stats = durationStats(profile.recentDurations);
+  const eventDetails = [
+    `Time: ${fmtTime(event.timestamp)}`,
+    `Status: ${event.status}`,
+    `Duration: ${fmtDuration(event.duration)}`,
+    `Path: ${event.pathSignature}`,
+    `Node count: ${event.nodeCount}`
+  ];
+  if (event.processContext) {
+    eventDetails.push(`Conformance score: ${event.processContext.conformanceScore}`);
+    eventDetails.push(`Is anomaly: ${event.processContext.isAnomaly}`);
+    eventDetails.push(`Variant: ${event.processContext.variant}`);
+  }
+  if (event.failurePoint) {
+    eventDetails.push(`Failed at: ${event.failurePoint.nodeName} (${event.failurePoint.nodeType})`);
+    if (event.failurePoint.error) eventDetails.push(`Error: ${event.failurePoint.error}`);
+  }
+  if (event.violations.length > 0) {
+    eventDetails.push(`Violations: ${event.violations.map((v) => v.message).join("; ")}`);
+  }
+  return `${ROLE}
+
+## Agent Baseline (from profile)
+- Agent: ${profile.agentId}
+- Total runs: ${profile.totalRuns}
+- Typical failure rate: ${(profile.failureRate * 100).toFixed(1)}%
+- Typical duration: avg ${fmtDuration(stats.avg)}, p50 ${fmtDuration(stats.p50)}, p95 ${fmtDuration(stats.p95)}
+- Last conformance score: ${profile.lastConformanceScore ?? "N/A"}
+- Known bottlenecks: ${profile.knownBottlenecks.length > 0 ? profile.knownBottlenecks.join(", ") : "none"}
+
+## Anomalous Execution
+${eventDetails.join("\n")}
+
+## Question
+This execution has been flagged as anomalous. Explain what is unusual about it compared to the agent's typical behavior. What might have caused this deviation?`;
+}
+function buildAgentSummaryPrompt(profile, recentEvents, patterns) {
+  const stats = durationStats(profile.recentDurations);
+  const recentOutcomes = recentEvents.slice(0, 10).map((e) => `  ${fmtTime(e.timestamp)} \u2014 ${e.eventType} (${fmtDuration(e.duration)})`).join("\n");
+  const patternSummary = patterns.length > 0 ? patterns.slice(0, 3).map((p) => {
+    const lines = [
+      `  Variants: ${p.pattern.variantCount} across ${p.pattern.totalGraphs} executions`,
+      `  Top variant: ${p.pattern.topVariants[0]?.pathSignature ?? "N/A"} (${p.pattern.topVariants[0]?.percentage.toFixed(0) ?? 0}%)`
+    ];
+    if (p.pattern.topBottlenecks.length > 0) {
+      const topB = p.pattern.topBottlenecks[0];
+      if (topB)
+        lines.push(`  Top bottleneck: ${topB.nodeName} (p95: ${fmtDuration(topB.p95)})`);
+    }
+    return lines.join("\n");
+  }).join("\n\n") : "  No patterns discovered yet.";
+  const dataNote = recentEvents.length === 0 && patterns.length === 0 ? "\nNote: Limited data available. Summary is based only on the profile statistics.\n" : "";
+  return `${ROLE}
+
+## Agent Profile
+- Agent: ${profile.agentId}
+- Total runs: ${profile.totalRuns}
+- Success rate: ${((1 - profile.failureRate) * 100).toFixed(1)}% (${profile.successCount} successes, ${profile.failureCount} failures)
+- Duration: avg ${fmtDuration(stats.avg)}, p50 ${fmtDuration(stats.p50)}, p95 ${fmtDuration(stats.p95)}, range ${fmtDuration(stats.min)}\u2013${fmtDuration(stats.max)}
+- Known bottlenecks: ${profile.knownBottlenecks.length > 0 ? profile.knownBottlenecks.join(", ") : "none"}
+- Last conformance score: ${profile.lastConformanceScore ?? "N/A"}
+- Last pattern analysis: ${profile.lastPatternTimestamp ? fmtTime(profile.lastPatternTimestamp) : "never"}
+${dataNote}
+## Recent Executions (last ${recentEvents.slice(0, 10).length})
+${recentOutcomes || "  No recent events."}
+
+## Pattern Analysis
+${patternSummary}
+
+## Question
+Provide a health summary for this agent. What are the key observations? Is the agent healthy, degrading, or in trouble? What should the operator pay attention to?`;
+}
+function buildFixSuggestionPrompt(events, profile, patterns) {
+  const failureGroups = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    const key = e.failurePoint?.error ?? e.pathSignature;
+    const group = failureGroups.get(key) ?? [];
+    group.push(e);
+    failureGroups.set(key, group);
+  }
+  const failureGroupSummary = [...failureGroups.entries()].map(([key, group]) => {
+    const latest = group[0];
+    return `  "${key}" \u2014 ${group.length} occurrence(s), latest at ${latest ? fmtTime(latest.timestamp) : "unknown"}`;
+  }).join("\n");
+  const bottleneckDetails = patterns.flatMap((p) => p.pattern.topBottlenecks).map((b) => `  ${b.nodeName} (${b.nodeType}) \u2014 p95: ${fmtDuration(b.p95)}`);
+  const uniqueBottlenecks = [...new Set(bottleneckDetails)].join("\n");
+  const conformanceIssues = events.filter((e) => e.processContext && e.processContext.conformanceScore < 0.8).map(
+    (e) => `  ${fmtTime(e.timestamp)}: conformance ${e.processContext?.conformanceScore}, variant "${e.processContext?.variant}"`
+  ).join("\n");
+  return `${ROLE}
+
+## Agent Profile
+- Agent: ${profile.agentId}
+- Failure rate: ${(profile.failureRate * 100).toFixed(1)}%
+- Known bottlenecks: ${profile.knownBottlenecks.length > 0 ? profile.knownBottlenecks.join(", ") : "none"}
+
+## Failure Patterns (${events.length} failures)
+${failureGroupSummary || "  No failures recorded."}
+
+## Bottlenecks
+${uniqueBottlenecks || "  No bottlenecks detected."}
+
+## Conformance Issues
+${conformanceIssues || "  No conformance issues."}
+
+## Question
+Based on the failure patterns, bottlenecks, and conformance issues above, provide specific, actionable recommendations to improve this agent's reliability and performance. Prioritize by impact.`;
+}
+
+// src/insight-engine.ts
+var DEFAULT_CACHE_TTL_MS = 36e5;
+var SCHEMA_VERSION2 = 1;
+function simpleHash(input) {
+  let hash = 0;
+  for (let i = 0; i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = (hash << 5) - hash + char | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+function createInsightEngine(store, analysisFn, config) {
+  const cacheTtlMs = config?.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  function checkCache(agentId, insightType, dataHash) {
+    const recent = store.getRecentInsights(agentId, { type: insightType, limit: 1 });
+    if (recent.length === 0) return null;
+    const cached = recent[0];
+    if (!cached || cached.dataHash !== dataHash) return null;
+    const age = Date.now() - cached.timestamp;
+    if (age >= cacheTtlMs) return null;
+    return cached;
+  }
+  function storeAndReturn(agentId, insightType, prompt, response, dataHash) {
+    const event = {
+      eventType: "insight.generated",
+      agentId,
+      timestamp: Date.now(),
+      schemaVersion: SCHEMA_VERSION2,
+      insightType,
+      prompt,
+      response,
+      dataHash
+    };
+    store.appendInsight(event);
+    return {
+      agentId,
+      insightType,
+      content: response,
+      cached: false,
+      timestamp: event.timestamp
+    };
+  }
+  function shortCircuit(agentId, insightType, content, cached, timestamp) {
+    return { agentId, insightType, content, cached, timestamp: timestamp ?? Date.now() };
+  }
+  return {
+    async explainFailures(agentId) {
+      const profile = store.getAgentProfile(agentId);
+      if (!profile) {
+        return shortCircuit(
+          agentId,
+          "failure-analysis",
+          "No data available for this agent.",
+          false
+        );
+      }
+      const events = store.getRecentEvents(agentId, { limit: 50 });
+      const failures = events.filter((e) => e.eventType === "execution.failed");
+      if (failures.length === 0) {
+        return shortCircuit(
+          agentId,
+          "failure-analysis",
+          "No recent failures found for this agent.",
+          false
+        );
+      }
+      const dataHash = simpleHash(JSON.stringify({ failures, profile }));
+      const cached = checkCache(agentId, "failure-analysis", dataHash);
+      if (cached) {
+        return shortCircuit(agentId, "failure-analysis", cached.response, true, cached.timestamp);
+      }
+      const prompt = buildFailureAnalysisPrompt(failures, profile);
+      try {
+        const response = await analysisFn(prompt);
+        return storeAndReturn(agentId, "failure-analysis", prompt, response, dataHash);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return shortCircuit(agentId, "failure-analysis", `Analysis failed: ${message}`, false);
+      }
+    },
+    async explainAnomaly(agentId, event) {
+      const profile = store.getAgentProfile(agentId);
+      if (!profile) {
+        return shortCircuit(
+          agentId,
+          "anomaly-explanation",
+          "No data available for this agent.",
+          false
+        );
+      }
+      const dataHash = simpleHash(JSON.stringify({ event, profile }));
+      const cached = checkCache(agentId, "anomaly-explanation", dataHash);
+      if (cached) {
+        return shortCircuit(
+          agentId,
+          "anomaly-explanation",
+          cached.response,
+          true,
+          cached.timestamp
+        );
+      }
+      const prompt = buildAnomalyExplanationPrompt(event, profile);
+      try {
+        const response = await analysisFn(prompt);
+        return storeAndReturn(agentId, "anomaly-explanation", prompt, response, dataHash);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return shortCircuit(agentId, "anomaly-explanation", `Analysis failed: ${message}`, false);
+      }
+    },
+    async summarizeAgent(agentId) {
+      const profile = store.getAgentProfile(agentId);
+      if (!profile) {
+        return shortCircuit(agentId, "agent-summary", "No data available for this agent.", false);
+      }
+      const recentEvents = store.getRecentEvents(agentId, { limit: 20 });
+      const patterns = store.getPatternHistory(agentId, { limit: 5 });
+      const dataHash = simpleHash(JSON.stringify({ profile, recentEvents, patterns }));
+      const cached = checkCache(agentId, "agent-summary", dataHash);
+      if (cached) {
+        return shortCircuit(agentId, "agent-summary", cached.response, true, cached.timestamp);
+      }
+      const prompt = buildAgentSummaryPrompt(profile, recentEvents, patterns);
+      try {
+        const response = await analysisFn(prompt);
+        return storeAndReturn(agentId, "agent-summary", prompt, response, dataHash);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return shortCircuit(agentId, "agent-summary", `Analysis failed: ${message}`, false);
+      }
+    },
+    async suggestFixes(agentId) {
+      const profile = store.getAgentProfile(agentId);
+      if (!profile) {
+        return shortCircuit(agentId, "fix-suggestion", "No data available for this agent.", false);
+      }
+      const events = store.getRecentEvents(agentId, { limit: 50 });
+      const failures = events.filter((e) => e.eventType === "execution.failed");
+      const patterns = store.getPatternHistory(agentId, { limit: 5 });
+      if (failures.length === 0 && profile.knownBottlenecks.length === 0) {
+        return shortCircuit(
+          agentId,
+          "fix-suggestion",
+          "Agent is healthy \u2014 no failures or bottlenecks detected.",
+          false
+        );
+      }
+      const dataHash = simpleHash(JSON.stringify({ failures, profile, patterns }));
+      const cached = checkCache(agentId, "fix-suggestion", dataHash);
+      if (cached) {
+        return shortCircuit(agentId, "fix-suggestion", cached.response, true, cached.timestamp);
+      }
+      const prompt = buildFixSuggestionPrompt(failures, profile, patterns);
+      try {
+        const response = await analysisFn(prompt);
+        return storeAndReturn(agentId, "fix-suggestion", prompt, response, dataHash);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return shortCircuit(agentId, "fix-suggestion", `Analysis failed: ${message}`, false);
+      }
+    }
+  };
+}
+
 // src/guards.ts
 var DEFAULT_TIMEOUTS = {
   tool: 3e4,
@@ -89,6 +732,9 @@ function checkGuards(graph, config) {
     });
   }
   violations.push(...detectReasoningLoops(graph, maxReasoningSteps, now));
+  if (config?.policySource) {
+    violations.push(...checkPolicyViolations(graph, config.policySource, config.policyThresholds, now));
+  }
   return violations;
 }
 function detectReasoningLoops(graph, maxSteps, timestamp) {
@@ -123,6 +769,40 @@ function detectReasoningLoops(graph, maxSteps, timestamp) {
   walk(graph.rootNodeId, 0, null);
   return violations;
 }
+function checkPolicyViolations(graph, policySource, thresholds, timestamp) {
+  const violations = [];
+  const maxFailureRate = thresholds?.maxFailureRate ?? 0.5;
+  const minConformance = thresholds?.minConformance ?? 0.7;
+  const failureRate = policySource.recentFailureRate(graph.agentId);
+  if (failureRate > maxFailureRate) {
+    violations.push({
+      type: "high-failure-rate",
+      nodeId: graph.rootNodeId,
+      message: `Agent ${graph.agentId} has a recent failure rate of ${(failureRate * 100).toFixed(0)}% (threshold: ${(maxFailureRate * 100).toFixed(0)}%)`,
+      timestamp
+    });
+  }
+  const conformanceScore = policySource.lastConformanceScore(graph.agentId);
+  if (conformanceScore !== null && conformanceScore < minConformance) {
+    violations.push({
+      type: "conformance-drift",
+      nodeId: graph.rootNodeId,
+      message: `Agent ${graph.agentId} conformance score ${(conformanceScore * 100).toFixed(0)}% is below threshold ${(minConformance * 100).toFixed(0)}%`,
+      timestamp
+    });
+  }
+  for (const node of graph.nodes.values()) {
+    if (node.status === "running" && policySource.isKnownBottleneck(node.name)) {
+      violations.push({
+        type: "known-bottleneck",
+        nodeId: node.id,
+        message: `Node ${node.name} (${node.type}) is a known bottleneck`,
+        timestamp
+      });
+    }
+  }
+  return violations;
+}
 function withGuards(builder, config) {
   const logger = config?.logger ?? ((msg) => console.warn(`[AgentFlow Guard] ${msg}`));
   const onViolation = config?.onViolation ?? "warn";
@@ -186,14 +866,539 @@ function withGuards(builder, config) {
     }
   };
 }
+
+// src/json-event-writer.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+function createJsonEventWriter(config) {
+  const { outputDir } = config;
+  function ensureDir() {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  function eventFileName(event) {
+    const typePart = event.eventType.replace(/\./g, "-");
+    const agentId = "agentId" in event ? event.agentId : "unknown";
+    return `${typePart}-${agentId}-${event.timestamp}.json`;
+  }
+  return {
+    async write(_graph) {
+    },
+    async writeEvent(event) {
+      ensureDir();
+      const fileName = eventFileName(event);
+      const filePath = join(outputDir, fileName);
+      writeFileSync(filePath, JSON.stringify(event, null, 2), "utf-8");
+    }
+  };
+}
+
+// src/knowledge-store.ts
+import {
+  existsSync,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { join as join2 } from "path";
+var DEFAULT_BASE_DIR = ".agentflow/knowledge";
+var MAX_RECENT_DURATIONS = 100;
+var writeCounter = 0;
+function toDateDir(epochMs) {
+  return new Date(epochMs).toISOString().slice(0, 10);
+}
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonAtomic(filePath, data) {
+  const tmpPath = `${filePath}.tmp.${Date.now()}`;
+  writeFileSync2(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+  renameSync(tmpPath, filePath);
+}
+function emptyProfile(agentId) {
+  return {
+    agentId,
+    totalRuns: 0,
+    successCount: 0,
+    failureCount: 0,
+    failureRate: 0,
+    recentDurations: [],
+    lastConformanceScore: null,
+    knownBottlenecks: [],
+    lastPatternTimestamp: null,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function mergeExecutionEvent(profile, event) {
+  const totalRuns = profile.totalRuns + 1;
+  const isFailure = event.eventType === "execution.failed";
+  const successCount = profile.successCount + (isFailure ? 0 : 1);
+  const failureCount = profile.failureCount + (isFailure ? 1 : 0);
+  const durations = [...profile.recentDurations, event.duration];
+  if (durations.length > MAX_RECENT_DURATIONS) {
+    durations.shift();
+  }
+  const conformanceScore = event.processContext?.conformanceScore ?? profile.lastConformanceScore;
+  return {
+    agentId: profile.agentId,
+    totalRuns,
+    successCount,
+    failureCount,
+    failureRate: failureCount / totalRuns,
+    recentDurations: durations,
+    lastConformanceScore: conformanceScore,
+    knownBottlenecks: profile.knownBottlenecks,
+    lastPatternTimestamp: profile.lastPatternTimestamp,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function mergePatternEvent(profile, event) {
+  const existingBottlenecks = new Set(profile.knownBottlenecks);
+  for (const b of event.pattern.topBottlenecks) {
+    existingBottlenecks.add(b.nodeName);
+  }
+  return {
+    ...profile,
+    knownBottlenecks: [...existingBottlenecks],
+    lastPatternTimestamp: event.timestamp,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createKnowledgeStore(config) {
+  const baseDir = config?.baseDir ?? DEFAULT_BASE_DIR;
+  const eventsDir = join2(baseDir, "events");
+  const patternsDir = join2(baseDir, "patterns");
+  const profilesDir = join2(baseDir, "profiles");
+  const insightsDir = join2(baseDir, "insights");
+  function ensureDir(dir) {
+    mkdirSync2(dir, { recursive: true });
+  }
+  function profilePath(agentId) {
+    return join2(profilesDir, `${agentId}.json`);
+  }
+  function appendExecutionEvent(event) {
+    const dateDir = join2(eventsDir, event.agentId, toDateDir(event.timestamp));
+    ensureDir(dateDir);
+    const typePart = event.eventType.replace(/\./g, "-");
+    const seq = String(writeCounter++).padStart(4, "0");
+    const fileName = `${typePart}-${event.timestamp}-${seq}.json`;
+    writeFileSync2(join2(dateDir, fileName), JSON.stringify(event, null, 2), "utf-8");
+    ensureDir(profilesDir);
+    const existing = readJson(profilePath(event.agentId)) ?? emptyProfile(event.agentId);
+    const updated = mergeExecutionEvent(existing, event);
+    writeJsonAtomic(profilePath(event.agentId), updated);
+  }
+  function appendPatternEvent(event) {
+    const agentPatternDir = join2(patternsDir, event.agentId);
+    ensureDir(agentPatternDir);
+    const seq = String(writeCounter++).padStart(4, "0");
+    const fileName = `${event.timestamp}-${seq}.json`;
+    writeFileSync2(join2(agentPatternDir, fileName), JSON.stringify(event, null, 2), "utf-8");
+    ensureDir(profilesDir);
+    const existing = readJson(profilePath(event.agentId)) ?? emptyProfile(event.agentId);
+    const updated = mergePatternEvent(existing, event);
+    writeJsonAtomic(profilePath(event.agentId), updated);
+  }
+  return {
+    baseDir,
+    append(event) {
+      if (event.eventType === "pattern.discovered" || event.eventType === "pattern.updated") {
+        appendPatternEvent(event);
+      } else {
+        appendExecutionEvent(event);
+      }
+    },
+    getRecentEvents(agentId, options) {
+      const limit = options?.limit ?? 50;
+      const since = options?.since ?? 0;
+      const agentDir = join2(eventsDir, agentId);
+      if (!existsSync(agentDir)) return [];
+      const events = [];
+      const dateDirs = readdirSync(agentDir).sort().reverse();
+      for (const dateDir of dateDirs) {
+        const fullDateDir = join2(agentDir, dateDir);
+        let files;
+        try {
+          files = readdirSync(fullDateDir).filter((f) => f.endsWith(".json"));
+        } catch {
+          continue;
+        }
+        for (const file of files) {
+          const event = readJson(join2(fullDateDir, file));
+          if (event && event.timestamp > since) {
+            events.push(event);
+          }
+        }
+        if (events.length >= limit * 2) break;
+      }
+      events.sort((a, b) => b.timestamp - a.timestamp);
+      return events.slice(0, limit);
+    },
+    getAgentProfile(agentId) {
+      return readJson(profilePath(agentId));
+    },
+    getPatternHistory(agentId, options) {
+      const limit = options?.limit ?? 20;
+      const agentPatternDir = join2(patternsDir, agentId);
+      if (!existsSync(agentPatternDir)) return [];
+      const files = readdirSync(agentPatternDir).filter((f) => f.endsWith(".json")).sort().reverse();
+      const events = [];
+      for (const file of files.slice(0, limit)) {
+        const event = readJson(join2(agentPatternDir, file));
+        if (event) events.push(event);
+      }
+      return events;
+    },
+    compact(options) {
+      let removed = 0;
+      if (existsSync(eventsDir)) {
+        for (const agentId of readdirSync(eventsDir)) {
+          const agentDir = join2(eventsDir, agentId);
+          let dateDirs;
+          try {
+            dateDirs = readdirSync(agentDir);
+          } catch {
+            continue;
+          }
+          for (const dateDir of dateDirs) {
+            const fullDateDir = join2(agentDir, dateDir);
+            let files;
+            try {
+              files = readdirSync(fullDateDir).filter((f) => f.endsWith(".json"));
+            } catch {
+              continue;
+            }
+            for (const file of files) {
+              const parts = file.replace(".json", "").split("-");
+              const tsPart = parts[parts.length - 2];
+              const ts = tsPart ? Number.parseInt(tsPart, 10) : 0;
+              if (!Number.isNaN(ts) && ts < options.olderThan) {
+                try {
+                  rmSync(join2(fullDateDir, file));
+                  removed++;
+                } catch {
+                }
+              }
+            }
+            try {
+              if (readdirSync(fullDateDir).length === 0) {
+                rmSync(fullDateDir, { recursive: true });
+              }
+            } catch {
+            }
+          }
+        }
+      }
+      if (existsSync(patternsDir)) {
+        for (const agentId of readdirSync(patternsDir)) {
+          const agentPatternDir = join2(patternsDir, agentId);
+          let files;
+          try {
+            files = readdirSync(agentPatternDir).filter((f) => f.endsWith(".json"));
+          } catch {
+            continue;
+          }
+          for (const file of files) {
+            const ts = Number.parseInt(file.split("-")[0], 10);
+            if (!Number.isNaN(ts) && ts < options.olderThan) {
+              try {
+                rmSync(join2(agentPatternDir, file));
+                removed++;
+              } catch {
+              }
+            }
+          }
+        }
+      }
+      if (existsSync(insightsDir)) {
+        for (const agentId of readdirSync(insightsDir)) {
+          const agentInsightDir = join2(insightsDir, agentId);
+          let files;
+          try {
+            files = readdirSync(agentInsightDir).filter((f) => f.endsWith(".json"));
+          } catch {
+            continue;
+          }
+          for (const file of files) {
+            const parts = file.replace(".json", "").split("-");
+            const tsPart = parts[parts.length - 2];
+            const ts = tsPart ? Number.parseInt(tsPart, 10) : 0;
+            if (!Number.isNaN(ts) && ts < options.olderThan) {
+              try {
+                rmSync(join2(agentInsightDir, file));
+                removed++;
+              } catch {
+              }
+            }
+          }
+        }
+      }
+      return { removed };
+    },
+    appendInsight(event) {
+      const agentInsightDir = join2(insightsDir, event.agentId);
+      ensureDir(agentInsightDir);
+      const seq = String(writeCounter++).padStart(4, "0");
+      const fileName = `${event.insightType}-${event.timestamp}-${seq}.json`;
+      writeFileSync2(join2(agentInsightDir, fileName), JSON.stringify(event, null, 2), "utf-8");
+    },
+    getRecentInsights(agentId, options) {
+      const limit = options?.limit ?? 10;
+      const typeFilter = options?.type;
+      const agentInsightDir = join2(insightsDir, agentId);
+      if (!existsSync(agentInsightDir)) return [];
+      const files = readdirSync(agentInsightDir).filter((f) => f.endsWith(".json"));
+      const events = [];
+      for (const file of files) {
+        const event = readJson(join2(agentInsightDir, file));
+        if (event) {
+          if (typeFilter && event.insightType !== typeFilter) continue;
+          events.push(event);
+        }
+      }
+      events.sort((a, b) => b.timestamp - a.timestamp);
+      return events.slice(0, limit);
+    },
+    // EventWriter interface
+    async write(_graph) {
+    },
+    async writeEvent(event) {
+      this.append(event);
+    }
+  };
+}
+
+// src/policy-source.ts
+import { readdirSync as readdirSync2 } from "fs";
+import { join as join3 } from "path";
+function createPolicySource(store) {
+  return {
+    recentFailureRate(agentId) {
+      const profile = store.getAgentProfile(agentId);
+      return profile?.failureRate ?? 0;
+    },
+    isKnownBottleneck(nodeName) {
+      const profilesDir = join3(store.baseDir, "profiles");
+      let agentIds;
+      try {
+        agentIds = readdirSync2(profilesDir).filter((f) => f.endsWith(".json")).map((f) => f.replace(".json", ""));
+      } catch {
+        return false;
+      }
+      for (const agentId of agentIds) {
+        const profile = store.getAgentProfile(agentId);
+        if (profile && profile.knownBottlenecks.includes(nodeName)) {
+          return true;
+        }
+      }
+      return false;
+    },
+    lastConformanceScore(agentId) {
+      const profile = store.getAgentProfile(agentId);
+      return profile?.lastConformanceScore ?? null;
+    },
+    getAgentProfile(agentId) {
+      return store.getAgentProfile(agentId);
+    }
+  };
+}
+
+// src/soma-event-writer.ts
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
+function compactIso(epochMs) {
+  return new Date(epochMs).toISOString().slice(0, 19).replace(/:/g, "");
+}
+function isoDate(epochMs) {
+  return new Date(epochMs).toISOString().slice(0, 10);
+}
+function renderFrontmatter(fields) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.map((v) => `'${v}'`).join(", ")}]`);
+    } else if (typeof value === "string") {
+      lines.push(`${key}: '${value}'`);
+    } else {
+      lines.push(`${key}: ${String(value)}`);
+    }
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms.toFixed(0)}ms`;
+  if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
+  return `${(ms / 6e4).toFixed(1)}min`;
+}
+function executionEventToMarkdown(event) {
+  const isCompleted = event.eventType === "execution.completed";
+  const subtype = isCompleted ? "completed" : "failed";
+  const tags = [
+    "agentflow/execution",
+    `agent/${event.agentId}`,
+    `status/${subtype}`
+  ];
+  if (event.processContext?.isAnomaly) {
+    tags.push("agentflow/anomaly");
+  }
+  const frontmatter = {
+    type: "execution",
+    subtype,
+    name: `Execution: ${event.agentId} \u2014 ${subtype}`,
+    source: "agentflow",
+    created: isoDate(event.timestamp),
+    alfred_tags: tags,
+    agentflow_graph_id: event.graphId,
+    duration_ms: event.duration,
+    node_count: event.nodeCount
+  };
+  if (event.processContext) {
+    frontmatter.conformance_score = event.processContext.conformanceScore;
+    frontmatter.is_anomaly = event.processContext.isAnomaly;
+  }
+  const body = [];
+  body.push(`# Execution: ${event.agentId} \u2014 ${subtype}
+`);
+  body.push(`**Duration:** ${formatDuration(event.duration)}  `);
+  body.push(`**Nodes:** ${event.nodeCount}  `);
+  body.push(`**Status:** ${event.status}
+`);
+  if (event.pathSignature) {
+    body.push(`## Path
+`);
+    body.push(`\`${event.pathSignature}\`
+`);
+  }
+  if (!isCompleted && event.failurePoint) {
+    const fp = event.failurePoint;
+    body.push(`## Failure Point
+`);
+    body.push(`**Node:** ${fp.nodeType}:${fp.nodeName} (\`${fp.nodeId}\`)  `);
+    if (fp.error) {
+      body.push(`**Error:** ${fp.error}
+`);
+    }
+  }
+  if (event.processContext) {
+    body.push(`## Process Context
+`);
+    body.push(`**Conformance:** ${(event.processContext.conformanceScore * 100).toFixed(0)}%  `);
+    body.push(`**Anomaly:** ${event.processContext.isAnomaly ? "yes" : "no"}
+`);
+  }
+  body.push(`## Related
+`);
+  body.push(`- [[agent/${event.agentId}]]`);
+  return `${renderFrontmatter(frontmatter)}
+
+${body.join("\n")}`;
+}
+function patternEventToMarkdown(event) {
+  const { pattern } = event;
+  const tags = [
+    "agentflow/pattern",
+    `agent/${event.agentId}`
+  ];
+  const frontmatter = {
+    type: "synthesis",
+    subtype: "pattern-discovery",
+    name: `Pattern: ${event.agentId} \u2014 ${pattern.variantCount} variants across ${pattern.totalGraphs} runs`,
+    source: "agentflow",
+    created: isoDate(event.timestamp),
+    alfred_tags: tags,
+    variant_count: pattern.variantCount,
+    total_graphs: pattern.totalGraphs
+  };
+  const body = [];
+  body.push(`# Pattern: ${event.agentId}
+`);
+  body.push(`**Variants:** ${pattern.variantCount}  `);
+  body.push(`**Total Runs:** ${pattern.totalGraphs}
+`);
+  if (pattern.topVariants.length > 0) {
+    body.push(`## Top Variants
+`);
+    body.push(`| Path | Count | % |`);
+    body.push(`|------|-------|---|`);
+    for (const v of pattern.topVariants) {
+      const sig = v.pathSignature.length > 60 ? `${v.pathSignature.slice(0, 57)}...` : v.pathSignature;
+      body.push(`| \`${sig}\` | ${v.count} | ${v.percentage.toFixed(1)}% |`);
+    }
+    body.push("");
+  }
+  if (pattern.topBottlenecks.length > 0) {
+    body.push(`## Top Bottlenecks
+`);
+    body.push(`| Node | Type | p95 |`);
+    body.push(`|------|------|-----|`);
+    for (const b of pattern.topBottlenecks) {
+      body.push(`| ${b.nodeName} | ${b.nodeType} | ${formatDuration(b.p95)} |`);
+    }
+    body.push("");
+  }
+  body.push(`## Related
+`);
+  body.push(`- [[agent/${event.agentId}]]`);
+  return `${renderFrontmatter(frontmatter)}
+
+${body.join("\n")}`;
+}
+function createSomaEventWriter(config) {
+  const { inboxDir } = config;
+  function ensureDir() {
+    mkdirSync3(inboxDir, { recursive: true });
+  }
+  function eventFileName(event) {
+    const agentId = event.agentId;
+    const ts = compactIso(event.timestamp);
+    if (event.eventType === "pattern.discovered" || event.eventType === "pattern.updated") {
+      return `synthesis-${agentId}-${ts}.md`;
+    }
+    return `execution-${agentId}-${ts}.md`;
+  }
+  return {
+    async write(_graph) {
+    },
+    async writeEvent(event) {
+      ensureDir();
+      const markdown = event.eventType === "pattern.discovered" || event.eventType === "pattern.updated" ? patternEventToMarkdown(event) : executionEventToMarkdown(event);
+      const fileName = eventFileName(event);
+      writeFileSync3(join4(inboxDir, fileName), markdown, "utf-8");
+    }
+  };
+}
 export {
   auditProcesses,
+  buildAgentSummaryPrompt,
+  buildAnomalyExplanationPrompt,
+  buildFailureAnalysisPrompt,
+  buildFixSuggestionPrompt,
+  checkConformance,
   checkGuards,
+  createEventEmitter,
+  createExecutionEvent,
   createGraphBuilder,
+  createInsightEngine,
+  createJsonEventWriter,
+  createKnowledgeStore,
+  createPatternEvent,
+  createPolicySource,
+  createSomaEventWriter,
   createTraceStore,
+  discoverProcess,
   discoverProcessConfig,
+  findVariants,
   findWaitingOn,
   formatAuditReport,
+  getBottlenecks,
   getChildren,
   getCriticalPath,
   getDepth,
@@ -202,6 +1407,7 @@ export {
   getHungNodes,
   getNode,
   getParent,
+  getPathSignature,
   getStats,
   getSubtree,
   getTraceTree,