@north-light/api 0.3.580 → 0.3.588

package/dist/clients/attach/render/group-activity.d.ts

@@ -0,0 +1,84 @@
+import type { CardPresentation } from './card-presentation.js';
+import { type GeneratedCard } from '../../../shared/generated-context.js';
+export type FileActivity = {
+    key: string;
+    displayPath: string;
+    kind: 'edit' | 'write';
+    added: number;
+    removed: number;
+    hasKnownCounts: boolean;
+    countsIncomplete: boolean;
+};
+/** One canvas document this group read, wrote, edited or deleted, by its full
+ * name (`<owner-handle>/<name>`). Documents are canvas rows, not files, so the
+ * chip carries no path to hyperlink. */
+export type DocumentActivity = {
+    action: 'read' | 'write' | 'edit' | 'delete';
+    name: string;
+};
+/** One node this group started or saw finish. `name` is the spawn's display
+ * name, or the node id when the finish has no matching spawn in this session. */
+export type NodeActivity = {
+    action: 'spawned' | 'finished';
+    name: string;
+    id: string;
+};
+/** A card whose fold-time contribution is structured: its own summary line. */
+export type CardActivity = {
+    summary: string;
+};
+/** A card that folds to one terse line. Repeats compress into `count` so a run
+ * of recoveries costs one row, not one row each. */
+export type EventActivity = {
+    text: string;
+    count: number;
+};
+export type GroupActivity = {
+    files: readonly FileActivity[];
+    documents: readonly DocumentActivity[];
+    nodes: readonly NodeActivity[];
+    cards: readonly CardActivity[];
+    events: readonly EventActivity[];
+    /** Distinct events past the budget, so the recap can say what it dropped. */
+    eventsOmitted: number;
+};
+/** Per-group recorder. Calls retain only their current transcript references
+ * until they settle; the settled activity is plain immutable evidence. */
+export declare class GroupActivityRecorder {
+    private readonly cwd;
+    private readonly roster;
+    private readonly calls;
+    private readonly files;
+    private readonly documents;
+    private readonly documentSet;
+    private readonly nodes;
+    private readonly nodeSet;
+    private readonly cards;
+    private readonly cardSet;
+    private readonly events;
+    private eventsOmitted;
+    /** `roster` is the ChatView-wide node id → display name record: spawns fill
+     * it, and a later group's finish reads the name a sibling group recorded. */
+    constructor(cwd: string, roster?: Map<string, string>);
+    /** What one runtime card leaves behind when its group folds, decided entirely
+     * by the card's presentation policy. */
+    noteCard(card: GeneratedCard, presentation: CardPresentation): void;
+    noteCall(id: string, name: string, args: unknown): void;
+    settle(id: string, result: unknown, isError: boolean): void;
+    resolveWithoutResult(id: string): void;
+    activity(): GroupActivity;
+    /** The nodes an inbox digest reports finished. The spawn roster supplies the
+     * display name when it has one. A sender carrying only the person's own words
+     * is the human speaking, not a node that finished. */
+    private addFinishedSenders;
+    private addCard;
+    private addEvent;
+    private addNode;
+    /** The recorded leaf path is authoritative: which command ran and what it
+     * returned are both facts here, so a read can never be logged as a save and
+     * an inserted output field can never break a chip. A record carrying an
+     * `error` is a failed call, which is not activity. */
+    private noteCrtrInvocation;
+    private addDocument;
+    private extract;
+}

package/dist/clients/attach/render/group-activity.js

@@ -0,0 +1,276 @@
+// Deterministic, transcript-derived activity evidence for one folded tool group.
+// This deliberately knows no rendering or broker state: it reduces completed
+// calls into the exact evidence already present in the session transcript.
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isHumanWordsEntry } from '../../../shared/generated-context.js';
+import { crtrPreviewRecords } from '../../../core/preview-registry.js';
+import { countDisplayDiffLines } from './edit-diff.js';
+/** Distinct event lines one recap will show before it starts counting. */
+const MAX_RECAP_EVENTS = 3;
+const EMPTY_ACTIVITY = Object.freeze({
+    files: Object.freeze([]),
+    documents: Object.freeze([]),
+    nodes: Object.freeze([]),
+    cards: Object.freeze([]),
+    events: Object.freeze([]),
+    eventsOmitted: 0,
+});
+function object(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function filePath(args) {
+    const value = object(args);
+    const path = value?.file_path ?? value?.path;
+    return typeof path === 'string' && path !== '' ? path : undefined;
+}
+function lineCount(content) {
+    if (content.length === 0)
+        return 0;
+    return (content.match(/\n/g)?.length ?? 0) + (content.endsWith('\n') ? 0 : 1);
+}
+function text(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+const DOC_ACTIONS = {
+    'doc write': 'write',
+    'doc edit': 'edit',
+    'doc delete': 'delete',
+};
+/** A `canvas read` names a document by owner handle and name; other object
+ * types (nodes, jobs, owners) and deleted/remote answers are not document
+ * activity. */
+function readDocumentName(fields) {
+    if (fields['type'] !== 'document')
+        return undefined;
+    const read = object(fields['object']);
+    const name = read === undefined ? undefined : text(read['name']);
+    if (name === undefined)
+        return undefined;
+    const handle = text(object(read?.['owner'])?.['handle']);
+    return handle === undefined ? name : `${handle}/${name}`;
+}
+/** Local mirror of pi's `resolveToCwd`: file tools expand `~` before resolving
+ * against the node cwd, and the recap must key the exact same file identically. */
+function canonicalPath(rawPath, cwd) {
+    const normalized = rawPath === '~'
+        ? homedir()
+        : rawPath.startsWith('~/') ? join(homedir(), rawPath.slice(2)) : rawPath;
+    return resolve(cwd, normalized);
+}
+function fileChange(name, args, result) {
+    if (name === 'edit') {
+        const diff = object(object(result)?.details)?.diff;
+        return typeof diff === 'string'
+            ? { kind: 'edit', ...countDisplayDiffLines(diff), known: true }
+            : { kind: 'edit', added: 0, removed: 0, known: false };
+    }
+    if (name === 'write') {
+        const content = object(args)?.content;
+        return typeof content === 'string'
+            ? { kind: 'write', added: lineCount(content), removed: 0, known: true }
+            : { kind: 'write', added: 0, removed: 0, known: false };
+    }
+    return undefined;
+}
+/** Per-group recorder. Calls retain only their current transcript references
+ * until they settle; the settled activity is plain immutable evidence. */
+export class GroupActivityRecorder {
+    cwd;
+    roster;
+    calls = new Map();
+    files = new Map();
+    documents = [];
+    documentSet = new Set();
+    nodes = [];
+    nodeSet = new Set();
+    cards = [];
+    cardSet = new Set();
+    events = new Map();
+    eventsOmitted = 0;
+    /** `roster` is the ChatView-wide node id → display name record: spawns fill
+     * it, and a later group's finish reads the name a sibling group recorded. */
+    constructor(cwd, roster = new Map()) {
+        this.cwd = cwd;
+        this.roster = roster;
+    }
+    /** What one runtime card leaves behind when its group folds, decided entirely
+     * by the card's presentation policy. */
+    noteCard(card, presentation) {
+        switch (presentation.groupFolded) {
+            case 'omit':
+                return;
+            case 'event':
+                this.addEvent(presentation.summary(card));
+                return;
+            case 'activity':
+                this.addCard({ summary: presentation.summary(card) });
+                return;
+            case 'senders':
+                this.addFinishedSenders(card);
+                return;
+        }
+    }
+    noteCall(id, name, args) {
+        const existing = this.calls.get(id);
+        if (existing?.settled)
+            return;
+        this.calls.set(id, { name, args, settled: false });
+    }
+    settle(id, result, isError) {
+        const entry = this.calls.get(id);
+        if (!entry || entry.settled)
+            return;
+        entry.settled = true;
+        if (!isError && object(result)?.isError !== true)
+            this.extract(entry, result);
+        // Release message-owned references after the operation is reduced.
+        entry.args = undefined;
+    }
+    resolveWithoutResult(id) {
+        const entry = this.calls.get(id);
+        if (!entry || entry.settled)
+            return;
+        entry.settled = true;
+        entry.args = undefined;
+    }
+    activity() {
+        if (this.files.size === 0 && this.documents.length === 0 && this.nodes.length === 0
+            && this.cards.length === 0 && this.events.size === 0)
+            return EMPTY_ACTIVITY;
+        const files = [...this.files.values()].map((file) => Object.freeze({ ...file }));
+        const documents = this.documents.map((document) => Object.freeze({ ...document }));
+        const nodes = this.nodes.map((node) => Object.freeze({ ...node }));
+        const cards = this.cards.map((card) => Object.freeze({ ...card }));
+        const events = [...this.events].map(([text, count]) => Object.freeze({ text, count }));
+        return Object.freeze({
+            files: Object.freeze(files),
+            documents: Object.freeze(documents),
+            nodes: Object.freeze(nodes),
+            cards: Object.freeze(cards),
+            events: Object.freeze(events),
+            eventsOmitted: this.eventsOmitted,
+        });
+    }
+    /** The nodes an inbox digest reports finished. The spawn roster supplies the
+     * display name when it has one. A sender carrying only the person's own words
+     * is the human speaking, not a node that finished. */
+    addFinishedSenders(card) {
+        for (const sender of card.senders) {
+            const onlyHumanWords = sender.entries.length > 0
+                && sender.entries.every(isHumanWordsEntry);
+            if (!sender.finished || onlyHumanWords)
+                continue;
+            this.addNode({ action: 'finished', name: this.roster.get(sender.id) ?? sender.id, id: sender.id });
+        }
+    }
+    addCard(card) {
+        const key = card.summary;
+        if (this.cardSet.has(key))
+            return;
+        this.cardSet.add(key);
+        this.cards.push(card);
+    }
+    addEvent(text) {
+        const line = text.trim();
+        if (line === '')
+            return;
+        const seen = this.events.get(line);
+        if (seen !== undefined) {
+            this.events.set(line, seen + 1);
+            return;
+        }
+        if (this.events.size >= MAX_RECAP_EVENTS) {
+            this.eventsOmitted += 1;
+            return;
+        }
+        this.events.set(line, 1);
+    }
+    addNode(node) {
+        const key = `${node.action}:${node.id}`;
+        if (this.nodeSet.has(key))
+            return;
+        this.nodeSet.add(key);
+        this.nodes.push(node);
+        if (node.action === 'spawned')
+            this.roster.set(node.id, node.name);
+    }
+    /** The recorded leaf path is authoritative: which command ran and what it
+     * returned are both facts here, so a read can never be logged as a save and
+     * an inserted output field can never break a chip. A record carrying an
+     * `error` is a failed call, which is not activity. */
+    noteCrtrInvocation(invocation) {
+        if (invocation.error !== undefined || invocation.result === undefined)
+            return;
+        const fields = invocation.result;
+        switch (invocation.path) {
+            case 'canvas read': {
+                const name = readDocumentName(fields);
+                if (name !== undefined)
+                    this.addDocument({ action: 'read', name });
+                return;
+            }
+            case 'doc write':
+            case 'doc edit':
+            case 'doc delete': {
+                const name = text(fields['name']);
+                if (name === undefined)
+                    return;
+                this.addDocument({ action: DOC_ACTIONS[invocation.path], name });
+                return;
+            }
+            case 'node new': {
+                // `frozen_at` is the deferred-broker case: capacity held the child's
+                // engine back, so nothing started and the recap says nothing.
+                if (fields['frozen_at'] !== undefined && fields['frozen_at'] !== null)
+                    return;
+                const id = text(fields['node_id']);
+                const name = text(fields['name']);
+                if (id !== undefined && name !== undefined)
+                    this.addNode({ action: 'spawned', name, id });
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    addDocument(document) {
+        const key = `${document.action}:${document.name}`;
+        if (this.documentSet.has(key))
+            return;
+        this.documentSet.add(key);
+        this.documents.push(document);
+    }
+    extract(entry, result) {
+        if (entry.name === 'bash') {
+            for (const invocation of crtrPreviewRecords(result))
+                this.noteCrtrInvocation(invocation);
+            return;
+        }
+        const rawPath = filePath(entry.args);
+        const change = fileChange(entry.name, entry.args, result);
+        if (!rawPath || !change)
+            return;
+        const pathKey = canonicalPath(rawPath, this.cwd);
+        // Keep edits and writes distinct: a write is its own durable action even
+        // when it touches a path already changed by an edit in this group.
+        const key = `${change.kind}:${pathKey}`;
+        let file = this.files.get(key);
+        if (!file) {
+            file = {
+                key: pathKey,
+                displayPath: rawPath,
+                kind: change.kind,
+                added: 0,
+                removed: 0,
+                hasKnownCounts: false,
+                countsIncomplete: false,
+            };
+            this.files.set(key, file);
+        }
+        file.added += change.added;
+        file.removed += change.removed;
+        file.hasKnownCounts ||= change.known;
+        file.countsIncomplete ||= !change.known;
+    }
+}

package/dist/clients/attach/render/group-recap.d.ts

@@ -0,0 +1,13 @@
+import { Container } from '@earendil-works/pi-tui';
+import type { AttachPalette } from '../config.js';
+import type { ToolGroupSummary } from '../../../shared/tool-groups.js';
+import type { GroupActivity } from './group-activity.js';
+/** Direct history child for a folded group. It is empty (zero rows) unless the
+ * group is eligible to collapse, preserving the member rows for Ctrl+O. */
+export declare class GroupRecapComponent extends Container {
+    setRecap(summary: ToolGroupSummary | undefined, toolCount: number, activity: GroupActivity, detailed: boolean, palette: AttachPalette): void;
+    /** Runtime cards the fold hid. Terse events are already compressed by count,
+     * so every card contributes exactly one row. */
+    private addCardEvidence;
+    private addFile;
+}

package/dist/clients/attach/render/group-recap.js

@@ -0,0 +1,146 @@
+// Folded visual recap for one broker-summarized tool group. All evidence arrives
+// pre-reduced from GroupActivityRecorder; this component owns only layout/color.
+import { Container, Spacer, Text, getCapabilities, hyperlink, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { ICON } from '../../../core/inspector/model.js';
+import { TOOL_ICON } from '../../../core/preview-registry.js';
+const DOCUMENT_ICON = String.fromCodePoint(0xf02d);
+// trash — deletion has no tool of its own, so it borrows no TOOL_ICON entry.
+const DELETE_ICON = String.fromCodePoint(0xf1f8);
+// info-circle — runtime context the fold hid, kept as its own evidence line.
+const CARD_ICON = String.fromCodePoint(0xf05a);
+function count(value, singular, plural) {
+    return `${value} ${value === 1 ? singular : plural}`;
+}
+function shortened(path) {
+    const home = homedir();
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+function filePath(file) {
+    const path = shortened(file.displayPath);
+    return getCapabilities().hyperlinks ? hyperlink(path, pathToFileURL(file.key).href) : path;
+}
+function countDocuments(documents, action) {
+    return documents.filter((document) => document.action === action).length;
+}
+const DOCUMENT_ACTION_ICON = {
+    read: DOCUMENT_ICON,
+    write: TOOL_ICON.write,
+    edit: TOOL_ICON.edit,
+    delete: DELETE_ICON,
+};
+/** One stat per action a group actually performed, in the order the work
+ *  naturally happens. A group rarely does more than two of them, so the stat
+ *  line stays short. */
+const DOCUMENT_STATS = [
+    ['read', 'document read', 'documents read'],
+    ['write', 'document saved', 'documents saved'],
+    ['edit', 'document revised', 'documents revised'],
+    ['delete', 'document deleted', 'documents deleted'],
+];
+function distinctFileCount(files) {
+    return new Set(files.map((file) => file.key)).size;
+}
+function countNodes(nodes, action) {
+    return nodes.filter((node) => node.action === action).length;
+}
+class RecapDetailLine {
+    prefix;
+    path;
+    suffix;
+    constructor(prefix, path, suffix) {
+        this.prefix = prefix;
+        this.path = path;
+        this.suffix = suffix;
+    }
+    invalidate() { }
+    render(width) {
+        const pathWidth = Math.max(1, width - visibleWidth(this.prefix) - visibleWidth(this.suffix));
+        const path = truncateToWidth(this.path, pathWidth, '…');
+        return [truncateToWidth(`${this.prefix}${path}${this.suffix}`, width, '')];
+    }
+}
+/** Direct history child for a folded group. It is empty (zero rows) unless the
+ * group is eligible to collapse, preserving the member rows for Ctrl+O. */
+export class GroupRecapComponent extends Container {
+    setRecap(summary, toolCount, activity, detailed, palette) {
+        this.clear();
+        if (!summary)
+            return;
+        this.addChild(new Spacer(1));
+        if (detailed) {
+            for (const node of activity.nodes) {
+                this.addChild(new RecapDetailLine(`${palette.accent(ICON.graph)} `, palette.muted(node.name), palette.muted(node.action === 'spawned' ? ' spawned' : ' finished')));
+            }
+            for (const document of activity.documents) {
+                const icon = DOCUMENT_ACTION_ICON[document.action];
+                const tone = document.action === 'delete' ? palette.diffRemoved : palette.info;
+                this.addChild(new RecapDetailLine(`${tone(icon)} `, palette.muted(document.name), ''));
+            }
+            for (const file of activity.files)
+                this.addFile(file, palette);
+        }
+        const toolCallCount = `${palette.active(TOOL_ICON.bash)} ${palette.muted(count(toolCount, 'tool call', 'tool calls'))}`;
+        if (detailed) {
+            this.addChild(new Text(toolCallCount, 0, 0));
+        }
+        else {
+            const stats = [toolCallCount];
+            const nodesSpawned = countNodes(activity.nodes, 'spawned');
+            if (nodesSpawned >= 1) {
+                stats.push(`${palette.accent(ICON.graph)} ${palette.muted(count(nodesSpawned, 'node spawned', 'nodes spawned'))}`);
+            }
+            const nodesFinished = countNodes(activity.nodes, 'finished');
+            if (nodesFinished >= 1) {
+                stats.push(`${palette.accent(ICON.graph)} ${palette.muted(count(nodesFinished, 'node finished', 'nodes finished'))}`);
+            }
+            const changedFiles = distinctFileCount(activity.files);
+            if (changedFiles >= 1) {
+                stats.push(`${palette.warning(TOOL_ICON.edit)} ${palette.muted(count(changedFiles, 'file changed', 'files changed'))}`);
+            }
+            // Deletions never enter activity.files (only edit/write calls do), so the
+            // model's count covers a disjoint set and cannot double-count a change.
+            if (summary.filesDeleted >= 1) {
+                stats.push(`${palette.diffRemoved(DELETE_ICON)} ${palette.muted(count(summary.filesDeleted, 'file deleted', 'files deleted'))}`);
+            }
+            for (const [action, singular, plural] of DOCUMENT_STATS) {
+                const changed = countDocuments(activity.documents, action);
+                if (changed < 1)
+                    continue;
+                const tone = action === 'delete' ? palette.diffRemoved : palette.info;
+                stats.push(`${tone(DOCUMENT_ACTION_ICON[action])} ${palette.muted(count(changed, singular, plural))}`);
+            }
+            this.addChild(new Text(stats.join(palette.muted(' · ')), 0, 0));
+        }
+        this.addCardEvidence(activity, palette);
+        for (const bullet of summary.bullets)
+            this.addChild(new Text(palette.muted(`  • ${bullet.trim()}`), 0, 0));
+        this.addChild(new Spacer(1));
+    }
+    /** Runtime cards the fold hid. Terse events are already compressed by count,
+     * so every card contributes exactly one row. */
+    addCardEvidence(activity, palette) {
+        for (const card of activity.cards) {
+            this.addChild(new Text(`${palette.info(CARD_ICON)} ${palette.muted(card.summary)}`, 0, 0));
+        }
+        for (const event of activity.events) {
+            const repeats = event.count > 1 ? ` ×${event.count}` : '';
+            this.addChild(new Text(`${palette.info(CARD_ICON)} ${palette.muted(`${event.text}${repeats}`)}`, 0, 0));
+        }
+        if (activity.eventsOmitted > 0) {
+            this.addChild(new Text(palette.muted(`  ${count(activity.eventsOmitted, 'more runtime event', 'more runtime events')}`), 0, 0));
+        }
+    }
+    addFile(file, palette) {
+        const counts = file.hasKnownCounts
+            ? `${palette.diffAdded(`+${file.added}`)}${file.kind === 'edit' ? ` ${palette.diffRemoved(`-${file.removed}`)}` : ''}`
+            : '';
+        const availability = file.countsIncomplete
+            ? palette.muted(file.hasKnownCounts ? ' · counts incomplete' : 'counts unavailable')
+            : '';
+        const suffix = counts || availability ? ` ${counts}${availability}` : '';
+        const icon = file.kind === 'write' ? TOOL_ICON.write : TOOL_ICON.edit;
+        this.addChild(new RecapDetailLine(`${palette.warning(icon)} `, filePath(file), suffix));
+    }
+}

package/dist/clients/attach/render/markdown-source.d.ts

@@ -0,0 +1,21 @@
+/** Decorate a Markdown block for terminal rendering: heading hierarchy and XML
+ *  tag lines. Fenced examples remain literal Markdown, never decorated
+ *  terminal output. */
+export declare function styleAttachMarkdownSource(markdown: string): string;
+/** Every source-text transform the viewer applies to AGENT-authored Markdown,
+ *  in one place: heading and XML syntax, then glyph expansion. A human's own
+ *  message keeps `styleAttachMarkdownSource` alone — the `U+XXXX` escape hatch
+ *  exists for agents that cannot type a Nerd Font character. */
+export declare function styleAttachAgentMarkdown(markdown: string): string;
+/** Name `[[owner/name]]` document links readably and link them to their
+ *  materialized page (render/doc-links.ts), leaving code spans and fences
+ *  literal. For Markdown the viewer renders outside the transcript — inbox
+ *  pages and inline page blocks. */
+export declare function rewriteMarkdownDocLinks(markdown: string): string;
+/** Copy a pi message for terminal rendering and decorate only Markdown-bearing
+ * text/thinking blocks. The broker's source event is never mutated. */
+export declare function styleAttachMessageMarkdown<T>(message: T): T;
+/** Copy an expanded pi summary without changing its persisted source. */
+export declare function styleAttachSummaryMarkdown<T extends {
+    summary: string;
+}>(message: T): T;