agentfootprint-lens 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -22,11 +22,13 @@ var src_exports = {};
 __export(src_exports, {
   AgentLens: () => AgentLens,
   IterationStrip: () => IterationStrip,
+  LiveTimelineBuilder: () => LiveTimelineBuilder,
   MessagesPanel: () => MessagesPanel,
   ToolCallInspector: () => ToolCallInspector,
   fromAgentSnapshot: () => fromAgentSnapshot,
   resolveLensTheme: () => resolve,
-  useLensTheme: () => useLensTheme
+  useLensTheme: () => useLensTheme,
+  useLiveTimeline: () => useLiveTimeline
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -273,12 +275,26 @@ var import_jsx_runtime = require("react/jsx-runtime");
 function MessagesPanel({
   timeline,
   onToolCallClick,
-  systemPrompt
+  systemPrompt,
+  selectedIterKey
 }) {
   const t = useLensTheme();
+  const scrollRef = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    if (!selectedIterKey || !scrollRef.current) return;
+    const target = scrollRef.current.querySelector(
+      `[data-iter-key="${CSS.escape(selectedIterKey)}"]`
+    );
+    if (!target) return;
+    target.scrollIntoView({ block: "start", behavior: "smooth" });
+    target.setAttribute("data-iter-selected", "true");
+    const h = window.setTimeout(() => target.removeAttribute("data-iter-selected"), 1200);
+    return () => window.clearTimeout(h);
+  }, [selectedIterKey]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
     "div",
     {
+      ref: scrollRef,
       "data-fp-lens": "messages-panel",
       style: {
         display: "flex",
@@ -365,7 +381,15 @@ function TurnBlock({
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { display: "flex", flexDirection: "column", gap: 12 }, children: [
     /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TurnHeader, { turn }),
     /* @__PURE__ */ (0, import_jsx_runtime.jsx)(UserBubble, { text: turn.userPrompt }),
-    turn.iterations.map((iter) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IterationBlock, { iter, onToolCallClick }, iter.index)),
+    turn.iterations.map((iter) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      IterationBlock,
+      {
+        iter,
+        turnIndex: turn.index,
+        onToolCallClick
+      },
+      iter.index
+    )),
     turn.finalContent && turn.iterations.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { fontSize: 11, color: t.textSubtle, textAlign: "center" }, children: [
       "turn ",
       turn.index + 1,
@@ -427,27 +451,51 @@ function UserBubble({ text }) {
 }
 function IterationBlock({
   iter,
+  turnIndex,
   onToolCallClick
 }) {
   const t = useLensTheme();
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IterationBadge, { iter }),
-    iter.assistantContent && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-      "div",
-      {
-        style: {
-          background: t.bgElev,
-          border: `1px solid ${t.border}`,
-          borderRadius: `2px ${t.radius} ${t.radius} ${t.radius}`,
-          padding: "10px 14px",
-          maxWidth: 820,
-          whiteSpace: "pre-wrap"
-        },
-        children: iter.assistantContent
-      }
-    ),
-    iter.toolCalls.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { display: "flex", flexDirection: "column", gap: 6, paddingLeft: 12 }, children: iter.toolCalls.map((tc) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToolCallCard, { invocation: tc, onClick: onToolCallClick }, tc.id)) })
-  ] });
+  const key = `${turnIndex}.${iter.index}`;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "div",
+    {
+      "data-iter-key": key,
+      "data-turn-index": turnIndex,
+      "data-iter-index": iter.index,
+      style: {
+        display: "flex",
+        flexDirection: "column",
+        gap: 6,
+        // When the parent adds data-iter-selected (via IterationStrip
+        // click), pulse a soft ring using the accent color. Subtle so
+        // the chat itself stays readable.
+        padding: 8,
+        margin: -8,
+        borderRadius: t.radius,
+        outline: "2px solid transparent",
+        outlineOffset: 2,
+        transition: "outline-color 180ms ease, background 180ms ease"
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IterationBadge, { iter }),
+        iter.assistantContent && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "div",
+          {
+            style: {
+              background: t.bgElev,
+              border: `1px solid ${t.border}`,
+              borderRadius: `2px ${t.radius} ${t.radius} ${t.radius}`,
+              padding: "10px 14px",
+              maxWidth: 820,
+              whiteSpace: "pre-wrap"
+            },
+            children: iter.assistantContent
+          }
+        ),
+        iter.toolCalls.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { display: "flex", flexDirection: "column", gap: 6, paddingLeft: 12 }, children: iter.toolCalls.map((tc) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToolCallCard, { invocation: tc, onClick: onToolCallClick }, tc.id)) })
+      ]
+    }
+  );
 }
 function IterationBadge({ iter }) {
   const t = useLensTheme();
@@ -882,6 +930,12 @@ function AgentLens({
         fontFamily: t.fontSans
       },
       children: [
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("style", { children: `
+        [data-iter-selected="true"] {
+          outline-color: currentColor !important;
+          background: color-mix(in srgb, currentColor 8%, transparent);
+        }
+      ` }),
         /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: { gridArea: "strip" }, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
           IterationStrip,
           {
@@ -895,6 +949,7 @@ function AgentLens({
           {
             timeline,
             onToolCallClick: handleToolClick,
+            selectedIterKey,
             ...derivedSystemPrompt && { systemPrompt: derivedSystemPrompt }
           }
         ) }),
@@ -921,14 +976,244 @@ function AgentLens({
     }
   );
 }
+
+// src/adapters/LiveTimelineBuilder.ts
+var LiveTimelineBuilder = class {
+  constructor() {
+    this.turns = [];
+    this.currentTurn = null;
+    this.currentIter = null;
+    this.toolByCallId = /* @__PURE__ */ new Map();
+    this.messages = [];
+    this.finalDecision = {};
+  }
+  /**
+   * Begin a new turn. Call this BEFORE `agent.run(userPrompt)` so the
+   * user's prompt appears alongside the iterations it produced. Safe to
+   * call even mid-conversation — it closes the previous turn cleanly.
+   */
+  startTurn(userPrompt) {
+    if (this.currentTurn) this.commitCurrentTurn();
+    this.currentTurn = {
+      index: this.turns.length,
+      userPrompt,
+      iterations: [],
+      finalContent: "",
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      totalDurationMs: 0,
+      startMs: Date.now()
+    };
+    this.messages.push({ role: "user", content: userPrompt });
+  }
+  /**
+   * Optional — attach the system prompt so MessagesPanel can render it
+   * in the collapsible preamble. Usually set once at agent construction.
+   */
+  setSystemPrompt(prompt) {
+    this.systemPrompt = prompt;
+  }
+  /**
+   * Feed one agent stream event. Safe to call for unknown events; we
+   * ignore anything we don't recognize.
+   */
+  ingest(event) {
+    const e = event;
+    if (!e || typeof e.type !== "string") return;
+    switch (e.type) {
+      case "llm_start":
+      case "agentfootprint.stream.llm_start":
+        this.onLLMStart(e);
+        return;
+      case "llm_end":
+      case "agentfootprint.stream.llm_end":
+        this.onLLMEnd(e);
+        return;
+      case "tool_start":
+      case "agentfootprint.stream.tool_start":
+        this.onToolStart(e);
+        return;
+      case "tool_end":
+      case "agentfootprint.stream.tool_end":
+        this.onToolEnd(e);
+        return;
+      case "turn_end":
+      case "agentfootprint.agent.turn_complete":
+        this.commitCurrentTurn();
+        return;
+      default:
+        return;
+    }
+  }
+  onLLMStart(e) {
+    if (!this.currentTurn) return;
+    const iterNum = e.iteration ?? this.currentTurn.iterations.length + 1;
+    this.currentIter = {
+      index: iterNum,
+      assistantContent: "",
+      toolCalls: [],
+      decisionAtStart: {},
+      visibleTools: [],
+      startMs: Date.now()
+    };
+    this.currentTurn.iterations.push(this.currentIter);
+  }
+  onLLMEnd(e) {
+    if (!this.currentIter || !this.currentTurn) return;
+    this.currentIter.assistantContent = e.content ?? this.currentIter.assistantContent;
+    if (e.model) this.currentIter.model = e.model;
+    if (e.usage?.inputTokens !== void 0) this.currentIter.inputTokens = e.usage.inputTokens;
+    if (e.usage?.outputTokens !== void 0) this.currentIter.outputTokens = e.usage.outputTokens;
+    if (e.stopReason) this.currentIter.stopReason = e.stopReason;
+    this.currentIter.durationMs = e.durationMs ?? Date.now() - this.currentIter.startMs;
+    this.currentTurn.totalInputTokens += this.currentIter.inputTokens ?? 0;
+    this.currentTurn.totalOutputTokens += this.currentIter.outputTokens ?? 0;
+    this.currentTurn.totalDurationMs += this.currentIter.durationMs ?? 0;
+    if (this.currentIter.assistantContent) {
+      this.messages.push({ role: "assistant", content: this.currentIter.assistantContent });
+    }
+    if ((e.toolCallCount ?? 0) === 0) {
+      this.currentTurn.finalContent = this.currentIter.assistantContent;
+    }
+  }
+  onToolStart(e) {
+    if (!this.currentIter || !this.currentTurn) return;
+    const tool = {
+      id: e.toolCallId ?? `tool-${this.currentIter.toolCalls.length}`,
+      name: e.toolName ?? "unknown",
+      arguments: e.args ?? {},
+      result: "",
+      iterationIndex: this.currentIter.index,
+      turnIndex: this.currentTurn.index,
+      startMs: Date.now()
+    };
+    this.currentIter.toolCalls.push(tool);
+    this.toolByCallId.set(tool.id, tool);
+  }
+  onToolEnd(e) {
+    const tool = this.toolByCallId.get(e.toolCallId ?? "");
+    if (!tool) return;
+    const r = e.result;
+    if (typeof r === "string") {
+      tool.result = r;
+    } else if (r && typeof r === "object") {
+      tool.result = r.content ?? "";
+      if (r.error === true) tool.error = true;
+    }
+    tool.durationMs = e.durationMs ?? Date.now() - tool.startMs;
+    this.messages.push({ role: "tool", content: tool.result, toolCallId: tool.id });
+  }
+  commitCurrentTurn() {
+    if (!this.currentTurn) return;
+    this.turns.push(this.currentTurn);
+    this.currentTurn = null;
+    this.currentIter = null;
+  }
+  /**
+   * Snapshot the current state as an immutable `AgentTimeline`. Safe to
+   * call at any point — mid-run gives you the partial state so Lens can
+   * live-update.
+   */
+  getTimeline() {
+    const allTurns = [...this.turns];
+    if (this.currentTurn) allTurns.push(this.currentTurn);
+    const tools = [];
+    const frozenTurns = allTurns.map((t) => {
+      const iterations = t.iterations.map((i) => {
+        const tcs = i.toolCalls.map((tc) => ({ ...tc }));
+        tools.push(...tcs);
+        return { ...i, toolCalls: tcs };
+      });
+      return { ...t, iterations };
+    });
+    return {
+      turns: frozenTurns,
+      messages: [...this.messages],
+      tools,
+      finalDecision: { ...this.finalDecision },
+      rawSnapshot: null
+    };
+  }
+  /**
+   * Fold in a final `decision` scope after the run — useful when
+   * the consumer wants the Decision Ribbon (phase-2) to reflect the
+   * post-run state. Safe no-op during the run itself.
+   */
+  setFinalDecision(decision) {
+    this.finalDecision = decision;
+  }
+  /** Get the optional system prompt for the Messages preamble. */
+  getSystemPrompt() {
+    return this.systemPrompt;
+  }
+  /** Wipe state. Useful when the consumer starts a fresh conversation. */
+  reset() {
+    this.turns = [];
+    this.currentTurn = null;
+    this.currentIter = null;
+    this.toolByCallId.clear();
+    this.messages = [];
+    this.finalDecision = {};
+  }
+};
+
+// src/adapters/useLiveTimeline.ts
+var import_react3 = require("react");
+function useLiveTimeline() {
+  const builderRef = (0, import_react3.useRef)(null);
+  if (!builderRef.current) builderRef.current = new LiveTimelineBuilder();
+  const builder = builderRef.current;
+  const [timeline, setTimeline] = (0, import_react3.useState)(() => builder.getTimeline());
+  const sync = (0, import_react3.useCallback)(() => {
+    setTimeline(builder.getTimeline());
+  }, [builder]);
+  const ingest = (0, import_react3.useCallback)(
+    (event) => {
+      builder.ingest(event);
+      sync();
+    },
+    [builder, sync]
+  );
+  const startTurn = (0, import_react3.useCallback)(
+    (userPrompt) => {
+      builder.startTurn(userPrompt);
+      sync();
+    },
+    [builder, sync]
+  );
+  const setSystemPrompt = (0, import_react3.useCallback)(
+    (prompt) => {
+      builder.setSystemPrompt(prompt);
+      sync();
+    },
+    [builder, sync]
+  );
+  const setFinalDecision = (0, import_react3.useCallback)(
+    (decision) => {
+      builder.setFinalDecision(decision);
+      sync();
+    },
+    [builder, sync]
+  );
+  const reset = (0, import_react3.useCallback)(() => {
+    builder.reset();
+    sync();
+  }, [builder, sync]);
+  return (0, import_react3.useMemo)(
+    () => ({ timeline, ingest, startTurn, setSystemPrompt, setFinalDecision, reset, builder }),
+    [timeline, ingest, startTurn, setSystemPrompt, setFinalDecision, reset, builder]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentLens,
   IterationStrip,
+  LiveTimelineBuilder,
   MessagesPanel,
   ToolCallInspector,
   fromAgentSnapshot,
   resolveLensTheme,
-  useLensTheme
+  useLensTheme,
+  useLiveTimeline
 });
 //# sourceMappingURL=index.cjs.map