agentfootprint 1.23.0 → 2.1.0

package/dist/types/events/payloads.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Event payload types — the 45 typed event payloads across 13 domains.
+ *
+ * Pattern: Discriminated Union (Gang of Four inspired, TS-native).
+ * Role:    Contract layer of Event-Driven Hexagonal Architecture.
+ * Emits:   (types only).
+ */
+import type { CompositionKind, ContextLifetime, ContextRecency, ContextRole, ContextSlot, ContextSource, LLMProviderName, ToolProtocol } from './types.js';
+export interface CompositionEnterPayload {
+    readonly kind: CompositionKind;
+    readonly id: string;
+    readonly name: string;
+    readonly childCount: number;
+}
+export interface CompositionExitPayload {
+    readonly kind: CompositionKind;
+    readonly id: string;
+    readonly status: 'ok' | 'err' | 'break' | 'budget_exhausted';
+    readonly durationMs: number;
+}
+export interface ParallelForkStartPayload {
+    readonly parentId: string;
+    readonly branches: readonly {
+        id: string;
+        name: string;
+    }[];
+}
+export interface ParallelBranchCompletePayload {
+    readonly parentId: string;
+    readonly branchId: string;
+    readonly status: 'ok' | 'err';
+    readonly durationMs: number;
+}
+export interface ParallelMergeEndPayload {
+    readonly parentId: string;
+    readonly strategy: 'llm' | 'fn';
+    readonly resultSummary: string;
+    readonly mergedBranchCount: number;
+}
+export interface ConditionalRouteDecidedPayload {
+    readonly conditionalId: string;
+    readonly chosen: string;
+    readonly rationale?: string;
+    readonly evidence?: unknown;
+}
+export interface LoopIterationStartPayload {
+    readonly loopId: string;
+    readonly iteration: number;
+}
+export interface LoopIterationExitPayload {
+    readonly loopId: string;
+    readonly iteration: number;
+    readonly reason: 'budget' | 'guard_false' | 'break' | 'body_complete';
+}
+export interface AgentTurnStartPayload {
+    readonly turnIndex: number;
+    readonly userPrompt: string;
+}
+export interface AgentTurnEndPayload {
+    readonly turnIndex: number;
+    readonly finalContent: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly iterationCount: number;
+    readonly durationMs: number;
+}
+export interface AgentIterationStartPayload {
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+}
+export interface AgentIterationEndPayload {
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+    readonly toolCallCount: number;
+}
+export interface AgentRouteDecidedPayload {
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+    readonly chosen: 'tool-calls' | 'final';
+    readonly rationale?: string;
+}
+export interface AgentHandoffPayload {
+    readonly fromAgentId: string;
+    readonly toAgentId: string;
+    readonly reason?: string;
+    readonly viaProtocol?: 'native' | 'mcp' | 'http';
+}
+export interface LLMStartPayload {
+    readonly iteration: number;
+    readonly provider: LLMProviderName;
+    readonly model: string;
+    readonly systemPromptChars: number;
+    readonly messagesCount: number;
+    readonly toolsCount: number;
+    readonly estimatedPromptTokens?: number;
+    readonly temperature?: number;
+    readonly providerRequestRef?: string;
+}
+export interface LLMEndPayload {
+    readonly iteration: number;
+    readonly content: string;
+    readonly toolCallCount: number;
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+    };
+    readonly stopReason: string;
+    readonly durationMs: number;
+    readonly providerResponseRef?: string;
+}
+export interface LLMTokenPayload {
+    readonly iteration: number;
+    readonly tokenIndex: number;
+    readonly content: string;
+}
+export interface ToolStartPayload {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly parallelCount?: number;
+    readonly protocol?: ToolProtocol;
+}
+export interface ToolEndPayload {
+    readonly toolCallId: string;
+    readonly result: unknown;
+    readonly error?: boolean;
+    readonly durationMs: number;
+}
+export interface ContextInjectedPayload {
+    readonly contentSummary: string;
+    readonly contentHash: string;
+    readonly rawContent?: string;
+    readonly slot: ContextSlot;
+    readonly asRole?: ContextRole;
+    readonly asRecency?: ContextRecency;
+    readonly position?: number;
+    readonly sectionTag?: string;
+    readonly source: ContextSource;
+    readonly sourceId?: string;
+    readonly upstreamRef?: string;
+    readonly reason: string;
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    readonly threshold?: number;
+    readonly budgetSpent?: {
+        readonly tokens: number;
+        readonly fractionOfCap: number;
+    };
+    readonly expiresAfter?: ContextLifetime;
+}
+export interface ContextEvictedPayload {
+    readonly slot: ContextSlot;
+    readonly contentHash: string;
+    readonly reason: 'budget' | 'stale' | 'low_score' | 'policy' | 'user_revoked';
+    readonly survivalMs: number;
+}
+export interface ContextSlotComposedPayload {
+    readonly slot: ContextSlot;
+    readonly iteration: number;
+    readonly budget: {
+        readonly cap: number;
+        readonly used: number;
+        readonly headroomChars: number;
+    };
+    readonly sourceBreakdown: Readonly<Partial<Record<ContextSource, {
+        readonly chars: number;
+        readonly count: number;
+    }>>>;
+    readonly orderingStrategy?: string;
+    readonly droppedCount: number;
+    readonly droppedSummaries: readonly string[];
+}
+export interface ContextBudgetPressurePayload {
+    readonly slot: ContextSlot;
+    readonly capTokens: number;
+    readonly projectedTokens: number;
+    readonly overflowBy: number;
+    readonly planAction: 'evict' | 'summarize' | 'abort';
+}
+export interface ErrorFatalPayload {
+    readonly error: string;
+    readonly stage: string;
+    readonly scope: string;
+}
+export interface PauseRequestPayload {
+    readonly reason: string;
+    readonly questionPayload: Readonly<Record<string, unknown>>;
+}
+export interface PauseResumePayload {
+    readonly resumeInput: Readonly<Record<string, unknown>>;
+    readonly pausedDurationMs: number;
+}
+export interface MemoryStrategyAppliedPayload {
+    readonly strategyId: string;
+    readonly strategyKind: 'sliding-window' | 'summarizing' | 'semantic' | 'fact-extraction' | 'hybrid';
+    readonly reason: string;
+    readonly scoreEvidence?: Readonly<Record<string, unknown>>;
+    readonly inputMemoryCount: number;
+    readonly outputMemoryCount: number;
+    readonly droppedIds: readonly string[];
+    readonly addedIds: readonly string[];
+}
+export interface MemoryAttachedPayload {
+    readonly memoryId: string;
+    readonly contentSummary: string;
+    readonly score?: number;
+    readonly rank?: number;
+    readonly source: 'store' | 'auto-extract' | 'manual';
+    readonly retriever?: 'pinecone' | 'weaviate' | 'qdrant' | 'chroma' | 'custom';
+}
+export interface MemoryDetachedPayload {
+    readonly memoryId: string;
+    readonly reason: 'stale' | 'budget' | 'score_low' | 'policy';
+}
+export interface MemoryWrittenPayload {
+    readonly memoryId: string;
+    readonly contentSummary: string;
+    readonly source: 'auto' | 'manual';
+    readonly actor?: string;
+}
+export interface ToolsOfferedPayload {
+    readonly availableIds: readonly string[];
+    readonly withheldIds: readonly string[];
+    readonly withheldReasons: Readonly<Record<string, 'permission' | 'skill_inactive' | 'gated' | 'cost_guard'>>;
+    readonly reason: string;
+}
+export interface ToolsActivatedPayload {
+    readonly toolId: string;
+    readonly reason: 'skill_activated' | 'autoActivate' | 'permission_granted';
+    readonly source?: string;
+}
+export interface ToolsDeactivatedPayload {
+    readonly toolId: string;
+    readonly reason: 'skill_deactivated' | 'permission_revoked';
+}
+export interface SkillActivatedPayload {
+    readonly skillId: string;
+    readonly reason: 'autoActivate' | 'read_skill_result' | 'manual';
+    readonly injectedTools?: readonly string[];
+    readonly injectedSystemPromptChars?: number;
+}
+export interface SkillDeactivatedPayload {
+    readonly skillId: string;
+    readonly reason: string;
+}
+export interface PermissionCheckPayload {
+    readonly capability: 'tool_call' | 'memory_read' | 'memory_write' | 'external_net' | 'user_data';
+    readonly actor: string;
+    readonly target?: string;
+    readonly result: 'allow' | 'deny' | 'gate_open';
+    readonly policyEngine?: 'opa' | 'cerbos' | 'custom';
+    readonly policyRuleId?: string;
+    readonly rationale?: string;
+}
+export interface PermissionGateOpenedPayload {
+    readonly gateId: string;
+    readonly openedBy: string;
+    readonly expiresAt?: number;
+}
+export interface PermissionGateClosedPayload {
+    readonly gateId: string;
+    readonly reason: string;
+}
+export interface RiskFlaggedPayload {
+    readonly severity: 'low' | 'medium' | 'high' | 'critical';
+    readonly category: 'pii' | 'prompt_injection' | 'runaway_loop' | 'cost_overrun' | 'hallucination_flag';
+    readonly detector: 'nemo_guardrails' | 'llama_guard' | 'custom' | 'heuristic';
+    readonly evidence: Readonly<Record<string, unknown>>;
+    readonly action: 'warn' | 'redact' | 'abort';
+}
+export interface FallbackTriggeredPayload {
+    readonly kind: 'provider' | 'tool' | 'skill';
+    readonly primary: string;
+    readonly fallback: string;
+    readonly reason: string;
+}
+export interface CostTickPayload {
+    readonly scope: 'iteration' | 'turn' | 'run';
+    readonly tokensInput: number;
+    readonly tokensOutput: number;
+    readonly estimatedUsd: number;
+    readonly cumulative: {
+        readonly tokensInput: number;
+        readonly tokensOutput: number;
+        readonly estimatedUsd: number;
+    };
+}
+export interface CostLimitHitPayload {
+    readonly kind: 'max_tokens' | 'max_cost' | 'max_iterations' | 'max_wallclock';
+    readonly limit: number;
+    readonly actual: number;
+    readonly action: 'abort' | 'warn' | 'degrade';
+}
+export interface EvalScorePayload {
+    readonly metricId: string;
+    readonly value: number;
+    readonly threshold?: number;
+    readonly target: 'iteration' | 'turn' | 'run' | 'toolCall';
+    readonly targetRef: string;
+    readonly evaluator?: 'llm' | 'fn' | 'heuristic';
+    readonly evidence?: Readonly<Record<string, unknown>>;
+}
+export interface EvalThresholdCrossedPayload {
+    readonly metricId: string;
+    readonly direction: 'above' | 'below';
+    readonly value: number;
+    readonly threshold: number;
+    readonly actionTaken?: string;
+}
+export interface ErrorRetriedPayload {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly lastError: string;
+    readonly backoffMs: number;
+    readonly reason: string;
+}
+export interface ErrorRecoveredPayload {
+    readonly attempt: number;
+    readonly totalDurationMs: number;
+}
+export interface EmbeddingGeneratedPayload {
+    readonly model: string;
+    readonly provider: 'openai' | 'cohere' | 'voyage' | 'local' | 'custom';
+    readonly inputKind: 'query' | 'document';
+    readonly dimension: number;
+    readonly count: number;
+    readonly durationMs: number;
+    readonly tokensSpent?: number;
+}
+//# sourceMappingURL=payloads.d.ts.map

package/dist/types/events/payloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloads.d.ts","sourceRoot":"","sources":["../../../src/events/payloads.ts"],"names":[],"mappings":"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"}

package/dist/types/events/registry.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Event registry — 45 typed events across 13 domains.
+ *
+ * Pattern: Discriminated Union + Typed Factory (Gang of Four adapted for TS).
+ * Role:    The stable public event contract — the "ports" of the hexagonal
+ *          architecture (Cockburn, 2005).
+ * Emits:   N/A — this file DEFINES event types and factory helpers.
+ *
+ * Consumers subscribe via `.on(type, listener)`. Emitters construct events
+ * via typed helpers (e.g. `makeContextInjected(payload)`) rather than raw
+ * strings — compile-time safety prevents typos and payload drift.
+ *
+ * Events are additive within a major version; breaking changes require a
+ * major bump. See agentfootprint_v2_detailed_design.md for rules.
+ */
+import type { AgentfootprintEventEnvelope } from './types.js';
+import type { AgentHandoffPayload, AgentIterationEndPayload, AgentIterationStartPayload, AgentRouteDecidedPayload, AgentTurnEndPayload, AgentTurnStartPayload, CompositionEnterPayload, CompositionExitPayload, ConditionalRouteDecidedPayload, ContextBudgetPressurePayload, ContextEvictedPayload, ContextInjectedPayload, ContextSlotComposedPayload, CostLimitHitPayload, CostTickPayload, EmbeddingGeneratedPayload, ErrorFatalPayload, ErrorRecoveredPayload, ErrorRetriedPayload, EvalScorePayload, EvalThresholdCrossedPayload, FallbackTriggeredPayload, LLMEndPayload, LLMStartPayload, LLMTokenPayload, LoopIterationExitPayload, LoopIterationStartPayload, MemoryAttachedPayload, MemoryDetachedPayload, MemoryStrategyAppliedPayload, MemoryWrittenPayload, ParallelBranchCompletePayload, ParallelForkStartPayload, ParallelMergeEndPayload, PauseRequestPayload, PauseResumePayload, PermissionCheckPayload, PermissionGateClosedPayload, PermissionGateOpenedPayload, RiskFlaggedPayload, SkillActivatedPayload, SkillDeactivatedPayload, ToolEndPayload, ToolsActivatedPayload, ToolsDeactivatedPayload, ToolsOfferedPayload, ToolStartPayload } from './payloads.js';
+export declare const EVENT_NAMES: {
+    readonly composition: {
+        readonly enter: "agentfootprint.composition.enter";
+        readonly exit: "agentfootprint.composition.exit";
+        readonly forkStart: "agentfootprint.composition.fork_start";
+        readonly branchComplete: "agentfootprint.composition.branch_complete";
+        readonly mergeEnd: "agentfootprint.composition.merge_end";
+        readonly routeDecided: "agentfootprint.composition.route_decided";
+        readonly iterationStart: "agentfootprint.composition.iteration_start";
+        readonly iterationExit: "agentfootprint.composition.iteration_exit";
+    };
+    readonly agent: {
+        readonly turnStart: "agentfootprint.agent.turn_start";
+        readonly turnEnd: "agentfootprint.agent.turn_end";
+        readonly iterationStart: "agentfootprint.agent.iteration_start";
+        readonly iterationEnd: "agentfootprint.agent.iteration_end";
+        readonly routeDecided: "agentfootprint.agent.route_decided";
+        readonly handoff: "agentfootprint.agent.handoff";
+    };
+    readonly stream: {
+        readonly llmStart: "agentfootprint.stream.llm_start";
+        readonly llmEnd: "agentfootprint.stream.llm_end";
+        readonly token: "agentfootprint.stream.token";
+        readonly toolStart: "agentfootprint.stream.tool_start";
+        readonly toolEnd: "agentfootprint.stream.tool_end";
+    };
+    readonly context: {
+        readonly injected: "agentfootprint.context.injected";
+        readonly evicted: "agentfootprint.context.evicted";
+        readonly slotComposed: "agentfootprint.context.slot_composed";
+        readonly budgetPressure: "agentfootprint.context.budget_pressure";
+    };
+    readonly memory: {
+        readonly strategyApplied: "agentfootprint.memory.strategy_applied";
+        readonly attached: "agentfootprint.memory.attached";
+        readonly detached: "agentfootprint.memory.detached";
+        readonly written: "agentfootprint.memory.written";
+    };
+    readonly tools: {
+        readonly offered: "agentfootprint.tools.offered";
+        readonly activated: "agentfootprint.tools.activated";
+        readonly deactivated: "agentfootprint.tools.deactivated";
+    };
+    readonly skill: {
+        readonly activated: "agentfootprint.skill.activated";
+        readonly deactivated: "agentfootprint.skill.deactivated";
+    };
+    readonly permission: {
+        readonly check: "agentfootprint.permission.check";
+        readonly gateOpened: "agentfootprint.permission.gate_opened";
+        readonly gateClosed: "agentfootprint.permission.gate_closed";
+    };
+    readonly risk: {
+        readonly flagged: "agentfootprint.risk.flagged";
+    };
+    readonly fallback: {
+        readonly triggered: "agentfootprint.fallback.triggered";
+    };
+    readonly cost: {
+        readonly tick: "agentfootprint.cost.tick";
+        readonly limitHit: "agentfootprint.cost.limit_hit";
+    };
+    readonly eval: {
+        readonly score: "agentfootprint.eval.score";
+        readonly thresholdCrossed: "agentfootprint.eval.threshold_crossed";
+    };
+    readonly error: {
+        readonly retried: "agentfootprint.error.retried";
+        readonly recovered: "agentfootprint.error.recovered";
+        readonly fatal: "agentfootprint.error.fatal";
+    };
+    readonly pause: {
+        readonly request: "agentfootprint.pause.request";
+        readonly resume: "agentfootprint.pause.resume";
+    };
+    readonly embedding: {
+        readonly generated: "agentfootprint.embedding.generated";
+    };
+};
+export interface AgentfootprintEventMap {
+    'agentfootprint.composition.enter': AgentfootprintEventEnvelope<'agentfootprint.composition.enter', CompositionEnterPayload>;
+    'agentfootprint.composition.exit': AgentfootprintEventEnvelope<'agentfootprint.composition.exit', CompositionExitPayload>;
+    'agentfootprint.composition.fork_start': AgentfootprintEventEnvelope<'agentfootprint.composition.fork_start', ParallelForkStartPayload>;
+    'agentfootprint.composition.branch_complete': AgentfootprintEventEnvelope<'agentfootprint.composition.branch_complete', ParallelBranchCompletePayload>;
+    'agentfootprint.composition.merge_end': AgentfootprintEventEnvelope<'agentfootprint.composition.merge_end', ParallelMergeEndPayload>;
+    'agentfootprint.composition.route_decided': AgentfootprintEventEnvelope<'agentfootprint.composition.route_decided', ConditionalRouteDecidedPayload>;
+    'agentfootprint.composition.iteration_start': AgentfootprintEventEnvelope<'agentfootprint.composition.iteration_start', LoopIterationStartPayload>;
+    'agentfootprint.composition.iteration_exit': AgentfootprintEventEnvelope<'agentfootprint.composition.iteration_exit', LoopIterationExitPayload>;
+    'agentfootprint.agent.turn_start': AgentfootprintEventEnvelope<'agentfootprint.agent.turn_start', AgentTurnStartPayload>;
+    'agentfootprint.agent.turn_end': AgentfootprintEventEnvelope<'agentfootprint.agent.turn_end', AgentTurnEndPayload>;
+    'agentfootprint.agent.iteration_start': AgentfootprintEventEnvelope<'agentfootprint.agent.iteration_start', AgentIterationStartPayload>;
+    'agentfootprint.agent.iteration_end': AgentfootprintEventEnvelope<'agentfootprint.agent.iteration_end', AgentIterationEndPayload>;
+    'agentfootprint.agent.route_decided': AgentfootprintEventEnvelope<'agentfootprint.agent.route_decided', AgentRouteDecidedPayload>;
+    'agentfootprint.agent.handoff': AgentfootprintEventEnvelope<'agentfootprint.agent.handoff', AgentHandoffPayload>;
+    'agentfootprint.stream.llm_start': AgentfootprintEventEnvelope<'agentfootprint.stream.llm_start', LLMStartPayload>;
+    'agentfootprint.stream.llm_end': AgentfootprintEventEnvelope<'agentfootprint.stream.llm_end', LLMEndPayload>;
+    'agentfootprint.stream.token': AgentfootprintEventEnvelope<'agentfootprint.stream.token', LLMTokenPayload>;
+    'agentfootprint.stream.tool_start': AgentfootprintEventEnvelope<'agentfootprint.stream.tool_start', ToolStartPayload>;
+    'agentfootprint.stream.tool_end': AgentfootprintEventEnvelope<'agentfootprint.stream.tool_end', ToolEndPayload>;
+    'agentfootprint.context.injected': AgentfootprintEventEnvelope<'agentfootprint.context.injected', ContextInjectedPayload>;
+    'agentfootprint.context.evicted': AgentfootprintEventEnvelope<'agentfootprint.context.evicted', ContextEvictedPayload>;
+    'agentfootprint.context.slot_composed': AgentfootprintEventEnvelope<'agentfootprint.context.slot_composed', ContextSlotComposedPayload>;
+    'agentfootprint.context.budget_pressure': AgentfootprintEventEnvelope<'agentfootprint.context.budget_pressure', ContextBudgetPressurePayload>;
+    'agentfootprint.memory.strategy_applied': AgentfootprintEventEnvelope<'agentfootprint.memory.strategy_applied', MemoryStrategyAppliedPayload>;
+    'agentfootprint.memory.attached': AgentfootprintEventEnvelope<'agentfootprint.memory.attached', MemoryAttachedPayload>;
+    'agentfootprint.memory.detached': AgentfootprintEventEnvelope<'agentfootprint.memory.detached', MemoryDetachedPayload>;
+    'agentfootprint.memory.written': AgentfootprintEventEnvelope<'agentfootprint.memory.written', MemoryWrittenPayload>;
+    'agentfootprint.tools.offered': AgentfootprintEventEnvelope<'agentfootprint.tools.offered', ToolsOfferedPayload>;
+    'agentfootprint.tools.activated': AgentfootprintEventEnvelope<'agentfootprint.tools.activated', ToolsActivatedPayload>;
+    'agentfootprint.tools.deactivated': AgentfootprintEventEnvelope<'agentfootprint.tools.deactivated', ToolsDeactivatedPayload>;
+    'agentfootprint.skill.activated': AgentfootprintEventEnvelope<'agentfootprint.skill.activated', SkillActivatedPayload>;
+    'agentfootprint.skill.deactivated': AgentfootprintEventEnvelope<'agentfootprint.skill.deactivated', SkillDeactivatedPayload>;
+    'agentfootprint.permission.check': AgentfootprintEventEnvelope<'agentfootprint.permission.check', PermissionCheckPayload>;
+    'agentfootprint.permission.gate_opened': AgentfootprintEventEnvelope<'agentfootprint.permission.gate_opened', PermissionGateOpenedPayload>;
+    'agentfootprint.permission.gate_closed': AgentfootprintEventEnvelope<'agentfootprint.permission.gate_closed', PermissionGateClosedPayload>;
+    'agentfootprint.risk.flagged': AgentfootprintEventEnvelope<'agentfootprint.risk.flagged', RiskFlaggedPayload>;
+    'agentfootprint.fallback.triggered': AgentfootprintEventEnvelope<'agentfootprint.fallback.triggered', FallbackTriggeredPayload>;
+    'agentfootprint.cost.tick': AgentfootprintEventEnvelope<'agentfootprint.cost.tick', CostTickPayload>;
+    'agentfootprint.cost.limit_hit': AgentfootprintEventEnvelope<'agentfootprint.cost.limit_hit', CostLimitHitPayload>;
+    'agentfootprint.eval.score': AgentfootprintEventEnvelope<'agentfootprint.eval.score', EvalScorePayload>;
+    'agentfootprint.eval.threshold_crossed': AgentfootprintEventEnvelope<'agentfootprint.eval.threshold_crossed', EvalThresholdCrossedPayload>;
+    'agentfootprint.error.retried': AgentfootprintEventEnvelope<'agentfootprint.error.retried', ErrorRetriedPayload>;
+    'agentfootprint.error.recovered': AgentfootprintEventEnvelope<'agentfootprint.error.recovered', ErrorRecoveredPayload>;
+    'agentfootprint.error.fatal': AgentfootprintEventEnvelope<'agentfootprint.error.fatal', ErrorFatalPayload>;
+    'agentfootprint.pause.request': AgentfootprintEventEnvelope<'agentfootprint.pause.request', PauseRequestPayload>;
+    'agentfootprint.pause.resume': AgentfootprintEventEnvelope<'agentfootprint.pause.resume', PauseResumePayload>;
+    'agentfootprint.embedding.generated': AgentfootprintEventEnvelope<'agentfootprint.embedding.generated', EmbeddingGeneratedPayload>;
+}
+/** Union of every typed event. Consumers use this for exhaustive `switch`. */
+export type AgentfootprintEvent = AgentfootprintEventMap[keyof AgentfootprintEventMap];
+/** Every known event-type string, useful for runtime lookups / lints. */
+export type AgentfootprintEventType = keyof AgentfootprintEventMap;
+/**
+ * Complete list of every registered event type, for lint / runtime validation.
+ * A new event MUST be added here or the exhaustiveness tests fail.
+ */
+export declare const ALL_EVENT_TYPES: readonly AgentfootprintEventType[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/events/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/events/registry.ts"],"names":[],"mappings":"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"}

package/dist/types/events/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * EventMeta + shared event vocabulary.
+ *
+ * Pattern: Domain-Driven Design value objects (Evans, 2003).
+ * Role:    Shared vocabulary for all 45 typed events in registry.ts.
+ * Emits:   (types only — no runtime behavior here).
+ */
+export type ContextSlot = 'system-prompt' | 'messages' | 'tools';
+/**
+ * The origin / flavor of a context injection.
+ *
+ * BASELINE sources (regular LLM-API flow — NOT context engineering):
+ *   - `user`        → the user's message (current turn or history replay)
+ *   - `tool-result` → tool return for a tool call (current or history)
+ *   - `assistant`   → prior-turn assistant output replayed as history
+ *   - `base`        → static system prompt configured at build time
+ *   - `registry`    → static tool registry configured at build time
+ *
+ * ENGINEERED sources (context engineering flavors — the teaching layer):
+ *   - `rag`          → retrieval-augmented injection
+ *   - `skill`        → skill activation (LLM-guided via read_skill)
+ *   - `memory`       → memory strategy re-injection
+ *   - `instructions` → rule-based behavior guidance
+ *   - `steering`     → always-on policy / persona / format rule
+ *   - `fact`         → developer-supplied data (user profile, env, …)
+ *   - `custom`       → consumer-defined (anything bespoke)
+ *
+ * Adding a new source is NOT a breaking change; removing one IS.
+ */
+export type ContextSource = 'rag' | 'skill' | 'memory' | 'instructions' | 'steering' | 'fact' | 'custom' | 'user' | 'tool-result' | 'assistant' | 'base' | 'registry';
+export type ContextRole = 'system' | 'user' | 'assistant' | 'tool';
+export type ContextRecency = 'latest' | 'earlier';
+export type ContextLifetime = 'iteration' | 'turn' | 'run' | 'persistent';
+export type LLMProviderName = 'anthropic' | 'openai' | 'google' | 'cohere' | 'local' | 'custom' | 'mock' | (string & {});
+export type ToolProtocol = 'native' | 'mcp' | 'http' | 'python-fn';
+export type CompositionKind = 'Sequence' | 'Parallel' | 'Conditional' | 'Loop';
+/**
+ * Metadata attached by the dispatcher to every event. Consumers never
+ * construct this manually — the dispatcher fills it in.
+ */
+export interface EventMeta {
+    /** Wall-clock ms — for external correlation / dashboards. */
+    readonly wallClockMs: number;
+    /** ms since run start — deterministic replay. */
+    readonly runOffsetMs: number;
+    /** footprintjs universal stage key. */
+    readonly runtimeStageId: string;
+    /** Subflow path parsed from runtimeStageId. */
+    readonly subflowPath: readonly string[];
+    /** Composition ancestry — e.g. ['Sequence:pipeline','Agent:ethics']. */
+    readonly compositionPath: readonly string[];
+    /** Turn index (Agent context only). */
+    readonly turnIndex?: number;
+    /** Iteration index (Agent context only). */
+    readonly iterIndex?: number;
+    /** OTEL trace id (when env.traceId is set). */
+    readonly traceId?: string;
+    /** OTEL span id for the current composition boundary. */
+    readonly spanId?: string;
+    /** Domain correlation id — ties retrieval → injection → LLM. */
+    readonly correlationId?: string;
+    /** Run id — demultiplex concurrent runs sharing one dispatcher. */
+    readonly runId: string;
+}
+/** Discriminated-union envelope every event implements. */
+export interface AgentfootprintEventEnvelope<TType extends string, TPayload> {
+    readonly type: TType;
+    readonly payload: TPayload;
+    readonly meta: EventMeta;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/events/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,aAAa,GAErB,KAAK,GACL,OAAO,GACP,QAAQ,GACR,cAAc,GACd,UAAU,GACV,MAAM,GACN,QAAQ,GAER,MAAM,GACN,aAAa,GACb,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY,CAAC;AAK1E,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,MAAM,GAEN,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,WAAW,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,MAAM,CAAC;AAE/E;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,WAAW,2BAA2B,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ;IACzE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B"}