@north-light/cli 0.0.0 → 0.3.413

package/dist/clients/inbox/tui.d.ts

@@ -0,0 +1,17 @@
+import type { InboxRow } from './dto-adapt.js';
+export declare const KIND_ICON: Record<string, string>;
+export declare const KIND_COLOR: Record<string, string>;
+export declare function formatTimeAgo(iso: string): string;
+/** What the list is currently showing, and the key that changes it. */
+export interface InboxScope {
+    /** Display name of the active scope; never used to decide membership. */
+    label: string;
+    /** Toggle hint, absent when there is no other scope to reach. */
+    hint?: string;
+}
+/** Pure inbox rows; selection and terminal ownership belong to InboxController.
+ *  The header carries the scope and its toggle whether or not anything is
+ *  listed: an empty list is when the reader most needs the way to the rest. */
+export declare function buildInboxLines(items: InboxRow[], width: number, selectedIndex: number, scope: InboxScope, height?: number): string[];
+/** What the agent suggests, for a row that says so without opening the page. */
+export declare function recommendedLabel(item: InboxRow): string | undefined;

package/dist/clients/inbox/tui.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var l=(n,e)=>y(n,"name",{value:e,configurable:!0});import{RESET as r,BOLD as b,DIM as $,ITALIC as m,CYAN as w,RED as x,GRAY as L,YELLOW as M,truncateRow as g}from"./tui/ansi.js";function I(n,e){switch(e){case"gray":return`${L}${n}${r}`;case"cyan":return`${w}${n}${r}`;case"red":return`${x}${n}${r}`;case"yellow":return`${M}${n}${r}`;default:return n}}l(I,"ansiColor");const R={notify:"\u2709",decision:"\u25C6",context:"\u270E",error:"\u26A0",review:"\u25A4",display:"\u2709",rich:"\u25A3",interactive:"\u25C6"},k={notify:"gray",decision:"cyan",context:"cyan",error:"red",review:"yellow",display:"gray",rich:"cyan",interactive:"cyan"};function v(n){const e=Math.floor((Date.now()-new Date(n).getTime())/6e4);return e>=60?`${Math.floor(e/60)}h ago`:e>0?`${e}m ago`:"just now"}l(v,"formatTimeAgo");function T(n,e,d,t,o=Number.MAX_SAFE_INTEGER){const i=[`  ${b}${n.length} pending${r}  ${$}\xB7 ${t.label}${r}`];if(t.hint!==void 0&&i.push(`  ${$}${t.hint}${r}`),i.push(""),n.length===0)return[...i,`  ${$}${m}No pending interactions${r}`];const u=e-4,f=n.map((a,h)=>A(a,h,d,u)),s=E(f,d,Math.max(1,o-i.length)),c=[...i];s.start>0&&c.push(`  ${$}\u2191 ${s.start} above${r}`);for(let a=s.start;a<s.end;a++)c.push(...f[a]);return s.end<n.length&&c.push(`  ${$}\u2193 ${n.length-s.end} below${r}`),c}l(T,"buildInboxLines");function A(n,e,d,t){const o=n.kind==="page"?n.awaitsResponse===!1?"display":"rich":n.kind,i=R[o]??"\xB7",u=v(n.kind==="page"?n.emittedAt:n.blockedSince),f=e===d?`${w}\u25B8${r} `:"  ",s=Math.max(1,t-u.length-6),c=`${f}${I(i,k[o]??"cyan")} ${b}${g(n.title||`(${n.id.slice(0,8)})`,s)}${r}  ${$}${u}${r}`,a=n.claim?`claimed by ${n.claim.owner} \xB7 ${n.subtitle}`:n.subtitle,h=[c,`      ${$}${g(a,t-6)}${r}`],p=D(n);return p!==void 0&&h.push(`      ${$}Recommended: ${g(p,Math.max(1,t-19))}${r}`),h}l(A,"buildItemLines");function D(n){if(!(n.kind!=="page"||n.recommendedOptions.length===0))return n.recommendedOptions.map(e=>e.label).join(" \xB7 ")}l(D,"recommendedLabel");function E(n,e,d){let t=Math.max(0,Math.min(e,n.length-1)),o=t+1,i=!0;for(;;){const u=o<n.length?{start:t,end:o+1}:void 0,f=t>0?{start:t-1,end:o}:void 0,c=(i?[u,f]:[f,u]).find(a=>a!==void 0&&N(n,a.start,a.end)<=d);if(c===void 0)break;t=c.start,o=c.end,i=!i}return{start:t,end:o}}l(E,"visibleWindow");function N(n,e,d){let t=e>0?1:0;for(let o=e;o<d;o++)t+=n[o].length;return d<n.length&&t++,t}l(N,"windowHeight");export{k as KIND_COLOR,R as KIND_ICON,T as buildInboxLines,v as formatTimeAgo,D as recommendedLabel};

package/dist/clients/surfaces/host.d.ts

@@ -0,0 +1,74 @@
+import type { Component } from '@earendil-works/pi-tui';
+/**
+ * A surface root: a pi-tui component rendered inside a host-assigned rectangle.
+ * The host pushes the rectangle height before every render and on resize; a
+ * surface must render exactly that many rows and must not read terminal or
+ * process geometry itself. A surface must never place its cursor marker on row
+ * 0, which is reserved for host notices.
+ */
+export interface SurfaceComponent extends Component {
+    /** Set the number of rows assigned by the host for the next render. */
+    setRows(rows: number): void;
+    /** Consume wheel input when applicable. */
+    handleWheel?(direction: 'up' | 'down', lines: number): boolean;
+}
+/** The identities used for mounted surfaces. */
+export type SurfaceId = 'inbox' | 'review';
+/** How long a notice stays up. */
+export interface SurfaceNoticeOptions {
+    /** Keep the notice up until it is replaced or cleared, with no auto-clear. */
+    sticky?: boolean;
+}
+/**
+ * The only host boundary available to a surface. Surfaces render only through
+ * the mounted component and use {@link notice} as their only output channel;
+ * they never write to the terminal, stdout, stderr, or raw input themselves.
+ */
+export interface SurfaceHost {
+    /**
+     * Mount a component into the host-assigned full rectangle. When the focused
+     * input component differs from the rendered root, pass it as `focus` so
+     * input and cursor ownership remain with that component.
+     */
+    mount(component: SurfaceComponent, opts?: {
+        focus?: Component;
+    }): SurfaceHandle;
+    /** Report transient output through the host; this is the only surface output channel. */
+    notice(text: string, opts?: SurfaceNoticeOptions): void;
+    /**
+     * Temporarily release the terminal for a child process and return a resume
+     * closure. Callers must invoke the closure in a `finally` block.
+     */
+    suspendForChild(): () => void;
+    /** Bring a node's viewer to the front; failures are reported through notice and never reject. */
+    focusNode(nodeId: string): Promise<boolean>;
+    /** Mount the shared review-file picker and resolve to its chosen path or null on cancellation. */
+    pickReviewFile(spec: {
+        candidates: readonly string[];
+        cwd: string;
+        title?: string;
+    }): Promise<string | null>;
+    /** Capability facts resolved once by the host for this session. */
+    readonly capabilities: {
+        /** True when this viewer is attached to a remote session. */
+        readonly remote: boolean;
+        /** True when focusing another node's viewer is available. */
+        readonly canFocusNode: boolean;
+        /** This viewer's own tmux pane — the target a surface splits against.
+         *  Undefined outside tmux. */
+        readonly selfPane: string | undefined;
+    };
+}
+/** A mounted surface's lifecycle controls. */
+export interface SurfaceHandle {
+    /** Close this surface and any surfaces mounted above it. Idempotent. */
+    close(): void;
+    /** Mark the surface dirty; the host schedules a redraw rather than drawing synchronously. */
+    invalidate(): void;
+    /**
+     * Register the only sanctioned teardown hook for timers, watchers, listeners,
+     * and poll re-arms. Closing initiates both synchronous and asynchronous
+     * cleanup; asynchronous cleanup is not awaited by the host.
+     */
+    onClose(fn: () => void | Promise<void>): void;
+}

package/dist/commands/api-client.d.ts

@@ -0,0 +1,104 @@
+import { CrtrClient } from '../api/index.js';
+import type { CanvasSource } from '../core/canvas/source.js';
+import type { NodeStatus, SubscriptionRef } from '../core/canvas/types.js';
+import type { Scope } from '../types.js';
+import type { NodeDetailDTO } from '../api/dto/nodes.js';
+import type { NodeMeta, NodeRow } from '../core/canvas/types.js';
+import type { RosterDTO } from '../api/dto/canvas.js';
+import type { ReportDTO } from '../api/index.js';
+/** Rethrow an `ApiError` as the clean structured CLI error agents parse
+ *  (`core/io` `handle`) — instead of the generic "internal bug" stderr path a
+ *  raw non-`CrtrError` throw would take. The mapping itself lives in ONE place
+ *  (`apiErrorToCliError`, `core/io.ts`); this is the explicit-catch helper a
+ *  leaf uses when it wants to attach a call-site `next` hint. Non-`ApiError`
+ *  throws propagate unchanged (a genuine bug still reads as `internal`). Typed
+ *  `never` so callers can use it as the tail of a `catch` without confusing
+ *  definite assignment. */
+export declare function rethrowAsCliError(err: unknown, next?: string): never;
+/** Fetch a node, mapping ONLY a 404 to `null` (the "not found" contract every
+ *  existence-check leaf wants) and surfacing every other failure as the clean
+ *  network-class CLI error via `rethrowAsCliError`. This replaces the old
+ *  `.catch(() => null)` idiom that, post-B-1 (`getNode` is now an HTTP round-trip),
+ *  masked a broken/slow/restarting daemon as a false "node not found". Same
+ *  404-only→null mapping as `ApiCanvasSource.orNull`, but returning the raw DTO
+ *  and rethrowing non-404s as CLI errors rather than swallowing them. */
+export declare function getNodeOrNull(nodeId: string): Promise<NodeDetailDTO | null>;
+/** Bounded tail of crtrd.log surfaced on a cold-start `/healthz` timeout.
+ *  Large enough to catch a real startup failure/stack trace,
+ *  small enough that a runaway daemon log can never leak unbounded into a CLI
+ *  error message. */
+export declare const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4096;
+/** Read a bounded tail of crtrd's event log to enrich a `daemon_unavailable`
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
+ *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
+ *  never `readFileSync`-ing the whole append-only log — then decodes/filters
+ *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
+ *  contract — a missing/unreadable/empty log yields `undefined` so the base
+ *  message is used unchanged. */
+export declare function readColdStartDiagnostic(): string | undefined;
+/** The local-socket `CrtrClient` every CLI verb uses. Autostart is on by
+ *  default: on a cold socket the injected `onColdSocket` hook fires
+ *  `ensureDaemon()` (spawns crtrd detached via the branded host), then the
+ *  client polls `/healthz` to a bounded deadline and retries once (the poll
+ *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable, the
+ *  client surfaces the final observed transport failure. This is the ONLY CLI
+ *  reference to `ensureDaemon`.
+ *
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows.
+ *  Both callers use the shared startup policy so a valid on-disk migration
+ *  cannot outlast the initiating CLI command. */
+export declare function cliClient(opts?: {
+    timeoutMs?: number;
+}): CrtrClient;
+export declare class ApiCanvasSource implements CanvasSource {
+    private readonly client;
+    private rosterCache;
+    private rosterInFlight;
+    constructor(client?: CrtrClient);
+    private roster;
+    /** Map a 404 from the API to the interface's `null` "not found" contract;
+     *  re-throw everything else. */
+    private orNull;
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+    }): Promise<NodeRow[]>;
+    /** The browse screen uses one slim, compressed read for rows AND topology.
+     * The same roster index feeds subscriptionsOf/view until its normal TTL ends. */
+    browseSnapshot(): Promise<NodeRow[]>;
+    panelRoster(): Promise<RosterDTO>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    /** BFS over the active `subscribes_to` edges from `root` (its transitive view),
+     *  excluding `root` itself — the same traversal shape as
+     *  `RemoteCanvasSource.view`, expressed over the API's edge lists. */
+    view(root: string): Promise<string[]>;
+    /** Per-NODE open-ticket counts across `root`'s view. The renderer badges each
+     * node with the tickets it raised (the human bridge's parent), so this must
+     * be per-node. Request only this view's ids: using the
+     * enriched full-canvas snapshot for a five-second viewer poll blocked crtrd
+     * behind metadata and telemetry reads for every historical node. */
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
+    /** True when `nodeId` has at least one active (`active` edge flag, not just a
+     *  live subscriber) subscription to a node that is currently live
+     *  (`active`/`idle` status). `subscriptionsOf`'s roster-backed edges carry the
+     *  real per-edge `active` flag, so this filter is exact, not an over-report. */
+    newestReport(nodeId: string): Promise<ReportDTO | null>;
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+}
+/** The active read source for a CLI command. Mirrors `resolveCanvasSource`'s
+ *  selection WITHOUT importing `core/canvas/source.ts` (which pulls
+ *  `LocalCanvasSource` → `openDb`, failing the Stage-C import checker): an
+ *  explicit `--canvas <name>` wins, else the durable `crtr canvas use` selection
+ *  (`ScopeState.activeCanvas`), else the API-backed local source. The remote
+ *  branch reuses the verified-openDb-free `RemoteCanvasSource` (plan Q-3). */
+export declare function cliCanvasSource(opts?: {
+    canvasName?: string;
+    scope?: Scope;
+}, sandboxed?: boolean): CanvasSource;

package/dist/commands/api-client.js

@@ -0,0 +1,4 @@
+var m=Object.defineProperty;var a=(r,t)=>m(r,"name",{value:t,configurable:!0});import{closeSync as w,fstatSync as b,openSync as _,readSync as g}from"node:fs";import{join as S}from"node:path";import{gunzipSync as y}from"node:zlib";import{ApiError as l}from"../api/index.js";import{localClient as d}from"../api/node-transport.js";import{apiErrorToCliError as v}from"../core/io.js";import{autostartDisabled as C,daemonAutostartStartupFailure as N,ensureDaemon as T}from"../daemon/manage.js";import{DAEMON_STARTUP_WINDOW_MS as M}from"../daemon/startup-policy.js";import{readState as A}from"../core/config.js";import{resolveRemoteCanvasTarget as O}from"../core/remote-canvas-target.js";import{RemoteCanvasSource as R}from"../core/canvas/remote-canvas-source.js";import{crtrHome as I}from"../core/canvas/paths.js";import{isSandboxedNode as x}from"../shared/env.js";import{ownerOnly as D}from"../core/errors.js";function u(r){return{...r,fault:r.fault??null}}a(u,"withRowFault");function F(r,t){throw r instanceof l?v(r,t):r}a(F,"rethrowAsCliError");async function Z(r){try{return await h().getNode(r)}catch(t){if(t instanceof l&&t.status===404)return null;F(t)}}a(Z,"getNodeOrNull");const E=4096,L=20;function k(){let r;try{r=_(S(I(),"crtrd.log"),"r");const{size:t}=b(r),s=Math.max(0,t-E),n=t-s;if(n<=0)return;const e=Buffer.alloc(n);g(r,e,0,n,s);const o=e.toString("utf8").split(`
+`).filter(c=>c.trim()!=="").slice(-L).join(`
+`).trim();return o===""?void 0:`crtrd.log (tail):
+${o}`}catch{return}finally{if(r!==void 0)try{w(r)}catch{}}}a(k,"readColdStartDiagnostic");function h(r){return process.env.CRTR_API_SOCKET?d({autostart:!1,...r?.timeoutMs!==void 0?{timeoutMs:r.timeoutMs}:{}}):C()?d({autostart:!1,...r?.timeoutMs!==void 0?{timeoutMs:r.timeoutMs}:{}}):d({...r?.timeoutMs!==void 0?{timeoutMs:r.timeoutMs}:{},onColdSocket:a(async()=>{T()},"onColdSocket"),coldStartDiagnostic:k,coldStartFailure:N,coldStartPollWindowMs:M})}a(h,"cliClient");const B=2e3;class p{static{a(this,"ApiCanvasSource")}client;rosterCache=null;rosterInFlight=null;constructor(t=h()){this.client=t}async roster(){const t=Date.now();return this.rosterCache!==null&&t-this.rosterCache.at<B?this.rosterCache.index:this.rosterInFlight!==null?this.rosterInFlight:(this.rosterInFlight=this.client.canvasRoster().then(s=>{const n={snapshot:s,subscriptions:new Map,subscribers:new Map};for(const e of s.edges){const i={node_id:e.to_id,active:e.active,created:e.created},o={node_id:e.from_id,active:e.active,created:e.created},c=n.subscriptions.get(e.from_id);c===void 0?n.subscriptions.set(e.from_id,[i]):c.push(i);const f=n.subscribers.get(e.to_id);f===void 0?n.subscribers.set(e.to_id,[o]):f.push(o)}return this.rosterCache={at:Date.now(),index:n},n}).finally(()=>{this.rosterInFlight=null}),this.rosterInFlight)}async orNull(t){try{return await t()}catch(s){if(s instanceof l&&s.status===404)return null;throw s}}async getNode(t){const s=await this.orNull(()=>this.client.getNode(t));return s===null?null:u(s)}async getRow(t){const s=await this.orNull(()=>this.client.getNode(t));return s===null?null:u(s)}async listNodes(t){const s=t?.status;let n;if(Array.isArray(s)){const e=new Set(s);n=(await this.client.listNodes()).filter(o=>e.has(o.status))}else s!==void 0?n=await this.client.listNodes({status:s}):n=await this.client.listNodes();return n.map(e=>u(e))}async browseSnapshot(){const t=await this.client.canvasBrowseCompressed(),s=JSON.parse(y(t).toString("utf8")),n={subscriptions:new Map,subscribers:new Map};for(const e of s.edges){const i=n.subscriptions.get(e.from_id)??[];i.push({node_id:e.to_id,active:e.active,created:e.created}),n.subscriptions.set(e.from_id,i);const o=n.subscribers.get(e.to_id)??[];o.push({node_id:e.from_id,active:e.active,created:e.created}),n.subscribers.set(e.to_id,o)}return this.rosterCache={at:Date.now(),index:n},s.nodes.map(e=>u(e))}async panelRoster(){const t=await this.roster();return t.snapshot!==void 0?t.snapshot:(this.rosterCache=null,(await this.roster()).snapshot)}async subscriptionsOf(t){return this.roster().then(s=>s.subscriptions.get(t)??[])}async subscribersOf(t){return this.roster().then(s=>s.subscribers.get(t)??[])}async view(t){const s=new Set([t]),n=[],e=(await this.subscriptionsOf(t)).map(i=>i.node_id);for(;e.length>0;){const i=e.shift();if(!s.has(i)){s.add(i),n.push(i);for(const o of await this.subscriptionsOf(i))s.has(o.node_id)||e.push(o.node_id)}}return n}async ticketCountsForNodes(t){return(await this.client.attentionCounts([...t])).counts}async ticketCountsForView(t){return this.ticketCountsForNodes([t,...await this.view(t)])}async newestReport(t){return(await this.client.getReports(t,{limit:1}))[0]??null}async hasActiveLiveSubscription(t){const s=(await this.subscriptionsOf(t)).filter(n=>n.active);for(const n of s){const e=await this.getRow(n.node_id);if(e&&(e.status==="active"||e.status==="idle"))return!0}return!1}}function tt(r,t=x()){const s=r?.scope??"user";if(t){if(r?.canvasName!==void 0)throw D("--canvas selects the person's remote canvas targets, which an app's node cannot reach","Omit --canvas; this node reads its own runtime's canvas.");return new p}const n=r?.canvasName??A(s).activeCanvas??null;if(!n)return new p;const{previewEndpoint:e,relayToken:i}=O(n,s);return new R(e,i)}a(tt,"cliCanvasSource");export{p as ApiCanvasSource,E as COLD_START_DIAGNOSTIC_TAIL_BYTES,tt as cliCanvasSource,h as cliClient,Z as getNodeOrNull,k as readColdStartDiagnostic,F as rethrowAsCliError};

package/dist/commands/attention.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare const attentionBranch: BranchDef;

package/dist/commands/attention.js

@@ -0,0 +1 @@
+var p=Object.defineProperty;var c=(o,e)=>p(o,"name",{value:e,configurable:!0});import{defineBranch as f,defineLeaf as h}from"../core/command.js";import{InputError as d}from"../core/io.js";import{cliClient as u,cliCanvasSource as l}from"./api-client.js";async function w(o,e){return new Set([e,...await o.view(e)])}c(w,"viewNodeSet");const g=h({name:"count",description:"total pending human-ticket count (machine-parseable stdout.count)",whenToUse:"a lightweight summary when you just need the number, not which cwds are blocked \u2014 scope it to a node or a sub-DAG, or default to canvas-wide. Use `list` when you need to act on where to go answer.",help:{name:"canvas attention count",summary:"return the number of pending human tickets (asks, reviews, notifications); stdout.count is machine-parseable",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Count tickets asked by this node. Mutually exclusive with --view."},{kind:"flag",name:"view",type:"string",required:!1,constraint:"Sum tickets for all nodes in the sub-DAG rooted at this id. Mutually exclusive with --node."}],output:[{name:"count",type:"integer",required:!0,constraint:"Total pending human tickets in the requested scope."}],outputKind:"object",effects:["Read-only: scans humanloop interaction dirs."]},run:c(async o=>{const e=o.node,t=o.view;if(e!==void 0&&t!==void 0)throw new d({error:"ambiguous_scope",message:"--node and --view are mutually exclusive",next:"Use one of --node <id>, --view <id>, or neither (canvas-wide)."});if(e!==void 0){if(await l().getNode(e)===null)throw new d({error:"not_found",message:`no node: ${e}`,next:"List nodes with `crtr node inspect list`."});return{count:(await u().attentionCounts([e])).counts[e]??0}}const s=(await u().attention()).items;if(t!==void 0){const n=l();if(await n.getNode(t)===null)throw new d({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const i=await w(n,t);return{count:s.filter(r=>i.has(r.node_id)).reduce((r,m)=>r+m.count,0)}}return{count:s.reduce((n,i)=>n+i.count,0)}},"run")}),v=h({name:"list",description:"itemised list of cwds with pending human tickets",whenToUse:"finding which agents are blocked waiting on the user \u2014 an itemised list of the cwds with pending tickets (asks, reviews, notifications), oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.",help:{name:"canvas attention list",summary:"list nodes that asked pending human tickets",params:[{kind:"flag",name:"view",type:"string",required:!1,constraint:"Scope the list to the sub-DAG rooted at this node id. Omit for canvas-wide."}],output:[{name:"items",type:"object[]",required:!0,constraint:"Each: {node_id, name, cwd, count}. One entry per asking node with count > 0."},{name:"total",type:"integer",required:!0,constraint:"Sum of counts across all entries."}],outputKind:"object",effects:["Read-only: scans humanloop interaction dirs."]},run:c(async o=>{const e=o.view;let t=(await u().attention()).items;if(e!==void 0){const n=l();if(await n.getNode(e)===null)throw new d({error:"not_found",message:`no node: ${e}`,next:"List nodes with `crtr node inspect list`."});const i=await w(n,e);t=t.filter(a=>i.has(a.node_id))}const s=t.reduce((n,i)=>n+i.count,0);return{items:t,total:s}},"run")}),b=h({name:"map",description:"per-node ticket counts for a visible set, batched in one pass",whenToUse:"labelling every node in a UI with its pending-ticket count in one batched pass \u2014 the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs",tier:"hidden",help:{name:"canvas attention map",summary:"per-node pending human-ticket counts for a visible set of nodes in ONE pass \u2014 the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs",params:[{kind:"flag",name:"view",type:"string",required:!1,constraint:"Include this node and its whole sub-DAG (root + reports recursively). Union with --nodes. At least one of --view/--nodes is required."},{kind:"flag",name:"nodes",type:"string",required:!1,constraint:"Comma-separated explicit node ids to include (e.g. ancestry + peers). Union with --view."}],output:[{name:"counts",type:"object",required:!0,constraint:"Map of node_id \u2192 pending human-ticket count. Every requested id is present (0 when none)."}],outputKind:"object",effects:["Read-only: scans the registered humanloop node root once."]},run:c(async o=>{const e=o.view,t=o.nodes;if(e===void 0&&(t===void 0||t.trim()===""))throw new d({error:"missing_scope",message:"at least one of --view <id> or --nodes <a,b,c> is required",next:"Pass --view <root> to cover a sub-DAG, --nodes <a,b,c> for an explicit set, or both."});const s=l(),n=new Set;if(e!==void 0){if(await s.getNode(e)===null)throw new d({error:"not_found",message:`no node: ${e}`,next:"List nodes with `crtr node inspect list`."});n.add(e);for(const a of await s.view(e))n.add(a)}if(t!==void 0)for(const a of t.split(",").map(r=>r.trim()).filter(r=>r!==""))n.add(a);return{counts:(await u().attentionCounts([...n])).counts}},"run")}),S=f({name:"attention",description:"count/list pending human tickets across the graph",whenToUse:"checking whether any agent on the canvas is blocked waiting on the user, and where: count the pending tickets (asks, reviews, notifications) or list the cwds that have them. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster",help:{name:"canvas attention",summary:"aggregate pending human tickets across the canvas",model:"`count` returns a single integer (stdout.count is machine-parseable) and accepts --node or --view; `list` returns itemised asking-node entries and accepts --view only. Both default to canvas-wide. A ticket is any humanloop interaction awaiting the user: an ask, a review, or a notification."},children:[g,v,b]});export{S as attentionBranch};

package/dist/commands/canvas/edges.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const edgesLeaf: LeafDef;

package/dist/commands/canvas/edges.js

@@ -0,0 +1,2 @@
+var r=Object.defineProperty;var o=(e,n)=>r(e,"name",{value:n,configurable:!0});import{defineLeaf as s}from"../../core/command.js";import{cliClient as a,rethrowAsCliError as i}from"../api-client.js";import{REF_CONSTRAINT as c}from"./read.js";const d=["acted-on","links-to","watches"],g=s({name:"edges",description:"list the edges of an object: acted-on, links-to, watches",whenToUse:"you need what a document links to or what links to it, who acted on an object, or who watches it. Records nothing.",help:{name:"canvas edges",summary:"list an object\u2019s acted-on, links-to and watches edges; records nothing",params:[{kind:"positional",name:"ref",required:!0,constraint:c},{kind:"flag",name:"type",type:"enum",choices:d,required:!1,constraint:"Only edges of this type. acted-on: an actor changed or wrote the object. links-to: a body names the object as `[[name]]`. watches: a watcher of the object."},{kind:"flag",name:"direction",type:"enum",choices:["out","in"],required:!1,constraint:"out: edges from this object; in: edges to it. Omit for both."}],output:[{name:"items",type:"string[]",required:!0,constraint:"One row per edge you can read both ends of: type, source and destination as id and `[[name]]`, and for links-to the name as the body wrote it."}],outputKind:"object",effects:["None. Listing edges records no watch."]},run:o(async e=>{const n={...e.type?{type:e.type}:{},...e.direction?{direction:e.direction}:{}};try{return{...await a().objects.edges(e.ref,n)}}catch(t){i(t)}},"run"),render:o(e=>{const{items:n}=e;return n.length===0?"No edges.":n.map(t=>`- ${t.type}: ${t.src.id} [[${t.src.name}]] \u2192 ${t.dst.id} [[${t.dst.name}]]${t.written_as?` (written as [[${t.written_as}]])`:""}`).join(`
+`)},"render")});export{g as edgesLeaf};

package/dist/commands/canvas/list.d.ts

@@ -0,0 +1,4 @@
+import type { LeafDef } from '../../core/command.js';
+import type { ObjectListItemDTO } from '../../api/dto/objects.js';
+export declare function listItemRow(item: ObjectListItemDTO): string;
+export declare const listLeaf: LeafDef;

package/dist/commands/canvas/list.js

@@ -0,0 +1,3 @@
+var s=Object.defineProperty;var t=(e,r)=>s(e,"name",{value:r,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{PRIVACY_LEVELS_DTO as i}from"../../api/dto/objects.js";import{cliClient as c,rethrowAsCliError as d}from"../api-client.js";import{objectRow as l}from"./read.js";function m(e){const r=l(e);if(e.type!=="document")return r;const n=[`privacy=${e.privacy}`,e.rules!==void 0?`rules=${e.rules}`:""].filter(Boolean).join(" ");return`${r}
+  ${n}${e.summary?` \u2014 ${e.summary}`:""}`}t(m,"listItemRow");const g=a({name:"list",description:"list objects by type, kind, owner, privacy or name prefix",whenToUse:"browsing what exists without reading it \u2014 the documents an owner holds, a node\u2019s reports, every job of a node. Records nothing, so listing does not make you a watcher.",help:{name:"canvas list",summary:"list the objects you can read, filtered; records nothing",params:[{kind:"flag",name:"type",type:"string",required:!1,constraint:"Only objects of this kind: document, node, job, person, app, repo or profile. The daemon rejects a name no kind declares and lists the kinds."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Only objects of this kind: for documents knowledge, preference or report; for nodes the node kind."},{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Only objects this owner owns directly: a node id, a handle, or any name `crtr canvas read` accepts."},{kind:"flag",name:"privacy",type:"enum",choices:[...i],required:!1,constraint:"Only objects at this privacy level."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Only objects whose name starts with this prefix."},{kind:"flag",name:"deleted",type:"bool",required:!1,constraint:"When present, lists deleted objects instead of live ones."},{kind:"flag",name:"limit",type:"int",required:!1,default:50,constraint:"Page size, 1 to 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"The `next_cursor` of the previous page."}],output:[{name:"items",type:"string[]",required:!0,constraint:"One row per object: id, `[[name]]`, type/kind, owner handle and preview. A document row adds its privacy, its rule count and its summary."},{name:"next_cursor",type:"string",required:!1,constraint:"Pass as `--cursor` for the next page; absent on the last page."}],outputKind:"object",effects:["None. Listing records no watch."]},run:t(async e=>{const r={...e.type?{type:e.type}:{},...e.kind?{kind:e.kind}:{},...e.owner?{owner:e.owner}:{},...e.privacy?{privacy:e.privacy}:{},...e.name?{name:e.name}:{},...e.deleted===!0?{deleted:!0}:{},limit:e.limit??50,...e.cursor?{cursor:e.cursor}:{}};try{return{...await c().objects.list(r)}}catch(n){d(n)}},"run"),render:t(e=>{const{items:r,next_cursor:n}=e;if(r.length===0)return"No objects match.";const o=r.map(m);return n&&o.push("",`More: \`crtr canvas list \u2026 --cursor ${n}\`.`),o.join(`
+`)},"render")});export{m as listItemRow,g as listLeaf};

package/dist/commands/canvas/read.d.ts

@@ -0,0 +1,14 @@
+import type { LeafDef } from '../../core/command.js';
+import type { ObjectReadDTO } from '../../api/dto/objects.js';
+export declare const REF_CONSTRAINT = "A name (the `[[ ]]` brackets are optional) or a raw object id. A name is `<owner-handle>/<path>`; a node or other owner is also named by its id or handle.";
+export { attr, objectRow } from '../../core/graph/kinds/render.js';
+export declare function renderRead(result: ObjectReadDTO): string;
+export declare function documentReadParts(result: ObjectReadDTO): {
+    body: string;
+    metadata: string;
+    context: string;
+} | null;
+/** Never mirror bodies into viewer metadata; a head's body belongs in the tool result. */
+export declare function previewRead(result: ObjectReadDTO): Record<string, unknown>;
+export declare function renderReadOutput(result: ObjectReadDTO): string;
+export declare const readLeaf: LeafDef;

package/dist/commands/canvas/read.js

@@ -0,0 +1,10 @@
+var l=Object.defineProperty;var o=(t,e)=>l(t,"name",{value:e,configurable:!0});import{defineLeaf as p}from"../../core/command.js";import{attr as i,header as m,section as f}from"../../core/graph/kinds/render.js";import{PREVIEW_RESULT_PATH_ENV as c}from"../../core/preview-result-path.js";import{isJsonOutput as b}from"../../core/io.js";import{cliClient as w,rethrowAsCliError as y}from"../api-client.js";const j="A name (the `[[ ]]` brackets are optional) or a raw object id. A name is `<owner-handle>/<path>`; a node or other owner is also named by its id or handle.";import{attr as q,objectRow as O}from"../../core/graph/kinds/render.js";function h(t){if(t.state==="remote")return`No object named ${t.remote} on this runtime. It may be on another runtime, or the name may be misspelled.`;if(t.state==="deleted"){const e=t.deleted;return[`${m("deleted",e,i("deleted_at",e.deleted_at))}`,`Last preview: ${e.preview}`,"</deleted>"].join(`
+`)}return`${t.text}
+</object>`}o(h,"renderRead");function u(t){if(t.state!=="object"||t.type!=="document")return null;const e=t.data,n=t.object,r=[m("object",n,i("privacy",n.privacy)+i("revision",e.revision)),`Preview: ${n.preview}`];if(e.summary&&r.push(`Summary: ${e.summary}`),e.fields!==void 0&&r.push(`<fields>
+${JSON.stringify(e.fields,null,2)}
+</fields>`),e.needs_merge&&(e.heads.forEach((a,d)=>r.push(`<head${i("rev",a.rev_id)}${i("number",a.number)}${i("author",a.author_id)}>
+${e.bodies[d]??""}
+</head>`)),r.push(`This document has ${e.heads.length} heads. Your next \`crtr doc edit\` writes the merged body and joins them into one revision.`)),e.listing?.length){const a=e.listing.some(s=>s.owner?.id===n.owner?.id&&s.name.startsWith(`${n.name}/`)),d=e.listing.some(s=>s.owner?.id!==n.owner?.id||!s.name.startsWith(`${n.name}/`));r.push("",...f(a&&d?`Names under ${n.name}/ and documents it links to`:a?`Names under ${n.name}/`:"Documents it links to",e.listing))}return r.push("</object>"),{body:e.needs_merge?"":e.bodies[0]??"",metadata:r.join(`
+`),context:e.attachments??""}}o(u,"documentReadParts");function v(t){const e=u(t);return e===null||t.state!=="object"||b()?t:{state:"object",type:"document",object:t.object,readMetadata:e.metadata,readContext:e.context}}o(v,"previewRead");function g(t){const e=u(t);if(e===null||process.env[c]===void 0&&process.stdout.isTTY)return h(t);const n=`${e.metadata}
+${e.context?`${e.context}
+`:""}`;return process.env[c]||process.stderr.write(n),e.body}o(g,"renderReadOutput");const k=p({name:"read",description:"read one object \u2014 a document, node, job or owner \u2014 by name or id",whenToUse:"you need the content or state of an object you can name: a document\u2019s body, a node\u2019s status and what it owns, a job\u2019s result. Reading makes you a watcher of the object. Find the name first with `crtr canvas search` or `crtr canvas list` when you do not know it.",help:{name:"canvas read",summary:"read one object by name or id and become a watcher of it",params:[{kind:"positional",name:"ref",required:!0,constraint:j},{kind:"flag",name:"fields",type:"bool",required:!1,constraint:"When present, a document read also returns its delivery rules, why-it-exists, unlisted, lint-ignore and plugin extension fields."}],output:[{name:"object",type:"string",required:!0,constraint:"A document prints only its exact body to stdout (including when piped or redirected). Its attributed `<object>` header, preview, summary, revision, listing, linked previews, and `<auto-loaded-context>` arrive AFTER command output in a node\u2019s tool result. Several heads print no stdout body; each head with its text appears in metadata, and the next `crtr doc edit` merges them. Outside a node, metadata goes to stderr when stdout is not a TTY; a TTY shows the full rendering as before. `--json` is unchanged. Non-document objects retain their full rendered stdout."},{name:"deleted",type:"string",required:!1,constraint:"`<deleted \u2026>` with the last preview when the object was deleted."},{name:"remote",type:"string",required:!1,constraint:"A line saying no object has that name on this runtime: it may be on another runtime, or the name may be misspelled."}],outputKind:"object",effects:["A live read records a watch on the object for you (every event subject) and publishes a read event to its other watchers. A deleted or remote answer records nothing."]},run:o(async t=>{try{return{...await w().objects.read(t.ref,t.fields===!0?{fields:!0}:void 0)}}catch(e){y(e)}},"run"),render:o(t=>g(t),"render"),preview:o(t=>v(t),"preview"),stdoutExact:o(t=>u(t)!==null&&!(process.env[c]===void 0&&process.stdout.isTTY),"stdoutExact")});export{j as REF_CONSTRAINT,q as attr,u as documentReadParts,O as objectRow,v as previewRead,k as readLeaf,h as renderRead,g as renderReadOutput};

package/dist/commands/canvas/search.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const searchLeaf: LeafDef;

package/dist/commands/canvas/search.js

@@ -0,0 +1,3 @@
+var o=Object.defineProperty;var r=(e,t)=>o(e,"name",{value:t,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{cliClient as s,rethrowAsCliError as c}from"../api-client.js";import{listItemRow as d}from"./list.js";const p=i({name:"search",description:"search objects by name, preview or body text",whenToUse:"finding an object when you do not know its name \u2014 a document on a topic, a report that mentions something, the exact line a regex matches. Records nothing; read a hit with `crtr canvas read`.",help:{name:"canvas search",summary:"find the objects you can read by text; records nothing",params:[{kind:"positional",name:"text",required:!0,constraint:"Words matched against names, previews and summaries (and document bodies with --body)."},{kind:"flag",name:"body",type:"bool",required:!1,constraint:"When present, also matches document bodies."},{kind:"flag",name:"grep",type:"string",required:!1,constraint:"An ECMAScript regex matched against document body lines; each hit lists its matching lines with line numbers."},{kind:"flag",name:"type",type:"string",required:!1,constraint:"Only objects of this kind: document, node, job, person, app, repo or profile. The daemon rejects a name no kind declares and lists the kinds."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Only objects of this kind."},{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Only objects this owner owns directly: a node id, a handle, or any name `crtr canvas read` accepts."},{kind:"flag",name:"limit",type:"int",required:!1,constraint:"Most hits returned, 1 to 100."}],output:[{name:"items",type:"string[]",required:!0,constraint:"One row per hit, as `crtr canvas list` shows it, followed by the matching body lines when --grep is set."}],outputKind:"object",effects:["None. Searching records no watch."]},run:r(async e=>{const t={text:e.text,...e.body===!0?{body:!0}:{},...e.grep?{grep:e.grep}:{},...e.type?{type:e.type}:{},...e.kind?{kind:e.kind}:{},...e.owner?{owner:e.owner}:{},...e.limit?{limit:e.limit}:{}};try{return{...await s().objects.search(t)}}catch(n){c(n)}},"run"),render:r(e=>{const{items:t}=e;return t.length===0?"No objects match.":t.map(n=>[d(n.object),...(n.matches??[]).map(a=>`    ${a.line}: ${a.text}`)].join(`
+`)).join(`
+`)},"render")});export{p as searchLeaf};

package/dist/commands/canvas/unwatch.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const unwatchLeaf: LeafDef;

package/dist/commands/canvas/unwatch.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var o=(e,t)=>a(e,"name",{value:t,configurable:!0});import{defineLeaf as n}from"../../core/command.js";import{routes as s}from"../../api/routes.js";import{publishToken as c}from"../custom-object/shared.js";import{cliClient as i,rethrowAsCliError as m}from"../api-client.js";import{REF_CONSTRAINT as u}from"./read.js";import{PATTERN_CONSTRAINT as d}from"./watch.js";const b=n({name:"unwatch",description:"stop watching an object as yourself or a custom object",whenToUse:"you or your custom object no longer need an object\u2019s events \u2014 a document you read once, a node whose work no longer concerns you.",help:{name:"canvas unwatch",summary:"remove your or a custom object\u2019s watch, optionally for one pattern only",params:[{kind:"positional",name:"ref",required:!0,constraint:u},{kind:"flag",name:"pattern",type:"string",required:!1,constraint:`Remove only this pattern. ${d} Omit to remove every pattern.`},{kind:"flag",name:"as",type:"string",required:!1,constraint:"Custom-object ref whose watch to remove instead of your node\u2019s. Use an authorized principal or its publish token via CRTR_PUBLISH_TOKEN."}],output:[{name:"unwatched",type:"string",required:!0,constraint:"The object and how many watch patterns were removed."}],outputKind:"object",effects:["Removes the watcher\u2019s patterns on the object; its events stop reaching that receiver. Watches that keep a spawned node in your tree are removed the same way."]},run:o(async e=>{try{const t={...e.pattern?{pattern:e.pattern}:{},...e.as?{watcher:e.as}:{}},r=new URLSearchParams(t);return{...await i().request("DELETE",`${s.objectWatch(e.ref)}?${r}`,void 0,e.as?c(e):void 0)}}catch(t){m(t)}},"run"),render:o(e=>{const{object:t,removed:r}=e;return`<unwatched id="${t.id}" name="${t.name}" removed="${r}">`},"render")});export{b as unwatchLeaf};

package/dist/commands/canvas/watch.d.ts

@@ -0,0 +1,3 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const PATTERN_CONSTRAINT = "An event subject pattern: dot-separated segments, where `*` matches exactly one segment and `>` matches one or more trailing segments. `>` alone matches every event.";
+export declare const watchLeaf: LeafDef;

package/dist/commands/canvas/watch.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(e,t)=>i(e,"name",{value:t,configurable:!0});import{defineLeaf as c}from"../../core/command.js";import{usage as u}from"../../core/errors.js";import{cliClient as d,rethrowAsCliError as h}from"../api-client.js";import{routes as l}from"../../api/routes.js";import{publishToken as f}from"../custom-object/shared.js";import{REF_CONSTRAINT as m}from"./read.js";const p="An event subject pattern: dot-separated segments, where `*` matches exactly one segment and `>` matches one or more trailing segments. `>` alone matches every event.";function a(e,t){if(t===void 0)return;let r;try{r=JSON.parse(t)}catch{r=void 0}if(r===null||typeof r!="object"||Array.isArray(r))throw u(`--${e} must be a JSON object`,{field:e,received:t,next:`Run \`crtr canvas watch -h\` for the --${e} shape.`});return r}n(a,"parseJsonObject");const N=c({name:"watch",description:"watch an object as yourself or as a custom object",whenToUse:"you or a registered custom object should receive an object\u2019s future events \u2014 a document edit, a node report \u2014 without reading it now. Reading already makes you a watcher; use this for patterns or a listening configuration.",help:{name:"canvas watch",summary:"make yourself or a custom object a watcher, optionally for chosen events only",params:[{kind:"positional",name:"ref",required:!0,constraint:m},{kind:"flag",name:"pattern",type:"string",required:!1,repeatable:!0,constraint:`${p} Default \`>\`.`},{kind:"flag",name:"listen",type:"string",required:!1,constraint:'JSON object mapping an event level (1\u201310) to how it reaches you: `{"<level>":"interrupt|steer|after-turn|next-turn"}`. Omitted levels use the watcher\u2019s listening default (your node or --as object).'},{kind:"flag",name:"filter",type:"string",required:!1,constraint:"JSON object of event fields an event must match to be delivered."},{kind:"flag",name:"as",type:"string",required:!1,constraint:"Custom-object ref to watch as instead of your node. Its receiver gets events under its owner\u2019s read rights; use an authorized principal or its publish token via CRTR_PUBLISH_TOKEN."}],output:[{name:"watching",type:"string",required:!0,constraint:"The object and the patterns you now watch it for."}],outputKind:"object",effects:["Records a watch; matching events reach your node or the --as object\u2019s receiver, and the watched object\u2019s other watchers see a watched event."]},run:n(async e=>{const t=a("listen",e.listen),r=a("filter",e.filter),o={...Array.isArray(e.pattern)?{patterns:e.pattern}:{},...t?{config:t}:{},...r?{filter:r}:{},...e.as?{watcher:e.as}:{}};try{return{...await d().request("POST",l.objectWatch(e.ref),o,e.as?f(e):void 0)}}catch(s){h(s)}},"run"),render:n(e=>{const{object:t,patterns:r}=e;return`<watching id="${t.id}" name="${t.name}" patterns="${r.join(" ")}">`},"render")});export{p as PATTERN_CONSTRAINT,N as watchLeaf};

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

@@ -0,0 +1,52 @@
+/** Horizontal bar at eighth-cell resolution, `value` scaled against `max` over
+ *  `cells` columns, padded to exactly `cells`. A non-zero value shows at least
+ *  one eighth, so it never reads as zero. */
+export declare function hbar(value: number, max: number, cells: number): string;
+/** The fills a stacked bar uses, in order. The last one is for "other". */
+export declare const STACK_FILLS: readonly ["█", "▓", "▒", "░"];
+export declare const OTHER_FILL = "\u259A";
+/** One fill per part: the first four parts take `STACK_FILLS`, any later part
+ *  takes `OTHER_FILL`. Callers put "other" last. */
+export declare function stackFill(index: number): string;
+/** A bar of exactly `cells` whole cells split by share of the parts' total.
+ *  Each non-zero part gets at least one cell while cells allow, so a part that
+ *  exists never disappears from the bar. `fills[i]` defaults to `stackFill(i)`. */
+export declare function stackedBar(parts: readonly number[], cells: number, fills?: readonly string[]): string;
+/** The legend for a stacked bar: "█ opus  ▓ sonnet  ▒ codex  ░ gemini  ▚ other". */
+export declare function stackLegend(labels: readonly string[], fills?: readonly string[]): string;
+/** A column chart `rows` high, top row first. Each value is one column of
+ *  `columnWidth` cells, columns separated by `gap` spaces, scaled to the
+ *  largest value at eighth-cell resolution. A non-zero value shows at least ▁. */
+export declare function columnChart(values: readonly number[], rows: number, columnWidth?: number, gap?: number): string[];
+/** A log-scale axis from `minMs` to `maxMs` over `cells` columns. */
+export interface LogAxis {
+    minMs: number;
+    maxMs: number;
+    cells: number;
+}
+/** The column (0 … cells−1) for `ms` on a log axis; values outside the axis
+ *  sit at its end. */
+export declare function logPosition(ms: number, axis: LogAxis): number;
+/** A percentile line on a log axis: `─` from p10 to p90 and `●` at the
+ *  median, padded to exactly `axis.cells`. One sample (p10 = p90) is one `●`. */
+export declare function percentileLine(stats: {
+    p10_ms: number;
+    median_ms: number;
+    p90_ms: number;
+}, axis: LogAxis): string;
+/** Tick labels placed at their log positions over `axis.cells` columns, each
+ *  label starting at its tick; a label that would overlap the previous one is
+ *  dropped. */
+export declare function logAxisLabels(ticks: ReadonlyArray<{
+    ms: number;
+    label: string;
+}>, axis: LogAxis): string;
+/** A ranked list folded to its first `keep` rows plus the rest as one sum, for
+ *  "<n> more …" rows. The rest is undefined when nothing is folded. */
+export declare function foldRanked<T>(rows: readonly T[], keep: number, value: (row: T) => number): {
+    top: T[];
+    rest: {
+        count: number;
+        sum: number;
+    } | undefined;
+};

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

@@ -0,0 +1 @@
+var p=Object.defineProperty;var l=(n,t)=>p(n,"name",{value:t,configurable:!0});const M=["","\u258F","\u258E","\u258D","\u258C","\u258B","\u258A","\u2589"],b="\u2588";function k(n,t,e){if(e<=0)return"";if(t<=0||n<=0)return" ".repeat(e);const o=Math.max(1,Math.round(Math.min(n,t)/t*e*8)),i=Math.floor(o/8);return"\u2588".repeat(i)+M[o%8]+" ".repeat(e-i-(o%8===0?0:1))}l(k,"hbar");const d=["\u2588","\u2593","\u2592","\u2591"],g="\u259A";function s(n){return d[n]??g}l(s,"stackFill");function _(n,t,e){const o=n.reduce((r,a)=>r+Math.max(0,a),0);if(t<=0)return"";if(o<=0)return" ".repeat(t);const i=n.map(r=>Math.max(0,r)/o*t),c=i.map(Math.floor);let h=t-c.reduce((r,a)=>r+a,0);const f=i.map((r,a)=>({i:a,r:r-Math.floor(r)})).sort((r,a)=>a.r-r.r);for(const{i:r}of f){if(h===0)break;c[r]+=1,h-=1}for(let r=0;r<n.length;r+=1){if(n[r]<=0||c[r]>0)continue;let a=0;for(let u=1;u<c.length;u+=1)c[u]>c[a]&&(a=u);if(c[a]<=1)break;c[a]-=1,c[r]=1}return c.map((r,a)=>(e?.[a]??s(a)).repeat(r)).join("")}l(_,"stackedBar");function j(n,t){return n.map((e,o)=>`${t?.[o]??s(o)} ${e}`).join("  ")}l(j,"stackLegend");const L=[" ","\u2581","\u2582","\u2583","\u2584","\u2585","\u2586","\u2587","\u2588"];function E(n,t,e=2,o=1){const i=Math.max(0,...n),c=n.map(f=>f<=0||i<=0?0:Math.max(1,Math.round(f/i*t*8))),h=[];for(let f=t-1;f>=0;f-=1){const r=c.map(a=>{const u=Math.max(0,Math.min(8,a-f*8));return L[u].repeat(e)});h.push(r.join(" ".repeat(o)))}return h}l(E,"columnChart");function m(n,t){if(t.cells<=1)return 0;const e=Math.min(t.maxMs,Math.max(t.minMs,n)),o=Math.log(e/t.minMs)/Math.log(t.maxMs/t.minMs);return Math.round(o*(t.cells-1))}l(m,"logPosition");function F(n,t){const e=Array.from({length:t.cells},()=>" "),o=m(n.p10_ms,t),i=m(n.p90_ms,t);for(let c=o;c<=i;c+=1)e[c]="\u2500";return e[m(n.median_ms,t)]="\u25CF",e.join("")}l(F,"percentileLine");function H(n,t){let e="";for(const o of n){const i=Math.min(m(o.ms,t),Math.max(0,t.cells-o.label.length));i<e.length+(e===""?0:1)||(e=e.padEnd(i)+o.label)}return e.padEnd(t.cells).slice(0,t.cells)}l(H,"logAxisLabels");function I(n,t,e){if(n.length<=t)return{top:[...n],rest:void 0};const o=n.slice(0,Math.max(0,t)),i=n.slice(o.length);return{top:o,rest:{count:i.length,sum:i.reduce((c,h)=>c+e(h),0)}}}l(I,"foldRanked");export{g as OTHER_FILL,d as STACK_FILLS,E as columnChart,I as foldRanked,k as hbar,H as logAxisLabels,m as logPosition,F as percentileLine,s as stackFill,j as stackLegend,_ as stackedBar};

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

@@ -0,0 +1,34 @@
+import type { AnalyticsDTO } from '../../api/dto/analytics.js';
+import { type AnalyticsNav } from './view.js';
+/** A text column shares the free width with the other text columns (at most
+ *  `max` cells); a number column is as wide as its widest value, right-aligned. */
+export interface DrillColumn {
+    header: string;
+    kind: 'text' | 'number';
+    max?: number;
+}
+export interface DrillRow {
+    node_id: string;
+    graph_id: string;
+    cells: string[];
+}
+export declare class AgentDrilldown {
+    private readonly title;
+    private readonly columns;
+    private readonly rows;
+    private readonly nav;
+    private cursor;
+    constructor(title: string, columns: readonly DrillColumn[], rows: readonly DrillRow[], nav: AnalyticsNav);
+    render(width: number, height: number): string[];
+    /** 'close' on Esc: the owning view pops this list. */
+    handleKey(key: string): 'handled' | 'close' | 'unhandled';
+    keyLine(narrow: boolean): string;
+    private line;
+    private widths;
+    /** The selected row's text cells in full, when any of them was cut. */
+    private fullText;
+}
+/** A graph's display name: its graph row (root title, else root name), else
+ *  the root agent's name, else the id. A graph with no active agent in the
+ *  window has no graph row. */
+export declare function graphName(data: AnalyticsDTO, graphId: string): string;

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

@@ -0,0 +1 @@
+var p=Object.defineProperty;var a=(u,e)=>p(u,"name",{value:e,configurable:!0});import{matchesKey as l,visibleWidth as c}from"@earendil-works/pi-tui";import{theme as d}from"../../core/tui/panel.js";import{padLeft as g,padRight as w,truncate as m}from"./format.js";import{listWindow as x,markRow as M,moreRow as _}from"./view.js";const f="  ";class R{static{a(this,"AgentDrilldown")}title;columns;rows;nav;cursor=0;constructor(e,t,n,i){this.title=e,this.columns=t,this.rows=n,this.nav=i}render(e,t){const n=[d.bold(m(this.title,e))];if(this.rows.length===0)return[...n,"None in this window."];const i=this.widths(e);n.push(d.fg("dim",`  ${this.line(this.columns.map(o=>o.header),i)}`));const h=this.fullText(i),s=Math.max(1,t-n.length-(h===void 0?0:1)),r=x(this.rows.length,this.cursor,s);for(let o=r.start;o<r.end;o+=1)n.push(M(this.line(this.rows[o].cells,i),o===this.cursor));return r.more>0&&n.push(_(r.more,"agents")),h!==void 0&&n.push(d.fg("dim",m(`  ${h}`,e))),n}handleKey(e){if(l(e,"escape"))return"close";if(l(e,"down")||l(e,"j"))this.cursor=Math.min(this.rows.length-1,this.cursor+1);else if(l(e,"up")||l(e,"k"))this.cursor=Math.max(0,this.cursor-1);else if(l(e,"enter")){const t=this.rows[this.cursor];t!==void 0&&this.nav.openGraphDetail(t.graph_id,t.node_id)}else return"unhandled";return this.cursor=Math.max(0,this.cursor),"handled"}keyLine(e){return this.rows.length===0?"":e?"\u2191\u2193 Enter":"\u2191\u2193 agent \xB7 Enter: its graph, agent selected"}line(e,t){return e.map((n,i)=>this.columns[i].kind==="number"?g(n,t[i]):w(n,t[i])).join(f)}widths(e){const t=this.columns.map((s,r)=>Math.min(s.max??1/0,Math.max(c(s.header),...this.rows.map(o=>c(o.cells[r]??""))))),n=this.columns.flatMap((s,r)=>s.kind==="text"?[r]:[]),i=t.reduce((s,r,o)=>s+(this.columns[o].kind==="number"?r:0),0);let h=e-2-i-f.length*(this.columns.length-1);return n.sort((s,r)=>t[s]-t[r]),n.forEach((s,r)=>{t[s]=Math.max(4,Math.min(t[s],Math.floor(h/(n.length-r)))),h-=t[s]}),t}fullText(e){const t=this.rows[this.cursor];if(t===void 0)return;const n=t.cells.filter((h,s)=>this.columns[s].kind==="text");return t.cells.some((h,s)=>this.columns[s].kind==="text"&&c(h)>e[s])?n.join(" \xB7 "):void 0}}function $(u,e){const t=u.graphs.ok?u.graphs.value.graphs.find(n=>n.graph_id===e):void 0;return t!==void 0?t.root_deleted?`${t.name} (root deleted)`:t.name:u.agents.find(n=>n.node_id===e)?.name??e}a($,"graphName");export{R as AgentDrilldown,$ as graphName};

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

@@ -0,0 +1,29 @@
+/** API-price estimate: "<$1" under one dollar, whole dollars otherwise ("$4",
+ *  "$1,236"). Exactly zero reads "$0": "<$1" would claim a non-zero amount. */
+export declare function formatPrice(dollars: number): string;
+/** Tokens with 2–3 significant figures and k/M/B ("950", "9.8M", "121M"). */
+export declare function formatTokens(tokens: number): string;
+/** Durations: "<1m", "14m", "1h 30m", "1h", "1d 4h", "2d". Rounded down. */
+export declare function formatDuration(ms: number): string;
+/** Counts with thousands separators ("1,376"). */
+export declare function formatCount(n: number): string;
+/** A 0–1 ratio as a whole percentage ("90%"). */
+export declare function formatShare(ratio: number): string;
+/** "1 graph" / "14 graphs", count formatted. */
+export declare function plural(n: number, one: string, many: string): string;
+/** A failed measure, in place of its numbers. */
+export declare function unavailable(reason: string): string;
+/** Cut to `width` columns, ending in "…" when cut. */
+export declare function truncate(text: string, width: number): string;
+/** Cut or pad to exactly `width` columns, left-aligned. */
+export declare function padRight(text: string, width: number): string;
+/** Cut or pad to exactly `width` columns, right-aligned (numbers). */
+export declare function padLeft(text: string, width: number): string;
+/** Local weekday and time, "Thu 18:00". Arithmetic stays UTC; only labels are local. */
+export declare function formatClock(at: string | number | Date): string;
+/** Local time of day, "18:00". */
+export declare function formatTimeOfDay(at: string | number | Date): string;
+/** Local date and time, "Sep 3 18:00". */
+export declare function formatDateTime(at: string | number | Date): string;
+/** The local timezone abbreviation, "PDT". */
+export declare function formatTimezone(at: string | number | Date): string;

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

@@ -0,0 +1 @@
+var x=Object.defineProperty;var o=(t,n)=>x(t,"name",{value:n,configurable:!0});import{truncateToWidth as d,visibleWidth as s}from"@earendil-works/pi-tui";function D(t){return t===0?"$0":t<1?"<$1":`$${m(Math.round(t))}`}o(D,"formatPrice");const l=[[1e9,"B"],[1e6,"M"],[1e3,"k"]];function S(t){const n=Math.round(t);if(n<1e3)return String(n);for(const[r,a]of l){if(n<r)continue;const e=n/r,p=e<10?e.toFixed(1).replace(/\.0$/,""):String(Math.round(e));return p==="1000"&&a!=="B"?S(r*1e3):`${p}${a}`}return String(n)}o(S,"formatTokens");const i=6e4,u=60*i,f=24*u;function T(t){if(t<i)return"<1m";if(t<u)return`${Math.floor(t/i)}m`;if(t<f){const a=Math.floor(t/u),e=Math.floor(t%u/i);return e===0?`${a}h`:`${a}h ${e}m`}const n=Math.floor(t/f),r=Math.floor(t%f/u);return r===0?`${n}d`:`${n}d ${r}h`}o(T,"formatDuration");function m(t){return t.toLocaleString("en-US")}o(m,"formatCount");function y(t){return`${Math.round(t*100)}%`}o(y,"formatShare");function U(t,n,r){return`${m(t)} ${t===1?n:r}`}o(U,"plural");function k(t){return`unavailable: ${t}`}o(k,"unavailable");function $(t,n){return d(t,Math.max(0,n),"\u2026")}o($,"truncate");function v(t,n){const r=$(t,n);return r+" ".repeat(Math.max(0,n-s(r)))}o(v,"padRight");function N(t,n){const r=$(t,n);return" ".repeat(Math.max(0,n-s(r)))+r}o(N,"padLeft");const c=o(t=>t instanceof Date?t:new Date(t),"toDate");function L(t){const n=c(t);return`${n.toLocaleDateString("en-US",{weekday:"short"})} ${h(n)}`}o(L,"formatClock");function h(t){const n=c(t);return`${String(n.getHours()).padStart(2,"0")}:${String(n.getMinutes()).padStart(2,"0")}`}o(h,"formatTimeOfDay");function b(t){const n=c(t);return`${n.toLocaleDateString("en-US",{month:"short",day:"numeric"})} ${h(n)}`}o(b,"formatDateTime");function w(t){return new Intl.DateTimeFormat("en-US",{timeZoneName:"short"}).formatToParts(c(t)).find(r=>r.type==="timeZoneName")?.value??"local time"}o(w,"formatTimezone");export{L as formatClock,m as formatCount,b as formatDateTime,T as formatDuration,D as formatPrice,y as formatShare,h as formatTimeOfDay,w as formatTimezone,S as formatTokens,N as padLeft,v as padRight,U as plural,$ as truncate,k as unavailable};

package/dist/commands/canvas-analytics/graph-detail.d.ts

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

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

@@ -0,0 +1,2 @@
+var q=Object.defineProperty;var p=(r,t)=>q(r,"name",{value:t,configurable:!0});import{matchesKey as u,visibleWidth as K}from"@earendil-works/pi-tui";import{rule as V,theme as g,wrapText as C}from"../../core/tui/panel.js";import{formatClock as b,formatDuration as U,formatPrice as y,formatTimeOfDay as E,formatTokens as H,padLeft as x,padRight as T,plural as W,unavailable as J}from"./format.js";import{fullNameLine as Q,graphLabel as X}from"./graphs.js";import{isNarrow as Y,listWindow as Z,markRow as I}from"./view.js";const w=6e4,A=[1,2,5,7.5,10,15,30,60,120,180,240],B=[15,30,60,120,180,360,720,1440,2880];function ee(r){const t=new Set(r.map(e=>e.node_id)),o=[...r].sort((e,i)=>Date.parse(e.created)-Date.parse(i.created)||e.node_id.localeCompare(i.node_id)),n=new Map,s=[];for(const e of o)if(e.parent!==null&&t.has(e.parent)){const i=n.get(e.parent)??[];i.push(e),n.set(e.parent,i)}else s.push(e);const a=[],d=p((e,i,l)=>{a.push({agent:e,guide:i+l});const h=n.get(e.node_id)??[],_=l===""?i:i+(l==="\u251C "?"\u2502 ":"  ");h.forEach((v,D)=>d(v,_,D===h.length-1?"\u2514 ":"\u251C "))},"walk");for(const e of s)d(e,"","");return a}p(ee,"treeRows");function R(r){return`${r.guide}${r.agent.kind}  ${r.agent.name}`}p(R,"rowLabel");function te(r){return r<60?`${r}-min`:`${r/60}-hour`}p(te,"slotLabel");function F(r,t,o){const n=-new Date(r).getTimezoneOffset()*w;let s;for(const a of A){const d=a*w,e=Math.floor((r+n)/d)*d-n,i=Math.floor((t-e)/d)+1;if(s={start:e,slotMs:d,slots:i,offset:n},i<=o)break}return s}p(F,"timelineFor");function ne(r,t){const o=r.slotMs/w,n=r.slots*r.slotMs>1440*w,s=n?9:5,d=(B.find(i=>i>=o&&i%o===0&&i/o>=s+2)??B.at(-1))*w;let e="";for(let i=0;i<r.slots&&i<t;i+=1){const l=r.start+i*r.slotMs;if((l+r.offset)%d!==0||i<e.length+(e===""?0:1))continue;const h=n?b(l):E(l);if(i+h.length>t)break;e=e.padEnd(i)+h}return e.padEnd(t).slice(0,t)}p(ne,"axisLine");function se(r,t,o){const n=Date.parse(r.created),s=r.finalized_at===null?void 0:Date.parse(r.finalized_at),a=new Set(r.response_times_ms.map(e=>Math.floor((e-t.start)/t.slotMs)));let d="";for(let e=0;e<Math.min(t.slots,o);e+=1){const i=t.start+e*t.slotMs,l=i+t.slotMs;s!==void 0&&s>=i&&s<l?d+="\u25C6":a.has(e)?d+="\u2588":n<l&&(s===void 0||s>=l)?d+="\u2500":d+=" "}return d.padEnd(o)}p(se,"timelineCells");function oe(r){return r.agent_time_ms!==null?U(r.agent_time_ms):r.lifecycle==="resident"?"resident":"open"}p(oe,"createdToFinal");class re{static{p(this,"GraphDetailView")}ctx;rows;graph;rootName;root;unlisted;cursor=0;report;constructor(t,o,n){this.ctx=t;const s=t.data;this.graph=s.graphs.ok?s.graphs.value.graphs.find(e=>e.graph_id===o):void 0;const a=new Map(s.agents.map(e=>[e.node_id,e])),d=new Map(s.agents.filter(e=>e.graph_id===o&&e.in_graph_detail).map(e=>[e.node_id,e]));for(let e=n===void 0?void 0:a.get(n);e!==void 0&&!d.has(e.node_id);e=e.parent===null?void 0:a.get(e.parent))d.set(e.node_id,e);this.rows=ee([...d.values()]),this.cursor=Math.max(0,this.rows.findIndex(e=>e.agent.node_id===n)),this.unlisted=n!==void 0&&!a.has(n)?this.readerNamed(n):void 0,this.root=s.agents.find(e=>e.graph_id===o&&e.parent===null),this.rootName=this.graph!==void 0?X(this.graph):this.root?.name??o}readerNamed(t){const o=this.ctx.data.memory;return o.ok?[...o.value.read.rows,...o.value.loaded.rows].flatMap(s=>s.readers).find(s=>s.node_id===t):void 0}get selected(){return this.rows[this.cursor]?.agent}handleKey(t){if(this.report!==void 0){if(u(t,"escape")||u(t,"r"))this.report=void 0;else if(u(t,"down")||u(t,"j"))this.report.scroll+=1;else if(u(t,"up")||u(t,"k"))this.report.scroll=Math.max(0,this.report.scroll-1);else return"unhandled";return"handled"}if(u(t,"escape"))return"back";const o=this.selected;if(u(t,"up")||u(t,"k"))this.cursor=Math.max(0,this.cursor-1);else if(u(t,"down")||u(t,"j"))this.cursor=Math.min(this.rows.length-1,this.cursor+1);else{if(o===void 0)return"unhandled";if(u(t,"enter"))this.ctx.nav.openInspector(o.node_id);else if(u(t,"o"))this.ctx.nav.openConversation(o.node_id);else if(u(t,"r")){if(o.final_report_ref===null)return"handled";this.openReport(o.final_report_ref,`${o.kind} ${o.name}`)}else return"unhandled"}return"handled"}openReport(t,o){const n={ref:t,name:o,scroll:0,text:void 0,error:void 0};this.report=n,this.ctx.nav.readFinalReport(t).then(s=>{n.text=s,this.ctx.nav.requestRender()},s=>{n.error=s instanceof Error?s.message:String(s),this.ctx.nav.requestRender()})}keyLine(t){if(this.report!==void 0)return t?"\u2191\u2193":"\u2191\u2193 scroll";if(this.rows.length===0)return"";const o=this.selected?.final_report_ref!==null;return t?["\u2191\u2193 Enter",...o?["r"]:[],"o open, may wake it"].join(" "):["\u2191\u2193 agent \xB7 Enter inspect, read-only",...o?["r final report"]:[],"o open, may wake it"].join(" \xB7 ")}escapeLabel(){return this.report!==void 0?"close report":void 0}render(t,o,n){const s=this.header(t,n),a=this.report!==void 0?this.reportBody(t,o-s.length,this.report):this.treeBody(t,o-s.length);return[...s,...a]}header(t,o){const n=[g.bold(`< Graphs  /  ${this.rootName}`)],s=this.graph,a=p((d,e,i)=>`Root: ${d} \xB7 ${e==="resident"?"resident conversation":"terminal"} \xB7 created ${b(i)}`,"rootLine");return o.graphs.ok?s===void 0?(this.root!==void 0&&n.push(a(this.root.kind,this.root.lifecycle,this.root.created)),n.push("No agent in this graph had a model response in this window.")):(n.push(a(s.root_kind,s.root_lifecycle,s.root_created)),n.push(`${W(s.active_agents,"agent","agents")} \xB7 depth ${s.depth} \xB7 ${H(s.tokens)} tokens \xB7 ${y(s.api_price_estimate)} API-price est.`)):n.push(J(o.graphs.reason)),n.push(V(t)),n}treeBody(t,o){if(!this.ctx.data.graphs.ok||this.rows.length===0)return[];const n=Y(t),s=15,a=9,d=Math.max(0,...this.rows.map(f=>K(R(f))));let e=n?t-2-s-a:Math.max(20,Math.min(d,Math.floor(t*.4)));const i=p(f=>n?0:Math.max(10,t-2-f-1-s-a),"cellsFor");let l=i(e);const h=[],_=this.rows.flatMap(f=>f.agent.response_times_ms),v=Math.min(..._),D=Math.max(..._);let c=!n&&_.length>0?F(v,D,l):void 0;if(c!==void 0&&c.slots>l&&(e=Math.max(20,e-(c.slots-l)),l=i(e),c=F(v,D,l)),!n)if(c===void 0)h.push("Timeline: no model responses in this window.");else{const f=c.start+Math.min(c.slots,l)*c.slotMs,m=new Date(c.start).toDateString()===new Date(f-1).toDateString()?`${E(c.start)}\u2013${E(f)}`:`${b(c.start)}\u2013${b(f)}`;h.push(`Timeline: ${m}, the part of the window with activity`)}const j=c===void 0?" ".repeat(l):ne(c,l);h.push(g.fg("dim",`  ${T("Agent",e)}${n?"":` ${j}`}${x("created\u2192final",s)}${x("est.",a)}`));const S=c===void 0?[]:["",g.fg("dim",`\u2588 ${te(c.slotMs/w)} slot with a model response   \u2500 alive, no response   \u25C6 final report`)],z=this.rows[this.cursor],L=Q(R(z),e),k=this.unlisted!==void 0?g.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.`):void 0,G=S.length+(L!==void 0?1:0)+(k!==void 0?1:0),M=Z(this.rows.length,this.cursor,Math.max(1,o-h.length-G));for(let f=M.start;f<M.end;f+=1){const $=this.rows[f],m=$.agent,N=T(R($),e),O=n?"":` ${c===void 0?" ".repeat(l):se(m,c,l)}`,P=m.active?y(m.api_price_estimate):"\u2014";h.push(I(`${N}${O}${x(oe(m),s)}${x(P,a)}`,f===this.cursor))}if(M.more>0){const f=this.rows.slice(M.end).reduce((m,N)=>m+N.agent.api_price_estimate,0),$=`  ${W(M.more,"more agent","more agents")} \u2193`;h.push(`${T($,t-a)}${x(y(f),a)}`)}return L!==void 0&&h.push(L),k!==void 0&&h.push(k),h.push(...S),h}reportBody(t,o,n){const s=g.bold(`Final report \xB7 ${n.name}`);if(n.error!==void 0)return[s,"",...C(`Could not read the final report: ${n.error}`,t)];if(n.text===void 0)return[s,"","Loading the final report\u2026"];const a=n.text.split(`
+`).flatMap(h=>h.trim()===""?[""]:C(h,t)),d=Math.max(1,o-2);n.scroll=Math.min(n.scroll,Math.max(0,a.length-d));const e=a.slice(n.scroll,n.scroll+d),i=a.length-n.scroll-e.length,l=i>0?g.fg("dim",` \xB7 ${i} more lines \u2193`):"";return[`${s}${l}`,"",...e]}}const fe=p((r,t,o)=>new re(r,t,o),"createGraphDetailView");export{fe as createGraphDetailView};

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;

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

@@ -0,0 +1 @@
+var F=Object.defineProperty;var l=(s,t)=>F(s,"name",{value:t,configurable:!0});import{matchesKey as c,visibleWidth as g}from"@earendil-works/pi-tui";import{rule as E,theme as C,wrapText as K}from"../../core/tui/panel.js";import{foldRanked as B,hbar as A}from"./chart.js";import{formatCount as b,formatPrice as D,formatTokens as Y,padLeft as f,padRight as k,plural as O,unavailable as Z}from"./format.js";import{NARROW_BAR_CELLS as S,isNarrow as q,listWindow as H,markRow as v,moreRow as J,textWidth as Q}from"./view.js";function N(s){return s.root_deleted?`${s.name} (root deleted)`:s.name}l(N,"graphLabel");function U(s,t){return t.api_price_estimate-s.api_price_estimate||s.name.localeCompare(t.name)}l(U,"byEstimate");function T(s,t,e,i){return g(s)<e?`${k(s,e)}${f(t,i)}`:s}l(T,"chartTitle");function X(s,t){return g(s)>t?C.fg("dim",`  ${s}`):void 0}l(X,"fullNameLine");const M=[{key:"estimate",label:"API est.",value:l(s=>s.api_price_estimate,"value")},{key:"agents",label:"agents",value:l(s=>s.active_agents,"value")},{key:"depth",label:"depth",value:l(s=>s.depth,"value")},{key:"tokens",label:"tokens",value:l(s=>s.tokens,"value")}],tt={1:[1,1],"2\u20135":[2,5],"6\u201310":[6,10],"11\u201320":[11,20],"21+":[21,Number.POSITIVE_INFINITY]};function et(s){const t=s.spawned_by_kind,e=t.length>5?B(t,4,n=>n.agents):{top:t,rest:void 0},i=e.top.map(n=>({label:n.kind,agents:n.agents,kinds:[n.kind]}));return e.rest!==void 0&&i.push({label:`${b(e.rest.count)} more kinds`,agents:e.rest.sum,kinds:t.slice(4).map(n=>n.kind)}),i}l(et,"kindRows");const G=l(s=>s==="1"?"1 agent":`${s} agents`,"sizeLabel");class st{static{l(this,"GraphsView")}ctx;zone="list";lastChart="size";sizeIndex=0;kindIndex=0;listIndex=0;sort=0;filter;secondOpen=!1;narrow=!1;constructor(t){this.ctx=t}get graphs(){return this.ctx.data.graphs.ok?this.ctx.data.graphs.value:void 0}get kinds(){return this.graphs===void 0?[]:et(this.graphs)}listed(){const t=this.graphs?.graphs??[],e=M[this.sort],i=this.filter;return t.filter(n=>i===void 0||i.match(n)).sort((n,r)=>e.value(r)-e.value(n)||U(n,r))}get buckets(){const t=this.graphs?.size_buckets??[];return t.some(e=>e.graphs>0)?t:[]}sizeRowCount(){return this.buckets.length+(this.narrow?1:0)}land(t){t.tab==="graphs"&&(this.filter=void 0,this.listIndex=0,t.at==="size-chart"?(this.zone="size",this.lastChart="size",this.sizeIndex=0,this.secondOpen=!1):t.at==="kind-chart"?(this.zone="kind",this.lastChart="kind",this.kindIndex=0,this.secondOpen=!0):(this.zone="list",this.sort=0))}handleKey(t){return this.graphs===void 0?c(t,"escape")?"back":"unhandled":c(t,"escape")?this.narrow&&this.secondOpen?(this.secondOpen=!1,this.zone==="kind"&&(this.zone="size",this.sizeIndex=this.sizeRowCount()-1),this.lastChart="size","handled"):this.filter!==void 0?(this.filter=void 0,this.listIndex=0,"handled"):"back":c(t,"c")?(this.sort=(this.sort+1)%M.length,this.listIndex=0,"handled"):c(t,"up")||c(t,"k")?this.move(-1):c(t,"down")||c(t,"j")?this.move(1):c(t,"left")||c(t,"h")?this.side("size"):c(t,"right")||c(t,"l")?this.side("kind"):c(t,"enter")?this.enter():"unhandled"}visibleChart(){return this.narrow?this.secondOpen?"kind":"size":this.lastChart}move(t){const e=this.listed().length;if(this.zone==="list"){if(t===-1&&this.listIndex===0){const h=this.visibleChart(),o=h==="size"?this.sizeRowCount():this.kinds.length;o>0&&(this.zone=h,h==="size"?this.sizeIndex=o-1:this.kindIndex=o-1)}else this.listIndex=Math.max(0,Math.min(e-1,this.listIndex+t));return"handled"}const i=this.zone==="size"?this.sizeRowCount():this.kinds.length,r=(this.zone==="size"?this.sizeIndex:this.kindIndex)+t;return r>=i?e>0&&(this.lastChart=this.zone,this.zone="list",this.listIndex=0):r>=0&&(this.zone==="size"?this.sizeIndex=r:this.kindIndex=r),"handled"}side(t){if(this.narrow||this.zone==="list"||this.zone===t)return"unhandled";const e=t==="size"?this.sizeRowCount():this.kinds.length;if(e===0)return"handled";const i=this.zone==="size"?this.sizeIndex:this.kindIndex;return this.zone=t,this.lastChart=t,t==="size"?this.sizeIndex=Math.min(i,e-1):this.kindIndex=Math.min(i,e-1),"handled"}enter(){if(this.zone==="list"){const t=this.listed()[this.listIndex];return t!==void 0&&this.ctx.nav.openGraphDetail(t.graph_id),"handled"}if(this.zone==="size"){const t=this.buckets[this.sizeIndex];if(t===void 0)return this.secondOpen=!0,this.zone="kind",this.lastChart="kind",this.kindIndex=0,this.kinds.length===0&&(this.zone="size"),"handled";const[e,i]=tt[t.label];this.filter={label:`graphs with ${G(t.label)}`,match:l(n=>n.active_agents>=e&&n.active_agents<=i,"match")}}else{const t=this.kinds[this.kindIndex];if(t===void 0)return"handled";const e=new Set(t.kinds),i=t.kinds.length===1?`graphs that spawned ${nt(t.label)} in this window`:`graphs that spawned one of the ${t.label} in this window`;this.filter={label:i,match:l(n=>n.spawned_kinds.some(r=>e.has(r)),"match")}}return this.listIndex=0,"handled"}keyLine(t){return this.graphs===void 0?"":t?"\u2190\u2192\u2191\u2193 \xB7 Enter \xB7 c sort":`\u2190\u2192\u2191\u2193 select \xB7 ${this.zone==="list"?"Enter open graph":this.zone==="size"&&this.buckets[this.sizeIndex]===void 0?"Enter open chart":"Enter filter the list"} \xB7 c sort`}escapeLabel(){if(this.narrow&&this.secondOpen)return"close chart";if(this.filter!==void 0)return"clear filter"}render(t,e,i){if(this.narrow=q(t),!i.graphs.ok)return[Z(i.graphs.reason)];const n=i.graphs.value;this.narrow&&this.zone==="kind"&&!this.secondOpen&&(this.zone="size"),this.sizeIndex=Math.min(this.sizeIndex,Math.max(0,this.sizeRowCount()-1));const r=this.narrow?this.narrowCharts(t):this.wideCharts(t),h=this.listLines(t,Math.max(3,e-r.length),n);return[...r,...h]}sizeChart(t){const n=this.narrow?S:Math.max(4,t-2-12-1-6-1),r=T("Agents per graph","graphs",15+n,6),h=this.buckets;if(h.length===0)return[r,"  None in this window."];const o=Math.max(...h.map(a=>a.graphs)),d=h.map((a,z)=>{const x=`${k(G(a.label),12)} ${A(a.graphs,o,n)}${f(b(a.graphs),6)}`;return v(x,this.zone==="size"&&this.sizeIndex===z)});return[r,...d]}kindChart(t){const e=this.kinds,i=Math.max(14,Math.min(this.narrow?14:24,Math.max(0,...e.map(a=>g(a.label))))),n=6,r=this.narrow?S:Math.max(4,t-2-i-1-n-1),h=T("Agents spawned in window, by kind","agents",2+i+1+r,n);if(e.length===0)return[h,"  None in this window."];const o=Math.max(...e.map(a=>a.agents)),d=e.map((a,z)=>{const x=`${k(a.label,i)} ${A(a.agents,o,r)}${f(b(a.agents),n)}`;return v(x,this.zone==="kind"&&this.kindIndex===z)});return[h,...d]}wideCharts(t){const e=Math.floor((t-3)/2),i=t-e-3,n=this.sizeChart(e),r=this.kindChart(i),h=Math.max(n.length,r.length),o=[];for(let d=0;d<h;d+=1)o.push(`${k(n[d]??"",e)} \u2502 ${r[d]??""}`);return o.push(C.fg("border",`${"\u2500".repeat(e+1)}\u2534${"\u2500".repeat(Math.max(0,t-e-2))}`)),o}narrowCharts(t){if(this.secondOpen)return[...this.kindChart(t),E(t)];const e=v("Agents spawned in window, by kind \u2192",this.zone==="size"&&this.sizeIndex===this.buckets.length);return[...this.sizeChart(t),e,E(t)]}listLines(t,e,i){const n=this.narrow,r=M[this.sort],h=`${O(i.count,"graph","graphs")} \xB7 deepest ${O(i.deepest,"level","levels")} below root`,o=n?`sort: ${r.label}`:`sort: ${M.map(u=>u===r?`[${u.label}]`:u.label).join("  ")}`,d=this.listed(),[a,z,x,_]=n?[7,6,9,7]:[9,8,12,9],w=a+z+x+_,P=Math.max(0,...d.map(u=>g(N(u)))),I=n?Math.max(8,Math.min(t,t-2-w)):Math.max(8,Math.min(t-2-w,Q(t-2-w,P,44))),V=n?t:Math.max(2+I+w,g(h)+g(o)+2),L=Math.min(t,V)-g(h)-g(o),p=[L>=2?`${h}${" ".repeat(L)}${o}`:`${h} \xB7 ${o}`];if(this.filter!==void 0){const u=`Filter: ${this.filter.label} \xB7 ${O(d.length,"graph","graphs")} \xB7 Esc clears`;p.push(...K(u,t).map(m=>C.fg("accent",m)))}if(p.push(C.fg("dim",`  ${k("Graph",I)}${f("agents",a)}${f("depth",z)}${f("est.",x)}${f("tokens",_)}`)),d.length===0)return p.push(this.filter!==void 0?"  No graphs match this filter.":"  None in this window."),p;this.listIndex=Math.min(this.listIndex,d.length-1);const W=this.zone==="list"?d[this.listIndex]:void 0,R=W===void 0?void 0:X(N(W),I),j=Math.max(1,e-p.length-(R!==void 0?1:0)),$=H(d.length,this.zone==="list"?this.listIndex:0,j);for(let u=$.start;u<$.end;u+=1){const m=d[u],y=`${k(N(m),I)}${f(b(m.active_agents),a)}${f(b(m.depth),z)}${f(D(m.api_price_estimate),x)}${f(Y(m.tokens),_)}`;p.push(v(y,m===W))}return $.more>0&&p.push(J($.more,"graphs")),R!==void 0&&p.push(R),p}}function nt(s){return/^[aeiou]/i.test(s)?`an ${s}`:`a ${s}`}l(nt,"article");const lt=l(s=>new st(s),"createGraphsView");export{U as byEstimate,lt as createGraphsView,X as fullNameLine,N as graphLabel};

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

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

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

@@ -0,0 +1 @@
+var N=Object.defineProperty;var M=(b,t)=>N(b,"name",{value:t,configurable:!0});import{matchesKey as m,visibleWidth as O}from"@earendil-works/pi-tui";import{columns as S,theme as g,wrapText as v}from"../../core/tui/panel.js";import{foldRanked as j,hbar as B}from"./chart.js";import{AgentDrilldown as K,graphName as T}from"./drilldown.js";import{formatCount as w,formatDateTime as W,padLeft as u,padRight as x,plural as _,truncate as E,unavailable as H}from"./format.js";import{NARROW_BAR_CELLS as V,isNarrow as F,listWindow as U,markRow as C,moreRow as q,textWidth as z}from"./view.js";const L={read:"Read on purpose",loaded:"Loaded automatically"},$={read:{one:"read",many:"reads",verb:"read",first:"first read"},loaded:{one:"load",many:"loads",verb:"loaded",first:"first loaded"}},G="A read does not show whether the document changed the work.",h=7;class I{static{M(this,"MemoryView")}ctx;show="read";cursor=0;doc=0;layers=[];narrow=!1;constructor(t){this.ctx=t}get view(){return this.ctx.data.memory.ok?this.ctx.data.memory.value[this.show]:void 0}count(){const t=this.view?.rows.length??0;return t===0?0:t+(this.narrow?1:0)}render(t,s,e){if(!e.memory.ok)return[`Memory: ${H(e.memory.reason)}`];const o=e.memory.value[this.show],n=F(t);this.narrow=n,n||(this.layers=this.layers.filter(p=>p.kind!=="readers")),this.cursor=Math.min(this.cursor,Math.max(0,this.count()-1));const r=[this.switchLine(),...v(this.summary(o,e),t)],d=v(G,t).map(p=>g.fg("dim",p)),c=this.layers.at(-1);if(c?.kind==="drill")return[...r,"",...c.list.render(t,s-r.length-1)];const a=this.labels(o);if(c?.kind==="readers")return[...r,"",...this.readersChart(o.rows[this.doc],a[this.doc],t,s-r.length-1)];if(o.rows.length===0)return[...r,"",`No documents ${L[this.show].toLowerCase()} in this window.`,"",...d];const l=Math.max(3,s-r.length-1-d.length-1);if(n){const p=this.documents(o,a,t,l-1),A=C(E(`Who ${$[this.show].verb} ${a[this.doc]} \u2192`,t-2),this.cursor===o.rows.length);return[...r,"",...p,A,"",...d]}const f=t-3-2-3*h,k=Math.max(8,...a.map(p=>O(p))),y=2+z(f,k,24)+3*h,i=t-y-3,D=this.documents(o,a,y,l),R=this.readersChart(o.rows[this.doc],a[this.doc],i,l);return R.push("",g.fg("dim",E("Enter: agents and graphs",i))),[...r,"",...S(D,y,R.slice(0,l),i),"",...d]}switchLine(){const t=this.show==="read"?"loaded":"read",s=g.bold(`[${L[this.show]}]`),e=` ${L[t]} `;return`Show: ${this.show==="read"?`${s}  ${e}`:`${e}  ${s}`}`}summary(t,s){const e=$[this.show],o=`${_(t.entries,e.one,e.many)} of ${_(t.documents,"document","documents")} \xB7 ${w(t.agents_with_entry)} of ${_(t.active_agents,"agent","agents")} ${e.verb} at least one`,n=s.memory_log_started_at;return n!==null&&Date.parse(s.window_start)<Date.parse(n)?`${o} \xB7 recorded since ${W(n)}`:o}labels(t){const s=new Map;for(const e of t.rows)s.set(e.name,(s.get(e.name)??0)+1);return t.rows.map(e=>s.get(e.name)>1?`${e.name} \xB7 ${e.scope}`:e.name)}documents(t,s,e,o){const n=Math.max(8,e-2-3*h),r=$[this.show],d=[g.fg("dim",`  ${x("Document",n)}${u(r.many,h)}${u("agents",h)}${u("graphs",h)}`)],c=U(t.rows.length,Math.min(this.cursor,t.rows.length-1),Math.max(1,o-1));for(let a=c.start;a<c.end;a+=1){const l=t.rows[a],f=`${x(s[a],n)}${u(w(l.reads),h)}${u(w(l.agents),h)}${u(w(l.graphs),h)}`;d.push(C(f,a===this.cursor))}return c.more>0&&d.push(q(c.more,"documents")),d}readersChart(t,s,e,o){const n=$[this.show],r=v(`${s} \xB7 who ${n.verb} it`,e).slice(0,2).map(i=>g.bold(i));r.push(g.fg("dim",`${x(`scope: ${t.scope}`,e-h)}${u("agents",h)}`));const d=14,c=this.narrow?V:Math.max(4,e-2-d-1-h),a=Math.max(2,o-r.length-2),{top:l,rest:f}=j(t.readers_by_kind,t.readers_by_kind.length>a?a-1:a,i=>i.agents),k=[...l.map(i=>({label:i.kind,agents:i.agents})),...f!==void 0?[{label:`${_(f.count,"more kind","more kinds")}`,agents:f.sum}]:[]],y=Math.max(0,...k.map(i=>i.agents));for(const i of k)r.push(`  ${x(i.label,d)}${B(i.agents,y,c)} ${u(w(i.agents),h-1)}`);return r}handleKey(t){if(m(t,"t")&&this.ctx.data.memory.ok)return this.show=this.show==="read"?"loaded":"read",this.cursor=0,this.doc=0,this.layers=[],"handled";const s=this.layers.at(-1);if(s?.kind==="drill")return s.list.handleKey(t)==="close"&&this.layers.pop(),"handled";if(s?.kind==="readers")return m(t,"escape")?(this.layers.pop(),"handled"):"unhandled";if(m(t,"escape"))return"back";const e=this.view;if(e===void 0||e.rows.length===0)return"unhandled";if(m(t,"down")||m(t,"j"))this.cursor=Math.min(this.count()-1,this.cursor+1);else if(m(t,"up")||m(t,"k"))this.cursor=Math.max(0,this.cursor-1);else return m(t,"enter")?(this.cursor<e.rows.length?this.layers.push({kind:"drill",list:this.drill(e,this.cursor)}):this.layers.push({kind:"readers"}),"handled"):"unhandled";return this.cursor<e.rows.length&&(this.doc=this.cursor),"handled"}drill(t,s){const e=this.ctx.data,o=t.rows[s],n=$[this.show];return new K(`${this.labels(t)[s]} \xB7 agents that ${n.verb} it`,[{header:"kind",kind:"text",max:18},{header:"agent",kind:"text"},{header:"graph",kind:"text"},{header:n.many,kind:"number"},{header:n.first,kind:"number"}],o.readers.map(r=>({node_id:r.node_id,graph_id:r.graph_id,cells:[r.kind,r.name,T(e,r.graph_id),w(r.reads),W(r.first_at)]})),this.ctx.nav)}keyLine(t){const s=this.layers.at(-1),e=t?"t":`t ${this.show==="read"?"loaded automatically":"read on purpose"}`;return s?.kind==="drill"?[s.list.keyLine(t),e].filter(o=>o!=="").join(" \xB7 "):s?.kind==="readers"||(this.view?.rows.length??0)===0?e:[t?"\u2191\u2193 Enter":`\u2191\u2193 document \xB7 Enter: agents that ${$[this.show].verb} it`,e].join(" \xB7 ")}escapeLabel(){const t=this.layers.at(-1);if(t?.kind==="drill")return"back to documents";if(t?.kind==="readers")return"back"}land(){this.show="read",this.layers=[],this.cursor=0,this.doc=0}}const et=M(b=>new I(b),"createMemoryView");export{et as createMemoryView};

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

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