@pat-lewczuk/cezar 0.1.2 → 0.1.4

package/dist/core/process-usage.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Live process telemetry for the Runs table (#348): while any run has a
+ * registered backend process, ONE `ps` snapshot every ~2 s is aggregated per
+ * run over the process's full descendant tree (the CLI plus every Bash child
+ * an agent spawned) into `{ cpuPct, rssBytes, procCount }`.
+ *
+ * Design constraints, in order:
+ *  - never affect a run — a missing/failing `ps` (Windows, exotic containers)
+ *    degrades silently to "no data";
+ *  - one shared sampler, not one per run — N parallel runs still cost a
+ *    single `ps` every tick, and the timer is unref()ed and stopped the
+ *    moment the registry empties, so an idle cockpit spawns nothing;
+ *  - parsing + tree aggregation are pure functions, testable against canned
+ *    `ps` output (scripts/test-process-usage.mjs).
+ */
+/** One aggregated sample for a run's process tree. */
+export interface ProcessUsage {
+    /** Sum of `%cpu` across the tree — can exceed 100 on multi-core work. */
+    cpuPct: number;
+    /** Sum of resident set sizes, in bytes. */
+    rssBytes: number;
+    /** Number of live processes in the tree, the root included. */
+    procCount: number;
+}
+/** One parsed `ps` row (`pid ppid rss %cpu`; rss is in KB, ps's unit). */
+export interface ProcStat {
+    pid: number;
+    ppid: number;
+    rssKb: number;
+    cpuPct: number;
+}
+/**
+ * Parse `ps -axo pid=,ppid=,rss=,%cpu=` output (the `=` suffixes suppress
+ * headers on darwin and linux alike). Malformed lines are skipped — `ps`
+ * racing process exits can truncate rows.
+ */
+export declare function parsePsOutput(text: string): ProcStat[];
+/**
+ * Aggregate the full descendant tree rooted at `rootPid` from one `ps`
+ * snapshot. Null when the root is gone (process exited between register and
+ * sample) — callers treat that as "no data", not zero usage.
+ */
+export declare function aggregateTreeUsage(procs: ProcStat[], rootPid: number): ProcessUsage | null;
+export declare const SAMPLE_INTERVAL_MS = 2000;
+type UsageListener = (usage: Record<string, ProcessUsage>) => void;
+/** Start tracking a run's process tree. A re-register (a run's next agent
+ *  step) replaces the pid but keeps nothing else — peaks are per session and
+ *  the engine maxes them into the run record on unregister. */
+export declare function registerRunProcess(runId: string, pid: number): void;
+/** Stop tracking; returns the session's peaks (undefined when no sample ever
+ *  landed — `ps` unavailable, or the process died before the first tick). */
+export declare function unregisterRunProcess(runId: string): {
+    peakRssBytes: number;
+    peakProcCount: number;
+} | undefined;
+/** Latest sample for one run, if any. */
+export declare function currentUsage(runId: string): ProcessUsage | undefined;
+/** Latest samples for every registered run that has data. */
+export declare function allUsage(): Record<string, ProcessUsage>;
+/** Subscribe to fresh samples (fires ~every 2 s while runs are registered);
+ *  returns the unsubscribe. The SSE endpoint relays these to the GUI. */
+export declare function onUsage(listener: UsageListener): () => void;
+export {};

package/dist/core/process-usage.js

@@ -0,0 +1,181 @@
+/**
+ * Live process telemetry for the Runs table (#348): while any run has a
+ * registered backend process, ONE `ps` snapshot every ~2 s is aggregated per
+ * run over the process's full descendant tree (the CLI plus every Bash child
+ * an agent spawned) into `{ cpuPct, rssBytes, procCount }`.
+ *
+ * Design constraints, in order:
+ *  - never affect a run — a missing/failing `ps` (Windows, exotic containers)
+ *    degrades silently to "no data";
+ *  - one shared sampler, not one per run — N parallel runs still cost a
+ *    single `ps` every tick, and the timer is unref()ed and stopped the
+ *    moment the registry empties, so an idle cockpit spawns nothing;
+ *  - parsing + tree aggregation are pure functions, testable against canned
+ *    `ps` output (scripts/test-process-usage.mjs).
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Parse `ps -axo pid=,ppid=,rss=,%cpu=` output (the `=` suffixes suppress
+ * headers on darwin and linux alike). Malformed lines are skipped — `ps`
+ * racing process exits can truncate rows.
+ */
+export function parsePsOutput(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 4)
+            continue;
+        const pid = Number(parts[0]);
+        const ppid = Number(parts[1]);
+        const rssKb = Number(parts[2]);
+        const cpuPct = Number(parts[3]);
+        if (!Number.isInteger(pid) || !Number.isInteger(ppid))
+            continue;
+        out.push({
+            pid,
+            ppid,
+            rssKb: Number.isFinite(rssKb) && rssKb > 0 ? rssKb : 0,
+            cpuPct: Number.isFinite(cpuPct) && cpuPct > 0 ? cpuPct : 0,
+        });
+    }
+    return out;
+}
+/**
+ * Aggregate the full descendant tree rooted at `rootPid` from one `ps`
+ * snapshot. Null when the root is gone (process exited between register and
+ * sample) — callers treat that as "no data", not zero usage.
+ */
+export function aggregateTreeUsage(procs, rootPid) {
+    const byPid = new Map();
+    const children = new Map();
+    for (const p of procs) {
+        byPid.set(p.pid, p);
+        const siblings = children.get(p.ppid);
+        if (siblings)
+            siblings.push(p.pid);
+        else
+            children.set(p.ppid, [p.pid]);
+    }
+    if (!byPid.has(rootPid))
+        return null;
+    let cpuPct = 0;
+    let rssKb = 0;
+    let procCount = 0;
+    const queue = [rootPid];
+    const seen = new Set(); // pid-reuse in a torn snapshot can't loop us
+    while (queue.length > 0) {
+        const pid = queue.pop();
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        const p = byPid.get(pid);
+        if (!p)
+            continue;
+        cpuPct += p.cpuPct;
+        rssKb += p.rssKb;
+        procCount += 1;
+        for (const child of children.get(pid) ?? [])
+            queue.push(child);
+    }
+    return { cpuPct: Math.round(cpuPct * 10) / 10, rssBytes: rssKb * 1024, procCount };
+}
+// ---- registry + sampler -----------------------------------------------------
+export const SAMPLE_INTERVAL_MS = 2_000;
+const entries = new Map();
+const listeners = new Set();
+let timer = null;
+let sampling = false;
+/** Start tracking a run's process tree. A re-register (a run's next agent
+ *  step) replaces the pid but keeps nothing else — peaks are per session and
+ *  the engine maxes them into the run record on unregister. */
+export function registerRunProcess(runId, pid) {
+    entries.set(runId, { pid, peakRssBytes: 0, peakProcCount: 0 });
+    if (!timer) {
+        timer = setInterval(() => void sample(), SAMPLE_INTERVAL_MS);
+        timer.unref?.();
+        void sample(); // first data point right away, not 2 s late
+    }
+}
+/** Stop tracking; returns the session's peaks (undefined when no sample ever
+ *  landed — `ps` unavailable, or the process died before the first tick). */
+export function unregisterRunProcess(runId) {
+    const entry = entries.get(runId);
+    entries.delete(runId);
+    if (entries.size === 0 && timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+    if (!entry || entry.peakProcCount === 0)
+        return undefined;
+    return { peakRssBytes: entry.peakRssBytes, peakProcCount: entry.peakProcCount };
+}
+/** Latest sample for one run, if any. */
+export function currentUsage(runId) {
+    return entries.get(runId)?.last;
+}
+/** Latest samples for every registered run that has data. */
+export function allUsage() {
+    const out = {};
+    for (const [runId, entry] of entries) {
+        if (entry.last)
+            out[runId] = entry.last;
+    }
+    return out;
+}
+/** Subscribe to fresh samples (fires ~every 2 s while runs are registered);
+ *  returns the unsubscribe. The SSE endpoint relays these to the GUI. */
+export function onUsage(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+async function sample() {
+    if (sampling || entries.size === 0)
+        return;
+    sampling = true;
+    try {
+        const text = await runPs();
+        if (text === null)
+            return; // ps unavailable — degrade to no data
+        const procs = parsePsOutput(text);
+        for (const entry of entries.values()) {
+            const usage = aggregateTreeUsage(procs, entry.pid);
+            entry.last = usage ?? undefined;
+            if (usage) {
+                entry.peakRssBytes = Math.max(entry.peakRssBytes, usage.rssBytes);
+                entry.peakProcCount = Math.max(entry.peakProcCount, usage.procCount);
+            }
+        }
+        if (listeners.size > 0) {
+            const snapshot = allUsage();
+            for (const listener of listeners) {
+                try {
+                    listener(snapshot);
+                }
+                catch {
+                    // a broken SSE stream must not kill the sampler
+                }
+            }
+        }
+    }
+    finally {
+        sampling = false;
+    }
+}
+/** One system-wide snapshot in the `pid ppid rssKb cpu` shape `parsePsOutput` expects; null on
+ *  any failure. Unix uses `ps`; Windows uses PowerShell's Win32_Process (WorkingSetSize → KB,
+ *  cpu reported as 0 — the memory guard only needs RSS). */
+function runPs() {
+    if (process.platform === 'win32') {
+        return new Promise((resolve) => {
+            execFile('powershell', [
+                '-NoProfile',
+                '-Command',
+                "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId) $($_.ParentProcessId) $([math]::Round($_.WorkingSetSize/1024)) 0\" }",
+            ], { maxBuffer: 16 * 1024 * 1024, windowsHide: true }, (err, stdout) => resolve(err ? null : stdout));
+        });
+    }
+    return new Promise((resolve) => {
+        execFile('ps', ['-axo', 'pid=,ppid=,rss=,%cpu='], { maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => resolve(err ? null : stdout));
+    });
+}
+//# sourceMappingURL=process-usage.js.map

package/dist/core/process-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-usage.js","sourceRoot":"","sources":["../../src/core/process-usage.ts"],"names":[],"mappings":"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"}

package/dist/core/runner-factory.d.ts

@@ -0,0 +1,8 @@
+import type { AgentBackend, AgentRunner, RunnerId } from './agent-runner.js';
+/**
+ * The single place that maps a backend id onto a concrete runner. Everything
+ * that used to `new ClaudeCliRunner()` (the planner and the workflow engine)
+ * goes through here so switching the agent backend is one function call.
+ * `claude-cli` is the legacy id for `claude`.
+ */
+export declare function createRunner(backend: AgentBackend | RunnerId | undefined): AgentRunner;

package/dist/core/runner-factory.js

@@ -0,0 +1,22 @@
+import { ClaudeCliRunner } from './claude-cli-runner.js';
+import { CodexAppServerRunner } from './codex-app-server-runner.js';
+import { OpencodeServerRunner } from './opencode-server-runner.js';
+/**
+ * The single place that maps a backend id onto a concrete runner. Everything
+ * that used to `new ClaudeCliRunner()` (the planner and the workflow engine)
+ * goes through here so switching the agent backend is one function call.
+ * `claude-cli` is the legacy id for `claude`.
+ */
+export function createRunner(backend) {
+    switch (backend) {
+        case 'codex':
+            return new CodexAppServerRunner();
+        case 'opencode':
+            return new OpencodeServerRunner();
+        case 'claude':
+        case 'claude-cli':
+        default:
+            return new ClaudeCliRunner();
+    }
+}
+//# sourceMappingURL=runner-factory.js.map

package/dist/core/runner-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-factory.js","sourceRoot":"","sources":["../../src/core/runner-factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4C;IACvE,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,IAAI,oBAAoB,EAAE,CAAC;QACpC,KAAK,UAAU;YACb,OAAO,IAAI,oBAAoB,EAAE,CAAC;QACpC,KAAK,QAAQ,CAAC;QACd,KAAK,YAAY,CAAC;QAClB;YACE,OAAO,IAAI,eAAe,EAAE,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/core/tool-display.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tool display model — turns a backend tool name + raw input into the
+ * `{toolKind, title, subtitle?}` a tool card renders. Computed ONCE here in
+ * the protocol layer (paseo's pattern), never in components, so the thread,
+ * activity groups and notifications all say the same thing.
+ *
+ * Pure function over untrusted input: tool inputs come off the wire and may
+ * be null, partial (streamed incrementally) or arbitrarily malformed —
+ * `toolDisplay` must never throw.
+ *
+ * Known names covered (matched case-insensitively so claude's `Bash` and
+ * opencode's `bash` share one row):
+ *  - claude:   Bash, Edit, Write, NotebookEdit, Read, Glob, Grep, WebFetch,
+ *              WebSearch, Task, TodoWrite, mcp__server__tool
+ *  - codex:    commandExecution, fileChange, mcpToolCall, webSearch,
+ *              todoList, plan
+ *  - opencode: bash, edit, write, read, grep, glob, webfetch, task, todowrite
+ */
+import type { ToolKind } from './ui-events.js';
+export interface ToolDisplay {
+    toolKind: ToolKind;
+    /** Human line for the card trigger, e.g. "Ran npm test". */
+    title: string;
+    /** Secondary detail, e.g. the claude Bash `description`. */
+    subtitle?: string;
+}
+export declare function toolDisplay(name: string, input?: unknown): ToolDisplay;

package/dist/core/tool-display.js

@@ -0,0 +1,150 @@
+/**
+ * Tool display model — turns a backend tool name + raw input into the
+ * `{toolKind, title, subtitle?}` a tool card renders. Computed ONCE here in
+ * the protocol layer (paseo's pattern), never in components, so the thread,
+ * activity groups and notifications all say the same thing.
+ *
+ * Pure function over untrusted input: tool inputs come off the wire and may
+ * be null, partial (streamed incrementally) or arbitrarily malformed —
+ * `toolDisplay` must never throw.
+ *
+ * Known names covered (matched case-insensitively so claude's `Bash` and
+ * opencode's `bash` share one row):
+ *  - claude:   Bash, Edit, Write, NotebookEdit, Read, Glob, Grep, WebFetch,
+ *              WebSearch, Task, TodoWrite, mcp__server__tool
+ *  - codex:    commandExecution, fileChange, mcpToolCall, webSearch,
+ *              todoList, plan
+ *  - opencode: bash, edit, write, read, grep, glob, webfetch, task, todowrite
+ */
+/** Longest title/subtitle we emit — display truncation belongs here, not in
+ *  every component that renders a tool line. */
+const MAX_LABEL = 120;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Collapse whitespace (multi-line commands become one line) and cap length. */
+function oneLine(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length > MAX_LABEL ? `${collapsed.slice(0, MAX_LABEL - 1)}…` : collapsed;
+}
+/** First non-empty string among `input[keys...]`, normalized for display. */
+function field(input, ...keys) {
+    if (!isRecord(input))
+        return undefined;
+    for (const key of keys) {
+        const value = input[key];
+        if (typeof value === 'string' && value.trim() !== '')
+            return oneLine(value);
+    }
+    return undefined;
+}
+/** claude Bash carries `command: string`; codex commandExecution may carry
+ *  a string or an argv array — join the string members. */
+function commandText(input) {
+    if (!isRecord(input))
+        return undefined;
+    const command = input.command;
+    if (typeof command === 'string' && command.trim() !== '')
+        return oneLine(command);
+    if (Array.isArray(command)) {
+        const argv = command.filter((part) => typeof part === 'string');
+        if (argv.length > 0)
+            return oneLine(argv.join(' '));
+    }
+    return undefined;
+}
+/** File paths listed by a codex `fileChange` item (`changes: [{path}]`). */
+function changePaths(input) {
+    if (!isRecord(input) || !Array.isArray(input.changes))
+        return [];
+    const paths = [];
+    for (const change of input.changes) {
+        if (isRecord(change) && typeof change.path === 'string' && change.path.trim() !== '') {
+            paths.push(change.path);
+        }
+    }
+    return paths;
+}
+/** The opencode research heuristic for unknown tools: the first plausible
+ *  human label in the input, in a fixed priority order. */
+function heuristicLabel(input) {
+    return field(input, 'description', 'query', 'url', 'filePath', 'file_path', 'path', 'pattern', 'name');
+}
+/** Verb + optional object → "Read src/a.ts", or just the verb when the
+ *  input gave us nothing usable. */
+function titled(verb, label) {
+    return label ? `${verb} ${label}` : verb;
+}
+export function toolDisplay(name, input) {
+    const key = typeof name === 'string' ? name.toLowerCase() : '';
+    switch (key) {
+        case 'bash':
+        case 'commandexecution':
+            return {
+                toolKind: 'execute',
+                title: titled('Ran', commandText(input)),
+                subtitle: field(input, 'description'),
+            };
+        case 'edit':
+        case 'multiedit':
+            return { toolKind: 'edit', title: titled('Edit', field(input, 'file_path', 'filePath', 'path')) };
+        case 'write':
+            return { toolKind: 'edit', title: titled('Write', field(input, 'file_path', 'filePath', 'path')) };
+        case 'notebookedit':
+            return {
+                toolKind: 'edit',
+                title: titled('Edit', field(input, 'notebook_path', 'notebookPath', 'file_path', 'filePath', 'path')),
+            };
+        case 'filechange': {
+            const paths = changePaths(input);
+            const label = paths.length === 1 ? paths[0] : paths.length > 1 ? `${paths.length} files` : undefined;
+            return { toolKind: 'edit', title: titled('Edit', label) };
+        }
+        case 'read':
+            return { toolKind: 'read', title: titled('Read', field(input, 'file_path', 'filePath', 'path')) };
+        case 'glob':
+        case 'grep':
+            return {
+                toolKind: 'search',
+                title: titled('Search', field(input, 'pattern', 'query')),
+                subtitle: field(input, 'path'),
+            };
+        case 'webfetch':
+            return { toolKind: 'fetch', title: titled('Fetch', field(input, 'url')) };
+        case 'websearch':
+            return { toolKind: 'fetch', title: titled('Web search', field(input, 'query')) };
+        case 'task': {
+            const description = field(input, 'description', 'prompt');
+            return {
+                toolKind: 'task',
+                title: description ? `Task: ${description}` : 'Task',
+                subtitle: field(input, 'subagent_type', 'subagentType'),
+            };
+        }
+        case 'todowrite':
+        case 'todolist':
+        case 'plan':
+            return { toolKind: 'plan', title: 'Update plan' };
+        case 'mcptoolcall': {
+            const server = field(input, 'server');
+            const tool = field(input, 'tool');
+            if (server && tool)
+                return { toolKind: 'other', title: `${server}.${tool}` };
+            return { toolKind: 'other', title: 'MCP tool', subtitle: heuristicLabel(input) };
+        }
+    }
+    // claude/opencode MCP tools are named `mcp__server__tool` → "server.tool".
+    if (key.startsWith('mcp__')) {
+        const parts = name.split('__').filter((part) => part !== '');
+        if (parts.length >= 3) {
+            return { toolKind: 'other', title: `${parts[1]}.${parts.slice(2).join('__')}` };
+        }
+    }
+    // Unknown tool: keep the backend's name as the title, heuristic subtitle.
+    return {
+        toolKind: 'other',
+        title: typeof name === 'string' && name.trim() !== '' ? oneLine(name) : 'Tool',
+        subtitle: heuristicLabel(input),
+    };
+}
+//# sourceMappingURL=tool-display.js.map

package/dist/core/tool-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-display.js","sourceRoot":"","sources":["../../src/core/tool-display.ts"],"names":[],"mappings":"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"}