@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/session/parse.d.ts

@@ -1,15 +1,39 @@
+/**
+ * Session file parsers for Claude, Codex, Gemini, and OpenCode.
+ *
+ * Each agent stores sessions in a different format (JSONL, JSON, SQLite).
+ * This module normalizes all of them into a flat array of SessionEvent
+ * objects suitable for rendering, filtering, and summarization.
+ */
 import type { SessionAgentId, SessionEvent } from './types.js';
+/**
+ * Largest session file we will load into memory. Above this we throw a clean
+ * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
+ * Node's ~512MB string ceiling with a healthy margin.
+ */
+export declare const SESSION_FILE_MAX_BYTES = 200000000;
+export declare function sanitizeForTerminal(s: string): string;
+/**
+ * Read a session file, refusing files above maxBytes. Bounded read protects
+ * against multi-GB session blobs that would OOM the CLI or exceed V8's
+ * ERR_STRING_TOO_LONG ceiling.
+ */
+export declare function safeReadSessionFile(filePath: string, maxBytes?: number): string;
 /**
  * Auto-detect agent type from file path and parse the session.
  */
 export declare function parseSession(filePath: string, agent?: SessionAgentId): SessionEvent[];
+/** Infer the agent type from a session file path using known directory conventions. */
 export declare function detectAgent(filePath: string): SessionAgentId | null;
 /**
  * Summarize a tool_use into a one-liner string.
  */
 export declare function summarizeToolUse(tool: string, args?: Record<string, any>): string;
+/** Parse a Claude JSONL session file into normalized events. */
 export declare function parseClaude(filePath: string): SessionEvent[];
+/** Parse a Codex JSONL session file into normalized events. */
 export declare function parseCodex(filePath: string): SessionEvent[];
+/** Parse a Gemini JSON session file into normalized events. */
 export declare function parseGemini(filePath: string): SessionEvent[];
 /**
  * Parse an OpenCode session from its SQLite database.
@@ -20,4 +44,7 @@ export declare function parseGemini(filePath: string): SessionEvent[];
  * Parts contain the actual content: text, tool, reasoning, patch, step-start/finish.
  */
 export declare function parseOpenCode(filePath: string): SessionEvent[];
-//# sourceMappingURL=parse.d.ts.map
+/** Parse a Rush JSONL session file into normalized events. */
+export declare function parseRush(filePath: string): SessionEvent[];
+/** Parse a Hermes session JSON file into normalized events. */
+export declare function parseHermes(filePath: string): SessionEvent[];

package/dist/lib/session/parse.js

@@ -1,5 +1,76 @@
+/**
+ * Session file parsers for Claude, Codex, Gemini, and OpenCode.
+ *
+ * Each agent stores sessions in a different format (JSONL, JSON, SQLite).
+ * This module normalizes all of them into a flat array of SessionEvent
+ * objects suitable for rendering, filtering, and summarization.
+ */
 import * as fs from 'fs';
 import { execSync } from 'child_process';
+/**
+ * Largest session file we will load into memory. Above this we throw a clean
+ * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
+ * Node's ~512MB string ceiling with a healthy margin.
+ */
+export const SESSION_FILE_MAX_BYTES = 200_000_000;
+/**
+ * Strip terminal control sequences that a malicious session file could use to
+ * hijack the user's terminal (clipboard via OSC 52, scrollback wipe, alt-screen
+ * takeover, cursor moves, etc.). Allowed through: tab (0x09), newline (0x0a),
+ * carriage return (0x0d). Everything else in the C0/C1 range and every CSI/OSC
+ * escape is dropped.
+ */
+const TERMINAL_ESCAPE_REGEX = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]|\x1b[@-_]|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+export function sanitizeForTerminal(s) {
+    if (typeof s !== 'string' || !s)
+        return s;
+    return s.replace(TERMINAL_ESCAPE_REGEX, '');
+}
+/** Recursively sanitize every string value within a tool-args object. */
+function sanitizeArgsDeep(value) {
+    if (typeof value === 'string')
+        return sanitizeForTerminal(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeArgsDeep);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value))
+            out[k] = sanitizeArgsDeep(value[k]);
+        return out;
+    }
+    return value;
+}
+/** In-place sanitize all user-visible string fields on an event. */
+function sanitizeEvent(e) {
+    if (e.content)
+        e.content = sanitizeForTerminal(e.content);
+    if (e.command)
+        e.command = sanitizeForTerminal(e.command);
+    if (e.path)
+        e.path = sanitizeForTerminal(e.path);
+    if (e.output)
+        e.output = sanitizeForTerminal(e.output);
+    if (e.tool)
+        e.tool = sanitizeForTerminal(e.tool);
+    if (e.model)
+        e.model = sanitizeForTerminal(e.model);
+    if (e.mediaType)
+        e.mediaType = sanitizeForTerminal(e.mediaType);
+    if (e.args)
+        e.args = sanitizeArgsDeep(e.args);
+}
+/**
+ * Read a session file, refusing files above maxBytes. Bounded read protects
+ * against multi-GB session blobs that would OOM the CLI or exceed V8's
+ * ERR_STRING_TOO_LONG ceiling.
+ */
+export function safeReadSessionFile(filePath, maxBytes = SESSION_FILE_MAX_BYTES) {
+    const stat = fs.statSync(filePath);
+    if (stat.size > maxBytes) {
+        throw new Error(`Session file too large: ${filePath} is ${stat.size} bytes (limit ${maxBytes}). Refusing to load.`);
+    }
+    return fs.readFileSync(filePath, 'utf-8');
+}
 /**
  * Auto-detect agent type from file path and parse the session.
  */
@@ -8,14 +79,38 @@ export function parseSession(filePath, agent) {
     if (!detected) {
         throw new Error(`Cannot detect agent type from path: ${filePath}`);
     }
+    let events;
     switch (detected) {
-        case 'claude': return parseClaude(filePath);
-        case 'codex': return parseCodex(filePath);
-        case 'gemini': return parseGemini(filePath);
-        case 'opencode': return parseOpenCode(filePath);
-        case 'openclaw': return []; // OpenClaw sessions don't have parseable files yet
+        case 'claude':
+            events = parseClaude(filePath);
+            break;
+        case 'codex':
+            events = parseCodex(filePath);
+            break;
+        case 'gemini':
+            events = parseGemini(filePath);
+            break;
+        case 'opencode':
+            events = parseOpenCode(filePath);
+            break;
+        case 'rush':
+            events = parseRush(filePath);
+            break;
+        case 'openclaw':
+            events = [];
+            break; // OpenClaw sessions don't have parseable files yet
+        case 'hermes':
+            events = parseHermes(filePath);
+            break;
     }
+    // Chokepoint: every string field that originated in an untrusted session
+    // file gets stripped of terminal escapes here, so renderers downstream can
+    // safely splat values into chalk/console output.
+    for (const e of events)
+        sanitizeEvent(e);
+    return events;
 }
+/** Infer the agent type from a session file path using known directory conventions. */
 export function detectAgent(filePath) {
     if (filePath.includes('/.claude/') || filePath.includes('\\.claude\\'))
         return 'claude';
@@ -23,6 +118,14 @@ export function detectAgent(filePath) {
         return 'codex';
     if (filePath.includes('/.gemini/') || filePath.includes('\\.gemini\\'))
         return 'gemini';
+    if (filePath.includes('/.rush/') || filePath.includes('\\.rush\\'))
+        return 'rush';
+    if (filePath.includes('/.hermes/') || filePath.includes('\\.hermes\\'))
+        return 'hermes';
+    // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
+    const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
+    if (cloudMatch)
+        return cloudMatch[1];
     if (filePath.includes('opencode.db'))
         return 'opencode';
     // Try file extension + content heuristic
@@ -79,9 +182,11 @@ export function summarizeToolUse(tool, args) {
         }
     }
 }
+/** Truncate a string to n characters, appending '...' if shortened. */
 function truncate(s, n) {
     return s.length <= n ? s : s.slice(0, n - 3) + '...';
 }
+/** Replace the home directory prefix with ~ for display. */
 function shortenPath(p) {
     const home = process.env.HOME || '';
     if (home && p.startsWith(home))
@@ -91,8 +196,9 @@ function shortenPath(p) {
 // ---------------------------------------------------------------------------
 // Claude parser
 // ---------------------------------------------------------------------------
+/** Parse a Claude JSONL session file into normalized events. */
 export function parseClaude(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
+    const content = safeReadSessionFile(filePath);
     const lines = content.split('\n').filter(l => l.trim());
     const events = [];
     // Map tool_use id -> {tool, args} for correlating with tool_result
@@ -279,8 +385,9 @@ export function parseClaude(filePath) {
 // ---------------------------------------------------------------------------
 // Codex parser
 // ---------------------------------------------------------------------------
+/** Parse a Codex JSONL session file into normalized events. */
 export function parseCodex(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
+    const content = safeReadSessionFile(filePath);
     const lines = content.split('\n').filter(l => l.trim());
     const events = [];
     // Track function_call id -> name for correlating with function_call_output
@@ -403,8 +510,9 @@ export function parseCodex(filePath) {
 // ---------------------------------------------------------------------------
 // Gemini parser
 // ---------------------------------------------------------------------------
+/** Parse a Gemini JSON session file into normalized events. */
 export function parseGemini(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
+    const content = safeReadSessionFile(filePath);
     let session;
     try {
         session = JSON.parse(content);
@@ -647,4 +755,154 @@ export function parseOpenCode(filePath) {
     }
     return events;
 }
-//# sourceMappingURL=parse.js.map
+// ---------------------------------------------------------------------------
+// Rush parser
+//
+// Rush messages.jsonl format is flat: one JSON object per line with
+//   { id, session_id, role, type, content, created_at, tool_call_id?, name? }
+// type ∈ {message, tool_call, tool_result}
+// content varies by type:
+//   message     -> { text: string }
+//   tool_call   -> { input: {...} }
+//   tool_result -> { input, output } (output.success === false marks an error)
+// ---------------------------------------------------------------------------
+/** Parse a Rush JSONL session file into normalized events. */
+export function parseRush(filePath) {
+    const content = safeReadSessionFile(filePath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    // Map tool_call id -> {tool, args} for correlating with tool_result.
+    const toolCallMap = new Map();
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            /* malformed JSONL line, skip */
+            continue;
+        }
+        const type = raw.type;
+        const timestamp = raw.created_at || new Date().toISOString();
+        const content = raw.content || {};
+        if (type === 'message') {
+            const text = typeof content.text === 'string' ? content.text.trim() : '';
+            if (!text)
+                continue;
+            const role = raw.role === 'user' ? 'user' : 'assistant';
+            // Rush wraps the first user turn in <user_input>...</user_input> — strip.
+            const cleaned = text
+                .replace(/^<user_input>/, '')
+                .replace(/<\/user_input>$/, '')
+                .trim();
+            // Skip sentinel execution-start marker that isn't human-readable.
+            if (raw.role === 'system' && cleaned === 'execution_start')
+                continue;
+            events.push({
+                type: 'message',
+                agent: 'rush',
+                timestamp,
+                role,
+                content: cleaned,
+            });
+        }
+        else if (type === 'tool_call') {
+            const toolName = raw.name || 'unknown';
+            const args = content.input || {};
+            const callId = raw.tool_call_id;
+            if (callId)
+                toolCallMap.set(callId, { tool: toolName, args });
+            events.push({
+                type: 'tool_use',
+                agent: 'rush',
+                timestamp,
+                tool: toolName,
+                args,
+                path: args.file_path || args.path || undefined,
+                command: (toolName === 'Bash' || toolName === 'shell') ? args.command : undefined,
+            });
+        }
+        else if (type === 'tool_result') {
+            const callId = raw.tool_call_id;
+            const info = callId ? toolCallMap.get(callId) : undefined;
+            const output = content.output;
+            let outputStr = '';
+            if (typeof output === 'string') {
+                outputStr = output;
+            }
+            else if (output !== undefined) {
+                try {
+                    outputStr = JSON.stringify(output);
+                }
+                catch {
+                    outputStr = String(output);
+                }
+            }
+            const success = output?.success !== false;
+            events.push({
+                type: success ? 'tool_result' : 'error',
+                agent: 'rush',
+                timestamp,
+                tool: info?.tool ?? raw.name,
+                success,
+                output: outputStr.length > 500 ? outputStr.slice(0, 497) + '...' : outputStr,
+            });
+            if (callId)
+                toolCallMap.delete(callId);
+        }
+    }
+    return events;
+}
+// ---------------------------------------------------------------------------
+// Hermes parser
+//
+// Hermes stores one JSON file per session at ~/.hermes/sessions/session_<id>.json:
+//   { session_id, model, platform, session_start, last_updated,
+//     system_prompt, message_count, messages: [{role, content}, ...] }
+// Content may be a string or an array of text parts.
+// ---------------------------------------------------------------------------
+/** Parse a Hermes session JSON file into normalized events. */
+export function parseHermes(filePath) {
+    let session;
+    try {
+        session = JSON.parse(safeReadSessionFile(filePath));
+    }
+    catch {
+        return [];
+    }
+    const messages = Array.isArray(session.messages) ? session.messages : [];
+    const timestamp = typeof session.session_start === 'string'
+        ? session.session_start
+        : new Date().toISOString();
+    const events = [];
+    for (const msg of messages) {
+        const role = msg?.role === 'user' ? 'user' : 'assistant';
+        const text = hermesContentToText(msg?.content);
+        if (!text)
+            continue;
+        events.push({
+            type: 'message',
+            agent: 'hermes',
+            timestamp,
+            role,
+            content: text,
+        });
+    }
+    return events;
+}
+function hermesContentToText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => {
+        if (typeof part === 'string')
+            return part;
+        if (typeof part?.text === 'string')
+            return part.text;
+        return '';
+    })
+        .join('\n')
+        .trim();
+}

package/dist/lib/session/prompt.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Prompt cleaning and topic extraction for session messages.
+ *
+ * Strips noise injected by the agent framework (system context lines, XML
+ * wrapper tags, team-spawn boilerplate) so that only the real user intent
+ * remains. Used by the session picker to show a human-readable topic line.
+ */
 export declare const HEADLESS_PLAN_MODE_PREFIX = "You are running in HEADLESS PLAN MODE.";
+/** Strip framework noise from a raw session prompt, returning only meaningful user text. */
 export declare function cleanSessionPrompt(raw: string): string;
+/** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export declare function extractSessionTopic(raw: string): string | undefined;
-//# sourceMappingURL=prompt.d.ts.map

package/dist/lib/session/prompt.js

@@ -1,3 +1,11 @@
+/**
+ * Prompt cleaning and topic extraction for session messages.
+ *
+ * Strips noise injected by the agent framework (system context lines, XML
+ * wrapper tags, team-spawn boilerplate) so that only the real user intent
+ * remains. Used by the session picker to show a human-readable topic line.
+ */
+/** Patterns that cause the entire message to be skipped for topic extraction. */
 const WHOLE_MESSAGE_SKIP_PATTERNS = [
     /<permissions instructions>/i,
     /<collaboration_mode>/i,
@@ -7,6 +15,7 @@ const WHOLE_MESSAGE_SKIP_PATTERNS = [
     // lives in the next user message, not in these wrapper tags.
     /<command-(message|name|args)>/i,
 ];
+/** Per-line noise patterns stripped during prompt cleaning (env context, bare paths, etc). */
 const NOISE_LINE_PATTERNS = [
     /^(cwd|shell|current_date|timezone|os|platform|arch|home|user)\b\s*:/i,
     /^\/[\w/.-]+$/,
@@ -15,25 +24,30 @@ const NOISE_LINE_PATTERNS = [
     /^[A-Z][A-Za-z]+\/[A-Z][\w+-]+$/,
     /^Caveat:/i,
 ];
+/** XML tag prefix used by local-command messages. */
 const LOCAL_COMMAND_PREFIX = '<local-command-caveat>';
 // Prefix prepended to every Claude-in-plan-mode team spawn prompt.
 // Ends at a blank line before the real user task.
 export const HEADLESS_PLAN_MODE_PREFIX = 'You are running in HEADLESS PLAN MODE.';
 // Wrappers added to team-spawned prompts in src/lib/teams/agents.ts.
 // Stripped before topic extraction so the picker shows what the user actually typed.
+/** Marker string appended to team-spawned prompts; stripped before topic extraction. */
 const TEAM_PROMPT_SUFFIX_MARKER = "When you're done, provide a brief summary of:";
+/** Remove headless-plan-mode prefix and team summary suffix from a raw prompt. */
 function stripTeamWrappers(raw) {
     let text = raw;
     if (text.trimStart().startsWith(HEADLESS_PLAN_MODE_PREFIX)) {
         const blankLine = text.indexOf('\n\n');
-        if (blankLine !== -1)
-            text = text.slice(blankLine + 2);
+        if (blankLine === -1)
+            return '';
+        text = text.slice(blankLine + 2);
     }
     const suffixIdx = text.indexOf(TEAM_PROMPT_SUFFIX_MARKER);
     if (suffixIdx !== -1)
         text = text.slice(0, suffixIdx);
     return text.trim();
 }
+/** Strip framework noise from a raw session prompt, returning only meaningful user text. */
 export function cleanSessionPrompt(raw) {
     let text = stripTeamWrappers(raw).replace(/\r/g, '').trim();
     if (!text)
@@ -46,6 +60,7 @@ export function cleanSessionPrompt(raw) {
         .filter(line => !NOISE_LINE_PATTERNS.some(pattern => pattern.test(line)));
     return meaningful.join('\n').trim();
 }
+/** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export function extractSessionTopic(raw) {
     if (!raw.trim())
         return undefined;
@@ -61,4 +76,3 @@ export function extractSessionTopic(raw) {
     const firstLine = cleaned.split('\n').map(line => line.trim()).find(Boolean);
     return firstLine || undefined;
 }
-//# sourceMappingURL=prompt.js.map

package/dist/lib/session/render.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Session rendering: summary, markdown conversation, and JSON output.
+ *
+ * Provides the display layer for `agents sessions <id>`. The summary renderer
+ * produces a chalk-formatted activity overview (modified files, commands,
+ * errors, final message). The markdown renderer emits a full conversation
+ * transcript. Filtering by role and turn slicing is handled here as well.
+ */
 import type { SessionEvent } from './types.js';
 /**
  * Return absPath relative to cwd; fall back to ~/… then absolute.
@@ -35,6 +43,7 @@ export declare function collapseRetries(commands: Array<{
     cmd: string;
     ts: number;
 }>): CmdRun[];
+/** Aggregated statistics computed from a session's parsed events. */
 export interface SessionStats {
     models: string[];
     userTurns: number;
@@ -46,6 +55,7 @@ export interface SessionStats {
     firstTs: number;
     lastTs: number;
 }
+/** Compute aggregate statistics (turns, tools, tokens, duration) from session events. */
 export declare function computeSummaryStats(events: SessionEvent[]): SessionStats;
 /**
  * Return the stats line for a session summary header.
@@ -57,8 +67,11 @@ export declare function renderSummaryHeader(stats: SessionStats): string;
  * Returns a chalk-formatted string (not markdown) for direct terminal output.
  */
 export declare function renderSummary(events: SessionEvent[], cwd?: string): string;
+/** Allowed values for --include/--exclude role filters. */
 export declare const VALID_ROLE_VALUES: readonly ["user", "assistant", "thinking", "tools"];
+/** A single role filter value derived from VALID_ROLE_VALUES. */
 export type RoleFilter = typeof VALID_ROLE_VALUES[number];
+/** Options for filtering session events by role and turn range. */
 export interface FilterOptions {
     include?: RoleFilter[];
     exclude?: RoleFilter[];
@@ -87,4 +100,3 @@ export declare function renderConversationMarkdown(events: SessionEvent[]): stri
  */
 export declare function renderJson(events: SessionEvent[]): string;
 export {};
-//# sourceMappingURL=render.d.ts.map

package/dist/lib/session/render.js

@@ -1,3 +1,11 @@
+/**
+ * Session rendering: summary, markdown conversation, and JSON output.
+ *
+ * Provides the display layer for `agents sessions <id>`. The summary renderer
+ * produces a chalk-formatted activity overview (modified files, commands,
+ * errors, final message). The markdown renderer emits a full conversation
+ * transcript. Filtering by role and turn slicing is handled here as well.
+ */
 import chalk from 'chalk';
 import { summarizeToolUse } from './parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
@@ -70,6 +78,7 @@ export function normalizeForDedup(cmd) {
     }
     return s.trim();
 }
+/** Command classification categories with signal levels for summary rendering. */
 const CATEGORIES = [
     { name: 'Probes', match: t => ['ls', 'cat', 'head', 'tail', 'wc', 'stat', 'file', 'which', 'tree', 'pwd'].includes(t), signal: 'low' },
     { name: 'Search', match: t => ['grep', 'rg', 'ag', 'fd', 'find'].includes(t), signal: 'low' },
@@ -81,6 +90,7 @@ const CATEGORIES = [
     { name: 'Shell', match: t => ['rm', 'mv', 'cp', 'mkdir', 'touch', 'echo', 'printf', 'chmod', 'ln', 'awk', 'sed', 'tee', 'xargs', 'for'].includes(t), signal: 'low' },
     { name: 'Wait', match: t => ['sleep', 'wait'].includes(t), signal: 'low' },
 ];
+/** CLI tools whose subcommand (second token) is included in the bucket key. */
 const TWO_LEVEL_TOKENS = new Set([
     'git', 'gh', 'bun', 'npm', 'cargo', 'docker', 'kubectl', 'rush', 'openclaw', 'pnpm', 'yarn',
 ]);
@@ -139,6 +149,7 @@ export function collapseRetries(commands) {
     }
     return result;
 }
+/** Compute aggregate statistics (turns, tools, tokens, duration) from session events. */
 export function computeSummaryStats(events) {
     const modelSet = new Set();
     let userTurns = 0;
@@ -188,9 +199,11 @@ export function computeSummaryStats(events) {
         lastTs: lastTs === -Infinity ? 0 : lastTs,
     };
 }
+/** Strip the 'claude-' prefix and date suffix from a model identifier. */
 function shortenModel(model) {
     return model.replace(/^claude-/, '').replace(/-\d{8}$/, '');
 }
+/** Format a token count as a human-readable string (e.g. 67.5K, 1.2M). */
 function formatTokenCount(n) {
     if (n === 0)
         return '0';
@@ -203,6 +216,7 @@ function formatTokenCount(n) {
     const m = n / 1_000_000;
     return (m >= 100 ? Math.round(m) : parseFloat(m.toFixed(1))) + 'M';
 }
+/** Format a duration in milliseconds as a human-readable string (e.g. '12 min', '2h 30min'). */
 function formatDuration(ms) {
     const totalMin = Math.round(ms / 60_000);
     if (totalMin < 1)
@@ -239,6 +253,7 @@ export function renderSummaryHeader(stats) {
     return parts.join(' · ');
 }
 // ── Prompt reference extraction ───────────────────────────────────────────────
+/** Extract @-mentions, slash paths, and ~/... references from a prompt string. */
 function extractReferences(text) {
     const refs = new Set();
     for (const m of text.matchAll(/@[\w/.-]+/g))
@@ -249,6 +264,7 @@ function extractReferences(text) {
         refs.add(m[0]);
     return Array.from(refs);
 }
+/** Render the Commands section of the summary, grouping by category and collapsing retries. */
 function renderCommandsSection(cmds, lines) {
     if (cmds.length === 0)
         return;
@@ -354,6 +370,7 @@ function truncateCmd(cmd, max) {
     return cmd.length <= max ? cmd : cmd.slice(0, max - 1) + '…';
 }
 // ── File grouping ─────────────────────────────────────────────────────────────
+/** Group file paths by their parent directory, relative to cwd. */
 function groupByParentDir(paths, cwd) {
     const groups = new Map();
     for (const p of paths) {
@@ -367,6 +384,7 @@ function groupByParentDir(paths, cwd) {
     }
     return new Map(Array.from(groups.entries()).sort((a, b) => b[1].length - a[1].length));
 }
+/** Render grouped file paths as indented, clickable terminal lines. */
 function renderFileGroup(lines, groups, absPathMap) {
     if (groups.size === 1) {
         const [dir, files] = Array.from(groups.entries())[0];
@@ -612,6 +630,7 @@ export function renderSummary(events, cwd) {
     return lines.join('\n');
 }
 // ── Event filters ─────────────────────────────────────────────────────────────
+/** Allowed values for --include/--exclude role filters. */
 export const VALID_ROLE_VALUES = ['user', 'assistant', 'thinking', 'tools'];
 /**
  * Parse a comma-separated role list (e.g. "user,assistant") into typed values.
@@ -769,10 +788,10 @@ export function renderConversationMarkdown(events) {
 export function renderJson(events) {
     return JSON.stringify(events, null, 2);
 }
+/** Replace the home directory prefix with ~ for trace display. */
 function shortenPathTrace(p) {
     const home = process.env.HOME || '';
     if (home && p.startsWith(home))
         return '~' + p.slice(home.length);
     return p;
 }
-//# sourceMappingURL=render.js.map

package/dist/lib/session/team-filter.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Classification and filtering of team-spawned sessions.
+ *
+ * Sessions launched by `agents teams` carry an 'sdk-cli' entrypoint and
+ * optionally have a meta.json with handle/mode info. This module determines
+ * whether a session is team-origin and splits session lists into visible
+ * and hidden groups for the picker UI.
+ */
 import type { SessionMeta, TeamOrigin } from './types.js';
 /**
  * Determine whether `session` was spawned by `agents teams`.
@@ -12,6 +20,7 @@ import type { SessionMeta, TeamOrigin } from './types.js';
  * when it is a normal interactive session.
  */
 export declare function classifyTeamSession(session: SessionMeta): TeamOrigin | null;
+/** Result of splitting sessions into visible and hidden (team-origin) groups. */
 export interface FilterResult {
     visible: SessionMeta[];
     hiddenCount: number;
@@ -23,4 +32,3 @@ export interface FilterResult {
  * excluded and counted in `hiddenCount`.
  */
 export declare function filterTeamSessions(sessions: SessionMeta[], showTeams: boolean): FilterResult;
-//# sourceMappingURL=team-filter.d.ts.map

package/dist/lib/session/team-filter.js

@@ -1,10 +1,20 @@
+/**
+ * Classification and filtering of team-spawned sessions.
+ *
+ * Sessions launched by `agents teams` carry an 'sdk-cli' entrypoint and
+ * optionally have a meta.json with handle/mode info. This module determines
+ * whether a session is team-origin and splits session lists into visible
+ * and hidden groups for the picker UI.
+ */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { getAgentsDir } from '../state.js';
 const HOME = os.homedir();
 // Default path; tests can override via AGENTS_TEAMS_DIR env var.
+/** Resolve the directory containing per-session team metadata files. */
 function teamsAgentsDir() {
-    return process.env.AGENTS_TEAMS_DIR ?? path.join(HOME, '.agents', 'teams', 'agents');
+    return process.env.AGENTS_TEAMS_DIR ?? path.join(getAgentsDir(), 'teams', 'agents');
 }
 /**
  * Determine whether `session` was spawned by `agents teams`.
@@ -63,4 +73,3 @@ export function filterTeamSessions(sessions, showTeams) {
     }
     return { visible, hiddenCount };
 }
-//# sourceMappingURL=team-filter.js.map