agentfootprint/dist/esm/events/registry.js

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * Event registry — every typed `agentfootprint.*` event (see ALL_EVENT_TYPES;
 * the event/domain counts in the docs are asserted against this file by
 * test/events/unit/registry.test.ts, so don't hardcode counts here).
 *
 * 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.
 */
// ─── Event type constants ─────────────────────────────────────────────
// Single source of truth for every event name. Low cardinality,
// all under the `agentfootprint.` namespace, three-segment dotted form.
export const EVENT_NAMES = {
    composition: {
        enter: 'agentfootprint.composition.enter',
        exit: 'agentfootprint.composition.exit',
        forkStart: 'agentfootprint.composition.fork_start',
        branchComplete: 'agentfootprint.composition.branch_complete',
        mergeEnd: 'agentfootprint.composition.merge_end',
        routeDecided: 'agentfootprint.composition.route_decided',
        iterationStart: 'agentfootprint.composition.iteration_start',
        iterationExit: 'agentfootprint.composition.iteration_exit',
    },
    agent: {
        turnStart: 'agentfootprint.agent.turn_start',
        turnEnd: 'agentfootprint.agent.turn_end',
        iterationStart: 'agentfootprint.agent.iteration_start',
        iterationEnd: 'agentfootprint.agent.iteration_end',
        routeDecided: 'agentfootprint.agent.route_decided',
        handoff: 'agentfootprint.agent.handoff',
        outputSchemaValidationFailed: 'agentfootprint.agent.output_schema_validation_failed',
        outputSchemaRetry: 'agentfootprint.agent.output_schema_retry',
        outputContractUnmet: 'agentfootprint.agent.output_contract_unmet',
        evidenceChecked: 'agentfootprint.agent.evidence_checked',
        groundingNudged: 'agentfootprint.agent.grounding_nudged',
        runConfigured: 'agentfootprint.agent.run_configured',
        thinkingParseFailed: 'agentfootprint.agent.thinking_parse_failed',
        thinkingOmitted: 'agentfootprint.agent.thinking_omitted',
        budgetExhausted: 'agentfootprint.agent.budget_exhausted',
    },
    stream: {
        llmStart: 'agentfootprint.stream.llm_start',
        llmEnd: 'agentfootprint.stream.llm_end',
        token: 'agentfootprint.stream.token',
        toolStart: 'agentfootprint.stream.tool_start',
        toolProgress: 'agentfootprint.stream.tool_progress',
        toolEnd: 'agentfootprint.stream.tool_end',
        thinkingDelta: 'agentfootprint.stream.thinking_delta',
        thinkingEnd: 'agentfootprint.stream.thinking_end',
    },
    context: {
        injected: 'agentfootprint.context.injected',
        evicted: 'agentfootprint.context.evicted',
        slotComposed: 'agentfootprint.context.slot_composed',
        budgetPressure: 'agentfootprint.context.budget_pressure',
        evaluated: 'agentfootprint.context.evaluated',
    },
    memory: {
        strategyApplied: 'agentfootprint.memory.strategy_applied',
        attached: 'agentfootprint.memory.attached',
        retrieved: 'agentfootprint.memory.retrieved',
        detached: 'agentfootprint.memory.detached',
        written: 'agentfootprint.memory.written',
    },
    tools: {
        offered: 'agentfootprint.tools.offered',
        activated: 'agentfootprint.tools.activated',
        deactivated: 'agentfootprint.tools.deactivated',
        discoveryStarted: 'agentfootprint.tools.discovery_started',
        discoveryCompleted: 'agentfootprint.tools.discovery_completed',
        discoveryFailed: 'agentfootprint.tools.discovery_failed',
        shadowed: 'agentfootprint.tools.shadowed',
        claimSwallowed: 'agentfootprint.tools.claim_swallowed',
        answeredOffWire: 'agentfootprint.tools.answered_off_wire',
        sessionStarted: 'agentfootprint.tools.session_started',
        sessionReused: 'agentfootprint.tools.session_reused',
        sessionClosed: 'agentfootprint.tools.session_closed',
        sessionCloseFailed: 'agentfootprint.tools.session_close_failed',
        effect: 'agentfootprint.tools.effect',
        resultRefused: 'agentfootprint.tools.result_refused',
        repeatedCall: 'agentfootprint.tools.repeated_call',
        absent: 'agentfootprint.tools.absent',
        coverageDeclared: 'agentfootprint.tools.coverage_declared',
        semanticsDeclared: 'agentfootprint.tools.semantics_declared',
        codeRun: 'agentfootprint.tools.code_run',
        requestAttempts: 'agentfootprint.tools.request_attempts',
        mcpClient: 'agentfootprint.tools.mcp_client',
    },
    skill: {
        activated: 'agentfootprint.skill.activated',
        graphDeclared: 'agentfootprint.skill.graph_declared',
        deactivated: 'agentfootprint.skill.deactivated',
        rejected: 'agentfootprint.skill.rejected',
        rerouteSuperseded: 'agentfootprint.skill.reroute_superseded',
        routeConflict: 'agentfootprint.skill.route_conflict',
        turnRouted: 'agentfootprint.skill.turn_routed',
        stepAdvanced: 'agentfootprint.skill.step_advanced',
        stepSkipped: 'agentfootprint.skill.step_skipped',
        stepsUnfinished: 'agentfootprint.skill.steps_unfinished',
        escalated: 'agentfootprint.skill.escalated',
    },
    map: {
        engaged: 'agentfootprint.map.engaged',
        parked: 'agentfootprint.map.parked',
    },
    integrity: {
        contextError: 'agentfootprint.integrity.context_error',
        disposition: 'agentfootprint.integrity.disposition',
        externalGroundUsed: 'agentfootprint.integrity.external_ground_used',
    },
    validation: {
        argsInvalid: 'agentfootprint.validation.args_invalid',
    },
    permission: {
        check: 'agentfootprint.permission.check',
        gateOpened: 'agentfootprint.permission.gate_opened',
        gateClosed: 'agentfootprint.permission.gate_closed',
        halt: 'agentfootprint.permission.halt',
    },
    credential: {
        requested: 'agentfootprint.credential.requested',
        acquired: 'agentfootprint.credential.acquired',
        authorizationRequired: 'agentfootprint.credential.authorization_required',
        failed: 'agentfootprint.credential.failed',
    },
    fallback: {
        triggered: 'agentfootprint.fallback.triggered',
    },
    cost: {
        tick: 'agentfootprint.cost.tick',
        limitHit: 'agentfootprint.cost.limit_hit',
    },
    eval: {
        score: 'agentfootprint.eval.score',
        thresholdCrossed: 'agentfootprint.eval.threshold_crossed',
    },
    error: {
        retried: 'agentfootprint.error.retried',
        recovered: 'agentfootprint.error.recovered',
        fatal: 'agentfootprint.error.fatal',
        circuitChanged: 'agentfootprint.error.circuit_changed',
    },
    reliability: {
        failFast: 'agentfootprint.reliability.fail_fast',
        retried: 'agentfootprint.reliability.retried',
        recovered: 'agentfootprint.reliability.recovered',
    },
    resilience: {
        outputFallbackTriggered: 'agentfootprint.resilience.output_fallback_triggered',
        outputCannedUsed: 'agentfootprint.resilience.output_canned_used',
    },
    pause: {
        request: 'agentfootprint.pause.request',
        resume: 'agentfootprint.pause.resume',
    },
    checkin: {
        request: 'agentfootprint.checkin.request',
        decision: 'agentfootprint.checkin.decision',
    },
    middleware: {
        decision: 'agentfootprint.middleware.decision',
    },
    findings: {
        declared: 'agentfootprint.findings.declared',
        standing: 'agentfootprint.findings.standing',
        judged: 'agentfootprint.findings.judged',
        judge_failed: 'agentfootprint.findings.judge_failed',
        contingent: 'agentfootprint.findings.contingent',
        // The inputs layer's verdict on one ruled argument of one call (honesty layer 2).
        argument: 'agentfootprint.findings.argument',
        // The results layer's verdict on one call's period (honesty layer 3, step 7b).
        period: 'agentfootprint.findings.period',
        negative_claim: 'agentfootprint.findings.negative_claim',
    },
    tool_choice: {
        picked: 'agentfootprint.tool_choice.picked',
        outcome: 'agentfootprint.tool_choice.outcome',
        failed: 'agentfootprint.tool_choice.failed',
    },
    ontology: {
        served: 'agentfootprint.ontology.served',
    },
    // The answer layer (honesty layer 4): the answer's standing, as data.
    answer: {
        assessed: 'agentfootprint.answer.assessed',
    },
    embedding: {
        generated: 'agentfootprint.embedding.generated',
    },
    artifacts: {
        minted: 'agentfootprint.artifacts.minted',
        resolved: 'agentfootprint.artifacts.resolved',
        expired: 'agentfootprint.artifacts.expired',
        refused: 'agentfootprint.artifacts.refused',
        presented: 'agentfootprint.artifacts.presented',
        handOverFailed: 'agentfootprint.artifacts.hand_over_failed',
    },
};
/**
 * Complete list of every registered event type, for lint / runtime validation.
 * A new event MUST be added here or the exhaustiveness tests fail.
 */
export const ALL_EVENT_TYPES = [
    'agentfootprint.composition.enter',
    'agentfootprint.composition.exit',
    'agentfootprint.composition.fork_start',
    'agentfootprint.composition.branch_complete',
    'agentfootprint.composition.merge_end',
    'agentfootprint.composition.route_decided',
    'agentfootprint.composition.iteration_start',
    'agentfootprint.composition.iteration_exit',
    'agentfootprint.agent.turn_start',
    'agentfootprint.agent.turn_end',
    'agentfootprint.agent.iteration_start',
    'agentfootprint.agent.iteration_end',
    'agentfootprint.agent.route_decided',
    'agentfootprint.agent.handoff',
    'agentfootprint.agent.output_schema_validation_failed',
    'agentfootprint.agent.output_schema_retry',
    'agentfootprint.agent.output_contract_unmet',
    'agentfootprint.agent.evidence_checked',
    'agentfootprint.agent.grounding_nudged',
    'agentfootprint.agent.run_configured',
    'agentfootprint.agent.thinking_parse_failed',
    'agentfootprint.agent.thinking_omitted',
    'agentfootprint.agent.budget_exhausted',
    'agentfootprint.stream.llm_start',
    'agentfootprint.stream.llm_end',
    'agentfootprint.stream.token',
    'agentfootprint.stream.tool_start',
    'agentfootprint.stream.tool_progress',
    'agentfootprint.stream.tool_end',
    'agentfootprint.stream.thinking_delta',
    'agentfootprint.stream.thinking_end',
    'agentfootprint.context.injected',
    'agentfootprint.context.evicted',
    'agentfootprint.context.slot_composed',
    'agentfootprint.context.budget_pressure',
    'agentfootprint.context.evaluated',
    'agentfootprint.memory.strategy_applied',
    'agentfootprint.memory.attached',
    'agentfootprint.memory.retrieved',
    'agentfootprint.memory.detached',
    'agentfootprint.memory.written',
    'agentfootprint.tools.offered',
    'agentfootprint.tools.activated',
    'agentfootprint.tools.deactivated',
    'agentfootprint.tools.discovery_started',
    'agentfootprint.tools.discovery_completed',
    'agentfootprint.tools.discovery_failed',
    'agentfootprint.tools.shadowed',
    'agentfootprint.tools.claim_swallowed',
    'agentfootprint.tools.answered_off_wire',
    'agentfootprint.tools.session_started',
    'agentfootprint.tools.session_reused',
    'agentfootprint.tools.session_closed',
    'agentfootprint.tools.session_close_failed',
    'agentfootprint.tools.effect',
    'agentfootprint.tools.result_refused',
    'agentfootprint.tools.repeated_call',
    'agentfootprint.tools.absent',
    'agentfootprint.tools.code_run',
    'agentfootprint.tools.request_attempts',
    'agentfootprint.tools.mcp_client',
    'agentfootprint.tools.coverage_declared',
    'agentfootprint.tools.semantics_declared',
    'agentfootprint.validation.args_invalid',
    'agentfootprint.skill.activated',
    'agentfootprint.skill.graph_declared',
    'agentfootprint.skill.deactivated',
    'agentfootprint.skill.rejected',
    'agentfootprint.skill.reroute_superseded',
    'agentfootprint.skill.route_conflict',
    'agentfootprint.skill.turn_routed',
    'agentfootprint.skill.step_advanced',
    'agentfootprint.skill.step_skipped',
    'agentfootprint.skill.steps_unfinished',
    'agentfootprint.skill.escalated',
    'agentfootprint.permission.check',
    'agentfootprint.permission.gate_opened',
    'agentfootprint.permission.gate_closed',
    'agentfootprint.permission.halt',
    'agentfootprint.credential.requested',
    'agentfootprint.credential.acquired',
    'agentfootprint.credential.authorization_required',
    'agentfootprint.credential.failed',
    'agentfootprint.fallback.triggered',
    'agentfootprint.cost.tick',
    'agentfootprint.cost.limit_hit',
    'agentfootprint.eval.score',
    'agentfootprint.eval.threshold_crossed',
    'agentfootprint.error.retried',
    'agentfootprint.error.recovered',
    'agentfootprint.error.fatal',
    'agentfootprint.error.circuit_changed',
    'agentfootprint.reliability.fail_fast',
    'agentfootprint.reliability.retried',
    'agentfootprint.reliability.recovered',
    'agentfootprint.resilience.output_fallback_triggered',
    'agentfootprint.resilience.output_canned_used',
    'agentfootprint.pause.request',
    'agentfootprint.pause.resume',
    'agentfootprint.checkin.request',
    'agentfootprint.checkin.decision',
    'agentfootprint.middleware.decision',
    'agentfootprint.findings.declared',
    'agentfootprint.findings.standing',
    'agentfootprint.findings.judged',
    'agentfootprint.findings.judge_failed',
    'agentfootprint.findings.contingent',
    'agentfootprint.findings.argument',
    'agentfootprint.findings.period',
    'agentfootprint.findings.negative_claim',
    'agentfootprint.tool_choice.picked',
    'agentfootprint.tool_choice.outcome',
    'agentfootprint.tool_choice.failed',
    'agentfootprint.ontology.served',
    'agentfootprint.answer.assessed',
    'agentfootprint.embedding.generated',
    'agentfootprint.artifacts.minted',
    'agentfootprint.artifacts.resolved',
    'agentfootprint.artifacts.expired',
    'agentfootprint.artifacts.refused',
    'agentfootprint.artifacts.presented',
    'agentfootprint.artifacts.hand_over_failed',
    'agentfootprint.map.engaged',
    'agentfootprint.map.parked',
    'agentfootprint.integrity.context_error',
    'agentfootprint.integrity.disposition',
    'agentfootprint.integrity.external_ground_used',
];
//# sourceMappingURL=registry.js.map