@north-light/api 0.3.580 → 0.3.588

package/dist/commands/canvas-analytics/overview.js

@@ -0,0 +1,189 @@
+// The Overview tab: how did my agents work in this window?
+//
+// Five headline numbers (←→), each opening the tab and cursor position the
+// spec's headline table names, and the top graphs by API-price estimate (↓).
+// `Enter` on a graph opens its detail; the last row, "<n> more graphs ↓",
+// opens the Graphs tab list sorted by API-price estimate.
+import { matchesKey, visibleWidth } from '@earendil-works/pi-tui';
+import { theme, wrapText } from '../../core/tui/panel.js';
+import { hbar } from './chart.js';
+import { formatCount, formatDuration, formatPrice, formatTokens, padLeft, padRight, unavailable } from './format.js';
+import { byEstimate, fullNameLine, graphLabel } from './graphs.js';
+import { NARROW_BAR_CELLS, isNarrow, markRow, moreRow, textWidth, } from './view.js';
+/** Top graphs shown at most in the narrow layout; the wide layout shows as
+ *  many as its height allows. */
+const TOP_GRAPHS = 10;
+function measured(measure, value) {
+    return measure.ok ? value(measure.value) : 'unavailable';
+}
+function headlines(data) {
+    return [
+        { label: 'GRAPHS', short: 'GRAPHS', value: measured(data.graphs, (g) => formatCount(g.count)), landing: { tab: 'graphs', at: 'size-chart' } },
+        { label: 'AGENTS SPAWNED', short: 'SPAWNED', value: measured(data.graphs, (g) => formatCount(g.spawned)), landing: { tab: 'graphs', at: 'kind-chart' } },
+        {
+            label: 'MEDIAN AGENT TIME',
+            short: 'MEDIAN TIME',
+            value: measured(data.time, (t) => (t.all === null ? 'none finished' : formatDuration(t.all.median_ms))),
+            landing: { tab: 'time', at: 'all-agents' },
+        },
+        { label: 'API-PRICE EST.', short: 'API-PRICE EST.', value: measured(data.usage, (u) => formatPrice(u.api_price_estimate)), landing: { tab: 'usage', at: 'top-model' } },
+        { label: 'MEMORY READS', short: 'MEMORY READS', value: measured(data.memory, (m) => formatCount(m.read.entries)), landing: { tab: 'memory', at: 'top-read-document' } },
+    ];
+}
+/** Each distinct failure reason once: the transcript scan fails several measures at once. */
+function failures(data) {
+    const reasons = [data.graphs, data.time, data.usage, data.memory].flatMap((m) => (m.ok ? [] : [m.reason]));
+    return [...new Set(reasons)];
+}
+class OverviewView {
+    ctx;
+    zone = 'headline';
+    headline = 0;
+    /** Index into the top graphs; `top.length` is the "<n> more graphs" row. */
+    row = 0;
+    /** How many graphs the last render showed, so keys move over what is on screen. */
+    shown = 0;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    ranked() {
+        const graphs = this.ctx.data.graphs;
+        return graphs.ok ? [...graphs.value.graphs].sort(byEstimate) : [];
+    }
+    /** List rows the cursor can visit: the shown graphs plus the "more" row when any are hidden. */
+    rowCount() {
+        const total = this.ranked().length;
+        return this.shown + (total > this.shown ? 1 : 0);
+    }
+    handleKey(key) {
+        if (matchesKey(key, 'escape'))
+            return 'back';
+        if (matchesKey(key, 'left') || matchesKey(key, 'h')) {
+            if (this.zone === 'headline')
+                this.headline = Math.max(0, this.headline - 1);
+            return 'handled';
+        }
+        if (matchesKey(key, 'right') || matchesKey(key, 'l')) {
+            if (this.zone === 'headline')
+                this.headline = Math.min(4, this.headline + 1);
+            return 'handled';
+        }
+        if (matchesKey(key, 'down') || matchesKey(key, 'j')) {
+            if (this.zone === 'headline') {
+                if (this.rowCount() > 0) {
+                    this.zone = 'list';
+                    this.row = 0;
+                }
+            }
+            else
+                this.row = Math.min(this.rowCount() - 1, this.row + 1);
+            return 'handled';
+        }
+        if (matchesKey(key, 'up') || matchesKey(key, 'k')) {
+            if (this.zone === 'list') {
+                if (this.row === 0)
+                    this.zone = 'headline';
+                else
+                    this.row -= 1;
+            }
+            return 'handled';
+        }
+        if (matchesKey(key, 'enter')) {
+            if (this.zone === 'headline') {
+                this.ctx.nav.openTab(headlines(this.ctx.data)[this.headline].landing);
+                return 'handled';
+            }
+            const graph = this.row < this.shown ? this.ranked()[this.row] : undefined;
+            if (graph !== undefined)
+                this.ctx.nav.openGraphDetail(graph.graph_id);
+            else
+                this.ctx.nav.openTab({ tab: 'graphs', at: 'list-by-estimate' });
+            return 'handled';
+        }
+        return 'unhandled';
+    }
+    keyLine(narrow) {
+        return narrow ? '←→↑↓ · Enter' : '←→↑↓ select · Enter open';
+    }
+    render(width, height, data) {
+        const narrow = isNarrow(width);
+        const out = narrow ? this.narrowHeadlines(width, data) : this.wideHeadlines(width, data);
+        for (const reason of failures(data))
+            out.push(...wrapText(unavailable(reason), width).map((line) => theme.fg('warning', line)));
+        out.push('');
+        out.push(...this.topGraphs(width, Math.max(3, height - out.length), data, narrow));
+        return out;
+    }
+    mark(i) {
+        const selected = this.zone === 'headline' && this.headline === i;
+        return { selected, prefix: selected ? '> ' : '  ' };
+    }
+    wideHeadlines(width, data) {
+        const column = Math.floor(width / 5);
+        let labels = '';
+        let values = '';
+        headlines(data).forEach((h, i) => {
+            const { selected, prefix } = this.mark(i);
+            const label = padRight(`${prefix}${h.label}`, column);
+            labels += selected ? theme.bold(label) : theme.fg('dim', label);
+            const value = padRight(`  ${h.value}`, column);
+            values += selected ? theme.bold(value) : value;
+        });
+        return [labels, values];
+    }
+    narrowHeadlines(width, data) {
+        const cells = headlines(data).map((h, i) => {
+            const { selected, prefix } = this.mark(i);
+            const text = `${prefix}${h.short} ${h.value}`;
+            return selected ? theme.bold(text) : text;
+        });
+        return [cells.slice(0, 3).join('  '), cells.slice(3).join('  ')].map((line) => padRight(line, width));
+    }
+    topGraphs(width, height, data, narrow) {
+        const [agentsW, estW, tokensW] = narrow ? [7, 9, 7] : [7, 9, 8];
+        const ranked = data.graphs.ok ? this.ranked() : [];
+        let barCells;
+        let nameWidth;
+        if (narrow) {
+            barCells = NARROW_BAR_CELLS;
+            nameWidth = Math.max(8, width - 2 - agentsW - 1 - barCells - estW - tokensW - 1);
+        }
+        else {
+            const free = width - 2 - agentsW - 1 - estW - tokensW - 3;
+            const natural = Math.max(0, ...ranked.map((g) => visibleWidth(graphLabel(g))));
+            nameWidth = textWidth(free, natural, 30);
+            barCells = Math.max(10, free - nameWidth);
+        }
+        const title = narrow ? 'Top graphs, API est.' : 'Top graphs, by API-price estimate';
+        const head = `${padRight(title, 2 + nameWidth)}${padLeft('agents', agentsW)} ${' '.repeat(barCells)}${padLeft('est.', estW)}${padLeft('tokens', tokensW)}`;
+        if (!data.graphs.ok)
+            return [head, `  ${unavailable(data.graphs.reason)}`];
+        if (ranked.length === 0) {
+            this.shown = 0;
+            return [head, '  None in this window.'];
+        }
+        // One row each for the header, a possible "more" row, and a possible full-name line.
+        const room = Math.max(1, height - 3);
+        this.shown = Math.min(narrow ? TOP_GRAPHS : ranked.length, ranked.length, room);
+        if (this.zone === 'list')
+            this.row = Math.min(this.row, this.rowCount() - 1);
+        const max = ranked[0].api_price_estimate;
+        const out = [theme.fg('dim', head)];
+        for (let i = 0; i < this.shown; i += 1) {
+            const g = ranked[i];
+            const text = `${padRight(graphLabel(g), nameWidth)}${padLeft(formatCount(g.active_agents), agentsW)} ${hbar(g.api_price_estimate, max, barCells)}${padLeft(formatPrice(g.api_price_estimate), estW)}${padLeft(formatTokens(g.tokens), tokensW)}`;
+            out.push(markRow(text, this.zone === 'list' && this.row === i));
+        }
+        const hidden = ranked.length - this.shown;
+        if (hidden > 0) {
+            const more = moreRow(hidden, 'graphs').slice(2);
+            out.push(markRow(more, this.zone === 'list' && this.row === this.shown));
+        }
+        const selected = this.zone === 'list' ? ranked[this.row] : undefined;
+        const full = selected !== undefined && this.row < this.shown ? fullNameLine(graphLabel(selected), nameWidth) : undefined;
+        if (full !== undefined)
+            out.push(full);
+        return out;
+    }
+}
+export const createOverviewView = (ctx) => new OverviewView(ctx);

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

@@ -0,0 +1,60 @@
+import { type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { type TuiPageControl } from '../../core/tui/page-host.js';
+type PageResult = {
+    open: string;
+};
+export declare class AnalyticsShell implements Component, Focusable {
+    private readonly tui;
+    private readonly rows;
+    private readonly suspendForChild;
+    private readonly control;
+    focused: boolean;
+    private readonly client;
+    private asOf;
+    private window;
+    private project;
+    private tab;
+    /** Detail views opened over the current tab, innermost last. */
+    private stack;
+    private load;
+    private overlay;
+    /** Identifies the newest request; an answer carrying an older number is dropped. */
+    private seq;
+    /** Picker choices from the newest successful answer. */
+    private projects;
+    constructor(tui: TUI, rows: () => number, suspendForChild: () => () => void, control: TuiPageControl<PageResult>);
+    /** Issue a request for the current T, window, and scope. */
+    request(): void;
+    private ready;
+    private nav;
+    /** Nothing is cached: every render draws from state. */
+    invalidate(): void;
+    dispose(): void;
+    private get shownTab();
+    private get topView();
+    handleInput(data: string): void;
+    private handleKey;
+    private cycleTab;
+    private pickerKey;
+    private sourcesKey;
+    render(width: number): string[];
+    private renderPage;
+    private fit;
+    private scopeLabel;
+    private controlsRow;
+    private tabRow;
+    private coverageLine;
+    private keyParts;
+    /** The longest spelling that fits: wide keys with the wide tail, then with the
+     *  short tail, then the narrow keys. */
+    private keyLine;
+    private body;
+    private pickerBody;
+    private sourcesBody;
+    /** The transcript scan's failure reason, which every scan-based measure carries. */
+    private scanFailure;
+}
+/** `pane` is the tmux pane the page was opened from (the prefix menu passes it);
+ *  without it, `o` opens beside this process's own pane. */
+export declare function runAnalytics(pane: string | undefined): Promise<void>;
+export {};

package/dist/commands/canvas-analytics/shell.js

@@ -0,0 +1,416 @@
+// The `crtr canvas analytics` page: the frame every tab shares.
+//
+// This file owns the fixed as-of time T, the window, the scope, the one /v1
+// read that fills the page, and every state around the tab views — Loading,
+// Empty, Error, the Sources panel, the project picker, the minimum-size
+// message. Tab content is built by the view modules against view.ts; the
+// navigation API they call is documented there.
+//
+// Numbers change only on R (new T), w (window), or p (scope): each builds a new
+// request, and only the newest request's answer is shown. The page talks to
+// crtrd only through `localClient({ autostart: false })`, so it never opens a
+// database or transcript and never starts a daemon (which would resume brokers).
+import { spawnSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { localClient } from '../../api/node-transport.js';
+import { runShellInBackground } from '../../core/runtime/placement-tmux.js';
+import { runTuiPage } from '../../core/tui/page-host.js';
+import { rule, theme, wrapText } from '../../core/tui/panel.js';
+import { shellQuote } from '../../shared/shell-quote.js';
+import { ExitCode } from '../../types.js';
+import { formatClock, formatCount, formatDateTime, formatPrice, formatTimezone, padRight, unavailable } from './format.js';
+import { createGraphDetailView } from './graph-detail.js';
+import { createGraphsView } from './graphs.js';
+import { createMemoryView } from './memory.js';
+import { createOverviewView } from './overview.js';
+import { createTimeView } from './time.js';
+import { createUsageView } from './usage.js';
+import { MAX_PAGE_WIDTH, TABS, isNarrow, listWindow, moreRow, } from './view.js';
+const MIN_WIDTH = 50;
+const MIN_HEIGHT = 20;
+const HOUR_MS = 3_600_000;
+const WINDOW_MS = { '24h': 24 * HOUR_MS, '7d': 168 * HOUR_MS };
+const WINDOW_LABEL = { '24h': 'Last 24h', '7d': 'Last 7d' };
+const SOURCES_LABEL_WIDTH = 16;
+/** "Nothing eligible" is only claimed when every source answered. */
+function isEmpty(data) {
+    return (data.graphs.ok &&
+        data.memory.ok &&
+        data.agents.length === 0 &&
+        data.memory.value.read.entries === 0 &&
+        data.memory.value.loaded.entries === 0);
+}
+function errorReason(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.trim().replace(/\.$/, '') || 'unknown error';
+}
+export class AnalyticsShell {
+    tui;
+    rows;
+    suspendForChild;
+    control;
+    focused = false;
+    client = localClient({ autostart: false });
+    asOf = new Date();
+    window = '24h';
+    project = null;
+    tab = 'overview';
+    /** Detail views opened over the current tab, innermost last. */
+    stack = [];
+    load = { kind: 'loading' };
+    overlay;
+    /** Identifies the newest request; an answer carrying an older number is dropped. */
+    seq = 0;
+    /** Picker choices from the newest successful answer. */
+    projects = [];
+    constructor(tui, rows, suspendForChild, control) {
+        this.tui = tui;
+        this.rows = rows;
+        this.suspendForChild = suspendForChild;
+        this.control = control;
+    }
+    /** Issue a request for the current T, window, and scope. */
+    request() {
+        const seq = ++this.seq;
+        this.load = { kind: 'loading' };
+        this.stack = [];
+        const query = {
+            as_of: this.asOf.toISOString(),
+            window: this.window,
+            ...(this.project !== null ? { project: this.project } : {}),
+        };
+        this.client.analytics(query).then((data) => {
+            if (seq !== this.seq)
+                return;
+            this.projects = data.projects;
+            this.load = this.ready(data);
+            this.tui.requestRender();
+        }, (error) => {
+            if (seq !== this.seq)
+                return;
+            this.load = { kind: 'error', reason: errorReason(error) };
+            this.tui.requestRender();
+        });
+        this.tui.requestRender();
+    }
+    ready(data) {
+        const ctx = { data, nav: this.nav() };
+        return {
+            kind: 'ready',
+            data,
+            ctx,
+            views: {
+                overview: createOverviewView(ctx),
+                graphs: createGraphsView(ctx),
+                time: createTimeView(ctx),
+                memory: createMemoryView(ctx),
+                usage: createUsageView(ctx),
+            },
+        };
+    }
+    nav() {
+        return {
+            openTab: (landing) => {
+                if (this.load.kind !== 'ready')
+                    return;
+                this.stack = [];
+                this.tab = landing.tab;
+                this.load.views[landing.tab].land?.(landing);
+                this.tui.requestRender();
+            },
+            openGraphDetail: (graphId, selectAgentId) => {
+                if (this.load.kind !== 'ready')
+                    return;
+                this.stack.push({ view: createGraphDetailView(this.load.ctx, graphId, selectAgentId), tab: 'graphs' });
+                this.tui.requestRender();
+            },
+            openInspector: (nodeId) => {
+                const resume = this.suspendForChild();
+                try {
+                    spawnSync('crtr', ['surface', 'inspect', nodeId, '--read-only'], { stdio: 'inherit' });
+                }
+                finally {
+                    resume();
+                }
+            },
+            openConversation: (nodeId) => this.control.submit({ open: nodeId }),
+            readFinalReport: async (ref) => (await this.client.historyRead({ ref })).content,
+            requestRender: () => this.tui.requestRender(),
+        };
+    }
+    /** Nothing is cached: every render draws from state. */
+    invalidate() { }
+    dispose() {
+        // Drop any answer still in flight.
+        this.seq += 1;
+    }
+    // input
+    get shownTab() {
+        return this.stack.at(-1)?.tab ?? this.tab;
+    }
+    get topView() {
+        if (this.load.kind !== 'ready' || isEmpty(this.load.data))
+            return undefined;
+        return this.stack.at(-1)?.view ?? this.load.views[this.tab];
+    }
+    handleInput(data) {
+        this.handleKey(data);
+        this.tui.requestRender();
+    }
+    handleKey(data) {
+        if (matchesKey(data, 'ctrl+c') || matchesKey(data, 'q'))
+            return this.control.cancel();
+        if (this.rows() < MIN_HEIGHT || this.tui.terminal.columns < MIN_WIDTH) {
+            if (matchesKey(data, 'escape'))
+                this.control.cancel();
+            return;
+        }
+        if (this.overlay?.kind === 'picker')
+            return this.pickerKey(data, this.overlay);
+        if (this.overlay?.kind === 'sources')
+            return this.sourcesKey(data, this.overlay);
+        if (matchesKey(data, 'shift+tab'))
+            return this.cycleTab(-1);
+        if (matchesKey(data, 'tab'))
+            return this.cycleTab(1);
+        if (matchesKey(data, 'w')) {
+            this.window = this.window === '24h' ? '7d' : '24h';
+            return this.request();
+        }
+        if (matchesKey(data, 'shift+r')) {
+            this.asOf = new Date();
+            return this.request();
+        }
+        if (matchesKey(data, 'p')) {
+            const at = this.projects.findIndex((p) => p.cwd === this.project);
+            this.overlay = { kind: 'picker', cursor: at + 1 };
+            return;
+        }
+        if (matchesKey(data, 's')) {
+            this.overlay = { kind: 'sources', scroll: 0 };
+            return;
+        }
+        const view = this.topView;
+        const outcome = view === undefined ? 'unhandled' : view.handleKey(data);
+        if (outcome === 'back' || (outcome === 'unhandled' && matchesKey(data, 'escape'))) {
+            if (this.stack.length > 0)
+                this.stack.pop();
+            else
+                this.control.cancel();
+        }
+    }
+    cycleTab(step) {
+        const at = TABS.findIndex((t) => t.id === this.shownTab);
+        this.tab = TABS[(at + step + TABS.length) % TABS.length].id;
+        this.stack = [];
+    }
+    pickerKey(data, picker) {
+        const count = this.projects.length + 1;
+        if (matchesKey(data, 'escape') || matchesKey(data, 'p'))
+            this.overlay = undefined;
+        else if (matchesKey(data, 'down') || matchesKey(data, 'j'))
+            picker.cursor = Math.min(count - 1, picker.cursor + 1);
+        else if (matchesKey(data, 'up') || matchesKey(data, 'k'))
+            picker.cursor = Math.max(0, picker.cursor - 1);
+        else if (matchesKey(data, 'enter')) {
+            this.overlay = undefined;
+            const chosen = picker.cursor === 0 ? null : this.projects[picker.cursor - 1].cwd;
+            if (chosen !== this.project) {
+                this.project = chosen;
+                this.request();
+            }
+        }
+    }
+    sourcesKey(data, sources) {
+        if (matchesKey(data, 'escape') || matchesKey(data, 's'))
+            this.overlay = undefined;
+        else if (matchesKey(data, 'down') || matchesKey(data, 'j'))
+            sources.scroll += 1;
+        else if (matchesKey(data, 'up') || matchesKey(data, 'k'))
+            sources.scroll = Math.max(0, sources.scroll - 1);
+    }
+    // rendering
+    render(width) {
+        const height = this.rows();
+        if (width < MIN_WIDTH || height < MIN_HEIGHT) {
+            const lines = wrapText(`Analytics needs at least ${MIN_WIDTH} × ${MIN_HEIGHT}; this window is ${width} × ${height}.`, width);
+            return this.fit(lines, height, width);
+        }
+        // Past MAX_PAGE_WIDTH the whole page, frame included, is drawn at that
+        // width and centered, so nothing is stranded at a far edge.
+        const page = Math.min(width, MAX_PAGE_WIDTH);
+        if (page === width)
+            return this.renderPage(width, height);
+        const indent = ' '.repeat(Math.floor((width - page) / 2));
+        return this.renderPage(page, height).map((line) => (line === '' ? '' : `${indent}${line}`));
+    }
+    renderPage(width, height) {
+        const narrow = isNarrow(width);
+        const top = [this.controlsRow(width, narrow), this.tabRow(narrow), rule(width)];
+        const coverage = this.coverageLine();
+        const bottom = [...(coverage !== undefined ? [coverage] : []), rule(width), this.keyLine(width, narrow)];
+        const bodyHeight = Math.max(1, height - top.length - bottom.length);
+        return this.fit([...top, ...this.fit(this.body(width, bodyHeight), bodyHeight, width), ...bottom], height, width);
+    }
+    fit(lines, height, width) {
+        const out = lines.slice(0, height).map((line) => truncateToWidth(line, width, '…'));
+        while (out.length < height)
+            out.push('');
+        return out;
+    }
+    scopeLabel() {
+        return this.project === null ? 'All projects' : basename(this.project) || this.project;
+    }
+    controlsRow(width, narrow) {
+        const scope = `${this.scopeLabel()} ▾`;
+        const asOf = `as of ${formatClock(this.asOf)}`;
+        const is24 = this.window === '24h';
+        const left = narrow
+            ? `${is24 ? '[24h] 7d' : '24h [7d]'} · ${scope}`
+            : `${padRight(scope, 34)}${is24 ? '[ Last 24h ]   Last 7d  ' : '  Last 24h   [ Last 7d ]'}`;
+        const gap = width - visibleWidth(left) - visibleWidth(asOf) - (narrow ? 0 : 3);
+        return gap >= 2 ? `${left}${' '.repeat(gap)}${theme.fg('dim', asOf)}` : `${left}  ${theme.fg('dim', asOf)}`;
+    }
+    tabRow(narrow) {
+        const shown = this.shownTab;
+        return TABS.map(({ id, label }) => {
+            const text = id === shown ? `[${label}]` : narrow ? label : ` ${label}`;
+            const cell = narrow ? text : padRight(text, 12);
+            return id === shown ? theme.fg('accent', theme.bold(cell)) : cell;
+        }).join(narrow ? ' ' : '');
+    }
+    coverageLine() {
+        if (this.load.kind !== 'ready')
+            return undefined;
+        const transcripts = this.load.data.transcripts;
+        if (transcripts === null || transcripts.unreadable.length === 0)
+            return undefined;
+        return theme.fg('warning', `Sources: ${formatCount(transcripts.unreadable.length)} of ${formatCount(transcripts.total)} transcripts unreadable (s)`);
+    }
+    keyParts(narrow) {
+        if (this.overlay?.kind === 'picker')
+            return [narrow ? '↑↓ Enter' : '↑↓ project · Enter choose', narrow ? 'Esc' : 'Esc close picker'];
+        if (this.overlay?.kind === 'sources')
+            return [narrow ? '↑↓' : '↑↓ scroll', narrow ? 'Esc' : 'Esc close sources'];
+        const view = this.topView;
+        const own = view?.keyLine(narrow) ?? '';
+        const escape = view?.escapeLabel?.() ?? (this.stack.length > 0 ? 'back' : 'close');
+        return [...(own !== '' ? [own] : []), narrow ? 'Esc' : `Esc ${escape}`];
+    }
+    /** The longest spelling that fits: wide keys with the wide tail, then with the
+     *  short tail, then the narrow keys. */
+    keyLine(width, narrow) {
+        const wide = 'Tab tab · w 24h/7d · p project · R refresh · s sources · q close';
+        const short = 'Tab w p R s q';
+        const shortest = [...this.keyParts(true), short].join(' · ');
+        const candidates = narrow ? [] : [[...this.keyParts(false), wide].join(' · '), [...this.keyParts(false), short].join(' · ')];
+        const line = candidates.find((text) => visibleWidth(text) <= width) ?? shortest;
+        return theme.fg('dim', line);
+    }
+    body(width, height) {
+        if (this.overlay?.kind === 'sources')
+            return this.sourcesBody(width, height, this.overlay);
+        if (this.overlay?.kind === 'picker')
+            return this.pickerBody(height, this.overlay);
+        switch (this.load.kind) {
+            case 'loading':
+                return ['Computing…'];
+            case 'error':
+                return wrapText(`Could not load analytics: ${this.load.reason}. R retries.`, width);
+            case 'ready': {
+                if (isEmpty(this.load.data))
+                    return [`No recorded activity in ${this.scopeLabel()}, ${WINDOW_LABEL[this.window]}.`];
+                return this.topView.render(width, height, this.load.data);
+            }
+        }
+    }
+    pickerBody(height, picker) {
+        const rows = [
+            { label: 'All projects', detail: '', path: '' },
+            ...this.projects.map((p) => ({ label: basename(p.cwd) || p.cwd, detail: formatPrice(p.api_price_estimate), path: p.cwd })),
+        ];
+        const head = [theme.bold('Project'), theme.fg('dim', 'Projects with at least one active agent in the window, by API-price estimate.'), ''];
+        const range = listWindow(rows.length, picker.cursor, Math.max(1, height - head.length));
+        const out = [...head];
+        for (let i = range.start; i < range.end; i += 1) {
+            const row = rows[i];
+            const selected = i === picker.cursor;
+            const current = (i === 0 ? null : row.path) === this.project ? ' (current)' : '';
+            const text = `${padRight(row.label, 32)} ${row.detail.padStart(6)}${current}${selected && row.path !== '' ? `  ${row.path}` : ''}`;
+            out.push(selected ? theme.bold(`> ${text}`) : `  ${text}`);
+        }
+        if (range.more > 0)
+            out.push(moreRow(range.more, 'projects'));
+        return out;
+    }
+    sourcesBody(width, height, sources) {
+        const load = this.load;
+        const data = load.kind === 'ready' ? load.data : undefined;
+        const missing = load.kind === 'loading' ? 'Computing…' : 'Could not load analytics.';
+        const start = data !== undefined ? new Date(data.window_start) : new Date(this.asOf.getTime() - WINDOW_MS[this.window]);
+        const entries = [
+            ['Window', `${WINDOW_LABEL[this.window]}, rolling: ${formatDateTime(start)} → ${formatDateTime(this.asOf)} ${formatTimezone(this.asOf)}, frozen until R.`],
+            ['Scope', this.project === null ? 'All projects.' : this.project],
+            ['Graph', 'A root agent and every agent whose parent chain leads to it. Every agent is in exactly one graph, so graph rows add up to page totals. An agent whose parent was deleted joins the graph of its topmost surviving ancestor, marked (root deleted).'],
+            ['Graph view', 'The canvas graph view follows report subscriptions and can group agents differently.'],
+            ['Active', 'An agent with at least one model response inside the window.'],
+            ['Spawned', 'A non-root agent created inside the window.'],
+            ['Finished', 'An agent whose final report landed inside the window. Its agent time is created → final report, full length, not clipped to the window.'],
+            ['Model response', 'An assistant message in any transcript bound to the agent whose stop reason is not error, at its recorded time. Responses copied into a forked agent count once, for the agent that produced them; one provider response id counts once.'],
+            ['Model', 'The provider and model recorded on each response, not the current setting.'],
+            ['Tokens', 'Per response: input + output + cache read + cache write.'],
+            ['Context size', 'Per response: input + cache read + cache write.'],
+            ['API-price est.', 'The price pi recorded for each response at published API rates when it was made; never recomputed. It is not what your subscriptions charged.'],
+            ['Transcripts', data === undefined ? missing : data.transcripts === null ? unavailable(this.scanFailure(data)) : `${formatCount(data.transcripts.read)} of ${formatCount(data.transcripts.total)} transcripts read.`],
+            ['Unknown', data === undefined ? missing : data.unknown_responses === null ? unavailable(this.scanFailure(data)) : `${formatCount(data.unknown_responses)} responses with no model or usage recorded.`],
+            ['Memory reads', `Read on purpose: an agent ran crtr canvas read and got the document back. Loaded automatically: a document's full body entered an agent's context another way — at launch, by a delivery rule, as a companion of a read, or by a document slash command. ${data === undefined ? missing : data.memory_log_started_at === null ? 'No recording start time is stored.' : `Recorded since ${formatDateTime(data.memory_log_started_at)}.`} Reads made while crtrd was unreachable are not recorded.`],
+            ['Time split', 'Running and waiting time are not recorded.'],
+            ['History', `${data === undefined ? missing : data.oldest_agent_created === null ? 'No surviving agents.' : `Oldest surviving agent created ${formatDateTime(data.oldest_agent_created)}.`} Deleted agents and their transcripts are not counted.`],
+        ];
+        const valueWidth = Math.max(10, width - SOURCES_LABEL_WIDTH - 2);
+        const lines = [theme.bold(`Sources · ${WINDOW_LABEL[this.window]} · ${this.scopeLabel()}`), ''];
+        for (const [label, value] of entries) {
+            wrapText(value, valueWidth).forEach((line, i) => {
+                lines.push(`${padRight(i === 0 ? label : '', SOURCES_LABEL_WIDTH)}  ${line}`);
+            });
+        }
+        const unreadable = data?.transcripts?.unreadable ?? [];
+        if (unreadable.length > 0) {
+            lines.push('', 'Unreadable transcripts:');
+            for (const item of unreadable)
+                lines.push(`  ${item.node_id} (${item.reason})`);
+        }
+        const maxScroll = Math.max(0, lines.length - height);
+        sources.scroll = Math.min(sources.scroll, maxScroll);
+        return lines.slice(sources.scroll, sources.scroll + height);
+    }
+    /** The transcript scan's failure reason, which every scan-based measure carries. */
+    scanFailure(data) {
+        return data.graphs.ok ? 'the transcript scan failed' : data.graphs.reason;
+    }
+}
+/** `pane` is the tmux pane the page was opened from (the prefix menu passes it);
+ *  without it, `o` opens beside this process's own pane. */
+export async function runAnalytics(pane) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        process.stderr.write('crtr canvas analytics needs an interactive terminal; open it from the prefix menu (shift+a) or run it in a terminal.\n');
+        process.exitCode = ExitCode.GENERAL;
+        return;
+    }
+    const result = await runTuiPage(({ tui, terminal, suspendForChild }, control) => {
+        const shell = new AnalyticsShell(tui, () => terminal.rows, suspendForChild, control);
+        shell.request();
+        return shell;
+    });
+    if (result !== undefined) {
+        // As the canvas navigator opens a node (core/canvas/browse/app.ts): from the
+        // tmux server, after this popup has closed. Focus of finished work opens a
+        // saved-transcript popup, which tmux refuses while this popup is still open.
+        const origin = pane ?? process.env['TMUX_PANE'];
+        const target = origin !== undefined && origin !== '' ? ` --pane ${shellQuote(origin)}` : '';
+        runShellInBackground(`crtr surface node focus ${shellQuote(result.open)}${target} >/dev/null 2>&1`);
+    }
+    // A superseded request may still be in flight; it must not hold the process open.
+    process.exit(0);
+}

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

@@ -0,0 +1,2 @@
+import { type AnalyticsViewFactory } from './view.js';
+export declare const createTimeView: AnalyticsViewFactory;