agentfootprint 6.43.0 → 6.45.0

package/dist/esm/core-flow/Sequence.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Sequence — sequential composition of runners (steps chained one after another).
+ *
+ * Pattern: Builder (GoF) + Adapter over footprintjs's `addSubFlowChartNext`.
+ * Role:    core-flow/ layer — pure control flow, no LLM deps.
+ *          Each step's output becomes the next step's input; default
+ *          mapping is string chaining (step N's return → step N+1's
+ *          `{ message }`). Custom mapping via `.mapBetween(fn)` between
+ *          any two steps.
+ * Emits:   agentfootprint.composition.enter / exit (via compositionRecorder).
+ */
+import { type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import type { StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from '../core/translator.js';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+export interface SequenceOptions {
+    /** Human-friendly name for events + topology. Default: 'Sequence'. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default: 'sequence'. */
+    readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * composition's internal chart (Seed + each step mount + Finalize).
+     *
+     * Cascade: each step runner attaches its OWN recorders at its own
+     * construction time. footprintjs does NOT propagate StructureRecorders
+     * into mounted subflows — attach the same recorders to every nested
+     * composition for full coverage.
+     *
+     * When omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `runner.getUIGroup()` invokes
+     * it with the Sequence's `GroupMetadata` (kind `'Sequence'`, id,
+     * name, ordered steps, no extras) and returns whatever shape the
+     * translator produces. When omitted, `getUIGroup()` returns
+     * `undefined`.
+     */
+    readonly groupTranslator?: GroupTranslator;
+}
+export interface SequenceInput {
+    readonly message: string;
+}
+export type SequenceOutput = string;
+type StepChild = Runner<{
+    message: string;
+}, string>;
+interface StepEntry {
+    readonly id: string;
+    readonly runner: StepChild;
+    /** Mapper applied BEFORE this step's run(). */
+    readonly mapFromPrev: (prev: string) => {
+        message: string;
+    };
+    /** Optional per-method translator override for THIS step only. */
+    readonly groupTranslator?: GroupTranslator;
+}
+/**
+ * Options bag accepted by `SequenceBuilder.step()` for per-method
+ * overrides. Backwards-compatible — when omitted the legacy two-arg
+ * `.step(id, runner)` signature still works.
+ */
+export interface SequenceStepOptions {
+    /** Per-method translator override. See `StepEntry.groupTranslator`. */
+    readonly groupTranslator?: GroupTranslator;
+}
+export declare class Sequence extends RunnerBase<SequenceInput, SequenceOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly steps;
+    private readonly opts;
+    private currentRunContext;
+    constructor(opts: SequenceOptions, steps: readonly StepEntry[]);
+    static create(opts?: SequenceOptions): SequenceBuilder;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /** Sequence is a flat ordered list of steps. One member per step,
+     *  preserving definition order so the consumer can render them
+     *  linearly (default Lens UX). Per-method overrides (L1c) take
+     *  precedence over the step runner's own translator. */
+    protected buildUIGroupMetadata(): GroupMetadata;
+    run(input: SequenceInput, options?: RunOptions): Promise<SequenceOutput | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<SequenceOutput | RunnerPauseOutcome>;
+    private createExecutor;
+    private finalizeResult;
+    private buildChart;
+}
+/**
+ * Fluent builder. Reads as natural English:
+ *   Sequence.create().step('a', A).pipeVia(fn).step('b', B).build()
+ *   →  "Sequence: step A, pipe via fn, step B."
+ *
+ * `step(id, runner)` adds a sequential step. `pipeVia(fn)` customises
+ * the transformation of the previous step's output before it feeds the
+ * next step (otherwise the default string-chain mapper is used).
+ */
+export declare class SequenceBuilder {
+    private readonly opts;
+    private readonly steps;
+    /** Pending pipeVia transformer for the NEXT step (consumed on .step()). */
+    private pendingPipe?;
+    private readonly seenIds;
+    constructor(opts: SequenceOptions);
+    /**
+     * Add a step. Runner must accept `{ message: string }` and return `string`.
+     * First step receives the Sequence input; subsequent steps receive the
+     * previous step's output (via the default string-chain mapper, or via
+     * the transformer set by a preceding `.pipeVia(fn)` call).
+     *
+     * Optional third arg `opts.groupTranslator` overrides the runner's
+     * own constructor-level translator for THIS step only — only its
+     * `member.uiGroup` flips to the override's output.
+     */
+    step(id: string, runner: StepChild, opts?: SequenceStepOptions): this;
+    /**
+     * Transform the previous step's string output before it reaches the
+     * next step. Consumed once by the next `.step()` call. Default
+     * mapping is `(prev) => ({ message: prev })`.
+     *
+     * Reads as English: `.step('a', A).pipeVia(fn).step('b', B)`
+     * →  "step A, pipe via fn, step B"
+     */
+    pipeVia(fn: (prev: string) => {
+        message: string;
+    }): this;
+    build(): Sequence;
+}
+export {};

package/dist/esm/events/dispatcher.d.ts

@@ -0,0 +1,134 @@
+/**
+ * EventDispatcher — the central event bus (one per runner).
+ *
+ * Pattern: Observer (GoF) + Pub/Sub over a typed discriminated union.
+ * Role:    Single flat dispatcher for every event emitted during a run.
+ *          Replaces DOM-style bubbling — we have a central bus by
+ *          construction, so tree propagation is unnecessary.
+ * Emits:   N/A — this IS the emitter. It ROUTES events to listeners.
+ *
+ * Semantics:
+ *   - Observers are ALWAYS fire-and-forget (inherited from footprintjs's
+ *     recorder contract). Promise returns are never awaited.
+ *   - Listener errors are caught; they become `agentfootprint.error.fatal`
+ *     events with stage:'observer'. The run continues.
+ *   - Dispatch is O(1) hash lookup by event type.
+ *   - Zero allocation when no listener for an event type AND no wildcard.
+ *   - Dev-mode wraps listeners to warn on async listener Promise return.
+ *   - Lifecycle: subscriptions release via the returned Unsubscribe or an
+ *     AbortSignal (`{ signal }`); `removeAllListeners()` is the bulk
+ *     escape hatch for long-lived server consumers; `listenerCount()` is
+ *     the leak diagnostic. Every removal path prunes emptied buckets and
+ *     detaches abort handlers, so listener storage is bounded by LIVE
+ *     subscriptions — never by subscription history.
+ */
+import type { AgentfootprintEvent, AgentfootprintEventMap, AgentfootprintEventType } from './registry.js';
+export type EventListener<K extends AgentfootprintEventType> = (event: AgentfootprintEventMap[K]) => void;
+export type WildcardListener = (event: AgentfootprintEvent) => void;
+export interface ListenOptions {
+    readonly once?: boolean;
+    readonly signal?: AbortSignal;
+}
+export type Unsubscribe = () => void;
+export type DomainWildcard = 'agentfootprint.composition.*' | 'agentfootprint.agent.*' | 'agentfootprint.stream.*' | 'agentfootprint.context.*' | 'agentfootprint.memory.*' | 'agentfootprint.tools.*' | 'agentfootprint.skill.*' | 'agentfootprint.permission.*' | 'agentfootprint.risk.*' | 'agentfootprint.fallback.*' | 'agentfootprint.cost.*' | 'agentfootprint.eval.*' | 'agentfootprint.error.*' | 'agentfootprint.pause.*' | 'agentfootprint.embedding.*';
+export type AllWildcard = '*';
+export type WildcardSubscription = DomainWildcard | AllWildcard;
+/**
+ * Central event bus. One per executable runner.
+ *
+ * Zero-alloc fast path: if `hasListenersFor(type)` is false AND there are
+ * no wildcards, `dispatch` returns immediately without iteration.
+ */
+export declare class EventDispatcher {
+    private readonly byType;
+    private readonly domainWildcards;
+    private readonly allWildcards;
+    /**
+     * Fast-path check. Returns true when at least one listener would fire
+     * for this type. Used by emitters to skip event-object allocation.
+     */
+    hasListenersFor(type: AgentfootprintEventType): boolean;
+    /**
+     * Subscribe a typed listener for a specific event type.
+     *
+     * The listener signature is `(event) => void` by design — Promises are
+     * NOT awaited. See dispatch() for details.
+     */
+    on<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>, options?: ListenOptions): Unsubscribe;
+    /** Subscribe to a domain wildcard ('agentfootprint.context.*') or '*'. */
+    on(type: WildcardSubscription, listener: WildcardListener, options?: ListenOptions): Unsubscribe;
+    /**
+     * Subscribe a one-shot listener. Fires at most once and then auto-removes.
+     * Equivalent to `on(type, listener, { once: true })`. Accepts `{ signal }`
+     * for AbortSignal auto-cleanup, same as `on()`.
+     */
+    once<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>, options?: Omit<ListenOptions, 'once'>): Unsubscribe;
+    once(type: WildcardSubscription, listener: WildcardListener, options?: Omit<ListenOptions, 'once'>): Unsubscribe;
+    /**
+     * Shared subscribe path for on()/once(). The public overloads constrain
+     * `type` to either typed keys or wildcards; internally the dispatcher's
+     * bucket logic accepts any string and classifies by shape.
+     */
+    private subscribe;
+    /**
+     * Remove a specific listener for a type. Prefer AbortSignal for auto-cleanup.
+     *
+     * Because listeners are wrapped in dev mode, identity is preserved via a
+     * WeakMap in addListener — consumers pass the original function.
+     */
+    off<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>): void;
+    off(type: WildcardSubscription, listener: WildcardListener): void;
+    /**
+     * Lifecycle escape hatch — drop EVERY listener (typed, domain-wildcard,
+     * and `'*'`) in one call. For long-lived server consumers that reuse one
+     * runner across many requests: when you can't thread an AbortSignal or
+     * keep every Unsubscribe handle, call this between requests to guarantee
+     * the dispatcher holds zero subscriptions.
+     *
+     * Safe to call mid-dispatch: the bucket currently being iterated
+     * finishes its already-taken snapshot (same semantics as `off()` during
+     * dispatch), buckets the in-flight dispatch has NOT yet reached deliver
+     * nothing (DOM-like "stop now"), and every SUBSEQUENT event sees no
+     * listeners. Abort handlers registered on consumer AbortSignals via
+     * `{ signal }` are detached too. Previously returned Unsubscribe
+     * handles become harmless no-ops.
+     */
+    removeAllListeners(): void;
+    /**
+     * Diagnostic — how many listeners the dispatcher currently retains.
+     *
+     * - `listenerCount()` — TOTAL across every bucket (typed + domain
+     *   wildcards + `'*'`). The number long-lived consumers watch to verify
+     *   per-run subscriptions are being released (leak detection).
+     * - `listenerCount(type)` — listeners registered under that exact
+     *   subscription key (`'agentfootprint.agent.turn_start'`,
+     *   `'agentfootprint.context.*'`, or `'*'`). NOTE: counts the bucket
+     *   only — a typed count does NOT include wildcard listeners that would
+     *   also fire for that type. "Would anything fire?" is
+     *   `hasListenersFor()`.
+     */
+    listenerCount(type?: AgentfootprintEventType | WildcardSubscription): number;
+    /**
+     * Route an event to all matching listeners (typed + domain-wildcard + all).
+     *
+     * Fire-and-forget: any returned Promise is IGNORED. Listener exceptions
+     * are caught and re-dispatched as `error.fatal` events with scope='observer'.
+     * The run continues regardless.
+     */
+    dispatch(event: AgentfootprintEvent): void;
+    private addListener;
+    /**
+     * Bounded-leak guarantee: a bucket emptied by ANY removal path is
+     * deleted from its Map so `byType` / `domainWildcards` never retain
+     * empty Sets for event types subscribed once and released. The
+     * identity check (`get(...) === bucket`) guards stale Unsubscribe
+     * closures — they must never delete a NEWER bucket re-created under
+     * the same key after this one was pruned. (`allWildcards` is a stable
+     * field, not a Map entry — nothing to prune.)
+     */
+    private pruneBucket;
+    private ensureBucket;
+    private bucketFor;
+    private fireBucket;
+    private domainKey;
+}