agentfootprint 13.0.0 → 14.0.0

package/dist/esm/events/payloads/runConfiguration.d.ts

@@ -0,0 +1,224 @@
+import type { MemoryFlavor, MemoryStrategyKind, MemoryType } from './dependencyTypes.js';
+/**
+ * The model this run STARTS with, and what may replace it mid-run.
+ *
+ * `model` is the agent's resolved default — the one `callLLM` sends unless
+ * something overrides it. It is deliberately not the "final" model: a
+ * `.configure()` resolver reads the run's input in the seed stage (AFTER this
+ * event), and per-skill brains pick per iteration. Resolving `.configure()`
+ * here to make this field "effective" would call a consumer's resolver twice
+ * per run, and two calls can disagree — so the manifest names the starting
+ * choice and {@link RunConfiguredLlmPayload.modelOverrides} names who is
+ * allowed to change it. What each call REALLY used is on
+ * `agentfootprint.stream.llm_start`, per call, as it always was.
+ */
+export interface RunConfiguredLlmPayload {
+    /** `LLMProvider.name` — the effective provider, decorators included. */
+    readonly provider: string;
+    /** The agent's resolved default model. */
+    readonly model: string;
+    /**
+     * Which mounted mechanisms may replace `model` during this run, by NAME —
+     * `'configure'` (a `.configure()` resolver) and `'skill-brains'` (per-skill
+     * providers/models, escalation included). Absent when nothing can: then
+     * `model` is what every call of this run used, and an experiment can group
+     * on it alone.
+     */
+    readonly modelOverrides?: readonly ('configure' | 'skill-brains')[];
+}
+/**
+ * One mounted memory, by the names it DECLARED.
+ *
+ * The store itself is not named: `MemoryStore` declares no id and no kind, so
+ * naming which backend was in play would mean inventing a label (a class name
+ * that survives no bundler, say) and an invented label is exactly what an arm
+ * must not be grouped on. What IS declared is here.
+ */
+export interface RunConfiguredMemoryPayload {
+    /** The `defineMemory({ id })` — the same id `memory.*` events carry. */
+    readonly id: string;
+    /** `'episodic' | 'semantic' | 'narrative' | 'causal'`. */
+    readonly type: MemoryType;
+    /** The strategy KIND it was compiled from (`'window'`, `'topK'`, …).
+     *  Absent for a hand-built definition, which declares none. */
+    readonly strategy?: MemoryStrategyKind;
+    /** `RetrievalStrategy.name`, when the memory was given a spelled-out
+     *  retrieval rule. Absent for the `{ topK, threshold }` shorthand — which
+     *  is a rule with no name, not the default one. */
+    readonly retrieval?: string;
+    /** The embedder in play, by its own `Embedder.id` (or the declared
+     *  `embedderId` when the store embeds server-side and no embedder was
+     *  passed). Absent when neither side named one. */
+    readonly embedderId?: string;
+    /** `'memory'` (conversation recall) or `'rag'` (corpus retrieval), when the
+     *  definition declared which claim it makes. */
+    readonly flavor?: MemoryFlavor;
+}
+/**
+ * The mounted skill graph's routing posture. The OBJECT's presence means a
+ * graph is mounted; each absent field means that half was not declared.
+ */
+export interface RunConfiguredSkillGraphPayload {
+    /** The mount's `strictness` — how much authority the graph has over the
+     *  model's own picks. Absent for a graph mounted without the turn-start
+     *  cascade options (routing then works exactly as it did in 9.16). */
+    readonly routing?: 'assist' | 'guard' | 'rails';
+    /** Whether the cursor survives the turn. Absent for the same reason. */
+    readonly continuity?: 'turn' | 'conversation';
+    /**
+     * `IntentScorer.name` — the `.classify()` scorer that routes turn starts.
+     * Absent when the graph declares no classifier, INCLUDING a graph routed by
+     * `entryBy()` / `entryByRelevance()`: those hand the agent a bound
+     * `scoreEntries` function and never the strategy that owns it, so there is
+     * no name here to report. `skill.turn_routed.scorer` names the scorer that
+     * really ran, whichever door it came through.
+     */
+    readonly scorer?: string;
+}
+/**
+ * The artifacts wiring. Presence means a store is configured; like
+ * `MemoryStore`, `ArtifactStore` declares no id, so WHICH store is not named.
+ */
+export interface RunConfiguredArtifactsPayload {
+    /** True when the placement dial is on — oversized tool results travel to
+     *  the model as a claim ticket instead of inline text. The threshold is a
+     *  number, not a name, so it is not carried. */
+    readonly placement?: true;
+    /** True when each run is filed as a recording artifact. */
+    readonly recordings?: true;
+}
+/**
+ * One applied recipe — the declared, versioned composition that produced part
+ * of this agent (9.48.0).
+ *
+ * The pair is what makes the row worth reading: two runs of `support-desk` that
+ * answered differently are a mystery until the record says one was `1.2.0` and
+ * the other `1.3.0`. The recipe's `description` is deliberately not here — it
+ * is prose about the composition, and the manifest carries what a consumer
+ * BRANCHES on.
+ */
+export interface RunConfiguredRecipePayload {
+    /** The composition's plain name, e.g. `'support-desk'`. */
+    readonly id: string;
+    /** Its SemVer version, e.g. `'1.2.0'`. Kept a SEPARATE field from `id` —
+     *  a composed `'support-desk@1.2.0'` would be one string that two different
+     *  pairs could produce as soon as either half may contain the separator. */
+    readonly version: string;
+}
+/**
+ * The run-configuration manifest — ONE event at run start naming which
+ * adapters and strategies this run is about to use.
+ *
+ * ## Why it exists
+ *
+ * Swapping a strategy in this library is easy; ATTRIBUTING an outcome to it
+ * was not. Every other event carries `meta.runId`, and the numbers are already
+ * there (tokens, latency, iterations, routing, refusals, evidence verdicts) —
+ * what was missing was the JOIN KEY that says which of them belong to the same
+ * ARM. Two ports used to name what varied (`skill.turn_routed.scorer`,
+ * `memory.retrieved.strategy`); everything else was anonymous, and grouping N
+ * runs into labelled arms was the experimenter's own bookkeeping, differently
+ * spelled in every study. Group by this payload and the arms name themselves.
+ *
+ * ## Names and ids ONLY — the hard rule
+ *
+ * No credentials, endpoints, connection strings, keys, tenants or principals,
+ * and no config VALUE that could be one. A manifest that leaks an endpoint is
+ * worse than no manifest: it travels into every recording, every vendor sink
+ * and every shared trace, which is precisely where a secret must not be. When
+ * the only handle on a component is a value (a directory, a URL, a table), the
+ * component is reported as PRESENT and left unnamed. Pinned by test.
+ *
+ * ## Absence is a fact, never a guess
+ *
+ * An absent field means "not configured" or "the strategy did not say" — never
+ * `'default'` or `'unknown'` filled in on a reader's behalf, the same
+ * distinction `CostTickPayload.provider` already makes. `memories: []` is the
+ * explicit "no memory is mounted".
+ *
+ * ## What it costs
+ *
+ * One small event per run, by design — the manifest of a run that emitted no
+ * manifest cannot be recovered afterwards. It carries names, never lists that
+ * grow with the workload (tool names ride `tools.offered`, injections ride
+ * `context.injected`), so its size is bounded by the agent's CONFIGURATION and
+ * not by the turn. Skipped entirely when nothing is listening.
+ *
+ * @example Group two runs into two arms
+ * ```ts
+ * const arms = new Map<string, string>();          // runId → arm label
+ * agent.on('agentfootprint.agent.run_configured', (e) => {
+ *   arms.set(e.meta.runId, `${e.payload.llm.model}/${e.payload.memories[0]?.retrieval ?? 'no-retrieval'}`);
+ * });
+ * agent.on('agentfootprint.agent.turn_end', (e) => {
+ *   record(arms.get(e.meta.runId), e.payload.durationMs);
+ * });
+ * ```
+ */
+export interface AgentRunConfiguredPayload {
+    /** The agent's stable id — the same one `meta.compositionPath` carries.
+     *  A study that runs two differently-configured agents groups on this. */
+    readonly agentId: string;
+    readonly llm: RunConfiguredLlmPayload;
+    /** The configured cache strategy cannot apply the declared policy.
+     * Configuration metadata only; absent when caching is off or supported. */
+    readonly cache?: {
+        readonly requested: 'explicit' | 'default';
+        readonly strategy: 'none';
+        readonly status: 'not-applicable';
+    };
+    /** Which chart shape ran the loop. A strategy choice with its own
+     *  behaviour, not a cosmetic one (see `AgentOptions.reactMode`). */
+    readonly reactMode: 'classic' | 'dynamic' | 'dynamic-grouped';
+    /** Every mounted memory, declaration order. `[]` means none is mounted —
+     *  stated rather than omitted, because "no memory" is itself an arm. */
+    readonly memories: readonly RunConfiguredMemoryPayload[];
+    /** `WindowStrategy.name` — the one strategy `.window()` or `.compaction()`
+     *  mounted (both doors set the same strategy). Absent = no window stage. */
+    readonly window?: string;
+    readonly skillGraph?: RunConfiguredSkillGraphPayload;
+    /** The evidence gate's posture (`.namesAndNumbersFromEvidence()`).
+     *  Presence means the gate is on; absence means it is not mounted. */
+    readonly evidenceGate?: 'assist' | 'guard' | 'rails';
+    readonly artifacts?: RunConfiguredArtifactsPayload;
+    /**
+     * The recipes `.recipe()` applied, in declaration order — which declared,
+     * versioned composition produced this agent (9.48.0).
+     *
+     * ABSENT when none was applied, and that is the one asymmetry with
+     * {@link memories}: "no memory" is an arm a study compares against, while
+     * "no recipe" is the state of every agent written before recipes existed,
+     * and an empty list on all of them would be new bytes in every recording for
+     * a feature nobody used.
+     */
+    readonly recipes?: readonly RunConfiguredRecipePayload[];
+}
+export interface AgentOutputSchemaValidationFailedPayload {
+    /** Validation error message (from Zod / parser), or a fixed sentence when
+     *  `draftWithheld` is true — parser text can quote the draft. */
+    readonly message: string;
+    /** Validation stage — JSON parse vs schema validate. Lets dashboards
+     *  distinguish "model emitted prose" (`json-parse`) from "model emitted
+     *  JSON but wrong shape" (`schema-validate`); they trend differently
+     *  under model drift. */
+    readonly stage: 'json-parse' | 'schema-validate';
+    /** Failing field path when the parser exposes one (e.g. `'amount.currency'`).
+     *  Only set when `stage === 'schema-validate'`. */
+    readonly path?: string;
+    /** The raw string output that failed — useful for narrative entries showing
+     *  "what the model actually said" alongside the validation error. Absent
+     *  when `draftWithheld` is true. */
+    readonly rawOutput?: string;
+    /** An output policy governs delivery, and this draft never passed output
+     *  admission: its text (`rawOutput`, and the parser's message) is withheld
+     *  from the event stream. Rules still read it on `validationError`. */
+    readonly draftWithheld?: true;
+    /** 1-indexed attempt counter. `1` for the first failure, `2` for the
+     *  retry that also failed, etc. */
+    readonly attempt: number;
+    /** Total output-schema failures in this gate execution. Same as
+     *  `validationErrorHistory.length`. Distinct from `attempt` because a
+     *  gate can also retry on non-validation errors (5xx, etc.) — this
+     *  counts ONLY the schema-driven failures. */
+    readonly cumulativeRetries: number;
+}

package/dist/esm/events/payloads/runConfiguration.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runConfiguration.js.map

package/dist/esm/events/payloads/runConfiguration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runConfiguration.js","sourceRoot":"","sources":["../../../../src/events/payloads/runConfiguration.ts"],"names":[],"mappings":""}

package/dist/esm/events/payloads/skills.d.ts

@@ -0,0 +1,359 @@
+import type { SkillGuardValueRecord } from './context.js';
+/**
+ * The turn-start routing verdict (SG-C) — one per turn on skill-graph agents
+ * whose graph ran the cascade (`classify` configured, or
+ * `continuity: 'conversation'` with something to decide). Fired by the
+ * RouteTurn stage DURING traversal (collect-during-traversal; never rebuilt),
+ * BEFORE iteration 1, so it precedes every `context.evaluated` of its turn.
+ *
+ * The LOSERS are on the record: `scores` ranks every candidate the tier-2
+ * scorer judged (role-hidden skills are excluded before scoring — a hidden
+ * capability is never named, not even to observers of this run); `offered`
+ * names the menu the model was handed; `policy` stamps the exact thresholds
+ * that judged the hop, so no observer has to guess which numbers decided.
+ */
+export interface SkillTurnRoutedPayload {
+    /** The tier that decided the turn's start:
+     *  `'entry'` — a tier-1 rule (the recorded vocabulary for rule-won starts);
+     *  `'intent'` — the tier-2 scorer was decisive;
+     *  `'continuity'` — the inherited cursor held (incumbent won / near-tie /
+     *  sticky default / the decider picked STAY — `decider` says which);
+     *  `'menu'` — a menu was put in-band (near-tie or unmatched);
+     *  `'decider'` — the configured tier-3 decider resolved the menu
+     *  out-of-band (9.19.0; `decider` carries the pick);
+     *  `'none'` — the cascade decided nothing the loop may act on (a rails
+     *  menu — the offer is still recorded here — or a dropped resume). */
+    readonly by: 'entry' | 'intent' | 'continuity' | 'menu' | 'decider' | 'none';
+    /** The inherited cursor (continuity), when one existed. */
+    readonly from?: string;
+    /** Where the turn starts. Absent = menu pending / none. */
+    readonly to?: string;
+    /** `IntentScorer.name` / entry-scorer name, when tier 2 ran. */
+    readonly scorer?: string;
+    /** EVERY candidate, ranked best-first — the losers, with the numbers that
+     *  lost. `score` is raw (strategy-specific); `relevance` is the
+     *  full-softmax share. */
+    readonly scores?: ReadonlyArray<{
+        readonly id: string;
+        readonly score: number;
+        readonly relevance: number;
+    }>;
+    /** The top-vs-2nd PAIRWISE gap actually judged (count-independent — see
+     *  routingPolicy.ts; NOT the difference of two `relevance` shares). */
+    readonly runnerUp?: {
+        readonly id: string;
+        readonly gap: number;
+    };
+    /** Whether tier 2 cleared the margin + floor. */
+    readonly decisive?: boolean;
+    /** WHAT the message said that won tier 1 (9.28.0) — present only on a
+     *  `by: 'entry'` verdict a DATA matcher (`match:` — RegExp / `{ keywords }` /
+     *  `{ all }`) decided. `text` is the matched substring of the USER message
+     *  (never tool or system text), whitespace-collapsed and bounded to 80
+     *  characters, ellipsis included; `keyword` names WHICH declared keyword hit
+     *  (keywords arm only). Absent for `when` predicates — opaque code the
+     *  library cannot quote — and for intent/scorer verdicts, whose evidence is
+     *  the `scores` above. */
+    readonly witness?: {
+        readonly text: string;
+        readonly keyword?: string;
+    };
+    /** The tier-3 menu (near-tie cluster, or every entry when unmatched). */
+    readonly offered?: readonly string[];
+    /** STAY was a first-class option in that menu (mid-conversation). */
+    readonly stayOffered?: boolean;
+    /** The thresholds that judged this turn, verbatim. `floor` is the EFFECTIVE
+     *  floor (`policy.floor ?? scorer.floor`); absent = no floor, so
+     *  `unmatched` was unreachable and near-tie governed. */
+    readonly policy: {
+        readonly nearTieMargin: number;
+        readonly menuSize: number;
+        readonly floor?: number;
+    };
+    /** Prior conversational turns the scorer saw (its declared window). */
+    readonly window?: number;
+    /** A continuity cursor that could not be honored — the stored id is not a
+     *  node of the currently mounted graph (a deploy changed it). The turn
+     *  started cold instead, and says so. */
+    readonly droppedResume?: {
+        readonly id: string;
+        readonly reason: 'unknown-skill';
+    };
+    /**
+     * The tier-3 DECIDER's involvement (9.19.0) — present whenever one was
+     * configured AND a menu verdict reached it. `picked` is the constrained
+     * pick that resolved the menu (an offered id, or `'stay'`); ABSENT when
+     * the decider declined (`'none'` / parse failure / a throw) and the
+     * in-band envelope stood. Recorded on every outcome so the record always
+     * says the decider was consulted — a resolver that ran and said nothing
+     * is still a fact.
+     */
+    readonly decider?: {
+        readonly provider: string;
+        readonly model?: string;
+        readonly picked?: string;
+    };
+}
+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;
+}
+/**
+ * Fired by the skill-graph read_skill GATE when the model tries to `read_skill`
+ * a skill that is NOT reachable from the current cursor. The jump is rejected
+ * (cursor/activations unchanged); the model gets a synthetic re-prompt naming
+ * `allowed`. Powers the lens / Why-panel "it tried to leave the graph here".
+ */
+/**
+ * Fired when a `read_skill` pick the gate ACCEPTED did not end up active — the
+ * model was told "Skill 'X' activated for the next iteration" and something else
+ * won. There is exactly one way to get here: a declared route edge fired on the
+ * same turn (the model emitted a domain tool AND `read_skill` in one message, and
+ * the tool's result matched the edge). The author's declared edge wins by design
+ * (`D1 > D2`), so the pick is superseded — and reported here rather than silently
+ * dropped. The next iteration shows the model where it actually is.
+ */
+export interface SkillRerouteSupersededPayload {
+    /** The skill the model picked with `read_skill` (accepted, then superseded). */
+    readonly volunteeredId: string;
+    /** The skill the declared edge routed to instead (the cursor that won). */
+    readonly wonId?: string;
+    /** The cursor the hop started from. */
+    readonly fromSkillId?: string;
+    /** The ReAct iteration whose evaluation dropped the pick. */
+    readonly iteration: number;
+    /**
+     * WHO volunteered the superseded move (9.19.0). Absent = the model's
+     * `read_skill` pick, exactly as this event has always meant;
+     * `'tool-proposal'` = an accepted `propose-transition` effect that a
+     * same-batch declared edge outran (D1 wins over the proposal exactly as
+     * it wins over a pick — the author's determinism is never overridden).
+     */
+    readonly source?: 'tool-proposal';
+}
+/**
+ * The DECLARED skill map, as the author drew it (9.50.0) — fired ONCE per run,
+ * right after `agent.run_configured`, for every agent whose `.skillGraph()`
+ * mount could state its map. Nodes and edges come from the BUILT graph
+ * (`graph.nodes` / `graph.edges`), never inferred from runtime hops — so a
+ * recording carries the complete authored topology, not the lower bound that
+ * per-hop `routing[]` provenance names (an edge appears there only once it
+ * FIRES). A consumer drawing the graph from a recording no longer has to say
+ * "partial" or ask the caller to pass the built graph in.
+ *
+ * ABSENT (no event) when no graph is mounted, or when a structurally-typed
+ * graph carries no `nodes` — the map is then honestly not on the record,
+ * never guessed.
+ */
+export interface SkillGraphDeclaredPayload {
+    /** The drawn nodes: `kind: 'skill'` boxes, plus `'predicate'` diamonds for a
+     *  decision `tree()`. `description` is the skill's catalog description,
+     *  verbatim (the text the model reads) — absent when the skill declares
+     *  none. `label` is the drawn caption (predicate nodes). */
+    readonly nodes: ReadonlyArray<{
+        readonly id: string;
+        /** `'skill' | 'predicate'` (reported verbatim from the graph). */
+        readonly kind: string;
+        readonly description?: string;
+        readonly label?: string;
+        /** The skill's declared plain name for a person (`defineSkill({ title })`)
+         *  — "array estate report" for `array-inventory`. Absent when the skill
+         *  declares none (the label a graph draws for a skill node is its id, so
+         *  a reader wanting a plain name reads this, never `label`). The model
+         *  never reads it. */
+        readonly title?: string;
+    }>;
+    /** The author's edges, verbatim. `from: null` is the synthetic START (an
+     *  entry edge — the lens's declared-edge consumers filter on
+     *  `from !== null`). `kind` is the declared `SkillEdgeKind`
+     *  (`'entry' | 'predicate' | 'on-tool-return' | 'on-tool-status' | 'guard'
+     *  | 'model'`). `guard` (9.51.0) is the edge's declared DATA guard,
+     *  verbatim — conditions in declaration order, all ANDed, the operator
+     *  vocabulary mirroring footprintjs's `WhereFilter` — so a recording's
+     *  SkillMap shows its guard conditions without anyone re-reading source. */
+    readonly edges: ReadonlyArray<{
+        readonly from: string | null;
+        readonly to: string;
+        readonly kind: string;
+        readonly label?: string;
+        readonly guard?: {
+            readonly conditions: ReadonlyArray<{
+                readonly key: string;
+                readonly op: string;
+                readonly value: SkillGuardValueRecord;
+            }>;
+        };
+    }>;
+}
+export interface SkillRejectedPayload {
+    /** The skill id the model requested via `read_skill`. */
+    readonly requestedId: string;
+    /** The cursor it was at (undefined = cold start, before any entry resolved). */
+    readonly currentSkillId?: string;
+    /**
+     * What the model was TOLD it could reach — role-filtered (9.86.0).
+     *
+     * No longer the set the call was bounded to: admission still reads the
+     * graph's raw set, and this is the SPEAKING set, so a skill the caller's
+     * `PermissionChecker` hides never appears here. Empty is therefore two
+     * different facts — nothing was reachable, or nothing reachable may be named
+     * — and a reader that needs them apart wants the run's graph, not this row.
+     */
+    readonly allowed: readonly string[];
+    /** The ReAct iteration the rejection fired on. */
+    readonly iteration: number;
+    /** Present when a POSTURE, not reachability, refused (SG-C `strictness`):
+     *  `'guard'` — the pick was reachable but off the outstanding menu (or no
+     *  menu was outstanding); `'rails'` — routing picks are refused outright
+     *  (rules/scorer route turn starts; declared routes handle transitions).
+     *  Absent = today's reachability refusal, unchanged. */
+    readonly posture?: 'guard' | 'rails';
+    /** WHICH ARM of the gate answered (9.84.0) — optional, so every consumer
+     *  written against the older shape keeps working unchanged:
+     *
+     *   • `'self-call'` — `requestedId === currentSkillId`. The model asked for
+     *     the skill it is already in; the cursor did not move because there was
+     *     nowhere to move it, and the tool result is an acknowledgement naming
+     *     the tools it can call, not a decline. Consumers that count refusals as
+     *     routing failures should read this one as a NAMING failure instead.
+     *   • `'unreachable'` — a genuine hop the cursor cannot make.
+     *   • `'posture'` — a reachable hop a declared `strictness` declined; pairs
+     *     with {@link SkillRejectedPayload.posture}, which names which one.
+     *
+     *  Before this, telling a self-call from an unreachable hop meant comparing
+     *  `requestedId` against `currentSkillId` and knowing why that mattered. */
+    readonly reason?: 'self-call' | 'unreachable' | 'posture';
+}
+/**
+ * Fired when two or more tool results of ONE parallel batch matched skill-graph
+ * edges to DIFFERENT targets (9.16.0). The first match in call order wins the
+ * cursor move; every later result matching another target is suppressed — and
+ * reported here so the record explains the hop the run did not take. Before
+ * 9.16.0 there was no conflict to report because there was no batch: only the
+ * LAST call of a batch was consulted, and the earlier calls' routing
+ * implications were silently dropped.
+ *
+ * Not fired for same-target matches (they all asked for the move that
+ * happened), nor for batches where only one result matched. Distinct from
+ * `skill.reroute_superseded`, which reports a declared edge outranking a
+ * `read_skill` pick — this one is edge-vs-edge, inside one batch.
+ */
+export interface SkillRouteConflictPayload {
+    /** The ReAct iteration whose evaluation resolved the batch. */
+    readonly iteration: number;
+    /** The cursor the winning hop started from. */
+    readonly fromSkillId?: string;
+    /** The call-order-first match — the one that moved the cursor. */
+    readonly winner: {
+        /** The provider's tool_use id for the winning call, when known. */
+        readonly toolCallId?: string;
+        readonly toolName: string;
+        /** The skill the cursor moved to. */
+        readonly target: string;
+    };
+    /** Later matches to other targets, in call order — the suppressed hops. */
+    readonly losers: ReadonlyArray<{
+        readonly toolCallId?: string;
+        readonly toolName: string;
+        /** The skill this result would have routed to. */
+        readonly target: string;
+    }>;
+    /**
+     * WHAT conflicted (9.19.0). Absent = declared route edges, exactly as
+     * this event has always meant; `'tool-proposal'` = two or more accepted
+     * `propose-transition` effects of one batch named different targets —
+     * first accepted in call order wins, the rest are suppressed and
+     * reported here under the same law.
+     */
+    readonly source?: 'tool-proposal';
+}
+/**
+ * A declared step completed: its tool returned (non-error) while it was
+ * current (9.18.0). Fired at the tool-return boundary, in batch call order —
+ * two adjacent steps naming the same tool advance twice in one batch, each
+ * on the record. A skip is NOT a completion: a `skip_step` that moved the
+ * pointer fires `step_skipped { policy: 'advance' }` alone.
+ */
+export interface SkillStepAdvancedPayload {
+    readonly skillId: string;
+    /** The step that just completed (or was skipped past). */
+    readonly step: {
+        readonly index: number;
+        readonly total: number;
+        readonly tool: string;
+        readonly note: string;
+    };
+    readonly iteration: number;
+    /** The provider's tool_use id for the completing call, when known. */
+    readonly toolCallId?: string;
+    /** Present on the LAST step: the procedure finished. */
+    readonly completed?: true;
+}
+/**
+ * The model declined a step, with its reason — the integrity condition, not
+ * polish (9.18.0). The framework moved on or held per the skill's declared
+ * `onSkip`; both facts are here. An empty reason never gets this far: the
+ * tool-calls stage answers it with a teaching result and no event.
+ */
+export interface SkillStepSkippedPayload {
+    readonly skillId: string;
+    readonly step: SkillStepAdvancedPayload['step'];
+    /** The model's own words. */
+    readonly reason: string;
+    readonly policy: 'advance' | 'hold';
+    readonly iteration: number;
+    readonly toolCallId?: string;
+}
+/**
+ * The turn is ending with steps unrun (9.18.0). `'nudged'` = the one
+ * teaching re-ask went back (at most once per turn); `'accepted'` = the
+ * model stopped again and the framework honored it — never a forced
+ * continue; `'cut-short'` = a limit (max-iterations / cost-budget) ended
+ * the turn, and a nudge would have spent an iteration the limit refused.
+ */
+export interface SkillStepsUnfinishedPayload {
+    readonly skillId: string;
+    readonly remaining: ReadonlyArray<{
+        readonly index: number;
+        readonly tool: string;
+        readonly note: string;
+    }>;
+    readonly total: number;
+    readonly action: 'nudged' | 'accepted' | 'cut-short';
+    readonly iteration: number;
+}
+/**
+ * The turn's refusal loop crossed the declared threshold and the rest of the
+ * turn runs on the escalation brain (9.19.0). Fired ONCE per turn, at the
+ * flip, from the gate that counted the refusals — escalation is always on
+ * recorded evidence (`skill.rejected` — reachability, posture or a self-call,
+ * all three refusal arms), never on
+ * vibes. De-escalation is the next turn's seed; no event marks it.
+ */
+export interface SkillEscalatedPayload {
+    /** The ReAct iteration whose refusal tripped the threshold. */
+    readonly iteration: number;
+    /** The declared threshold (`escalation.afterRefusals`). */
+    readonly afterRefusals: number;
+    /** The observed refusal count that tripped it (== afterRefusals at the
+     *  flip; the counter keeps counting but the event fires once). */
+    readonly refusals: number;
+    /** The brain that WAS serving — resolved by the same precedence chain
+     *  callLLM applies (skill brain > configured > default). */
+    readonly from: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    /** The declared escalation brain. `model` absent = it inherits down the
+     *  chain (same-provider escalations only; enforced at build). */
+    readonly to: {
+        readonly provider: string;
+        readonly model?: string;
+    };
+}

package/dist/esm/events/payloads/skills.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=skills.js.map

package/dist/esm/events/payloads/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../../../src/events/payloads/skills.ts"],"names":[],"mappings":""}