@north-light/api 0.3.579 → 0.3.587

package/dist/commands/canvas-analytics/graph-detail.js

@@ -0,0 +1,307 @@
+// Graph detail: where did this graph's time and API-price estimate go?
+//
+// Rows are the graph's agents with `in_graph_detail` (active agents plus the
+// ancestors connecting them to the root; crtrd decides which), in tree order:
+// parent before children, children by `created`. An agent a drilldown selected
+// that is not among them (it finished with no response in the window) is added
+// with the ancestors connecting it, shown like an inactive ancestor. Each row
+// has a timeline of fixed slots over the graph's first to last response in the
+// window, the created→final column, and the agent's API-price estimate; the
+// est. column sums to the header value. `Enter` opens the read-only Inspector, `r` the
+// final report, `o` the conversation (the only key that may wake an agent).
+// Narrow: no timeline.
+import { matchesKey, visibleWidth } from '@earendil-works/pi-tui';
+import { rule, theme, wrapText } from '../../core/tui/panel.js';
+import { formatClock, formatDuration, formatPrice, formatTimeOfDay, formatTokens, padLeft, padRight, plural, unavailable } from './format.js';
+import { fullNameLine, graphLabel } from './graphs.js';
+import { isNarrow, listWindow, markRow } from './view.js';
+const MINUTE = 60_000;
+/** Slot lengths, smallest first; the timeline uses the first whose slots fit. */
+const SLOTS_MIN = [1, 2, 5, 7.5, 10, 15, 30, 60, 120, 180, 240];
+/** Axis label spacing candidates, in minutes. */
+const LABEL_STEPS_MIN = [15, 30, 60, 120, 180, 360, 720, 1440, 2880];
+/** Parent before children, children by `created`. An agent whose parent is not
+ *  among the rows starts its own subtree (only the graph's root, by crtrd's rule). */
+function treeRows(agents) {
+    const ids = new Set(agents.map((a) => a.node_id));
+    const byCreated = [...agents].sort((a, b) => Date.parse(a.created) - Date.parse(b.created) || a.node_id.localeCompare(b.node_id));
+    const children = new Map();
+    const tops = [];
+    for (const agent of byCreated) {
+        if (agent.parent !== null && ids.has(agent.parent)) {
+            const list = children.get(agent.parent) ?? [];
+            list.push(agent);
+            children.set(agent.parent, list);
+        }
+        else
+            tops.push(agent);
+    }
+    const rows = [];
+    const walk = (agent, lead, branch) => {
+        rows.push({ agent, guide: lead + branch });
+        const kids = children.get(agent.node_id) ?? [];
+        const nextLead = branch === '' ? lead : lead + (branch === '├ ' ? '│ ' : '  ');
+        kids.forEach((kid, i) => walk(kid, nextLead, i === kids.length - 1 ? '└ ' : '├ '));
+    };
+    for (const top of tops)
+        walk(top, '', '');
+    return rows;
+}
+function rowLabel(row) {
+    return `${row.guide}${row.agent.kind}  ${row.agent.name}`;
+}
+function slotLabel(minutes) {
+    return minutes < 60 ? `${minutes}-min` : `${minutes / 60}-hour`;
+}
+/** The smallest slot at which the first-to-last response span fits `cells`,
+ *  slots aligned to local clock multiples of their length. */
+function timelineFor(first, last, cells) {
+    const offset = -new Date(first).getTimezoneOffset() * MINUTE;
+    let chosen;
+    for (const minutes of SLOTS_MIN) {
+        const slotMs = minutes * MINUTE;
+        const start = Math.floor((first + offset) / slotMs) * slotMs - offset;
+        const slots = Math.floor((last - start) / slotMs) + 1;
+        chosen = { start, slotMs, slots, offset };
+        if (slots <= cells)
+            break;
+    }
+    return chosen;
+}
+function axisLine(t, cells) {
+    const slotMin = t.slotMs / MINUTE;
+    const multiDay = t.slots * t.slotMs > 24 * 60 * MINUTE;
+    const labelWidth = multiDay ? 9 : 5;
+    const step = LABEL_STEPS_MIN.find((s) => s >= slotMin && s % slotMin === 0 && (s / slotMin) >= labelWidth + 2) ?? LABEL_STEPS_MIN.at(-1);
+    const stepMs = step * MINUTE;
+    let line = '';
+    for (let i = 0; i < t.slots && i < cells; i += 1) {
+        const at = t.start + i * t.slotMs;
+        if ((at + t.offset) % stepMs !== 0)
+            continue;
+        if (i < line.length + (line === '' ? 0 : 1))
+            continue;
+        const label = multiDay ? formatClock(at) : formatTimeOfDay(at);
+        if (i + label.length > cells)
+            break;
+        line = line.padEnd(i) + label;
+    }
+    return line.padEnd(cells).slice(0, cells);
+}
+function timelineCells(agent, t, cells) {
+    const created = Date.parse(agent.created);
+    const final = agent.finalized_at === null ? undefined : Date.parse(agent.finalized_at);
+    const responded = new Set(agent.response_times_ms.map((ms) => Math.floor((ms - t.start) / t.slotMs)));
+    let out = '';
+    for (let i = 0; i < Math.min(t.slots, cells); i += 1) {
+        const from = t.start + i * t.slotMs;
+        const to = from + t.slotMs;
+        if (final !== undefined && final >= from && final < to)
+            out += '◆';
+        else if (responded.has(i))
+            out += '█';
+        else if (created < to && (final === undefined || final >= to))
+            out += '─';
+        else
+            out += ' ';
+    }
+    return out.padEnd(cells);
+}
+function createdToFinal(agent) {
+    if (agent.agent_time_ms !== null)
+        return formatDuration(agent.agent_time_ms);
+    return agent.lifecycle === 'resident' ? 'resident' : 'open';
+}
+class GraphDetailView {
+    ctx;
+    rows;
+    graph;
+    rootName;
+    /** The graph's root agent row, for the header when the graph has no graph row. */
+    root;
+    /** A drilldown's agent with no AgentRowDTO at all (a memory reader outside agents[]). */
+    unlisted;
+    cursor = 0;
+    report;
+    constructor(ctx, graphId, selectAgentId) {
+        this.ctx = ctx;
+        const data = ctx.data;
+        this.graph = data.graphs.ok ? data.graphs.value.graphs.find((g) => g.graph_id === graphId) : undefined;
+        const byId = new Map(data.agents.map((a) => [a.node_id, a]));
+        const shown = new Map(data.agents.filter((a) => a.graph_id === graphId && a.in_graph_detail).map((a) => [a.node_id, a]));
+        for (let at = selectAgentId === undefined ? undefined : byId.get(selectAgentId); at !== undefined && !shown.has(at.node_id); at = at.parent === null ? undefined : byId.get(at.parent)) {
+            shown.set(at.node_id, at);
+        }
+        this.rows = treeRows([...shown.values()]);
+        this.cursor = Math.max(0, this.rows.findIndex((r) => r.agent.node_id === selectAgentId));
+        this.unlisted = selectAgentId !== undefined && !byId.has(selectAgentId) ? this.readerNamed(selectAgentId) : undefined;
+        this.root = data.agents.find((a) => a.graph_id === graphId && a.parent === null);
+        this.rootName = this.graph !== undefined ? graphLabel(this.graph) : (this.root?.name ?? graphId);
+    }
+    readerNamed(nodeId) {
+        const memory = this.ctx.data.memory;
+        if (!memory.ok)
+            return undefined;
+        const rows = [...memory.value.read.rows, ...memory.value.loaded.rows];
+        return rows.flatMap((row) => row.readers).find((reader) => reader.node_id === nodeId);
+    }
+    get selected() {
+        return this.rows[this.cursor]?.agent;
+    }
+    handleKey(key) {
+        if (this.report !== undefined) {
+            if (matchesKey(key, 'escape') || matchesKey(key, 'r'))
+                this.report = undefined;
+            else if (matchesKey(key, 'down') || matchesKey(key, 'j'))
+                this.report.scroll += 1;
+            else if (matchesKey(key, 'up') || matchesKey(key, 'k'))
+                this.report.scroll = Math.max(0, this.report.scroll - 1);
+            else
+                return 'unhandled';
+            return 'handled';
+        }
+        if (matchesKey(key, 'escape'))
+            return 'back';
+        const agent = this.selected;
+        if (matchesKey(key, 'up') || matchesKey(key, 'k'))
+            this.cursor = Math.max(0, this.cursor - 1);
+        else if (matchesKey(key, 'down') || matchesKey(key, 'j'))
+            this.cursor = Math.min(this.rows.length - 1, this.cursor + 1);
+        else if (agent === undefined)
+            return 'unhandled';
+        else if (matchesKey(key, 'enter'))
+            this.ctx.nav.openInspector(agent.node_id);
+        else if (matchesKey(key, 'o'))
+            this.ctx.nav.openConversation(agent.node_id);
+        else if (matchesKey(key, 'r')) {
+            if (agent.final_report_ref === null)
+                return 'handled';
+            this.openReport(agent.final_report_ref, `${agent.kind} ${agent.name}`);
+        }
+        else
+            return 'unhandled';
+        return 'handled';
+    }
+    openReport(ref, name) {
+        const report = { ref, name, scroll: 0, text: undefined, error: undefined };
+        this.report = report;
+        this.ctx.nav.readFinalReport(ref).then((text) => {
+            report.text = text;
+            this.ctx.nav.requestRender();
+        }, (error) => {
+            report.error = error instanceof Error ? error.message : String(error);
+            this.ctx.nav.requestRender();
+        });
+    }
+    keyLine(narrow) {
+        if (this.report !== undefined)
+            return narrow ? '↑↓' : '↑↓ scroll';
+        if (this.rows.length === 0)
+            return '';
+        const report = this.selected?.final_report_ref !== null;
+        // "open, may wake it" stays spelled out at every width: it is the one key that can wake an agent.
+        if (narrow)
+            return ['↑↓ Enter', ...(report ? ['r'] : []), 'o open, may wake it'].join(' ');
+        return ['↑↓ agent · Enter inspect, read-only', ...(report ? ['r final report'] : []), 'o open, may wake it'].join(' · ');
+    }
+    escapeLabel() {
+        return this.report !== undefined ? 'close report' : undefined;
+    }
+    render(width, height, data) {
+        const header = this.header(width, data);
+        const body = this.report !== undefined ? this.reportBody(width, height - header.length, this.report) : this.treeBody(width, height - header.length);
+        return [...header, ...body];
+    }
+    header(width, data) {
+        const out = [theme.bold(`< Graphs  /  ${this.rootName}`)];
+        const graph = this.graph;
+        const rootLine = (kind, lifecycle, created) => `Root: ${kind} · ${lifecycle === 'resident' ? 'resident conversation' : 'terminal'} · created ${formatClock(created)}`;
+        if (!data.graphs.ok)
+            out.push(unavailable(data.graphs.reason));
+        else if (graph === undefined) {
+            if (this.root !== undefined)
+                out.push(rootLine(this.root.kind, this.root.lifecycle, this.root.created));
+            out.push('No agent in this graph had a model response in this window.');
+        }
+        else {
+            out.push(rootLine(graph.root_kind, graph.root_lifecycle, graph.root_created));
+            out.push(`${plural(graph.active_agents, 'agent', 'agents')} · depth ${graph.depth} · ${formatTokens(graph.tokens)} tokens · ${formatPrice(graph.api_price_estimate)} API-price est.`);
+        }
+        out.push(rule(width));
+        return out;
+    }
+    treeBody(width, height) {
+        if (!this.ctx.data.graphs.ok || this.rows.length === 0)
+            return [];
+        const narrow = isNarrow(width);
+        const finalW = 15;
+        const estW = 9;
+        const longest = Math.max(0, ...this.rows.map((r) => visibleWidth(rowLabel(r))));
+        let agentW = narrow ? width - 2 - finalW - estW : Math.max(20, Math.min(longest, Math.floor(width * 0.4)));
+        const cellsFor = (agentWidth) => (narrow ? 0 : Math.max(10, width - 2 - agentWidth - 1 - finalW - estW));
+        let cells = cellsFor(agentW);
+        const out = [];
+        const times = this.rows.flatMap((r) => r.agent.response_times_ms);
+        const first = Math.min(...times);
+        const last = Math.max(...times);
+        let timeline = !narrow && times.length > 0 ? timelineFor(first, last, cells) : undefined;
+        if (timeline !== undefined && timeline.slots > cells) {
+            // Even 4-hour slots do not fit: give the agent column's width to the timeline.
+            agentW = Math.max(20, agentW - (timeline.slots - cells));
+            cells = cellsFor(agentW);
+            timeline = timelineFor(first, last, cells);
+        }
+        if (!narrow) {
+            if (timeline === undefined)
+                out.push('Timeline: no model responses in this window.');
+            else {
+                const end = timeline.start + Math.min(timeline.slots, cells) * timeline.slotMs;
+                const sameDay = new Date(timeline.start).toDateString() === new Date(end - 1).toDateString();
+                const span = sameDay ? `${formatTimeOfDay(timeline.start)}–${formatTimeOfDay(end)}` : `${formatClock(timeline.start)}–${formatClock(end)}`;
+                out.push(`Timeline: ${span}, the part of the window with activity`);
+            }
+        }
+        const axis = timeline === undefined ? ' '.repeat(cells) : axisLine(timeline, cells);
+        out.push(theme.fg('dim', `  ${padRight('Agent', agentW)}${narrow ? '' : ` ${axis}`}${padLeft('created→final', finalW)}${padLeft('est.', estW)}`));
+        const legend = timeline === undefined ? [] : ['', theme.fg('dim', `█ ${slotLabel(timeline.slotMs / MINUTE)} slot with a model response   ─ alive, no response   ◆ final report`)];
+        const selected = this.rows[this.cursor];
+        const full = fullNameLine(rowLabel(selected), agentW);
+        const note = this.unlisted !== undefined ? theme.fg('dim', `  ${this.unlisted.kind} ${this.unlisted.name} had no model response, spawn, or final report in this window, so it has no row here.`) : undefined;
+        const reserved = legend.length + (full !== undefined ? 1 : 0) + (note !== undefined ? 1 : 0);
+        const range = listWindow(this.rows.length, this.cursor, Math.max(1, height - out.length - reserved));
+        for (let i = range.start; i < range.end; i += 1) {
+            const row = this.rows[i];
+            const agent = row.agent;
+            const label = padRight(rowLabel(row), agentW);
+            const line = narrow ? '' : ` ${timeline === undefined ? ' '.repeat(cells) : timelineCells(agent, timeline, cells)}`;
+            const est = agent.active ? formatPrice(agent.api_price_estimate) : '—';
+            out.push(markRow(`${label}${line}${padLeft(createdToFinal(agent), finalW)}${padLeft(est, estW)}`, i === this.cursor));
+        }
+        if (range.more > 0) {
+            const hidden = this.rows.slice(range.end).reduce((sum, r) => sum + r.agent.api_price_estimate, 0);
+            const more = `  ${plural(range.more, 'more agent', 'more agents')} ↓`;
+            out.push(`${padRight(more, width - estW)}${padLeft(formatPrice(hidden), estW)}`);
+        }
+        if (full !== undefined)
+            out.push(full);
+        if (note !== undefined)
+            out.push(note);
+        out.push(...legend);
+        return out;
+    }
+    reportBody(width, height, report) {
+        const title = theme.bold(`Final report · ${report.name}`);
+        if (report.error !== undefined)
+            return [title, '', ...wrapText(`Could not read the final report: ${report.error}`, width)];
+        if (report.text === undefined)
+            return [title, '', 'Loading the final report…'];
+        const lines = report.text.split('\n').flatMap((line) => (line.trim() === '' ? [''] : wrapText(line, width)));
+        const room = Math.max(1, height - 2);
+        report.scroll = Math.min(report.scroll, Math.max(0, lines.length - room));
+        const shown = lines.slice(report.scroll, report.scroll + room);
+        const below = lines.length - report.scroll - shown.length;
+        const position = below > 0 ? theme.fg('dim', ` · ${below} more lines ↓`) : '';
+        return [`${title}${position}`, '', ...shown];
+    }
+}
+export const createGraphDetailView = (ctx, graphId, selectAgentId) => new GraphDetailView(ctx, graphId, selectAgentId);

package/dist/commands/canvas-analytics/graphs.d.ts

@@ -0,0 +1,9 @@
+import type { GraphRowDTO } from '../../api/dto/analytics.js';
+import { type AnalyticsViewFactory } from './view.js';
+/** A graph's name as its rows show it: "(root deleted)" when the root's parent row is gone. */
+export declare function graphLabel(graph: GraphRowDTO): string;
+/** Graphs by API-price estimate, largest first; ties by name so the order is stable. */
+export declare function byEstimate(a: GraphRowDTO, b: GraphRowDTO): number;
+/** The line under a list that shows the selected row's whole name, when its row cut it. */
+export declare function fullNameLine(label: string, shownWidth: number): string | undefined;
+export declare const createGraphsView: AnalyticsViewFactory;