agentfootprint/dist/strategies/types.js

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

"use strict";
/**
 * Strategy interface types for the v2.8 grouped-enabler architecture.
 *
 * Pattern: Strategy + Bridge + Hexagonal port. See the design memo
 *          `docs/inspiration/strategy-everywhere.md`.
 *
 * Four groups, four typed strategy interfaces. Each follows the same
 * shape (one canonical contract, locked at the type level):
 *
 *   1. `name: string`            — registry key for auto-registration
 *   2. `capabilities: {...}`     — what this strategy supports
 *   3. the hot-path method       — sync, side-effect-only. Named per
 *                                  group: `exportEvent` (observability),
 *                                  `recordCost`, `renderStatus`,
 *                                  `renderGraph`. There is no `onEvent`.
 *   4. `flush?(): Promise<void>` — optional batch flushing
 *   5. `stop?(): void`           — optional teardown
 *
 * Design constraints (from the panel review):
 *   - **PASSIVE / non-blocking by construction.** Strategies are
 *     observers — they NEVER block the agent loop. Async work
 *     (HTTP shipment, disk I/O, batching) is the STRATEGY's internal
 *     concern: buffer in `exportEvent` (sync), drain in `flush()`
 *     (async OK). The dispatcher never awaits the hot-path call.
 *   - `exportEvent` MUST be sync `void`. MUST NOT throw. Errors caught +
 *     routed to `_onError` at the dispatch layer; one bad strategy
 *     never breaks the agent loop.
 *   - Idempotent registration — registering the same `name` twice
 *     replaces, doesn't double-fire.
 *   - `stop()` is idempotent — halts everything that strategy enabled,
 *     nothing else, calling twice is a no-op. Since 8.12.0 the framework
 *     also guarantees it is DELIVERED at most once, however many places
 *     share the strategy.
 *   - `flush()` is optional, may be sync OR async — strategies that
 *     don't batch can omit it. Flush is the ONLY async path; the hot
 *     path is always sync.
 *
 * **Who calls `flush()` / `stop()` (8.12.0).** Three doors, and no
 * hidden fourth:
 *
 *   - `const telemetry = agent.enable.observability({...})` returns a
 *     handle. It is still the `Unsubscribe` function it always was —
 *     `telemetry()` detaches, and detaching still never stops your
 *     strategy — and it now also carries `telemetry.flush()` and
 *     `telemetry.stop()`.
 *   - `await agent.shutdown()` drains and releases everything enabled
 *     on that agent, in the one correct order.
 *   - `standingAgent({...})`'s `handle.close()` flushes by default
 *     (`shutdown: 'flush'`), because the last batch reaching the sink
 *     when a server stops is what everyone already assumed happened.
 *
 * `agent.run()` still never flushes: telemetry timing is not the agent
 * loop's business. Opt into a per-run drain with
 * `enable.observability({ flushOn: 'run-end' })`, which fires a flush
 * when a run ends but never gates the run on it.
 */
Object.defineProperty(exports, "__esModule", { value: true });
//# sourceMappingURL=types.js.map