agentflow-core 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -50,6 +50,25 @@ interface TraceEvent {
     readonly nodeId: string;
     readonly data: Readonly<Record<string, unknown>>;
 }
+/**
+ * Optional typed data for `decision` trace events.
+ * Frameworks can emit these to provide richer decision data than graph inference.
+ * SOMA will use these fields if present, falling back to graph-structure inference.
+ */
+interface DecisionTraceData {
+    /** What was selected */
+    readonly choice: string;
+    /** Other options available */
+    readonly alternatives?: readonly string[];
+    /** Why this choice was made */
+    readonly rationale?: string;
+    /** Confidence in the decision (0.0-1.0) */
+    readonly confidence?: number;
+    /** Arbitrary context */
+    readonly context?: Readonly<Record<string, unknown>>;
+    /** Decision outcome */
+    readonly outcome?: string;
+}
 /** The complete execution graph for one agent run. */
 interface ExecutionGraph {
     readonly id: string;
@@ -71,6 +90,8 @@ interface ExecutionGraph {
     readonly spanId?: string;
     /** Parent span ID, or null if this is the root span. */
     readonly parentSpanId?: string | null;
+    /** Arbitrary metadata preserved from the trace file. */
+    readonly metadata?: Record<string, unknown>;
 }
 /**
  * Configuration for AgentFlow.
@@ -229,6 +250,423 @@ interface DistributedTrace {
     readonly endTime: number | null;
     readonly status: GraphStatus;
 }
+/** A transition between two steps in a discovered process model. */
+interface ProcessTransition {
+    /** Source step identifier (`type:name`). */
+    readonly from: string;
+    /** Target step identifier (`type:name`). */
+    readonly to: string;
+    /** Absolute frequency: how many times this transition was observed. */
+    readonly count: number;
+    /** Relative frequency from the source step (0.0–1.0). */
+    readonly probability: number;
+}
+/** A process model discovered from multiple execution graphs. */
+interface ProcessModel {
+    /** All observed step identifiers (`type:name`). */
+    readonly steps: readonly string[];
+    /** All observed transitions with frequencies. */
+    readonly transitions: readonly ProcessTransition[];
+    /** Number of graphs used to build this model. */
+    readonly totalGraphs: number;
+    /** Agent ID from the input graphs. */
+    readonly agentId: string;
+}
+/** A group of execution graphs that share the same structural path. */
+interface Variant {
+    /** Canonical path signature for this variant. */
+    readonly pathSignature: string;
+    /** Number of graphs in this variant. */
+    readonly count: number;
+    /** Percentage of total graphs (0–100). */
+    readonly percentage: number;
+    /** IDs of graphs belonging to this variant. */
+    readonly graphIds: readonly string[];
+    /** First graph in the group (representative example). */
+    readonly exampleGraph: ExecutionGraph;
+}
+/** Duration statistics for a node across multiple execution graphs. */
+interface Bottleneck {
+    /** Node name (e.g. `"fetch-data"`). */
+    readonly nodeName: string;
+    /** Node type (e.g. `"tool"`). */
+    readonly nodeType: NodeType;
+    /** How many graphs contain this node. */
+    readonly occurrences: number;
+    /** Duration statistics in milliseconds. */
+    readonly durations: {
+        readonly median: number;
+        readonly p95: number;
+        readonly p99: number;
+        readonly min: number;
+        readonly max: number;
+    };
+    /** Fraction of input graphs that include this node (0–100). */
+    readonly percentOfGraphs: number;
+}
+/** Category of deviation detected during conformance checking. */
+type DeviationType = 'unexpected-transition' | 'missing-transition' | 'low-frequency-path';
+/** A specific deviation between a graph and a process model. */
+interface Deviation {
+    /** Category of deviation. */
+    readonly type: DeviationType;
+    /** Source step identifier. */
+    readonly from: string;
+    /** Target step identifier. */
+    readonly to: string;
+    /** Human-readable description of the deviation. */
+    readonly message: string;
+    /** Model probability of this transition (if applicable). */
+    readonly modelProbability?: number;
+}
+/** Result of comparing a single graph against a process model. */
+interface ConformanceReport {
+    /** Ratio of conforming transitions to total transitions (0.0–1.0). */
+    readonly conformanceScore: number;
+    /** True when conformanceScore is 1.0 (no deviations). */
+    readonly isConforming: boolean;
+    /** List of specific deviations found. */
+    readonly deviations: readonly Deviation[];
+}
+/** Explanation attached to every guard violation for transparency. */
+interface GuardExplanation {
+    /** The guard rule name (e.g., 'max-depth', 'timeout'). */
+    readonly rule: string;
+    /** The configured threshold that was exceeded. */
+    readonly threshold: number | string;
+    /** The actual observed value. */
+    readonly actual: number | string;
+    /** Where the threshold came from. */
+    readonly source: 'static' | 'soma-policy' | 'adaptive' | 'assertion';
+    /** Optional historical evidence supporting the threshold. */
+    readonly evidence?: string;
+}
+/** Outcome assertion for post-action verification. */
+interface OutcomeAssertion {
+    /** Human-readable label for this assertion. */
+    readonly name: string;
+    /** Verification function — returns true if the expected outcome occurred. */
+    readonly verify: () => Promise<boolean> | boolean;
+    /** Timeout in milliseconds (default: 5000). */
+    readonly timeout?: number;
+}
+/**
+ * A detected guard violation.
+ */
+interface GuardViolation {
+    readonly type: 'timeout' | 'reasoning-loop' | 'spawn-explosion' | 'high-failure-rate' | 'conformance-drift' | 'known-bottleneck' | 'outcome_mismatch';
+    readonly nodeId: string;
+    readonly message: string;
+    readonly timestamp: number;
+    readonly explanation: GuardExplanation;
+}
+/** Per-node cost attribution. */
+interface NodeCost {
+    readonly nodeId: string;
+    readonly name: string;
+    readonly type: NodeType;
+    readonly tokenCost: number | null;
+    readonly durationMs: number | null;
+}
+/** Wasteful pattern detection flag. */
+interface EfficiencyFlag {
+    readonly pattern: 'wasteful_retry' | 'context_bloat';
+    readonly nodeName: string;
+    readonly retryCount?: number;
+    readonly tokenCost: number;
+    readonly message: string;
+}
+/** Per-run efficiency summary. */
+interface RunEfficiency {
+    readonly graphId: string;
+    readonly agentId: string;
+    readonly totalTokenCost: number;
+    readonly completedNodes: number;
+    readonly costPerNode: number;
+}
+/** Aggregate efficiency report across runs. */
+interface EfficiencyReport {
+    readonly runs: readonly RunEfficiency[];
+    readonly aggregate: {
+        mean: number;
+        median: number;
+        p95: number;
+    };
+    readonly flags: readonly EfficiencyFlag[];
+    readonly nodeCosts: readonly NodeCost[];
+    readonly dataCoverage: number;
+}
+/** Per-step summary in a run receipt. */
+interface StepSummary {
+    readonly nodeId: string;
+    readonly name: string;
+    readonly type: NodeType;
+    readonly status: NodeStatus;
+    readonly durationMs: number | null;
+    readonly tokenCost: number | null;
+    readonly error: string | null;
+}
+/** Structured run summary. */
+interface RunReceipt {
+    readonly runId: string;
+    readonly agentId: string;
+    readonly status: GraphStatus;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly totalDurationMs: number | null;
+    readonly totalTokenCost: number | null;
+    readonly steps: readonly StepSummary[];
+    readonly summary: {
+        readonly attempted: number;
+        readonly succeeded: number;
+        readonly failed: number;
+        readonly skipped: number;
+    };
+}
+/** A single conformance history entry. */
+interface ConformanceHistoryEntry {
+    readonly agentId: string;
+    readonly timestamp: number;
+    readonly score: number;
+    readonly runId: string;
+}
+/** Conformance score history for an agent. */
+type ConformanceHistory = ConformanceHistoryEntry[];
+/** Options for drift detection. */
+interface DriftOptions {
+    /** Sliding window size (number of runs). Default: 50. */
+    readonly windowSize?: number;
+}
+/** Drift detection report. */
+interface DriftReport {
+    readonly status: 'stable' | 'degrading' | 'improving' | 'insufficient_data';
+    readonly slope: number;
+    readonly r2: number;
+    readonly windowSize: number;
+    readonly dataPoints: number;
+    readonly alert?: {
+        readonly type: 'conformance_trend_degradation';
+        readonly agentId: string;
+        readonly currentScore: number;
+        readonly trendSlope: number;
+        readonly windowSize: number;
+        readonly message: string;
+    };
+}
+/** Options for variant analysis. */
+interface VariantOptions {
+    /** Dimensions to include in variant signature. Default: ['path']. */
+    readonly dimensions?: readonly ('path' | 'modelId' | 'status')[];
+}
+/** Event type discriminator for AgentFlow events. */
+type AgentFlowEventType = 'execution.completed' | 'execution.failed' | 'pattern.discovered' | 'pattern.updated';
+/** Optional semantic context attached to an execution event by adapters. */
+interface SemanticContext {
+    readonly intent?: string;
+    readonly trigger?: string;
+    readonly inputSummary?: string;
+    readonly outputSummary?: string;
+    readonly tokenCost?: number;
+    readonly modelId?: string;
+}
+/** Process mining context for an execution event. */
+interface ProcessContext {
+    readonly variant: string;
+    readonly conformanceScore: number;
+    readonly isAnomaly: boolean;
+}
+/** The point at which an execution failed. */
+interface FailurePoint {
+    readonly nodeId: string;
+    readonly nodeName: string;
+    readonly nodeType: NodeType;
+    readonly error?: string;
+}
+/** A structured event emitted after an agent execution completes or fails. */
+interface ExecutionEvent {
+    readonly eventType: 'execution.completed' | 'execution.failed';
+    readonly graphId: string;
+    readonly agentId: string;
+    readonly timestamp: number;
+    readonly schemaVersion: number;
+    readonly status: GraphStatus;
+    readonly duration: number;
+    readonly nodeCount: number;
+    readonly pathSignature: string;
+    readonly failurePoint?: FailurePoint;
+    readonly processContext?: ProcessContext;
+    readonly semantic?: SemanticContext;
+    readonly violations: readonly GuardViolation[];
+}
+/** A structured event emitted when process mining discovers a pattern. */
+interface PatternEvent {
+    readonly eventType: 'pattern.discovered' | 'pattern.updated';
+    readonly agentId: string;
+    readonly timestamp: number;
+    readonly schemaVersion: number;
+    readonly pattern: {
+        readonly totalGraphs: number;
+        readonly variantCount: number;
+        readonly topVariants: readonly {
+            readonly pathSignature: string;
+            readonly count: number;
+            readonly percentage: number;
+        }[];
+        readonly topBottlenecks: readonly {
+            readonly nodeName: string;
+            readonly nodeType: NodeType;
+            readonly p95: number;
+        }[];
+        readonly processModel: ProcessModel;
+    };
+}
+/** Options for creating an ExecutionEvent from a graph. */
+interface ExecutionEventOptions {
+    readonly processContext?: ProcessContext;
+    readonly semantic?: SemanticContext;
+    readonly violations?: readonly GuardViolation[];
+}
+/** Configuration for the event emitter. */
+interface EventEmitterConfig {
+    readonly writers?: readonly EventWriter[];
+    readonly onError?: (error: unknown) => void;
+    /** Optional knowledge store for automatic event persistence. */
+    readonly knowledgeStore?: KnowledgeStore;
+}
+/**
+ * Extended Writer interface that can handle structured events.
+ * Backward-compatible — existing Writers are unaffected.
+ */
+interface EventWriter extends Writer {
+    /** Write a structured event to the output target. */
+    writeEvent(event: ExecutionEvent | PatternEvent): Promise<void>;
+}
+/** Event emitter for routing AgentFlow events to writers and subscribers. */
+interface EventEmitter {
+    /** Emit an event to all writers and subscribers. */
+    emit(event: ExecutionEvent | PatternEvent): Promise<void>;
+    /** Subscribe to events. Returns an unsubscribe function. */
+    subscribe(listener: (event: ExecutionEvent | PatternEvent) => void): () => void;
+}
+/** Derived per-agent profile accumulated from execution and pattern events. */
+interface AgentProfile {
+    readonly agentId: string;
+    readonly totalRuns: number;
+    readonly successCount: number;
+    readonly failureCount: number;
+    readonly failureRate: number;
+    readonly recentDurations: readonly number[];
+    readonly lastConformanceScore: number | null;
+    readonly knownBottlenecks: readonly string[];
+    readonly lastPatternTimestamp: number | null;
+    readonly updatedAt: string;
+}
+/** Configuration for the knowledge store. */
+interface KnowledgeStoreConfig {
+    /** Base directory for knowledge storage. Defaults to `.agentflow/knowledge`. */
+    readonly baseDir?: string;
+}
+/**
+ * Filesystem-based knowledge store that accumulates execution and pattern events.
+ * Implements EventWriter so it can be used directly with createEventEmitter.
+ */
+interface KnowledgeStore extends EventWriter {
+    /** Base directory of the knowledge store. */
+    readonly baseDir: string;
+    /** Persist an event and update the agent profile. */
+    append(event: ExecutionEvent | PatternEvent): void;
+    /** Query recent execution events for an agent. */
+    getRecentEvents(agentId: string, options?: {
+        limit?: number;
+        since?: number;
+    }): ExecutionEvent[];
+    /** Get the derived profile for an agent, or null if no history. */
+    getAgentProfile(agentId: string): AgentProfile | null;
+    /** Query pattern event history for an agent. */
+    getPatternHistory(agentId: string, options?: {
+        limit?: number;
+    }): PatternEvent[];
+    /** Remove event files older than the given timestamp. Profiles are preserved. */
+    compact(options: {
+        olderThan: number;
+    }): {
+        removed: number;
+    };
+    /** Persist an insight event generated by the insight engine. */
+    appendInsight(event: InsightEvent): void;
+    /** Query recent insight events for an agent. */
+    getRecentInsights(agentId: string, options?: {
+        type?: string;
+        limit?: number;
+    }): InsightEvent[];
+}
+/**
+ * Read-only interface for querying accumulated knowledge.
+ * Used by guards to make adaptive decisions based on execution history.
+ */
+interface PolicySource {
+    /** Recent failure rate for an agent (0.0–1.0). Returns 0 if no history. */
+    recentFailureRate(agentId: string): number;
+    /** Whether a node name appears as a known bottleneck across any agent. */
+    isKnownBottleneck(nodeName: string): boolean;
+    /** Most recent conformance score for an agent, or null if none recorded. */
+    lastConformanceScore(agentId: string): number | null;
+    /** Full derived profile for an agent, or null if no history. */
+    getAgentProfile(agentId: string): AgentProfile | null;
+}
+/**
+ * User-provided LLM function. AgentFlow constructs prompts and delegates
+ * the actual LLM call to this function. Any provider can be wrapped as an AnalysisFn.
+ */
+type AnalysisFn = (prompt: string) => Promise<string>;
+/** A structured event emitted when the insight engine generates an LLM-powered analysis. */
+interface InsightEvent {
+    readonly eventType: 'insight.generated';
+    readonly agentId: string;
+    readonly timestamp: number;
+    readonly schemaVersion: number;
+    readonly insightType: 'failure-analysis' | 'anomaly-explanation' | 'agent-summary' | 'fix-suggestion';
+    /** The prompt that was sent to the AnalysisFn (for auditing). */
+    readonly prompt: string;
+    /** The LLM response. */
+    readonly response: string;
+    /** Hash of input data — used for cache identity. */
+    readonly dataHash: string;
+}
+/** Result returned by InsightEngine methods. */
+interface InsightResult {
+    readonly agentId: string;
+    readonly insightType: InsightEvent['insightType'];
+    /** The LLM response or pre-computed message. */
+    readonly content: string;
+    /** Whether this result came from cache. */
+    readonly cached: boolean;
+    /** When the insight was generated (epoch ms). */
+    readonly timestamp: number;
+}
+/** Configuration for the insight engine. */
+interface InsightEngineConfig {
+    /** How long cached insights remain valid (ms). Default: 3600000 (1 hour). */
+    readonly cacheTtlMs?: number;
+}
+/** LLM-powered semantic analysis engine for agent execution data. */
+interface InsightEngine {
+    /** Explain recent failures for an agent in natural language. */
+    explainFailures(agentId: string): Promise<InsightResult>;
+    /** Explain why a specific execution was anomalous. */
+    explainAnomaly(agentId: string, event: ExecutionEvent): Promise<InsightResult>;
+    /** Generate a natural language health summary for an agent. */
+    summarizeAgent(agentId: string): Promise<InsightResult>;
+    /** Suggest actionable fixes based on failure patterns and bottlenecks. */
+    suggestFixes(agentId: string): Promise<InsightResult>;
+}
+/** Thresholds for policy-derived guard violations. */
+interface PolicyThresholds {
+    /** Maximum acceptable failure rate before triggering a violation (default 0.5). */
+    readonly maxFailureRate?: number;
+    /** Minimum acceptable conformance score before triggering a violation (default 0.7). */
+    readonly minConformance?: number;
+}
 /** @internal Mutable version of ExecutionNode used during graph construction. */
 interface MutableExecutionNode {
     id: string;
@@ -243,6 +681,80 @@ interface MutableExecutionNode {
     state: Record<string, unknown>;
 }
 
+/**
+ * Event emission layer for AgentFlow execution intelligence.
+ *
+ * Transforms completed execution graphs and process mining results into
+ * structured, self-describing events consumable by external systems
+ * (Soma, dashboards, sentinel agents, custom knowledge engines).
+ *
+ * @module
+ */
+
+/**
+ * Create a structured ExecutionEvent from a completed execution graph.
+ *
+ * Pure function — no side effects. The returned event is self-describing:
+ * it contains all context needed to understand the execution without
+ * reading the original graph.
+ *
+ * @param graph - The completed execution graph.
+ * @param options - Optional process mining context, semantic context, and violations.
+ * @returns A structured ExecutionEvent.
+ *
+ * @example
+ * ```ts
+ * const event = createExecutionEvent(graph, {
+ *   processContext: { variant: 'A→B→C', conformanceScore: 0.9, isAnomaly: false },
+ *   semantic: { intent: 'daily-rebalance', trigger: 'cron' },
+ * });
+ * ```
+ */
+declare function createExecutionEvent(graph: ExecutionGraph, options?: ExecutionEventOptions): ExecutionEvent;
+/**
+ * Create a structured PatternEvent from process mining results.
+ *
+ * Pure function — no side effects. Summarizes the mining results into
+ * a compact event with top variants (up to 5) and top bottlenecks (up to 5).
+ *
+ * @param agentId - The agent these patterns belong to.
+ * @param model - The discovered process model.
+ * @param variants - Variant analysis results.
+ * @param bottlenecks - Bottleneck detection results.
+ * @returns A structured PatternEvent.
+ *
+ * @example
+ * ```ts
+ * const model = discoverProcess(graphs);
+ * const variants = findVariants(graphs);
+ * const bottlenecks = getBottlenecks(graphs);
+ * const event = createPatternEvent('my-agent', model, variants, bottlenecks);
+ * ```
+ */
+declare function createPatternEvent(agentId: string, model: ProcessModel, variants: Variant[], bottlenecks: Bottleneck[]): PatternEvent;
+/**
+ * Create an event emitter for routing AgentFlow events to writers and subscribers.
+ *
+ * The emitter is a simple pub/sub — no queuing, no retry, no backpressure.
+ * Writer errors are reported via the `onError` callback and do not block emission.
+ *
+ * @param config - Optional configuration with writers and error handler.
+ * @returns An EventEmitter with emit and subscribe methods.
+ *
+ * @example
+ * ```ts
+ * const emitter = createEventEmitter({
+ *   writers: [jsonWriter],
+ *   onError: (err) => console.error('Event write failed:', err),
+ * });
+ *
+ * emitter.subscribe((event) => console.log('Event:', event.eventType));
+ *
+ * await emitter.emit(createExecutionEvent(graph));
+ * ```
+ */
+declare function createEventEmitter(config?: EventEmitterConfig): EventEmitter;
+
 /**
  * Closure-based factory for constructing execution graphs.
  *
@@ -423,16 +935,12 @@ interface GuardConfig {
     readonly onViolation?: 'warn' | 'error' | 'abort';
     /** Custom logger for warnings (defaults to console.warn). */
     readonly logger?: (message: string) => void;
+    /** Optional policy source for adaptive guard behavior based on accumulated knowledge. */
+    readonly policySource?: PolicySource;
+    /** Thresholds for policy-derived violations (only used when policySource is set). */
+    readonly policyThresholds?: PolicyThresholds;
 }
-/**
- * A detected guard violation.
- */
-interface GuardViolation {
-    readonly type: 'timeout' | 'reasoning-loop' | 'spawn-explosion';
-    readonly nodeId: string;
-    readonly message: string;
-    readonly timestamp: number;
-}
+
 /**
  * Check an execution graph for guard violations.
  *
@@ -475,6 +983,106 @@ declare function checkGuards(graph: ExecutionGraph, config?: GuardConfig): reado
  */
 declare function withGuards(builder: GraphBuilder, config?: GuardConfig): GraphBuilder;
 
+/**
+ * LLM-powered semantic analysis engine for agent execution data.
+ *
+ * The insight engine reads from the knowledge store, constructs prompts via
+ * pure prompt builder functions, delegates to a user-provided AnalysisFn,
+ * and caches results as InsightEvents in the store.
+ *
+ * @module
+ */
+
+/**
+ * Create an LLM-powered semantic analysis engine.
+ *
+ * @param store - The knowledge store to read data from and cache insights to.
+ * @param analysisFn - User-provided LLM function (prompt → response).
+ * @param config - Optional configuration (cache TTL).
+ * @returns An InsightEngine for semantic analysis of agent execution data.
+ *
+ * @example
+ * ```ts
+ * const engine = createInsightEngine(store, async (prompt) => {
+ *   return await myLlm.complete(prompt);
+ * });
+ * const result = await engine.explainFailures('my-agent');
+ * console.log(result.content);
+ * ```
+ */
+declare function createInsightEngine(store: KnowledgeStore, analysisFn: AnalysisFn, config?: InsightEngineConfig): InsightEngine;
+
+/**
+ * JSON file-based event writer for AgentFlow.
+ *
+ * Writes each event as an individual JSON file to a configurable directory.
+ * Designed for filesystem-as-IPC: Soma's Curator (or any file-watching consumer)
+ * picks up events from the output directory.
+ *
+ * @module
+ */
+
+/**
+ * Configuration for the JSON event writer.
+ */
+interface JsonEventWriterConfig {
+    /** Directory to write event files to. Created if it does not exist. */
+    readonly outputDir: string;
+}
+/**
+ * Create a JSON event writer that persists events as individual files.
+ *
+ * Each event is written to `{eventType}-{agentId}-{timestamp}.json` where
+ * dots in the eventType are replaced with dashes. Files are formatted with
+ * 2-space indentation for human readability.
+ *
+ * The `write(graph)` method is a no-op — this writer only handles structured events.
+ *
+ * @param config - Writer configuration with output directory.
+ * @returns An EventWriter that writes JSON files.
+ *
+ * @example
+ * ```ts
+ * const writer = createJsonEventWriter({ outputDir: './events' });
+ * await writer.writeEvent(executionEvent);
+ * // Creates: events/execution-completed-my-agent-1710800000000.json
+ * ```
+ */
+declare function createJsonEventWriter(config: JsonEventWriterConfig): EventWriter;
+
+/**
+ * Filesystem-based knowledge store for accumulating execution intelligence.
+ *
+ * Stores execution and pattern events as individual JSON files, organized by
+ * agentId and date. Maintains derived agent profiles that summarize execution
+ * history for fast querying by guards and dashboards.
+ *
+ * Storage layout:
+ * ```
+ * {baseDir}/
+ * ├── events/{agentId}/{YYYY-MM-DD}/{eventType}-{timestamp}.json
+ * ├── patterns/{agentId}/{timestamp}.json
+ * └── profiles/{agentId}.json
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Create a filesystem-based knowledge store for accumulating execution intelligence.
+ *
+ * @param config - Optional configuration with base directory path.
+ * @returns A KnowledgeStore that persists events and maintains agent profiles.
+ *
+ * @example
+ * ```ts
+ * const store = createKnowledgeStore({ baseDir: '.agentflow/knowledge' });
+ * store.append(createExecutionEvent(graph));
+ * const profile = store.getAgentProfile('my-agent');
+ * ```
+ */
+declare function createKnowledgeStore(config?: KnowledgeStoreConfig): KnowledgeStore;
+
 /**
  * AgentFlow Live Monitor — real-time terminal dashboard for any agent system.
  *
@@ -494,6 +1102,85 @@ declare function withGuards(builder: GraphBuilder, config?: GuardConfig): GraphB
 
 declare function startLive(argv: string[]): void;
 
+/**
+ * Load and deserialize execution graphs from JSON.
+ *
+ * Handles all serialization formats produced by the runner, graph-builder,
+ * and third-party tools:
+ *   - `nodes` as a plain object `{ "node_001": { ... } }`  (runner.ts output)
+ *   - `nodes` as an array of `[id, node]` pairs              (Map JSON serialization)
+ *   - `nodes` already a Map                                   (in-memory passthrough)
+ *
+ * @module
+ */
+
+/**
+ * Deserialize a JSON object (or JSON string) into a valid `ExecutionGraph`.
+ *
+ * Use this whenever you read a trace file from disk or receive one over the
+ * network.  It normalizes `nodes` into a proper `Map` regardless of the
+ * serialization format.
+ *
+ * @param input - A parsed JSON object, or a JSON string to be parsed.
+ * @returns A valid `ExecutionGraph` ready for use with query functions.
+ * @throws {Error} If the input cannot be parsed or is missing required fields.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'fs';
+ * import { loadGraph, getStats } from 'agentflow-core';
+ *
+ * const graph = loadGraph(readFileSync('trace.json', 'utf8'));
+ * console.log(getStats(graph));
+ * ```
+ */
+declare function loadGraph(input: string | Record<string, unknown>): ExecutionGraph;
+/**
+ * Serialize an `ExecutionGraph` to a plain JSON-safe object.
+ *
+ * The inverse of `loadGraph`.  `nodes` is written as a plain object keyed by
+ * node ID, which is the most readable format for trace files on disk.
+ *
+ * @param graph - The execution graph to serialize.
+ * @returns A plain object safe to pass to `JSON.stringify`.
+ *
+ * @example
+ * ```ts
+ * import { writeFileSync } from 'fs';
+ * import { graphToJson } from 'agentflow-core';
+ *
+ * writeFileSync('trace.json', JSON.stringify(graphToJson(graph), null, 2));
+ * ```
+ */
+declare function graphToJson(graph: ExecutionGraph): Record<string, unknown>;
+
+/**
+ * PolicySource: read-only interface over the knowledge store for adaptive guards.
+ *
+ * Bridges accumulated execution knowledge to guard decisions without
+ * coupling guards to storage internals.
+ *
+ * @module
+ */
+
+/**
+ * Create a PolicySource backed by a knowledge store.
+ *
+ * All methods delegate to the store's profile data. The PolicySource is a
+ * pure read interface — it never writes to the store.
+ *
+ * @param store - The knowledge store to query.
+ * @returns A PolicySource for use with adaptive guards.
+ *
+ * @example
+ * ```ts
+ * const store = createKnowledgeStore({ baseDir: '.agentflow/knowledge' });
+ * const policy = createPolicySource(store);
+ * const rate = policy.recentFailureRate('my-agent'); // 0.0–1.0
+ * ```
+ */
+declare function createPolicySource(store: KnowledgeStore): PolicySource;
+
 /**
  * AgentFlow Process Audit — OS-level process health checks for agent systems.
  *
@@ -581,6 +1268,22 @@ interface ProcessAuditConfig {
  * ```
  */
 declare function discoverProcessConfig(dirs: string[]): ProcessAuditConfig | null;
+/**
+ * Discover all process configurations from the given directories and systemd.
+ *
+ * Unlike `discoverProcessConfig` which returns only the first match, this
+ * scans all PID files and also discovers systemd user services to return
+ * a complete list of auditable processes.
+ *
+ * @example
+ * ```ts
+ * const configs = discoverAllProcessConfigs(['./data', '/var/run']);
+ * for (const config of configs) {
+ *   console.log(formatAuditReport(auditProcesses(config)));
+ * }
+ * ```
+ */
+declare function discoverAllProcessConfigs(dirs: string[]): ProcessAuditConfig[];
 /**
  * Run a full process health audit.
  *
@@ -609,56 +1312,198 @@ declare function auditProcesses(config: ProcessAuditConfig): ProcessAuditResult;
 declare function formatAuditReport(result: ProcessAuditResult): string;
 
 /**
- * Load and deserialize execution graphs from JSON.
+ * Process mining primitives for cross-run analysis of execution graphs.
  *
- * Handles all serialization formats produced by the runner, graph-builder,
- * and third-party tools:
- *   - `nodes` as a plain object `{ "node_001": { ... } }`  (runner.ts output)
- *   - `nodes` as an array of `[id, node]` pairs              (Map JSON serialization)
- *   - `nodes` already a Map                                   (in-memory passthrough)
+ * All functions are pure: they take frozen graphs and return derived data
+ * without mutation or side effects. Designed to operate on `ExecutionGraph[]`
+ * collections to discover patterns across multiple agent runs.
  *
  * @module
  */
 
 /**
- * Deserialize a JSON object (or JSON string) into a valid `ExecutionGraph`.
+ * Produce a canonical string representation of a graph's execution path.
  *
- * Use this whenever you read a trace file from disk or receive one over the
- * network.  It normalizes `nodes` into a proper `Map` regardless of the
- * serialization format.
+ * Performs a depth-first traversal, emitting `type:name` for each node.
+ * Children are sorted alphabetically by `type:name` to ensure deterministic output.
  *
- * @param input - A parsed JSON object, or a JSON string to be parsed.
- * @returns A valid `ExecutionGraph` ready for use with query functions.
- * @throws {Error} If the input cannot be parsed or is missing required fields.
+ * @param graph - The execution graph.
+ * @returns A `→`-separated path signature, or `""` if the root is unresolvable.
  *
  * @example
  * ```ts
- * import { readFileSync } from 'fs';
- * import { loadGraph, getStats } from 'agentflow-core';
+ * const sig = getPathSignature(graph);
+ * // "agent:main→tool:fetch→tool:analyze"
+ * ```
+ */
+declare function getPathSignature(graph: ExecutionGraph): string;
+/**
+ * Discover a process model from multiple execution graphs.
  *
- * const graph = loadGraph(readFileSync('trace.json', 'utf8'));
- * console.log(getStats(graph));
+ * Walks every graph's node tree and counts parent→child transitions.
+ * The returned model is a directly-follows graph (DFG) annotated with
+ * absolute and relative frequencies.
+ *
+ * @param graphs - Array of execution graphs (must not be empty).
+ * @returns A process model with steps, transitions, and frequencies.
+ * @throws If `graphs` is empty.
+ *
+ * @example
+ * ```ts
+ * const model = discoverProcess(graphs);
+ * for (const t of model.transitions) {
+ *   console.log(`${t.from} → ${t.to} (${(t.probability * 100).toFixed(0)}%)`);
+ * }
  * ```
  */
-declare function loadGraph(input: string | Record<string, unknown>): ExecutionGraph;
+declare function discoverProcess(graphs: ExecutionGraph[]): ProcessModel;
 /**
- * Serialize an `ExecutionGraph` to a plain JSON-safe object.
+ * Group execution graphs by their structural path and return variant clusters.
  *
- * The inverse of `loadGraph`.  `nodes` is written as a plain object keyed by
- * node ID, which is the most readable format for trace files on disk.
+ * Variants are sorted by frequency (most common first). Ties are broken
+ * alphabetically by path signature.
  *
- * @param graph - The execution graph to serialize.
- * @returns A plain object safe to pass to `JSON.stringify`.
+ * @param graphs - Array of execution graphs.
+ * @returns Variant clusters sorted by frequency descending.
  *
  * @example
  * ```ts
- * import { writeFileSync } from 'fs';
- * import { graphToJson } from 'agentflow-core';
+ * const variants = findVariants(graphs);
+ * console.log(`${variants[0].percentage}% of runs follow the happy path`);
+ * ```
+ */
+declare function findVariants(graphs: ExecutionGraph[]): Variant[];
+/**
+ * Identify performance bottlenecks by aggregating node durations across graphs.
  *
- * writeFileSync('trace.json', JSON.stringify(graphToJson(graph), null, 2));
+ * Collects duration samples per node `name` (grouped by `type:name`),
+ * computes percentile statistics, and returns results sorted by p95 descending.
+ *
+ * @param graphs - Array of execution graphs.
+ * @returns Bottleneck entries sorted by p95 duration descending.
+ *
+ * @example
+ * ```ts
+ * const bottlenecks = getBottlenecks(graphs);
+ * console.log(`Slowest: ${bottlenecks[0].nodeName} (p95: ${bottlenecks[0].durations.p95}ms)`);
  * ```
  */
-declare function graphToJson(graph: ExecutionGraph): Record<string, unknown>;
+declare function getBottlenecks(graphs: ExecutionGraph[]): Bottleneck[];
+/**
+ * Compare a single execution graph against a discovered process model.
+ *
+ * Classifies deviations into three categories:
+ * - `unexpected-transition`: exists in the graph but not in the model
+ * - `missing-transition`: exists in the model with probability > 0.5 but not in the graph
+ * - `low-frequency-path`: exists in both but model probability < 0.1
+ *
+ * @param graph - The execution graph to check.
+ * @param model - The process model to check against.
+ * @returns A conformance report with score, deviations, and conformance flag.
+ *
+ * @example
+ * ```ts
+ * const report = checkConformance(newRun, model);
+ * if (!report.isConforming) {
+ *   console.log(`Conformance: ${(report.conformanceScore * 100).toFixed(0)}%`);
+ *   for (const d of report.deviations) console.log(d.message);
+ * }
+ * ```
+ */
+declare function checkConformance(graph: ExecutionGraph, model: ProcessModel): ConformanceReport;
+
+/**
+ * Pure prompt construction functions for LLM-powered semantic analysis.
+ *
+ * Each function takes knowledge store data and returns a structured prompt string.
+ * No side effects, no filesystem access, no external calls.
+ *
+ * @module
+ */
+
+/**
+ * Build a structured prompt for LLM analysis of agent failures.
+ *
+ * @param events - Recent failed execution events for the agent.
+ * @param profile - The agent's derived profile.
+ * @returns A structured prompt string.
+ */
+declare function buildFailureAnalysisPrompt(events: ExecutionEvent[], profile: AgentProfile): string;
+/**
+ * Build a structured prompt for explaining why an execution was anomalous.
+ *
+ * @param event - The specific execution event flagged as anomalous.
+ * @param profile - The agent's derived profile for baseline context.
+ * @returns A structured prompt string.
+ */
+declare function buildAnomalyExplanationPrompt(event: ExecutionEvent, profile: AgentProfile): string;
+/**
+ * Build a structured prompt for generating an agent health summary.
+ *
+ * @param profile - The agent's derived profile.
+ * @param recentEvents - Recent execution events.
+ * @param patterns - Recent pattern discovery events.
+ * @returns A structured prompt string.
+ */
+declare function buildAgentSummaryPrompt(profile: AgentProfile, recentEvents: ExecutionEvent[], patterns: PatternEvent[]): string;
+/**
+ * Build a structured prompt for generating actionable fix recommendations.
+ *
+ * @param events - Recent failed execution events.
+ * @param profile - The agent's derived profile.
+ * @param patterns - Recent pattern discovery events.
+ * @returns A structured prompt string.
+ */
+declare function buildFixSuggestionPrompt(events: ExecutionEvent[], profile: AgentProfile, patterns: PatternEvent[]): string;
+
+/**
+ * Pure functions for building and formatting run receipts from execution graphs.
+ *
+ * A receipt is a structured summary of a completed (or running) agent execution,
+ * including per-step details, cost attribution, and aggregate counts.
+ * @module
+ */
+
+/**
+ * Walk an execution graph and produce a structured {@link RunReceipt}.
+ *
+ * Steps are sorted by `startTime`. Summary counts classify each node as
+ * succeeded (`completed`), failed (`failed | hung | timeout`), or skipped
+ * (none currently — reserved for future use). `attempted` equals the total
+ * node count.
+ *
+ * @param graph - A built (or snapshot) execution graph.
+ * @returns A frozen run receipt.
+ */
+declare function toReceipt(graph: ExecutionGraph): RunReceipt;
+/**
+ * Format a {@link RunReceipt} into a human-readable text block.
+ *
+ * Layout:
+ * ```
+ * === Run Receipt ===
+ * Run:      <runId>
+ * Agent:    <agentId>
+ * Status:   <status>
+ * Duration: <totalDurationMs>ms
+ *
+ * Summary: <attempted> attempted, <succeeded> succeeded, <failed> failed, <skipped> skipped
+ *
+ *  # | Step             | Type    | Status    | Duration | Tokens
+ * ---|------------------|---------|-----------|----------|-------
+ *  1 | fetch-data       | tool    | completed | 120ms    | 450
+ *  ...
+ *
+ * Total token cost: 1 250
+ * ```
+ *
+ * Shows `'---'` for missing duration and `'---'` for missing cost data per step.
+ * Shows `'no cost data'` for the totals line when no cost information is available.
+ *
+ * @param receipt - A run receipt produced by {@link toReceipt}.
+ * @returns Multi-line formatted string.
+ */
+declare function formatReceipt(receipt: RunReceipt): string;
 
 /**
  * CLI runner that wraps any command with automatic AgentFlow tracing.
@@ -709,6 +1554,41 @@ interface RunResult {
  */
 declare function runTraced(config: RunConfig): Promise<RunResult>;
 
+/**
+ * Soma-compatible event writer for AgentFlow.
+ *
+ * Converts AgentFlow events (ExecutionEvent, PatternEvent) into Markdown files
+ * with YAML frontmatter that Soma's Curator can ingest from its inbox directory.
+ *
+ * @module
+ */
+
+/**
+ * Configuration for the Soma event writer.
+ */
+interface SomaEventWriterConfig {
+    /** Directory to write event files to (Soma's inbox). Created if it does not exist. */
+    readonly inboxDir: string;
+}
+/**
+ * Create a Soma event writer that persists events as Curator-compatible Markdown files.
+ *
+ * Each event is written to `{type}-{agentId}-{compact-ISO-timestamp}.md` in the
+ * configured inbox directory. The Curator picks up these files on its 60-second cycle.
+ *
+ * @param config - Writer configuration with inbox directory path.
+ * @returns An EventWriter that writes Markdown files to the Soma inbox.
+ *
+ * @example
+ * ```ts
+ * const writer = createSomaEventWriter({ inboxDir: '~/.openclaw/workspace/inbox' });
+ * const emitter = createEventEmitter({ writers: [writer] });
+ * await emitter.emit(createExecutionEvent(graph));
+ * // Creates: ~/.openclaw/workspace/inbox/execution-alfred-20260314T083502.md
+ * ```
+ */
+declare function createSomaEventWriter(config: SomaEventWriterConfig): EventWriter;
+
 /**
  * JSON file-based trace storage for ExecutionGraphs.
  *
@@ -857,4 +1737,4 @@ interface AlertPayload {
     readonly dirs: readonly string[];
 }
 
-export { type Adapter, type AgentFlowConfig, type AlertCondition, type AlertPayload, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type OsProcess, type PidFileResult, type ProcessAuditConfig, type ProcessAuditResult, type RunConfig, type RunResult, type StartNodeOptions, type SystemdUnitResult, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type WorkerEntry, type WorkersResult, type Writer, auditProcesses, checkGuards, createGraphBuilder, createTraceStore, discoverProcessConfig, findWaitingOn, formatAuditReport, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };
+export { type Adapter, type AgentFlowConfig, type AgentFlowEventType, type AgentProfile, type AlertCondition, type AlertPayload, type AnalysisFn, type Bottleneck, type ConformanceHistory, type ConformanceHistoryEntry, type ConformanceReport, type DecisionTraceData, type Deviation, type DeviationType, type DistributedTrace, type DriftOptions, type DriftReport, type EdgeType, type EfficiencyFlag, type EfficiencyReport, type EventEmitter, type EventEmitterConfig, type EventWriter, type ExecutionEdge, type ExecutionEvent, type ExecutionEventOptions, type ExecutionGraph, type ExecutionNode, type FailurePoint, type GraphBuilder, type GraphStats, type GraphStatus, type GuardConfig, type GuardExplanation, type GuardViolation, type InsightEngine, type InsightEngineConfig, type InsightEvent, type InsightResult, type JsonEventWriterConfig, type KnowledgeStore, type KnowledgeStoreConfig, type MutableExecutionNode, type NodeCost, type NodeStatus, type NodeType, type NotifyChannel, type OsProcess, type OutcomeAssertion, type PatternEvent, type PidFileResult, type PolicySource, type PolicyThresholds, type ProcessAuditConfig, type ProcessAuditResult, type ProcessContext, type ProcessModel, type ProcessTransition, type RunConfig, type RunEfficiency, type RunReceipt, type RunResult, type SemanticContext, type SomaEventWriterConfig, type StartNodeOptions, type StepSummary, type SystemdUnitResult, type TraceEvent, type TraceEventType, type TraceStore, type Variant, type VariantOptions, type WatchConfig, type WorkerEntry, type WorkersResult, type Writer, auditProcesses, buildAgentSummaryPrompt, buildAnomalyExplanationPrompt, buildFailureAnalysisPrompt, buildFixSuggestionPrompt, checkConformance, checkGuards, createEventEmitter, createExecutionEvent, createGraphBuilder, createInsightEngine, createJsonEventWriter, createKnowledgeStore, createPatternEvent, createPolicySource, createSomaEventWriter, createTraceStore, discoverAllProcessConfigs, discoverProcess, discoverProcessConfig, findVariants, findWaitingOn, formatAuditReport, formatReceipt, getBottlenecks, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getPathSignature, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toReceipt, toTimeline, withGuards };