@phnx-labs/agents-cli 1.22.119 → 1.22.121

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

@@ -1,31 +1,13 @@
 import type { Command } from 'commander';
-import type { SessionMeta, SessionAgentId } from '../lib/session/types.js';
-/** Whether a session's transcript can be live-tailed (append-only JSONL agents). */
+import type { SessionMeta, SessionAgentId } from '@phnx-labs/sessions-cli/reader';
 export declare function isTailable(agent: SessionAgentId): boolean;
 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>;
-/**
- * Live-tail one already-resolved session's transcript to stdout until Ctrl+C.
- * Shared by `agents sessions tail` and `agents logs -f`.
- */
 export declare function streamSessionTail(session: SessionMeta, options?: {
     fromStart?: boolean;
     raw?: boolean;
 }): Promise<void>;
-/** Attach the `tail` subcommand to an existing `sessions` command. */
 export declare function registerSessionsTailCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-tail.js

@@ -1,34 +1,14 @@
-/**
- * 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). Output is compact by default;
- * --json keeps the raw JSONL stream.
- */
 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';
 import { setHelpSections } from '../lib/help.js';
-import { makeStreamRenderer } from '../lib/session/stream-render.js';
+import { makeStreamRenderer } from '@phnx-labs/sessions-cli/reader';
 const TAIL_SUPPORTED = ['claude', 'codex'];
-/** Whether a session's transcript can be live-tailed (append-only JSONL agents). */
 export function isTailable(agent) {
     return TAIL_SUPPORTED.includes(agent);
 }
-/**
- * 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);
@@ -49,7 +29,6 @@ export async function tailFile(filePath, onLine, ac, opts = {}) {
             offset = opts.fromStart ? 0 : st.size;
         }
         else {
-            // File appeared after we started watching — emit from byte 0.
             offset = 0;
             partial = '';
         }
@@ -62,7 +41,7 @@ export async function tailFile(filePath, onLine, ac, opts = {}) {
             try {
                 await h.close();
             }
-            catch { /* already closed */ }
+            catch { }
         }
     };
     const drain = async () => {
@@ -80,7 +59,6 @@ export async function tailFile(filePath, onLine, ac, opts = {}) {
                 }
                 const st = await fd.stat();
                 if (st.size < offset) {
-                    // Truncation or rotation: reset to start of the new content.
                     offset = 0;
                     partial = '';
                 }
@@ -119,15 +97,10 @@ export async function tailFile(filePath, onLine, ac, opts = {}) {
     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 = () => {
@@ -135,7 +108,7 @@ export async function tailFile(filePath, onLine, ac, opts = {}) {
             try {
                 watcher.close();
             }
-            catch { /* noop */ }
+            catch { }
             void closeFd().then(() => resolve());
         };
         if (ac.signal.aborted)
@@ -157,7 +130,6 @@ async function resolveTailable(sessionId) {
     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;
@@ -190,10 +162,6 @@ async function runTail(sessionId, options) {
     }
     await streamSessionTail(session, { fromStart: options.fromStart, raw: options.json });
 }
-/**
- * Live-tail one already-resolved session's transcript to stdout until Ctrl+C.
- * Shared by `agents sessions tail` and `agents logs -f`.
- */
 export async function streamSessionTail(session, options = {}) {
     const filePath = session.filePath.split('#')[0];
     const render = options.raw ? undefined : makeStreamRenderer(session.agent, session.cwd);
@@ -221,7 +189,6 @@ export async function streamSessionTail(session, options = {}) {
         process.off('SIGTERM', onSig);
     }
 }
-/** Attach the `tail` subcommand to an existing `sessions` command. */
 export function registerSessionsTailCommand(sessionsCmd) {
     const tailCmd = sessionsCmd
         .command('tail [sessionId]')

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

@@ -1,12 +1,10 @@
 import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
-import type { SessionTrajectory } from '../lib/session/trajectory.js';
-import type { TrajectoryComparison, TrajectoryDivergence, TrajectorySummary } from '../lib/session/trajectory-compare.js';
-import type { TrajectoryStep } from '../lib/session/trajectory.js';
-import type { LineageEdge, LineageNode, SessionLineage } from '../lib/session/trajectory-lineage.js';
-/** Versioned envelope emitted by `--json` — the stable contract for consumers. */
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
+import type { SessionTrajectory } from '@phnx-labs/sessions-cli/reader';
+import type { TrajectoryComparison, TrajectoryDivergence, TrajectorySummary } from '@phnx-labs/sessions-cli/reader';
+import type { TrajectoryStep } from '@phnx-labs/sessions-cli/reader';
+import type { LineageEdge, LineageNode, SessionLineage } from '@phnx-labs/sessions-cli/reader';
 export declare const SESSIONS_TRACE_SCHEMA_VERSION = 1;
-/** The `diff` block of a `layout: 'compare'` envelope — everything but the two full trajectories, which already ride `sessions`. */
 interface SessionsTraceDiffEnvelope {
     divergence?: TrajectoryDivergence;
     added: TrajectoryStep[];
@@ -16,7 +14,6 @@ interface SessionsTraceDiffEnvelope {
     truncatedA: number;
     truncatedB: number;
 }
-/** The `lineage` block of a `layout: 'lineage'` envelope — the delegation graph. */
 interface SessionsTraceLineageEnvelope {
     rootId: string;
     nodes: LineageNode[];
@@ -24,7 +21,6 @@ interface SessionsTraceLineageEnvelope {
     teams: string[];
     unresolvedParentIds: string[];
 }
-/** The `--json` envelope: the versioned contract for the ext / triaging agents. */
 interface SessionsTraceEnvelope {
     schemaVersion: typeof SESSIONS_TRACE_SCHEMA_VERSION;
     kind: 'sessions-trace';
@@ -33,16 +29,8 @@ interface SessionsTraceEnvelope {
     diff?: SessionsTraceDiffEnvelope;
     lineage?: SessionsTraceLineageEnvelope;
 }
-/** Build the versioned `--json` envelope for a single-session trajectory. */
 export declare function buildTraceEnvelope(models: SessionTrajectory[]): SessionsTraceEnvelope;
-/** Build the versioned `--json` envelope for a two-session compare. */
 export declare function buildCompareTraceEnvelope(cmp: TrajectoryComparison): SessionsTraceEnvelope;
-/**
- * Build the versioned `--json` envelope for a lineage. `sessions` carries the
- * ROOT's trajectory only: the graph's own numbers come from the indexed session
- * rows, so a consumer pays one transcript parse instead of one per teammate —
- * `agents sessions trace <child>` is how you get a child's full trajectory.
- */
 export declare function buildLineageTraceEnvelope(lineage: SessionLineage, rootTrajectory: SessionTrajectory): SessionsTraceEnvelope;
 interface TraceOptions {
     html?: boolean;
@@ -61,31 +49,12 @@ interface TraceOptions {
     tree?: boolean;
 }
 type RenderFormat = 'html' | 'text' | 'json';
-/**
- * Pick the rendering by audience: explicit `--html/--text/--json` win; otherwise
- * a person at a TTY gets the visual HTML and a piped/headless caller (an agent)
- * gets the compact text trajectory.
- */
 export declare function chooseFormat(options: TraceOptions, isTTY: boolean): RenderFormat;
-/**
- * Decide the trace layout from what the user TYPED (`selectorCount`) vs what
- * those selectors RESOLVED to (`resolvedCount`). Keyed on selector count so a
- * single content-search selector that happens to match two sessions never
- * silently becomes a compare — every unsupported combination fails loud with a
- * clear message. Pure, so the boundaries are unit-tested without the command.
- */
 export declare function decideTraceLayout(options: Pick<TraceOptions, 'tree' | 'compare'>, selectorCount: number, resolvedCount: number): 'single' | 'compare' | 'lineage';
-/**
- * Render one session's narration-anchored step list — the same fold the daemon
- * caches and the sidebar renders, computed here from the transcript so the
- * command works for any session, live or closed, cached or not.
- */
 export declare function renderSessionSteps(session: SessionMeta, options?: {
     redact?: boolean;
     knownSecrets?: readonly string[];
 }): string;
-/** Canonical `agents sessions trace <selectors...>`. */
 export declare function registerSessionsTraceCommand(sessionsCmd: Command): void;
-/** Top-level alias `agents trace <selectors...>` (mirrors `agents insights`). */
 export declare function registerTraceCommand(program: Command): void;
 export {};

package/dist/commands/sessions-trace.js

@@ -1,19 +1,3 @@
-/**
- * `agents sessions trace <selectors...>` (alias: `agents trace <selectors...>`) —
- * render one session as a derived trajectory, or two as a compare.
- *
- * One model (`buildTrajectory`), three renderings, audience auto-selected: a
- * person at a TTY gets the self-contained HTML opened in a browser; a piped or
- * headless caller (an agent) gets the compact text trajectory; `--json` emits the
- * versioned envelope the AGI EXT Fleet panel and triaging agents consume. Explicit
- * `--html/--text/--json` always win.
- *
- * Exactly two resolved selectors turn the single trajectory into a **compare**
- * (`diffTrajectories`, PR2/3) — the same three renderings, laid on a shared axis
- * with a divergence marker. `--tree` turns one selector into a **lineage**
- * (`buildLineage`, PR3/3): the orchestrator and every session it spawned, edges
- * read from the team records. Three or more selectors still fail loud.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
@@ -22,19 +6,17 @@ import { showFile } from '../lib/open-url.js';
 import { knownSecretValuesFromEnv } from '../lib/redact.js';
 import { getCacheDir } from '../lib/state.js';
 import { discoverSessions } from '../lib/session/discover.js';
-import { parseSession } from '../lib/session/parse.js';
-import { foldTimeline, projectSessionFiles, projectTimeline } from '../lib/session/timeline.js';
+import { parseSession } from '@phnx-labs/sessions-cli/reader';
+import { foldTimeline, projectSessionFiles, projectTimeline } from '@phnx-labs/sessions-cli/reader';
 import { parseTimelineEvents } from '../lib/session/timeline-pass.js';
-import { buildTrajectory } from '../lib/session/trajectory.js';
-import { diffTrajectories } from '../lib/session/trajectory-compare.js';
-import { buildLineage } from '../lib/session/trajectory-lineage.js';
-import { renderTrajectoryHtml, renderTrajectoryCompareHtml, renderLineageHtml } from '../lib/session/trajectory-html.js';
-import { renderTrajectoryText, renderTrajectoryCompareText, renderLineageText } from '../lib/session/trajectory-text.js';
+import { buildTrajectory } from '@phnx-labs/sessions-cli/reader';
+import { diffTrajectories } from '@phnx-labs/sessions-cli/reader';
+import { buildLineage } from '@phnx-labs/sessions-cli/reader';
+import { renderTrajectoryHtml, renderTrajectoryCompareHtml, renderLineageHtml } from '@phnx-labs/sessions-cli/reader';
+import { renderTrajectoryText, renderTrajectoryCompareText, renderLineageText } from '@phnx-labs/sessions-cli/reader';
 import { parseAgentFilter } from './sessions.js';
 import { selectSessions } from './sessions-export.js';
-/** Versioned envelope emitted by `--json` — the stable contract for consumers. */
 export const SESSIONS_TRACE_SCHEMA_VERSION = 1;
-/** Build the versioned `--json` envelope for a single-session trajectory. */
 export function buildTraceEnvelope(models) {
     return {
         schemaVersion: SESSIONS_TRACE_SCHEMA_VERSION,
@@ -43,7 +25,6 @@ export function buildTraceEnvelope(models) {
         sessions: models,
     };
 }
-/** Build the versioned `--json` envelope for a two-session compare. */
 export function buildCompareTraceEnvelope(cmp) {
     return {
         schemaVersion: SESSIONS_TRACE_SCHEMA_VERSION,
@@ -61,12 +42,6 @@ export function buildCompareTraceEnvelope(cmp) {
         },
     };
 }
-/**
- * Build the versioned `--json` envelope for a lineage. `sessions` carries the
- * ROOT's trajectory only: the graph's own numbers come from the indexed session
- * rows, so a consumer pays one transcript parse instead of one per teammate —
- * `agents sessions trace <child>` is how you get a child's full trajectory.
- */
 export function buildLineageTraceEnvelope(lineage, rootTrajectory) {
     return {
         schemaVersion: SESSIONS_TRACE_SCHEMA_VERSION,
@@ -82,11 +57,6 @@ export function buildLineageTraceEnvelope(lineage, rootTrajectory) {
         },
     };
 }
-/**
- * Pick the rendering by audience: explicit `--html/--text/--json` win; otherwise
- * a person at a TTY gets the visual HTML and a piped/headless caller (an agent)
- * gets the compact text trajectory.
- */
 export function chooseFormat(options, isTTY) {
     if (options.json)
         return 'json';
@@ -96,13 +66,6 @@ export function chooseFormat(options, isTTY) {
         return 'text';
     return isTTY ? 'html' : 'text';
 }
-/**
- * Decide the trace layout from what the user TYPED (`selectorCount`) vs what
- * those selectors RESOLVED to (`resolvedCount`). Keyed on selector count so a
- * single content-search selector that happens to match two sessions never
- * silently becomes a compare — every unsupported combination fails loud with a
- * clear message. Pure, so the boundaries are unit-tested without the command.
- */
 export function decideTraceLayout(options, selectorCount, resolvedCount) {
     if (options.tree) {
         if (options.compare) {
@@ -136,7 +99,6 @@ export function decideTraceLayout(options, selectorCount, resolvedCount) {
     }
     return 'single';
 }
-/** One step's counters, rendered as the sidebar renders them: `6 run · 2 blocked`. */
 function stepDetail(step) {
     const mix = Object.entries(step.mix ?? {})
         .filter(([, count]) => (count ?? 0) > 0)
@@ -149,11 +111,6 @@ function stepDetail(step) {
         ...(step.marks ?? []),
     ].filter(Boolean).join(' · ');
 }
-/**
- * Render one session's narration-anchored step list — the same fold the daemon
- * caches and the sidebar renders, computed here from the transcript so the
- * command works for any session, live or closed, cached or not.
- */
 export function renderSessionSteps(session, options = {}) {
     const state = foldTimeline(parseTimelineEvents(session.filePath, session.agent), undefined, {});
     const timeline = projectTimeline(state, undefined, state.steps.length, options);
@@ -183,7 +140,6 @@ export function renderSessionSteps(session, options = {}) {
     ].filter(Boolean).join(' · ');
     return `${lines.join('\n')}\n\n${footer}\n`;
 }
-/** Attach the trace behaviour to a command node (canonical or top-level alias). */
 function configureTraceCommand(cmd) {
     cmd
         .description('Visualize a session as a trajectory — a tool-call timeline you can read at a glance. Opens a visual for a person; prints a compact trajectory for an agent.')
@@ -247,20 +203,11 @@ Lineage resolves children from the scanned pool, so a very old team may need a w
 Three or more selectors, and --tree with more than one selector, fail loud.`,
     });
     cmd.action(async (selectors, _options, command) => {
-        // Merge parent globals: under `agents sessions trace`, the `sessions` command
-        // owns `--json`/`--no-redact`/`--all`/`--agent`/`--since` and captures them, so
-        // read the merged view (as `render`/`insights` do) — the top-level `agents
-        // trace` alias has no such parent and its own options fill the same fields.
         const options = command.optsWithGlobals();
-        // Lineage resolves its children FROM the scanned pool, and a teammate can sit
-        // well below the orchestrator in recency order, so --tree scans wider by
-        // default than the single/compare layouts. An explicit --limit still wins.
         const defaultLimit = options.tree ? 500 : 100;
         const limit = Math.max(1, Number.parseInt(options.limit || String(defaultLimit), 10) || defaultLimit);
         const agent = parseAgentFilter(options.agent).agent;
         const pool = await discoverSessions({
-            // Default to every directory so an id from any project resolves, matching
-            // `agents sessions render` (sessions-render.ts:126).
             all: options.all !== false,
             since: options.since,
             limit,
@@ -272,10 +219,6 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
             process.exitCode = 1;
             return;
         }
-        // Layout is keyed on what the USER TYPED (selector count), not the resolved
-        // count — a single content-search selector matching two sessions must NOT
-        // silently become a compare. All the fail-loud boundaries live in the pure
-        // decideTraceLayout so they are unit-tested (see sessions-trace.test.ts).
         if (options.steps && selectors.length > 1) {
             throw new Error('--steps renders one session\'s step list; pass a single selector.');
         }
@@ -288,15 +231,7 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
             return buildTrajectory(events, session, { redact, knownSecrets });
         };
         if (layout === 'lineage') {
-            // The pool must keep team-origin rows: they are hidden from the ordinary
-            // listing by default (AGENTS.md invariant 7), and they ARE the children.
-            // discoverSessions does not apply that presentation filter, so `pool` is
-            // already the teams-included set the graph needs.
             const root = sessions[0];
-            // An id-shaped selector resolves through the session INDEX, which reaches
-            // rows the scanned pool does not hold (selectSessions -> findSessionsById,
-            // sessions-export.ts:386). Seed the pool with the resolved root so the
-            // graph always roots where the user pointed.
             const pooled = pool.some((s) => s.id === root.id) ? pool : [root, ...pool];
             const lineage = buildLineage(pooled, { rootId: root.id });
             const idPart = root.shortId || root.id;
@@ -322,7 +257,6 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
                 }
                 return;
             }
-            // HTML.
             const html = renderLineageHtml(lineage, redact);
             if (options.output) {
                 fs.writeFileSync(options.output, html, { mode: 0o600 });
@@ -367,7 +301,6 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
                 }
                 return;
             }
-            // HTML.
             const html = renderTrajectoryCompareHtml(cmp);
             if (options.output) {
                 fs.writeFileSync(options.output, html, { mode: 0o600 });
@@ -387,12 +320,7 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
             }
             return;
         }
-        // One selector — the single-session trajectory.
         const session = sessions[0];
-        // --steps is the CLI door to the timeline fold the sidebar renders, so an
-        // agent can read what a session DID without the extension (PHNX-3939). It is
-        // a different model from the trajectory (narration beats, not tool steps),
-        // so it short-circuits before buildTrajectory rather than reshaping it.
         if (options.steps) {
             const out = renderSessionSteps(session, { redact, knownSecrets });
             if (options.output) {
@@ -427,7 +355,6 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
             }
             return;
         }
-        // HTML.
         const html = renderTrajectoryHtml(model);
         if (options.output) {
             fs.writeFileSync(options.output, html, { mode: 0o600 });
@@ -448,11 +375,9 @@ Three or more selectors, and --tree with more than one selector, fail loud.`,
     });
     return cmd;
 }
-/** Canonical `agents sessions trace <selectors...>`. */
 export function registerSessionsTraceCommand(sessionsCmd) {
     configureTraceCommand(sessionsCmd.command('trace <selectors...>'));
 }
-/** Top-level alias `agents trace <selectors...>` (mirrors `agents insights`). */
 export function registerTraceCommand(program) {
     configureTraceCommand(program.command('trace <selectors...>'));
 }