agentfootprint 10.2.0 → 10.3.1

package/dist/esm/lib/time-travel/milestoneStops.js

@@ -1,192 +0,0 @@
-/**
- * milestoneStops — the agent's own scrub stops, derived from its commit log.
- *
- * Role:  Fold. It reads a finished run's commit log and answers one question —
- *        "which positions in this run is a reader allowed to stop at?" It
- *        executes nothing, records nothing, and stores nothing beside the log.
- * Reads: a recorded commit log (plus the execution tree when the caller has
- *        it), and `conventions.ts` · `milestoneFor` for the domain vocabulary.
- * Emits: N/A.
- *
- * WHY THIS FILE EXISTS. footprintjs ships the reader's cursor (`timeTravel`)
- * and one stop grammar — `commitStops`, one stop per executed stage — because
- * that is the only grammar the substrate itself knows. It does NOT know what an
- * LLM turn is. agentfootprint does: `milestoneFor` has classified a local stage
- * id into an iteration / slot / llm-turn / tool-call / decision since 9.x, and
- * until 9.87 every consumer that wanted a milestone slider mapped that
- * classifier onto commits by hand. This is that mapping, once, on the strategy
- * seam the port opened — so the agent SUPPLIES the stops for its own runs and
- * every reader gets the same axis.
- *
- * WHAT IT IS (9.89.0). A FILTER over the port's own axis. footprintjs 9.18
- * shipped `filterStops(stops, keep)` — the bookend guard, the re-partition and
- * a `meta` slot on the stop — because two consumers had each re-derived all
- * three by hand against 9.17, this file among them. The hand-rolled copies are
- * gone: the one owner of the `[start, …stages, end]` contract is the library
- * that returns it, and this strategy is one expression over it. The axis is
- * byte-for-byte the 9.88.0 axis (`test/lib/time-travel/milestone-stops-equivalence.test.ts` pins
- * that against a verbatim copy of the 9.88.0 implementation); what is new is that the milestone now RIDES on the
- * stop as `meta`, and that a start which absorbed pre-milestone stages says so
- * with `prologue: true`.
- *
- * WHAT IT IS NOT. Not a second cursor. A strategy only says where the one
- * cursor may rest; `timeTravel` still owns the position, the folds and the
- * marks. And not a re-walk: a milestone that was never committed gets no stop,
- * because a cursor that stops where no evidence exists is telling a story
- * rather than reading one.
- */
-import { commitStops, filterStops } from 'foottrace';
-import { MILESTONE_KINDS, milestoneFor, milestoneFromTags, } from '../../conventions.js';
-/** Is this `meta` a {@link Milestone} — ours, not another strategy's? */
-function isMilestone(meta) {
-    if (meta === null || typeof meta !== 'object')
-        return false;
-    const { kind, label } = meta;
-    return typeof label === 'string' && MILESTONE_KINDS.includes(kind);
-}
-/**
- * The milestone a stop stands for, or `null` when it stands for none (the
- * `'start'` / `'end'` bookends).
- *
- * A stop that {@link milestoneStops} made carries its milestone as
- * `stop.meta`, and that is what is read — the classification the strategy
- * made when it put the stop on the axis, not a second run of the classifier.
- * A stop from ANOTHER strategy — the port's own `commitStops`, or a consumer's
- * filter that kept the stop without a milestone meta — has none, so the answer
- * falls back to where it always came from: `milestoneFor` over the stop's
- * `runtimeStageId`. Same classifier, same answer; a `meta` of some other
- * vocabulary is not mistaken for ours.
- *
- * @example
- * ```ts
- * const stop = cursor.at()!;
- * milestoneOf(stop)?.kind;   // 'llm-turn'
- * ```
- */
-export function milestoneOf(stop) {
-    if (isMilestone(stop.meta))
-        return stop.meta;
-    return stop.runtimeStageId ? milestoneFor(stop.runtimeStageId) : null;
-}
-/**
- * Derive one stop per committed MILESTONE from a recorded commit log.
- *
- * The rule, in one sentence: take footprintjs's own per-stage axis, keep the
- * stages `milestoneFor` classifies, and give the survivors the log back.
- *
- * **Composed, never re-derived.** The hard parts of the per-stage axis are
- * already solved upstream and are not repeated here: one stop per
- * `runtimeStageId` at its FIRST commit (a subflow mount commits twice, a
- * parallel fork child commits twice and siblings interleave — every repeat is
- * an empty bundle), the authoritative mount set read off the execution tree,
- * the `'start'` / `'end'` bookends, and the id-less leading commit that carries
- * a subflow's `inputMapper` seed. And since 9.89.0 the COMPOSITION itself is
- * the port's too: `filterStops` checks the `[start, …stages, end]` shape,
- * keeps what `keep` keeps, and re-partitions the log. A second implementation
- * of any of that would be a second chance to disagree with the library about
- * what a stage is.
- *
- * **The survivors re-partition the log.** A stage that classifies `null` is not
- * a stop, but its commits still happened, so they are folded into the stop that
- * PRECEDES them: every kept stop's `lastCommitIdx` is extended to just before
- * the next kept stop begins. Nothing is orphaned, and `stateAt(stop)` remains
- * exactly "the state that existed when the next milestone's stage started".
- * Commits before the FIRST milestone belong to `'start'` for the same reason —
- * so on a drilled cursor `'start'` reads as "what this subflow began with,
- * after its plumbing ran".
- *
- * **What that costs `'start'`, and the flag that says so.** On footprintjs's
- * own axis `'start'` is the fold base: the state before ANY stage ran. Here it
- * absorbs every stage that ran before the first milestone, so `stateAt(start)`
- * is the state the first milestone READ, not the run's raw base — a real agent
- * seeds a couple of dozen keys in `seed` before anything a reader would scrub
- * to. That is the right answer for this axis (the stops must still partition
- * the log), and since 9.18 the port marks it: the returned start carries
- * `prologue: true` whenever it absorbed a stage, so a renderer that means
- * "before anything ran" checks `kind === 'start' && !prologue` instead of
- * assuming it from the kind.
- *
- * **The milestone rides on the stop.** Every kept stop carries its
- * classification as `meta` — `Stop<Milestone>` — so a reader asks
- * `stop.meta?.kind` (or {@link milestoneOf}, which reads the same slot) rather
- * than re-running the classifier over the id. The bookends carry none.
- *
- * **A log with no milestones in it at all.** A non-empty log the classifier
- * recognises nothing in — a non-agent chart handed this strategy — yields the
- * two bookends and nothing between them: `'start'` folds the whole log,
- * `'end'` folds the whole log, and `jumpTo` any stage id refuses with
- * `reason: 'miss'`. An axis with nowhere meaningful to stand, which is the
- * truthful shape for a run that has no milestones — not an error, and not the
- * empty `[]` that says the log itself was empty.
- *
- * **It does not know which log it was given.** The classifier reads the LOCAL
- * segment of a stage id, so `sf-llm-call#3` on a run's outer log and
- * `sf-llm-call/call-llm#7` on that mount's drilled inner history are both
- * classified without the strategy being told which one it is holding. That is
- * what lets one strategy serve `reactMode: 'dynamic'` (the `call-llm` bundle is
- * in the outer log → an llm-turn stop on the outer cursor) and
- * `'dynamic-grouped'` (the outer log holds `sf-llm-call` mounts → iteration
- * stops; `drill()` gives the inner cursor, where the same strategy finds the
- * llm-turn, tool-call and decision stops).
- *
- * @param commitLog     the run's `commitLog`, or a subflow's own `history`.
- * @param executionTree the run's `executionTree`, when the caller has it — it
- *   is what makes a mount stop say `kind: 'mount'` rather than being guessed
- *   from bundle shape.
- *
- * @example
- * ```ts
- * import { timeTravel } from 'foottrace';
- * import { milestoneStopsStrategy } from 'agentfootprint';
- *
- * const cursor = timeTravel(agent.getSnapshot()!, { strategy: milestoneStopsStrategy });
- * cursor.stops.map((s) => [s.label, s.meta?.kind]);
- * // measured on a two-turn `dynamic` run — 42 commits, 15 stops:
- * // [['Run start', undefined], ['Iteration', 'iteration'],
- * //  ['System prompt', 'slot'], ['Messages', 'slot'], ['Tools', 'slot'],
- * //  ['LLM turn', 'llm-turn'], ['Route', 'decision'], ['Tool call', 'tool-call'],
- * //  … the second turn …, ['Run end', undefined]]
- * cursor.stops[0].prologue; // true — `seed` and the plumbing ran before the first Iteration
- * ```
- */
-export function milestoneStops(commitLog, executionTree) {
-    return filterStops(commitStops(commitLog, executionTree), (stop) => {
-        const milestone = milestoneAt(commitLog, stop);
-        return milestone ? { label: milestone.label, meta: milestone } : null;
-    });
-}
-/**
- * The milestone a stop stands for — **the tag is the fact, the id is the
- * fallback** (9.90.0; law 3 of footprintjs's declared-tags design).
- *
- * The stop's FIRST bundle (`stop.commitIdx` — where footprintjs stamps a
- * stage's declared tags) is read first: when it carries tags, the answer is
- * whatever `milestone:<kind>` / `milestone-label:<label>` they declare, and a
- * bundle that is tagged but NOT as a milestone is not a stop, however
- * recognisable its id — the chart said what this stage is. Only a bundle with
- * no tags at all is classified from its id: a recording made before the charts
- * declared their milestones. On a 9.90.0 recording that path runs ZERO times —
- * every milestone stage is declared, slot branch mounts included (footprintjs
- * 9.21.1 `SubflowMountOptions.tags`), and
- * `test/lib/time-travel/milestone-stops-equivalence.test.ts` counts the
- * fallback on every fixture. Both readings come from the one table in
- * `conventions.ts`, so they agree wherever both exist.
- */
-function milestoneAt(log, stop) {
-    const raw = log[stop.commitIdx]?.tags;
-    // A stored row is `unknown[]`-shaped until narrowed: only STRINGS count as
-    // declared tags (the same narrowing footprintjs's `tagStops` does), so a
-    // damaged row falls back to the id like an untagged one instead of vanishing.
-    const tags = Array.isArray(raw) ? raw.filter((t) => typeof t === 'string') : [];
-    if (tags.length > 0)
-        return milestoneFromTags(tags, stop.label);
-    return milestoneFor(stop.runtimeStageId);
-}
-/**
- * `milestoneStops` as a footprintjs `TimeTravelStrategy` — what you hand
- * `timeTravel(snapshot, { strategy })`. Typed over {@link Milestone}, so the
- * cursor's stops are `Stop<Milestone>` and `cursor.at()?.meta?.kind` is typed;
- * it is still assignable wherever a bare `TimeTravelStrategy` is expected.
- */
-export const milestoneStopsStrategy = { stopsFor: milestoneStops };
-//# sourceMappingURL=milestoneStops.js.map

package/dist/esm/lib/time-travel/milestoneStops.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"milestoneStops.js","sourceRoot":"","sources":["../../../../src/lib/time-travel/milestoneStops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,iBAAiB,GAElB,MAAM,sBAAsB,CAAC;AAE9B,yEAAyE;AACzE,SAAS,WAAW,CAAC,IAAa;IAChC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAA2C,CAAC;IACpE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAsC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC7C,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAkC,EAClC,aAA6B;IAE7B,OAAO,WAAW,CAAY,WAAW,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;QAC5E,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC/C,OAAO,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,WAAW,CAAC,GAA4B,EAAE,IAAmB;IACpE,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IACtC,2EAA2E;IAC3E,yEAAyE;IACzE,8EAA8E;IAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7F,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChE,OAAO,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC"}