feat(simulate): open a cited turn from the summary with its number

A summary citation could only be followed out of the terminal, by
ctrl+clicking its OSC 8 link into the dashboard. The turn it cites is
already in the run, so the TUI can open it directly.

Each citation now carries a number, and pressing that digit on the list
view opens the cited job. Numbering follows render order through one
index shared by every block of the summary, so the digit a reader presses
selects the citation whose label shows it. Only the first nine are
numbered: a number is an invitation to press that digit, and there is no
tenth digit.

A jump lands at the top of the printed job, which scrollback cannot be
scrolled past, so the cited turn is marked where it prints. The mark
rides the message text rather than the speaker header, which a message
continuing an open agent block never prints.

Numbering keys off a citation naming a job, not off a dashboard URL
resolving: the jump is local, so it works where the link does not.

Author: u9g

cmd/lk/simulate_refs.go

@@ -15,6 +15,7 @@
 package main
 
 import (
+	"fmt"
 	"regexp"
 	"strings"
 	"unicode"
@@ -40,16 +41,51 @@ func summaryRefStyle() lipgloss.Style {
 	return lipgloss.NewStyle().Foreground(util.Brand()).Underline(true)
 }
 
-// linkSummaryRefs replaces each <ref> in summary prose with its quoted text as
-// a clickable link to the cited chat item. A ref missing a job, or a run with
-// no dashboard URL, degrades to the quoted text alone.
-func linkSummaryRefs(text, projectID, runID string) string {
+// A citation's number is an invitation to press that digit, so only as many
+// citations as there are digits to press carry one.
+const maxNumberedSummaryRefs = 9
+
+// summaryRefTarget is the chat item a numbered citation points at.
+type summaryRefTarget struct {
+	job  string
+	item string
+}
+
+// summaryRefIndex numbers citations as they are rendered. The number a reader
+// sees has to select the same citation when pressed, so one index is threaded
+// through every block of a summary and numbering follows render order.
+type summaryRefIndex struct {
+	targets []summaryRefTarget
+}
+
+// add records a citation and returns its 1-based number, or false once every
+// digit is spoken for.
+func (x *summaryRefIndex) add(attrs map[string]string) (int, bool) {
+	if len(x.targets) >= maxNumberedSummaryRefs {
+		return 0, false
+	}
+	x.targets = append(x.targets, summaryRefTarget{job: attrs["job"], item: attrs["item"]})
+	return len(x.targets), true
+}
+
+// linkSummaryRefs replaces each <ref> in summary prose with its quoted text,
+// numbered so the digit keys can open the cited turn, and hyperlinked to the
+// cited item when the run has a dashboard URL. A ref naming no job cites
+// nothing openable and degrades to the quoted text alone.
+func linkSummaryRefs(text, projectID, runID string, refs *summaryRefIndex) string {
 	return replaceSummaryRefs(text, func(attrs map[string]string, label string) string {
-		url := simulationItemDashboardURL(projectID, runID, attrs["job"], attrs["item"])
-		if url == "" {
+		if attrs["job"] == "" {
 			return label
 		}
-		return util.Hyperlink(url, summaryRefStyle().Render(label))
+		n, ok := refs.add(attrs)
+		if !ok {
+			return label
+		}
+		rendered := summaryRefStyle().Render(label)
+		if url := simulationItemDashboardURL(projectID, runID, attrs["job"], attrs["item"]); url != "" {
+			rendered = util.Hyperlink(url, rendered)
+		}
+		return rendered + dimStyle.Render(fmt.Sprintf(" [%d]", n))
 	})
 }
 

cmd/lk/simulate_refs_test.go

@@ -41,7 +41,8 @@ func TestStripSummaryRefs(t *testing.T) {
 }
 
 func TestLinkSummaryRefs(t *testing.T) {
-	linked := linkSummaryRefs(refProse, "proj", "run")
+	var refs summaryRefIndex
+	linked := linkSummaryRefs(refProse, "proj", "run", &refs)
 
 	require.NotContains(t, linked, "<ref")
 	require.NotContains(t, linked, "</ref>")
@@ -50,10 +51,41 @@ func TestLinkSummaryRefs(t *testing.T) {
 	require.Contains(t, linked, "runs/run?job=SRJ_Bzb9ZaoJFJyp&item=item_13b90227fe38")
 	require.Contains(t, linked, `"I've had a few, sure"`)
 	require.Equal(t, 2, strings.Count(linked, "\x1b]8;;"+dashboardBaseURL()))
+
+	// the number a label carries selects the citation recorded under it
+	require.Contains(t, linked, "[1]")
+	require.Contains(t, linked, "[2]")
+	require.Equal(t, []summaryRefTarget{
+		{job: "SRJ_Bzb9ZaoJFJyp", item: "item_dd0ee81187bd"},
+		{job: "SRJ_Bzb9ZaoJFJyp", item: "item_13b90227fe38"},
+	}, refs.targets)
 }
 
 func TestLinkSummaryRefsWithoutTarget(t *testing.T) {
-	// no project or run to link to, and a ref with no job: quoted text only
-	require.Equal(t, stripSummaryRefs(refProse), linkSummaryRefs(refProse, "", ""))
-	require.Equal(t, "quoted", linkSummaryRefs(`<ref item="item_x">quoted</ref>`, "proj", "run"))
+	// a ref naming no job cites nothing that can be opened: quoted text alone
+	var unopenable summaryRefIndex
+	require.Equal(t, "quoted", linkSummaryRefs(`<ref item="item_x">quoted</ref>`, "proj", "run", &unopenable))
+	require.Empty(t, unopenable.targets)
+
+	// with no dashboard URL the job is still openable from the TUI, so the
+	// citation keeps its number and loses only the hyperlink
+	var local summaryRefIndex
+	linked := linkSummaryRefs(refProse, "", "", &local)
+	require.NotContains(t, linked, "\x1b]8;;")
+	require.Contains(t, linked, "[1]")
+	require.Len(t, local.targets, 2)
+}
+
+func TestSummaryRefIndexStopsAtTheLastDigit(t *testing.T) {
+	var b strings.Builder
+	for range maxNumberedSummaryRefs + 2 {
+		b.WriteString(`<ref job="J" item="i">q</ref>`)
+	}
+
+	var refs summaryRefIndex
+	linked := linkSummaryRefs(b.String(), "proj", "run", &refs)
+
+	require.Len(t, refs.targets, maxNumberedSummaryRefs)
+	require.Contains(t, linked, "[9]")
+	require.NotContains(t, linked, "[10]")
 }

cmd/lk/simulate_tui.go

@@ -217,6 +217,12 @@ type simulateModel struct {
 
 	cursor      int
 	detailJobID string
+	// The summary's citations, in the order their numbers were rendered, so a
+	// digit key resolves to the turn its label points at. refItemID is the chat
+	// item a jump cited, marked when the job view prints because printed
+	// scrollback cannot be scrolled to it.
+	summaryRefs []summaryRefTarget
+	refItemID   string
 	// The open job's view is printed into the terminal's own scrollback instead
 	// of being windowed in the live region; detailPrinted is what has already
 	// been emitted for it, so a re-render only ever appends its new tail.
@@ -953,6 +959,16 @@ func (m *simulateModel) handleKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 				m.viewScrollOff += pageScroll // clamped on render
 			}
 		}
+	// A citation's number opens the turn it cites. Only live on the list view,
+	// which is where the numbered summary is on screen to read them off.
+	case "1", "2", "3", "4", "5", "6", "7", "8", "9":
+		if m.detailJobID == "" {
+			if ref, ok := m.summaryRef(key); ok {
+				m.detailJobID = ref.job
+				m.refItemID = ref.item
+				return m, m.openDetailCmd()
+			}
+		}
 	// j and l sit either side of k on the home row, so they double for the
 	// left/right arrows without reaching for them.
 	case "enter", "right", "l":
@@ -1673,9 +1689,19 @@ func (m *simulateModel) openDetailCmd() tea.Cmd {
 func (m *simulateModel) closeDetailCmd() tea.Cmd {
 	m.detailJobID = ""
 	m.detailPrinted = ""
+	m.refItemID = ""
 	return tea.EnterAltScreen
 }
 
+// summaryRef resolves a digit key to the citation whose label carries it.
+func (m *simulateModel) summaryRef(key string) (summaryRefTarget, bool) {
+	n := int(key[0] - '0')
+	if n < 1 || n > len(m.summaryRefs) {
+		return summaryRefTarget{}, false
+	}
+	return m.summaryRefs[n-1], true
+}
+
 // clearScrollback empties the screen and the scrollback behind it. It rides
 // along with the first print of a job rather than being written to stdout
 // directly: a write inside a Cmd is not ordered against the event loop, so it
@@ -1760,8 +1786,9 @@ func (m *simulateModel) renderSummary() string {
 	)
 
 	wrapWidth := proseWidth(m.width, 6)
+	var refs summaryRefIndex
 	link := func(text string) string {
-		return linkSummaryRefs(text, m.projectID(), m.runID)
+		return linkSummaryRefs(text, m.projectID(), m.runID, &refs)
 	}
 
 	if summary.GoingWell != "" {
@@ -1811,6 +1838,10 @@ func (m *simulateModel) renderSummary() string {
 		b.WriteString("\n")
 	}
 
+	// what the digit keys resolve to, recorded as the labels are rendered so the
+	// two cannot disagree
+	m.summaryRefs = refs.targets
+
 	return b.String()
 }
 
@@ -1872,8 +1903,17 @@ func (m *simulateModel) renderChatTranscript(jobID string) string {
 				}
 			}
 			toolOpenedAgentBlock = false
-			for _, line := range wrapLines(text, wrapWidth) {
-				b.WriteString("      " + line + "\n")
+			cited := msg.Id != "" && msg.Id == m.refItemID
+			for i, line := range wrapLines(text, wrapWidth) {
+				b.WriteString("      " + line)
+				// a jump lands at the top of the printed job, so the cited turn
+				// says so where it prints. The mark rides the text, which every
+				// message has, and not the speaker header, which a message
+				// continuing an open agent block never prints.
+				if i == 0 && cited {
+					b.WriteString("  " + summaryRefStyle().Render("◀ cited"))
+				}
+				b.WriteString("\n")
 			}
 		case *agent.ChatContext_ChatItem_FunctionCall:
 			fc := v.FunctionCall
@@ -2096,6 +2136,9 @@ func (m *simulateModel) renderHint() string {
 	default:
 		// the collapsed description block already carries "(press d to expand)"
 		nav := "↑↓ navigate · →/ENTER detail"
+		if len(m.summaryRefs) > 0 {
+			nav += " · 1-9 cited turn"
+		}
 		if m.pageOverflow || m.viewScrollOff > 0 {
 			nav += " · PgUp/PgDn page"
 		}