@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/commands/sessions-picker.js

@@ -22,7 +22,7 @@ import { terminalWidth, stringWidth } from '../lib/session/width.js';
 import { itemPicker } from '../lib/picker.js';
 import { createMemoryCache } from '../lib/memory-cache.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
-import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
+import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills, harnessTracksBackgroundShells, isBackgroundShellStart, isSubAgentTool, } from '../lib/session/highlights.js';
 import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
 /** A session whose transcript FILE is on another machine (folded in over the
  * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
@@ -222,6 +222,10 @@ export function sanitizeRemoteDigest(raw) {
         planFile: str(d.planFile),
         todos,
         subAgentCount: num(d.subAgentCount),
+        // optNum, not num: a peer's JSON is untrusted, and the undefined-vs-0
+        // distinction is load-bearing here — num() would coerce a malformed value
+        // to 0, which reads as "scanned, none running".
+        backgroundShellCount: optNum(d.backgroundShellCount),
         toolTags: strList(d.toolTags),
         changes,
         dirs: strList(d.dirs),
@@ -472,6 +476,37 @@ function formatHeader(session, events) {
  * machine — far too much for a pane that repaints as the cursor moves. The line
  * names the command that does report them instead.
  */
+/**
+ * The "what did this session leave running" segments of the Doing line.
+ *
+ * Prefers a DERIVED count (fresh, from the transcript the caller just parsed)
+ * and falls back to the PERSISTED column, which is what lets a remote/unindexed
+ * row — rendered from `SessionMeta` alone, with no events — show fan-out at all.
+ * That fallback is the whole reason the counts are columns (RUSH-3091/3095).
+ *
+ * A count of 0 or undefined renders NOTHING. Both are real states — "scanned,
+ * none found" and "this harness cannot report it" — and a literal "0 background
+ * shells" would assert "nothing is running" for a harness that simply does not
+ * record them.
+ *
+ * Wording is "left behind", not "running": a transcript records a start and
+ * never a death (see extractBackgroundShells).
+ */
+export function formatFanOut(session, derived) {
+    // DERIVED wins when the caller has one. It is computed from the transcript as
+    // it stands right now, whereas the persisted column is only as fresh as the
+    // last scan — for a live session those disagree within seconds. The persisted
+    // value is the fallback that makes a remote/unindexed row (no events, so no
+    // derived value) render at all, which is the whole reason it is a column.
+    const subAgents = derived?.subAgentCount ?? session.subAgentCount ?? 0;
+    const shells = derived?.backgroundShellCount ?? session.backgroundShellCount ?? 0;
+    const out = [];
+    if (subAgents > 0)
+        out.push(chalk.gray(`${subAgents} sub-agent${subAgents === 1 ? '' : 's'}`));
+    if (shells > 0)
+        out.push(chalk.gray(`${shells} background shell${shells === 1 ? '' : 's'}`));
+    return out;
+}
 export function formatTeamLineage(session) {
     const origin = session.teamOrigin;
     if (origin) {
@@ -505,7 +540,7 @@ function formatMetaOnlyBody(session) {
     }
     const compact = formatTodoCompact(session.todos);
     const teamLine = formatTeamLineage(session);
-    const doing = [compact ? chalk.white(compact) : '', teamLine].filter(Boolean);
+    const doing = [compact ? chalk.white(compact) : '', teamLine, ...formatFanOut(session)].filter(Boolean);
     if (doing.length) {
         lines.push(verbLabel('Doing') + doing.join(DOT));
     }
@@ -630,6 +665,12 @@ export function buildSessionPreviewDigest(events, session) {
     /** Latest checklist from the transcript (Claude TodoWrite / Codex update_plan). */
     let latestTodos;
     let subAgentCount = 0;
+    // undefined, not 0, when the harness records no background-shell concept —
+    // formatFanOut renders absence for both, but conflating them here would let a
+    // later consumer read "0 shells" as a positive "none running" claim.
+    let backgroundShellCount = harnessTracksBackgroundShells(session.agent)
+        ? 0
+        : undefined;
     const toolTags = new Set();
     // usedBrowser/usedComputer are computed at scan time from a sessionId-scoped
     // events-log read (session/db.ts detectToolUsage), NOT a transcript regex —
@@ -658,6 +699,8 @@ export function buildSessionPreviewDigest(events, session) {
             }
             if (isSubAgentTool(tool, command))
                 subAgentCount++;
+            if (backgroundShellCount !== undefined && isBackgroundShellStart(event))
+                backgroundShellCount++;
             const p = event.path || event.args?.file_path || event.args?.path || '';
             if (['Read', 'read_file', 'view_file', 'cat_file', 'get_file'].includes(tool) && p) {
                 filesRead.add(p);
@@ -700,6 +743,7 @@ export function buildSessionPreviewDigest(events, session) {
         planFile,
         todos,
         subAgentCount,
+        backgroundShellCount,
         toolTags: [...toolTags],
         changes: chg,
         dirs: directoriesTouched(session, events, changes),
@@ -722,7 +766,7 @@ function verbLabel(v) {
     return chalk.cyan(v.padEnd(VERB_GUTTER)) + ' ';
 }
 function formatCompactPreview(digest, session, events) {
-    const { firstUser, lastAssistant, filesRead, toolCalls, planFile, todos, subAgentCount, toolTags, changes: chg, dirs, repos, artifacts, skills, plugins, hooks, links, errorCount, firstError, toolHistogram: hist, test, } = digest;
+    const { firstUser, lastAssistant, filesRead, toolCalls, planFile, todos, subAgentCount, backgroundShellCount, toolTags, changes: chg, dirs, repos, artifacts, skills, plugins, hooks, links, errorCount, firstError, toolHistogram: hist, test, } = digest;
     const lines = [];
     const termWidth = process.stdout.columns || 80;
     const valueWidth = termWidth - VERB_GUTTER - 5;
@@ -740,7 +784,7 @@ function formatCompactPreview(digest, session, events) {
     const doing = [
         compact ? chalk.white(compact) : '',
         teamLine,
-        subAgentCount ? chalk.gray(`${subAgentCount} sub-agent${subAgentCount === 1 ? '' : 's'}`) : '',
+        ...formatFanOut(session, { subAgentCount, backgroundShellCount }),
     ].filter(Boolean);
     if (doing.length) {
         lines.push(verbLabel('Doing') + doing.join(DOT));
@@ -854,11 +898,6 @@ function classifySessionTool(tool, command) {
         tags.push('computer');
     return tags;
 }
-function isSubAgentTool(tool, command) {
-    if (/^(Agent|Task)$/i.test(tool))
-        return true;
-    return /\b(?:agents|ag)\b[^\n;&|]*\b(?:run|cloud\s+run|teams\s+(?:add|start))\b/.test(command);
-}
 /**
  * Unique directories the session touched, compact and human-readable.
  * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so

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

@@ -0,0 +1,24 @@
+/**
+ * `agents sessions stop <id>` — end a live agent session outright: stop its
+ * interactive process and tear down its tmux/mux session, so the session becomes
+ * done/closed rather than an orphaned idle background process.
+ *
+ * The lifecycle sibling of `detach` that does NOT resume headless. `detach`
+ * backgrounds a still-wanted agent (stop the terminal, keep it working); `stop`
+ * is for when the work is over — the agent's editor tab was closed, or you want
+ * it gone. Both reuse the same live-session resolution and the same
+ * `stopInteractive` teardown (tmux `kill-session`, else SIGTERM→SIGKILL the pid),
+ * so a session killed here reaps its helpers exactly as `detach` does before it
+ * resumes.
+ *
+ * The primary caller is AGI EXT: when a user genuinely closes an agent tab
+ * (Cmd+W), the extension runs this so the underlying agent + its mux are shut
+ * down instead of being left running detached (the "Cmd+W orphans an idle
+ * session" bug). A window RELOAD does NOT call this — the extension distinguishes
+ * the two via `terminal.exitStatus.reason` and only a real user close tears down.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionsStopCommand(program: Command): void;
+export declare function stopSessionAction(id: string, opts?: {
+    local?: boolean;
+}): Promise<void>;

package/dist/commands/sessions-stop.js

@@ -0,0 +1,66 @@
+import chalk from 'chalk';
+import { gatherLiveTargets } from './go.js';
+import { resolveDetachTarget, resolveOne } from './detach-core.js';
+import { stopInteractive } from './detach.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
+import { setHelpSections } from '../lib/help.js';
+export function registerSessionsStopCommand(program) {
+    const cmd = program
+        .command('stop')
+        .argument('<id>', 'Short or full id of the live session to stop')
+        .option('--local', 'Only this machine (skip the cross-host sweep)')
+        .description('Stop a live agent outright — end its process and tear down its tmux/mux session')
+        .action(async (id, opts) => {
+        await stopSessionAction(id, opts);
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Stop a live session by a short id prefix
+      agents sessions stop 4b2f1a9c
+
+      # Only look on this machine (skip the fleet sweep)
+      agents sessions stop 4b2f1a9c --local
+    `,
+        notes: `
+      stop ENDS the session; it does not background it. To keep an agent working
+      unattended instead, use \`agents sessions detach <id>\`, and bring it back
+      with \`agents sessions resume <id>\`.
+
+      A session that lives on another machine is stopped THERE over SSH — its pid
+      and tmux socket only mean something where it actually runs.
+    `,
+    });
+}
+export async function stopSessionAction(id, opts = {}) {
+    const { self, activeById } = await gatherLiveTargets(!!opts.local, { includeCloud: true });
+    const resolved = resolveOne(activeById, id);
+    if ('error' in resolved) {
+        console.error(chalk.red(resolved.error));
+        process.exitCode = 1;
+        return;
+    }
+    const s = resolved;
+    const target = resolveDetachTarget(s, self);
+    // Cloud/team/id-less sessions have their own lifecycles — refuse rather than
+    // half-stopping one from here (same boundary `detach` enforces).
+    if (target.kind === 'refuse') {
+        console.error(chalk.red(target.reason));
+        process.exitCode = 1;
+        return;
+    }
+    const short = target.sessionId.slice(0, 8);
+    // A session on another host: its pid/tmux socket only mean something where it
+    // runs, so stop it THERE over SSH — never kill locally. Mirrors detach/focus.
+    if (target.kind === 'remote') {
+        console.log(chalk.gray(`${short} lives on ${target.machine} — stopping it there over SSH…`));
+        const rc = await runOnPeer(['sessions', 'stop', target.sessionId, '--local'], target.machine);
+        if (rc === 'no-target') {
+            console.error(chalk.red(`Can't reach ${target.machine} to stop ${short}.`));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Local: end the interactive process and tear down its tmux/mux session.
+    await stopInteractive(s);
+    console.log(chalk.green(`■ Stopped ${s.kind} ${short}`) + chalk.gray(' — process ended, session closed.'));
+}

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

@@ -0,0 +1,82 @@
+import type { Command } from 'commander';
+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. */
+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`. */
+export interface SessionsTraceDiffEnvelope {
+    divergence?: TrajectoryDivergence;
+    added: TrajectoryStep[];
+    removed: TrajectoryStep[];
+    summaryA: TrajectorySummary;
+    summaryB: TrajectorySummary;
+    truncatedA: number;
+    truncatedB: number;
+}
+/** The `lineage` block of a `layout: 'lineage'` envelope — the delegation graph. */
+export interface SessionsTraceLineageEnvelope {
+    rootId: string;
+    nodes: LineageNode[];
+    edges: LineageEdge[];
+    teams: string[];
+    unresolvedParentIds: string[];
+}
+/** The `--json` envelope: the versioned contract for the ext / triaging agents. */
+export interface SessionsTraceEnvelope {
+    schemaVersion: typeof SESSIONS_TRACE_SCHEMA_VERSION;
+    kind: 'sessions-trace';
+    layout: 'single' | 'compare' | 'lineage';
+    sessions: SessionTrajectory[];
+    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;
+    text?: boolean;
+    json?: boolean;
+    output?: string;
+    open?: boolean;
+    errorsOnly?: boolean;
+    redact?: boolean;
+    all?: boolean;
+    since?: string;
+    limit?: string;
+    agent?: string;
+    compare?: boolean;
+    tree?: boolean;
+}
+export 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';
+/** Attach the trace behaviour to a command node (canonical or top-level alias). */
+export declare function configureTraceCommand(cmd: Command): Command;
+/** 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 {};