agentfootprint-lens 0.53.5 → 0.55.0

package/README.md

@@ -78,7 +78,7 @@ changes.
 |---|---|
 | `agentfootprint-lens/why` | Replay a recording as the agent's own milestones. `<WhyLens recording={...} />` takes the recording straight (`recordRun()`'s `{ snapshot, events, structure }`, or the `persistRecording` envelope), validates it at mount, and mounts the shipped `<Lens>` shell on the milestone axis — plus the axis helpers (`scrubAxisFor`, `stepForCommitIdx`, `stepForRuntimeStageId`, `resolveNavigation`) for hosts holding one cursor across views. |
 | `agentfootprint-lens/skillgraph` | Debug how a run routed through its skills. `<SkillGraphDebugger recorder={...} />` plus its headless selectors (`selectSkillRoute`, `selectSkillBeats`, `selectSkillTopology`, `selectSkillFrameContext`, `stepForRuntimeStageId`, `resolveNavigation`). |
-| `agentfootprint-lens/context` | The context object at a stop, key by key — who wrote each, what moved, what was served. `<ContextView runner={...} />` walks the milestone axis on its own; hand it `cursor` and it follows the ONE cursor (0.53.1). |
+| `agentfootprint-lens/context` | What the model HAD at a stop — the served document of that epoch on top (the Served tab itself: pieces, messages, tools, verdicts, delta since the previous call) — and what it was BUILT from beneath: the record key by key, who wrote each, what moved; a long value opens in place (0.54.0). `<ContextView runner={...} />` walks the milestone axis on its own; hand it `cursor` and it follows the ONE cursor (0.53.1). |
 
 The axis model in three sentences: one run leaves one causal trace, and each
 lens replays one AXIS of it — the Why reading scrubs the milestones, the Flow
@@ -812,6 +812,37 @@ const href = to.ok ? `/runs/${runId}?step=${to.step}` : undefined;
 
 ---
 
+### One cursor across several lenses: `useSharedCursor`
+
+A debug tool that mounts Why, Flow, Context and the Skill Graph over one
+recording keeps ONE cursor. The lenses draw different axes — Flow every
+commit, Why and Context the agent's milestones — so what the host holds must
+be an ADDRESS on the record, not a step on an axis. `useSharedCursor` holds
+that address and hands each lens a `LensCursor` for the axis it draws:
+
+```tsx
+import { useSharedCursor, Lens, ContextView } from 'agentfootprint-lens';
+
+const shared = useSharedCursor(recorder);
+
+// Reads the address on the milestone axis; a click here moves the address.
+<ContextView runner={recording} cursor={shared.forAxis('group')} />
+
+// The older step + report contract, bridged into the same address — so a
+// `<Lens>` or a Skill Graph transport keeps working while you migrate one
+// lens at a time.
+<Lens recorder={recorder} granularity="step"
+      step={shared.forAxis('step').at.step} onStepChange={shared.onStepChange} />
+```
+
+The law: a tab DERIVES its step from the address (the exact stage when its
+axis has it, else the stop that contains the commit); only a MOVER changes
+the address; a visit to a coarser axis and back lands on the same commit.
+With no move yet the address is the run's end, from which each axis derives
+its own last stop; a new recorder drops the held address. Headless pieces on
+`/core`: `stepForAddress`, `cursorForAddress`, `addressOf`. Design and the
+facts the fixtures taught: docs/design/2026-09-shared-cursor.md.
+
 ## Time travel through one port
 
 **Nothing to do — this is how the cursor already moves.** Read it if you are

package/dist/{chunk-47W3TQT6.js → chunk-37NHCNSS.js}

@@ -486,6 +486,351 @@ function verify(view, receipt, runId, cause) {
   });
 }
 
+// src/core/served/foldFactsAt.ts
+import { stateAt } from "footprintjs/trace";
+var FOLD_FACT_KEYS = Object.freeze([
+  "iteration",
+  "currentSkillId",
+  "stepPointer",
+  "mapEngagement",
+  "activeInjections",
+  "hiddenSkillIds"
+]);
+function skippedIndicesOf(folded) {
+  const gaps = folded.skipped;
+  return gaps !== void 0 && gaps.length > 0 ? Object.freeze(gaps.map((g) => g.index)) : void 0;
+}
+function foldFactsAt(recording, cursor) {
+  const source = typeof recording === "object" && recording !== null ? recording : void 0;
+  let folded;
+  try {
+    folded = stateAt(source, cursor.commitIdx);
+  } catch (e) {
+    return Object.freeze({
+      redacted: false,
+      present: Object.freeze([]),
+      foldError: e instanceof Error ? e.message : String(e)
+    });
+  }
+  const state = folded.state;
+  const present = [];
+  const out = {};
+  for (const key of FOLD_FACT_KEYS) {
+    const value = state[key];
+    if (value === void 0) continue;
+    present.push(key);
+    out[key] = value;
+  }
+  const hidden = out.hiddenSkillIds;
+  const injections = out.activeInjections;
+  const skipped = skippedIndicesOf(folded);
+  return Object.freeze({
+    basis: folded.basis,
+    redacted: folded.redacted,
+    present: Object.freeze(present),
+    ...skipped !== void 0 ? { skipped } : {},
+    ...typeof out.iteration === "number" ? { iteration: out.iteration } : {},
+    ...typeof out.currentSkillId === "string" ? { currentSkillId: out.currentSkillId } : {},
+    ...out.stepPointer !== void 0 ? { stepPointer: out.stepPointer } : {},
+    ...out.mapEngagement !== void 0 ? { mapEngagement: out.mapEngagement } : {},
+    ...Array.isArray(injections) ? { activeInjections: Object.freeze([...injections]) } : {},
+    ...Array.isArray(hidden) && hidden.every((h) => typeof h === "string") ? { hiddenSkillIds: Object.freeze([...hidden]) } : {}
+  });
+}
+
+// src/core/served/servedGraphAt.ts
+import {
+  SERVED_GAPS as SERVED_GAPS2
+} from "agentfootprint";
+var SLOT_ORDER = Object.freeze({
+  "system-prompt": 0,
+  messages: 1,
+  tools: 2
+});
+var SERVED_SLOTS = Object.freeze(
+  Object.keys(SLOT_ORDER).sort((a, b) => SLOT_ORDER[a] - SLOT_ORDER[b])
+);
+var HELD_HONESTY_KEYS = Object.freeze([
+  "basis",
+  "redacted",
+  "skipped",
+  "foldError"
+]);
+var HELD_KEYS = Object.freeze([
+  ...FOLD_FACT_KEYS,
+  ...HELD_HONESTY_KEYS
+]);
+var RECONSTRUCTED = Object.freeze({ status: "reconstructed" });
+var NOT_ON_RECORD = Object.freeze({ status: "not-on-record" });
+function slotsOfFields(fields) {
+  const out = [];
+  for (const field of fields) {
+    const slot = field.startsWith("system.") ? "system-prompt" : field.startsWith("messages.") ? "messages" : field.startsWith("tools.") ? "tools" : void 0;
+    if (slot !== void 0 && !out.includes(slot)) out.push(slot);
+  }
+  return out;
+}
+function heldNodes(fold) {
+  const node = (key, value, status) => Object.freeze(value === void 0 ? { key, status } : { key, value, status });
+  const out = [];
+  for (const key of FOLD_FACT_KEYS) {
+    const value = fold[key];
+    out.push(value === void 0 ? node(key, void 0, "not-on-record") : node(key, value, "reconstructed"));
+  }
+  out.push(
+    fold.basis === void 0 ? node("basis", void 0, "not-on-record") : node("basis", fold.basis, "reconstructed")
+  );
+  out.push(node("redacted", fold.redacted, "reconstructed"));
+  if (fold.skipped !== void 0) out.push(node("skipped", fold.skipped, "damaged"));
+  if (fold.foldError !== void 0) out.push(node("foldError", fold.foldError, "damaged"));
+  return Object.freeze(out);
+}
+function servedEdges(input) {
+  const { row, checks, since } = input;
+  const view = row.view;
+  const edge = (e) => Object.freeze(e);
+  const out = [];
+  const compared = since !== void 0;
+  const enteredPieces = new Set(since?.system.enteredIndexes ?? []);
+  const enteredMessages = new Set(since?.messages.enteredIndexes ?? []);
+  const stateOf = (entered) => compared ? entered ? "entered" : "unchanged" : void 0;
+  const withState = (state) => state !== void 0 ? { state } : {};
+  view.system.pieces.forEach((piece, i) => {
+    out.push(
+      edge({
+        id: `piece:${i}`,
+        kind: "piece",
+        slot: piece.slot,
+        source: piece.source,
+        origin: piece.source,
+        text: piece.text,
+        check: checks.pieces[i] ?? RECONSTRUCTED,
+        ...withState(stateOf(enteredPieces.has(i)))
+      })
+    );
+  });
+  (since?.system.leftPieces ?? []).forEach((piece, i) => {
+    out.push(
+      edge({
+        id: `piece-left:${i}`,
+        kind: "piece",
+        slot: piece.slot,
+        source: piece.source,
+        origin: piece.source,
+        text: piece.text,
+        // Not on this request at all: there is no row here for a hash to check.
+        check: NOT_ON_RECORD,
+        state: "left"
+      })
+    );
+  });
+  view.messages.asSent.forEach((message, i) => {
+    const label = message.toolName ?? message.toolCallId;
+    out.push(
+      edge({
+        id: `message:${i}`,
+        kind: "message",
+        slot: "messages",
+        role: message.role,
+        origin: message.role,
+        ...label !== void 0 ? { label } : {},
+        text: message.content,
+        check: checks.messages[i] ?? RECONSTRUCTED,
+        ...withState(stateOf(enteredMessages.has(i)))
+      })
+    );
+  });
+  (since?.messages.leftEntries ?? []).forEach((message, i) => {
+    out.push(
+      edge({
+        id: `message-left:${i}`,
+        kind: "message",
+        slot: "messages",
+        role: message.role,
+        origin: message.role,
+        text: message.content,
+        check: NOT_ON_RECORD,
+        state: "left"
+      })
+    );
+  });
+  view.messages.requestOnly.forEach((line, i) => {
+    out.push(
+      edge({
+        id: `request-only:${i}`,
+        kind: "request-only",
+        slot: "messages",
+        role: line.role,
+        origin: line.role,
+        label: line.reason,
+        text: line.text,
+        check: checks.requestOnly[i] ?? RECONSTRUCTED
+      })
+    );
+  });
+  view.tools.names.forEach((name) => {
+    const schema = view.tools.schemas.find((s) => s.name === name);
+    const state = compared ? since !== void 0 && since.tools.added.includes(name) ? "entered" : "unchanged" : void 0;
+    out.push(
+      edge({
+        id: `tool:${name}`,
+        kind: "tool",
+        slot: "tools",
+        label: name,
+        // No rebuilt schema means no hash on this side; a NAME is never
+        // verified — the receipt carries names as plain strings.
+        check: schema !== void 0 ? checks.toolSchemas[name] ?? RECONSTRUCTED : RECONSTRUCTED,
+        ...view.tools.forced === name ? { forced: true } : {},
+        ...checks.onReceiptOnly.schemas.includes(name) ? { schemaOnReceiptOnly: true } : {},
+        ...since !== void 0 && since.tools.schemaChanged.includes(name) ? { schemaChanged: true } : {},
+        ...withState(state)
+      })
+    );
+  });
+  (since?.tools.removed ?? []).forEach((name) => {
+    out.push(
+      edge({
+        id: `tool-left:${name}`,
+        kind: "tool",
+        slot: "tools",
+        label: name,
+        check: NOT_ON_RECORD,
+        state: "left"
+      })
+    );
+  });
+  return Object.freeze(out);
+}
+function slotNodes(input, edges) {
+  const { row, checks } = input;
+  const view = row.view;
+  const receipt = row.receipt;
+  const gapsFor = (slot) => Object.freeze(view.gaps.filter((g) => slotsOfFields(g.fields).includes(slot)));
+  const rebuiltIn = (slot) => edges.filter((e) => e.slot === slot && e.state !== "left").length;
+  const onReceipt = {
+    "system-prompt": receipt?.system.pieces.length,
+    messages: receipt !== void 0 ? receipt.messages.entries.length + receipt.messages.requestOnly.length : void 0,
+    tools: checks.namesOnReceipt?.length
+  };
+  const check2 = {
+    "system-prompt": checks.system,
+    messages: void 0,
+    tools: checks.toolNames
+  };
+  const onReceiptOnly = {
+    "system-prompt": checks.onReceiptOnly.pieces,
+    messages: checks.onReceiptOnly.messages + checks.onReceiptOnly.requestOnly,
+    tools: checks.onReceiptOnly.toolNames.length
+  };
+  const rebuiltOnly = {
+    "system-prompt": checks.rebuiltOnly.pieces,
+    messages: checks.rebuiltOnly.messages + checks.rebuiltOnly.requestOnly,
+    tools: checks.rebuiltOnly.toolNames.length
+  };
+  return Object.freeze(
+    SERVED_SLOTS.map((slot) => {
+      const aggregate = check2[slot];
+      const count = onReceipt[slot];
+      return Object.freeze({
+        slot,
+        ...aggregate !== void 0 ? { check: aggregate } : {},
+        rebuilt: rebuiltIn(slot),
+        ...count !== void 0 ? { onReceipt: count } : {},
+        onReceiptOnly: onReceiptOnly[slot],
+        rebuiltOnly: rebuiltOnly[slot],
+        gaps: gapsFor(slot)
+      });
+    })
+  );
+}
+function withheldNodes(input) {
+  const { row, fold } = input;
+  const view = row.view;
+  const out = [];
+  if (view.tools.withheld !== void 0) {
+    out.push(
+      Object.freeze({
+        kind: "tool-withheld",
+        name: view.tools.withheld,
+        from: "view",
+        slot: "tools"
+      })
+    );
+  }
+  for (const id of fold.hiddenSkillIds ?? []) {
+    out.push(Object.freeze({ kind: "hidden-skill", name: id, from: "fold" }));
+  }
+  for (const turn of row.evictedTurns ?? []) {
+    out.push(
+      Object.freeze({
+        kind: "attention-drop",
+        name: "omittedForAttention",
+        from: "receipt",
+        slot: "messages",
+        hash: turn.hash,
+        ...turn.lastServedOn !== void 0 ? { lastServedOn: turn.lastServedOn } : {}
+      })
+    );
+  }
+  if (input.checks.omittedForAttention === "not-on-record") {
+    out.push(
+      Object.freeze({
+        kind: "attention-drop",
+        name: "omittedForAttention",
+        from: "receipt",
+        status: "not-on-record"
+      })
+    );
+  }
+  if (fold.redacted) {
+    out.push(Object.freeze({ kind: "redacted", name: "redacted", from: "fold" }));
+  }
+  for (const gap of view.gaps) {
+    const slots = slotsOfFields(gap.fields);
+    out.push(
+      Object.freeze({
+        kind: "gap",
+        name: gap.gap,
+        from: "view",
+        // One slot named: draw it there. Several, or none: the band itself.
+        ...slots.length === 1 ? { slot: slots[0] } : {},
+        why: SERVED_GAPS2[gap.gap].why,
+        fields: gap.fields,
+        ...gap.cause !== void 0 ? { cause: gap.cause } : {}
+      })
+    );
+  }
+  return Object.freeze(out);
+}
+function callNode(input, edges) {
+  const { row, checks } = input;
+  const basis = row.view.basis;
+  return Object.freeze({
+    epoch: row.epoch,
+    callRuntimeStageId: row.callRuntimeStageId,
+    commitIdx: row.commitIdx,
+    betweenCalls: row.betweenCalls,
+    ...row.previousEpoch !== void 0 ? { previousEpoch: row.previousEpoch } : {},
+    ...basis !== void 0 ? { basis } : {},
+    basisStatus: basis !== void 0 ? "reconstructed" : "not-on-record",
+    // Present only where the receipt SAYS — a string or null. A receipt
+    // without the key (pre-9.93.0) leaves it absent: "cannot say".
+    ...row.receipt !== void 0 && carriesCacheStrategy(row.receipt) ? { cacheStrategy: row.receipt.cache.strategy } : {},
+    ...row.receiptCause !== void 0 ? { receiptCause: row.receiptCause } : {},
+    damaged: checks.damaged || edges.some((e) => e.check.status === "damaged")
+  });
+}
+function servedGraphAt(input) {
+  const edges = servedEdges(input);
+  return Object.freeze({
+    held: heldNodes(input.fold),
+    served: slotNodes(input, edges),
+    withheld: withheldNodes(input),
+    call: callNode(input, edges),
+    edges
+  });
+}
+
 // src/core/utils/snapshotOfRunner.ts
 function snapshotOfRunner(runner) {
   const fn = runner?.getLastSnapshot;
@@ -590,6 +935,12 @@ export {
   sincePrevious,
   EXCUSING_GAPS,
   verify,
+  FOLD_FACT_KEYS,
+  foldFactsAt,
+  SERVED_SLOTS,
+  HELD_HONESTY_KEYS,
+  HELD_KEYS,
+  servedGraphAt,
   snapshotOfRunner,
   mountLogsOf,
   snapshotLogKey,
@@ -597,4 +948,4 @@ export {
   tagStopsFor,
   tagAxisPositions
 };
-//# sourceMappingURL=chunk-47W3TQT6.js.map
+//# sourceMappingURL=chunk-37NHCNSS.js.map