@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/sessions-picker.js

@@ -1,10 +1,40 @@
+/**
+ * Interactive session picker and preview renderer.
+ *
+ * Powers the fuzzy-searchable session list shown by `agents sessions` in a TTY.
+ * Builds a compact preview for each session (prompt, activity summary, last
+ * response) and delegates to the generic `itemPicker` for the interactive UI.
+ */
 import chalk from 'chalk';
-import { parseSession } from '../lib/session/parse.js';
+import { parseSession, sanitizeForTerminal } from '../lib/session/parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from '../lib/session/prompt.js';
 import { linkPath, relativeToCwd } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
+/**
+ * SessionMeta originates in discover.ts (gitBranch, cwd, label, etc. read from
+ * untrusted session files). parseSession sanitizes event payloads at its
+ * chokepoint, but meta fields bypass that path. Strip terminal escapes here
+ * before any meta string reaches a TTY.
+ */
+function sanitizeMeta(s) {
+    const clean = (v) => (v == null ? v : sanitizeForTerminal(v));
+    return {
+        ...s,
+        id: sanitizeForTerminal(s.id),
+        shortId: sanitizeForTerminal(s.shortId),
+        filePath: sanitizeForTerminal(s.filePath),
+        cwd: clean(s.cwd),
+        project: clean(s.project),
+        gitBranch: clean(s.gitBranch),
+        version: clean(s.version),
+        account: clean(s.account),
+        topic: clean(s.topic),
+        label: clean(s.label),
+    };
+}
 const previewCache = new Map();
+/** Build a cached multi-line preview string for display in the session picker. */
 export function buildPreview(session) {
     const cached = previewCache.get(session.id);
     if (cached)
@@ -15,12 +45,13 @@ export function buildPreview(session) {
         events = parseSession(session.filePath, session.agent);
     }
     catch (err) {
-        parseError = err.message;
+        parseError = sanitizeForTerminal(err?.message ?? String(err));
     }
-    const header = formatHeader(session, events);
+    const safe = sanitizeMeta(session);
+    const header = formatHeader(safe, events);
     const body = parseError
         ? '  ' + chalk.red(`Failed to parse session: ${parseError}`)
-        : formatCompactPreview(events, session);
+        : formatCompactPreview(events, safe);
     const output = [header, '', body].filter(Boolean).join('\n');
     previewCache.set(session.id, output);
     return output;
@@ -63,7 +94,7 @@ function formatHeader(session, events) {
     }
     if (session.label)
         line3.push(chalk.white(session.label));
-    line3.push(chalk.gray(session.id));
+    line3.push(chalk.gray(linkPath(session.filePath, session.id)));
     return [
         line1.join(DOT),
         line2.join(DOT),
@@ -140,6 +171,8 @@ function stripTags(text) {
     return cleaned;
 }
 const LAST_RESPONSE_MAX_LINES = 15;
+const LAST_RESPONSE_MAX_LINES_WITH_TODOS = 8;
+const TODOS_MAX_ITEMS = 5;
 function formatCompactPreview(events, session) {
     let firstUser = '';
     let lastAssistant = '';
@@ -147,6 +180,7 @@ function formatCompactPreview(events, session) {
     const filesRead = new Set();
     let toolCalls = 0;
     let planFile = '';
+    let latestTodos = null;
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user' && !firstUser && event.content) {
@@ -170,6 +204,9 @@ function formatCompactPreview(events, session) {
             if (!planFile && p && /\/plans\/[^/]+\.md$/.test(p)) {
                 planFile = p;
             }
+            if (tool === 'TodoWrite' && Array.isArray(event.args?.todos)) {
+                latestTodos = event.args.todos;
+            }
             toolCalls++;
         }
     }
@@ -195,8 +232,15 @@ function formatCompactPreview(events, session) {
         const basename = planFile.split('/').pop() || planFile;
         lines.push(chalk.cyan('Plan: ') + chalk.white(linkPath(planFile, basename)));
     }
+    const todosRendered = latestTodos ? renderTodos(latestTodos, termWidth) : [];
+    if (todosRendered.length > 0) {
+        lines.push(chalk.cyan('Todos:'));
+        for (const l of todosRendered)
+            lines.push('  ' + l);
+    }
     if (lastAssistant) {
-        const rendered = renderLastResponse(lastAssistant);
+        const maxLines = todosRendered.length > 0 ? LAST_RESPONSE_MAX_LINES_WITH_TODOS : LAST_RESPONSE_MAX_LINES;
+        const rendered = renderLastResponse(lastAssistant, maxLines);
         if (rendered.length > 0) {
             lines.push('');
             lines.push(chalk.cyan('Last response:'));
@@ -209,7 +253,7 @@ function formatCompactPreview(events, session) {
     }
     return lines.map(l => '  ' + l).join('\n');
 }
-function renderLastResponse(content) {
+function renderLastResponse(content, maxLines = LAST_RESPONSE_MAX_LINES) {
     const cleaned = stripTags(content).trim();
     if (!cleaned)
         return [];
@@ -226,16 +270,50 @@ function renderLastResponse(content) {
         all.shift();
     while (all.length && !all[all.length - 1].trim())
         all.pop();
-    if (all.length <= LAST_RESPONSE_MAX_LINES)
+    if (all.length <= maxLines)
         return all;
-    const shown = all.slice(0, LAST_RESPONSE_MAX_LINES);
-    const more = all.length - LAST_RESPONSE_MAX_LINES;
+    const shown = all.slice(0, maxLines);
+    const more = all.length - maxLines;
     shown.push(chalk.gray(`… (${more} more line${more === 1 ? '' : 's'})`));
     return shown;
 }
+function renderTodos(todos, termWidth) {
+    const out = [];
+    const shown = todos.slice(0, TODOS_MAX_ITEMS);
+    // Outer body indent (2) + inner '  ' (2) + marker (3) + space (1) = 8
+    const maxText = Math.max(20, termWidth - 8);
+    for (const item of shown) {
+        const rawText = (item.content || item.text || '').trim();
+        if (!rawText)
+            continue;
+        const text = truncate(rawText, maxText);
+        const status = item.status || 'pending';
+        let marker;
+        let textOut;
+        if (status === 'completed') {
+            marker = chalk.green('[x]');
+            textOut = chalk.gray(text);
+        }
+        else if (status === 'in_progress') {
+            marker = chalk.yellow('[>]');
+            textOut = chalk.white(text);
+        }
+        else {
+            marker = chalk.gray('[ ]');
+            textOut = chalk.white(text);
+        }
+        out.push(marker + ' ' + textOut);
+    }
+    if (todos.length > TODOS_MAX_ITEMS) {
+        const more = todos.length - TODOS_MAX_ITEMS;
+        out.push(chalk.gray(`… (${more} more)`));
+    }
+    return out;
+}
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max - 1) + '…' : s;
 }
+/** Show an interactive session picker and return the selected session with its action (resume or view). */
 export async function sessionPicker(config) {
     const picked = await itemPicker({
         message: config.message,
@@ -253,4 +331,3 @@ export async function sessionPicker(config) {
         return null;
     return { session: picked.item, action: 'resume' };
 }
-//# sourceMappingURL=sessions-picker.js.map

package/dist/commands/sessions-tail.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from 'commander';
+export interface TailFileOptions {
+    /** If true, emit every line from byte 0 first, then follow. Default false (EOF). */
+    fromStart?: boolean;
+}
+/**
+ * Tail a file: emit each newline-terminated line via onLine as it's written.
+ *
+ * Returns a promise that resolves when the AbortController fires. Uses
+ * fs.watch on the parent directory (more reliable on macOS than watching
+ * the file directly) and tracks byte offset to avoid re-reading content.
+ *
+ * Emits each line exactly once. Handles partial lines across reads, file
+ * truncation (offset reset), and files that don't exist yet (watches the
+ * parent dir until the file appears).
+ */
+export declare function tailFile(filePath: string, onLine: (line: string) => void, ac: AbortController, opts?: TailFileOptions): Promise<void>;
+/** Attach the `tail` subcommand to an existing `sessions` command. */
+export declare function registerSessionsTailCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-tail.js

@@ -0,0 +1,235 @@
+/**
+ * Live-tail a session file and stream new events as they're written.
+ *
+ * Implements `agents sessions tail` — position-tracked reader on the session
+ * JSONL, driven by an fs.watch on the parent directory. Claude and Codex
+ * only for v1 (both use append-only JSONL).
+ */
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+import chalk from 'chalk';
+import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+const TAIL_SUPPORTED = ['claude', 'codex'];
+/**
+ * Tail a file: emit each newline-terminated line via onLine as it's written.
+ *
+ * Returns a promise that resolves when the AbortController fires. Uses
+ * fs.watch on the parent directory (more reliable on macOS than watching
+ * the file directly) and tracks byte offset to avoid re-reading content.
+ *
+ * Emits each line exactly once. Handles partial lines across reads, file
+ * truncation (offset reset), and files that don't exist yet (watches the
+ * parent dir until the file appears).
+ */
+export async function tailFile(filePath, onLine, ac, opts = {}) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    let fd = null;
+    let offset = 0;
+    let partial = '';
+    let reading = false;
+    let dirty = false;
+    const openIfPossible = async (initial) => {
+        try {
+            fd = await fsp.open(filePath, 'r');
+        }
+        catch {
+            return false;
+        }
+        if (initial) {
+            const st = await fd.stat();
+            offset = opts.fromStart ? 0 : st.size;
+        }
+        else {
+            // File appeared after we started watching — emit from byte 0.
+            offset = 0;
+            partial = '';
+        }
+        return true;
+    };
+    const closeFd = async () => {
+        const h = fd;
+        fd = null;
+        if (h) {
+            try {
+                await h.close();
+            }
+            catch { /* already closed */ }
+        }
+    };
+    const drain = async () => {
+        if (reading) {
+            dirty = true;
+            return;
+        }
+        reading = true;
+        try {
+            while (!ac.signal.aborted) {
+                if (!fd) {
+                    const ok = await openIfPossible(false);
+                    if (!ok)
+                        return;
+                }
+                const st = await fd.stat();
+                if (st.size < offset) {
+                    // Truncation or rotation: reset to start of the new content.
+                    offset = 0;
+                    partial = '';
+                }
+                if (st.size === offset) {
+                    if (dirty) {
+                        dirty = false;
+                        continue;
+                    }
+                    return;
+                }
+                const len = st.size - offset;
+                const buf = Buffer.alloc(len);
+                await fd.read(buf, 0, len, offset);
+                offset = st.size;
+                const text = partial + buf.toString('utf-8');
+                const lines = text.split('\n');
+                partial = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (ac.signal.aborted)
+                        return;
+                    if (line.length > 0)
+                        onLine(line);
+                }
+                if (!dirty)
+                    return;
+                dirty = false;
+            }
+        }
+        finally {
+            reading = false;
+        }
+    };
+    if (fs.existsSync(filePath)) {
+        await openIfPossible(true);
+    }
+    const watcher = fs.watch(dir, { recursive: false }, (_event, filename) => {
+        if (ac.signal.aborted)
+            return;
+        // On macOS, filename is sometimes null — don't filter in that case.
+        if (filename !== null && filename !== base)
+            return;
+        // Stat detects append, truncation, or reappearance in drain(); trust that
+        // over the event type, which macOS coalesces inconsistently.
+        void drain();
+    });
+    // Initial drain in case the file has content beyond EOF-of-our-offset
+    // (e.g. --from-start, or a write between stat and watch attach).
+    await drain();
+    await new Promise((resolve) => {
+        const onAbort = () => {
+            ac.signal.removeEventListener('abort', onAbort);
+            try {
+                watcher.close();
+            }
+            catch { /* noop */ }
+            void closeFd().then(() => resolve());
+        };
+        if (ac.signal.aborted)
+            onAbort();
+        else
+            ac.signal.addEventListener('abort', onAbort);
+    });
+}
+async function findLatestTailable() {
+    const sessions = await discoverSessions({ all: true, limit: 100 });
+    const eligible = sessions.filter(s => TAIL_SUPPORTED.includes(s.agent));
+    if (eligible.length === 0)
+        return undefined;
+    eligible.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return eligible[0];
+}
+async function resolveTailable(sessionId) {
+    const sessions = await discoverSessions({ all: true, limit: 5000 });
+    const matches = resolveSessionById(sessions, sessionId);
+    if (matches.length === 0)
+        return undefined;
+    // Prefer a supported agent among matches; if only unsupported match, signal.
+    const supported = matches.find(s => TAIL_SUPPORTED.includes(s.agent));
+    if (supported)
+        return supported;
+    return 'unsupported';
+}
+async function runTail(sessionId, options) {
+    let session;
+    if (options.latest) {
+        session = await findLatestTailable();
+        if (!session) {
+            console.log(chalk.gray('No tailable sessions found (claude or codex).'));
+            return;
+        }
+    }
+    else {
+        if (!sessionId) {
+            console.error(chalk.red('Missing session ID. Pass an ID or use --latest.'));
+            process.exit(2);
+        }
+        const resolved = await resolveTailable(sessionId);
+        if (resolved === 'unsupported') {
+            console.error(chalk.red(`Tailing is supported for append-only JSONL agents only (claude, codex).`));
+            process.exit(2);
+        }
+        if (!resolved) {
+            console.error(chalk.red(`No session found matching: ${sessionId}`));
+            process.exit(1);
+        }
+        session = resolved;
+    }
+    const filePath = session.filePath.split('#')[0];
+    if (process.stderr.isTTY) {
+        process.stderr.write(chalk.gray(`Tailing ${session.agent} ${session.shortId} — ${filePath}\n`) +
+            chalk.gray('Ctrl+C to stop.\n'));
+    }
+    const ac = new AbortController();
+    const onSig = () => { ac.abort(); };
+    process.on('SIGINT', onSig);
+    process.on('SIGTERM', onSig);
+    try {
+        await tailFile(filePath, (line) => {
+            process.stdout.write(line + '\n');
+        }, ac, { fromStart: options.fromStart });
+    }
+    finally {
+        process.off('SIGINT', onSig);
+        process.off('SIGTERM', onSig);
+    }
+}
+/** Attach the `tail` subcommand to an existing `sessions` command. */
+export function registerSessionsTailCommand(sessionsCmd) {
+    sessionsCmd
+        .command('tail [sessionId]')
+        .description('Live-tail a session file, streaming new JSONL events as they are written. Long-running: press Ctrl+C to stop. Claude and Codex only.')
+        .option('--latest', 'Tail the most recent tailable session (claude or codex)')
+        .option('--from-start', 'Emit the full file first, then follow (default: start at EOF)')
+        .option('--json', 'Raw JSONL passthrough (default)')
+        .addHelpText('after', `
+This command runs until interrupted (Ctrl+C). Each line printed to stdout
+is a raw JSONL event from the session file — parse with jq or similar.
+
+Examples:
+  # Follow the most recent active Claude or Codex session
+  agents sessions tail --latest
+
+  # Follow a specific session by short or full ID
+  agents sessions tail a1b2c3d4
+
+  # Replay from the beginning, then follow
+  agents sessions tail a1b2c3d4 --from-start
+
+  # Pipe through jq to extract just user messages
+  agents sessions tail --latest | jq 'select(.type == "user")'
+
+Only Claude and Codex sessions are supported — they append JSONL one event
+per line, which makes live-tailing safe. Gemini, OpenCode, and OpenClaw
+use formats that rewrite the file or store state elsewhere.
+`)
+        .action(async (sessionId, options) => {
+        await runTail(sessionId, options);
+    });
+}

package/dist/commands/sessions.d.ts

@@ -11,6 +11,7 @@ import type { SessionMeta } from '../lib/session/types.js';
  * `agents sessions <id>` — that reader is version-agnostic.
  */
 export declare function buildResumeCommand(session: SessionMeta, activeVersion?: string): string[] | null;
+/** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
+/** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
-//# sourceMappingURL=sessions.d.ts.map