@swarmify/agents-cli 1.13.2 → 1.13.3

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sessions-tail.test.d.ts.map

package/dist/commands/__tests__/sessions-tail.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions-tail.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/sessions-tail.test.ts"],"names":[],"mappings":""}

package/dist/commands/__tests__/sessions-tail.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { tailFile } from '../sessions-tail.js';
+function mkTempDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'agents-tail-test-'));
+}
+/** Wait for a predicate to become true, polling every 20ms. */
+async function waitFor(predicate, timeoutMs = 2000) {
+    const start = Date.now();
+    while (!predicate()) {
+        if (Date.now() - start > timeoutMs) {
+            throw new Error(`timeout waiting for predicate after ${timeoutMs}ms`);
+        }
+        await new Promise((r) => setTimeout(r, 20));
+    }
+}
+describe('tailFile', () => {
+    it('emits each line exactly once across multiple appends', async () => {
+        const dir = mkTempDir();
+        const filePath = path.join(dir, 'session.jsonl');
+        fs.writeFileSync(filePath, '');
+        const lines = [];
+        const ac = new AbortController();
+        const tailPromise = tailFile(filePath, (l) => lines.push(l), ac);
+        // Give watcher time to attach
+        await new Promise((r) => setTimeout(r, 50));
+        await fsp.appendFile(filePath, 'one\n');
+        await waitFor(() => lines.length >= 1);
+        await fsp.appendFile(filePath, 'two\nthree\n');
+        await waitFor(() => lines.length >= 3);
+        // Partial line: should NOT emit until newline arrives
+        await fsp.appendFile(filePath, 'partial');
+        await new Promise((r) => setTimeout(r, 80));
+        expect(lines).toEqual(['one', 'two', 'three']);
+        await fsp.appendFile(filePath, '-done\n');
+        await waitFor(() => lines.length >= 4);
+        ac.abort();
+        await tailPromise;
+        expect(lines).toEqual(['one', 'two', 'three', 'partial-done']);
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it('starts at EOF by default (does not emit pre-existing lines)', async () => {
+        const dir = mkTempDir();
+        const filePath = path.join(dir, 'session.jsonl');
+        fs.writeFileSync(filePath, 'old-a\nold-b\n');
+        const lines = [];
+        const ac = new AbortController();
+        const tailPromise = tailFile(filePath, (l) => lines.push(l), ac);
+        await new Promise((r) => setTimeout(r, 80));
+        await fsp.appendFile(filePath, 'new\n');
+        await waitFor(() => lines.length >= 1);
+        ac.abort();
+        await tailPromise;
+        expect(lines).toEqual(['new']);
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it('replays the full file when fromStart is true', async () => {
+        const dir = mkTempDir();
+        const filePath = path.join(dir, 'session.jsonl');
+        fs.writeFileSync(filePath, 'a\nb\nc\n');
+        const lines = [];
+        const ac = new AbortController();
+        const tailPromise = tailFile(filePath, (l) => lines.push(l), ac, { fromStart: true });
+        await waitFor(() => lines.length >= 3);
+        ac.abort();
+        await tailPromise;
+        expect(lines).toEqual(['a', 'b', 'c']);
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it('waits for a file that does not exist yet', async () => {
+        const dir = mkTempDir();
+        const filePath = path.join(dir, 'later.jsonl');
+        const lines = [];
+        const ac = new AbortController();
+        const tailPromise = tailFile(filePath, (l) => lines.push(l), ac);
+        await new Promise((r) => setTimeout(r, 60));
+        fs.writeFileSync(filePath, 'hello\n');
+        await waitFor(() => lines.length >= 1);
+        expect(lines).toEqual(['hello']);
+        ac.abort();
+        await tailPromise;
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it('handles file truncation by resetting offset', async () => {
+        const dir = mkTempDir();
+        const filePath = path.join(dir, 'trunc.jsonl');
+        fs.writeFileSync(filePath, '');
+        const lines = [];
+        const ac = new AbortController();
+        const tailPromise = tailFile(filePath, (l) => lines.push(l), ac);
+        await new Promise((r) => setTimeout(r, 50));
+        await fsp.appendFile(filePath, 'first\nsecond\n');
+        await waitFor(() => lines.length >= 2);
+        // Truncate + write new content
+        fs.writeFileSync(filePath, 'after-trunc\n');
+        await waitFor(() => lines.length >= 3, 3000);
+        ac.abort();
+        await tailPromise;
+        expect(lines).toContain('first');
+        expect(lines).toContain('second');
+        expect(lines).toContain('after-trunc');
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+});
+//# sourceMappingURL=sessions-tail.test.js.map

package/dist/commands/__tests__/sessions-tail.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions-tail.test.js","sourceRoot":"","sources":["../../../src/commands/__tests__/sessions-tail.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,20 @@
+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;
+//# sourceMappingURL=sessions-tail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions-tail.d.ts","sourceRoot":"","sources":["../../src/commands/sessions-tail.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,EAAE,EAAE,eAAe,EACnB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAkGf;AAgFD,sEAAsE;AACtE,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA+BtE"}

package/dist/commands/sessions-tail.js

@@ -0,0 +1,236 @@
+/**
+ * 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);
+    });
+}
+//# sourceMappingURL=sessions-tail.js.map

package/dist/commands/sessions-tail.js.map

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

package/dist/commands/sessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/commands/sessions.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,KAAK,EAAkB,WAAW,EAAY,MAAM,yBAAyB,CAAC;AAqmBrF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAgBhG;AA2BD,yFAAyF;AACzF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,WAAW,EAAE,CAgDf;AAwMD,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2E/D"}
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/commands/sessions.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,KAAK,EAAkB,WAAW,EAAY,MAAM,yBAAyB,CAAC;AA4rBrF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAgBhG;AA2BD,yFAAyF;AACzF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,WAAW,EAAE,CAgDf;AAwMD,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkF/D"}

package/dist/commands/sessions.js

@@ -15,6 +15,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
+import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
@@ -24,6 +25,7 @@ import { colorAgent } from '../lib/agents.js';
 import { resolveVersion } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
+import { registerSessionsTailCommand } from './sessions-tail.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
@@ -131,8 +133,83 @@ async function renderArtifactsForSession(session, listAll, name) {
     }
     console.log(chalk.gray(`\n${artifacts.length} artifact${artifacts.length !== 1 ? 's' : ''}.`));
 }
+function statusColor(status) {
+    switch (status) {
+        case 'running': return chalk.green;
+        case 'idle': return chalk.gray;
+        case 'queued': return chalk.blue;
+        case 'input_required': return chalk.yellow;
+    }
+}
+function contextColor(context) {
+    switch (context) {
+        case 'terminal': return chalk.magenta;
+        case 'teams': return chalk.cyan;
+        case 'cloud': return chalk.blue;
+        case 'headless': return chalk.gray;
+    }
+}
+function shortCwd(cwd) {
+    if (!cwd)
+        return '-';
+    const home = os.homedir();
+    return cwd.startsWith(home) ? '~' + cwd.slice(home.length) : cwd;
+}
+function formatStartedAt(startedAtMs) {
+    if (!startedAtMs)
+        return '-';
+    return formatRelativeTime(new Date(startedAtMs).toISOString());
+}
+/** Render the unified active-session view. */
+async function renderActiveSessions(asJson) {
+    const sessions = await getActiveSessions();
+    if (asJson) {
+        process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+        return;
+    }
+    if (sessions.length === 0) {
+        console.log(chalk.gray('No active agent sessions.'));
+        return;
+    }
+    for (const s of sessions) {
+        const kindCol = colorAgent(s.kind)(padRight(truncate(s.kind, 8), 9));
+        const ctxCol = contextColor(s.context)(padRight(truncate(s.context, 8), 9));
+        const hostCol = chalk.gray(padRight(truncate(s.host ?? '-', 8), 9));
+        const statusCol = statusColor(s.status)(padRight(truncate(s.status, 8), 9));
+        const pidCol = chalk.yellow(padRight(s.pid ? String(s.pid) : '-', 7));
+        const idCol = chalk.white(padRight(s.sessionId ? s.sessionId.slice(0, 8) : '-', 10));
+        const detail = s.context === 'cloud'
+            ? `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`
+            : s.context === 'teams'
+                ? `${s.teamName ?? ''}${s.label ? ` · ${s.label}` : ''}`
+                : s.label ?? shortCwd(s.cwd);
+        console.log(pidCol +
+            kindCol +
+            ctxCol +
+            hostCol +
+            statusCol +
+            idCol +
+            chalk.cyan(padRight(truncate(detail || '-', 30), 32)) +
+            chalk.gray(formatStartedAt(s.startedAtMs)));
+    }
+    const runningCount = sessions.filter(s => s.status === 'running').length;
+    const idleCount = sessions.filter(s => s.status === 'idle').length;
+    const queuedCount = sessions.filter(s => s.status === 'queued' || s.status === 'input_required').length;
+    const parts = [];
+    if (runningCount > 0)
+        parts.push(`${runningCount} running`);
+    if (idleCount > 0)
+        parts.push(`${idleCount} idle`);
+    if (queuedCount > 0)
+        parts.push(`${queuedCount} queued`);
+    console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}).`));
+}
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    if (options.active) {
+        await renderActiveSessions(options.json === true);
+        return;
+    }
     let filterOpts;
     try {
         filterOpts = buildFilterOptions(options);
@@ -800,7 +877,7 @@ async function renderOneSession(query, mode, scope) {
 }
 /** Register the `agents sessions` command with all its options and help text. */
 export function registerSessionsCommands(program) {
-    program
+    const sessionsCmd = program
         .command('sessions')
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
         .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
@@ -819,6 +896,7 @@ export function registerSessionsCommands(program) {
         .option('--last <n>', 'Keep only the last N turns (a turn starts at each user message)')
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
+        .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
         .addHelpText('after', `
 Examples:
   # Interactive picker: browse and search recent sessions (TTY only)
@@ -866,6 +944,10 @@ Examples:
   # Include team-spawned sessions in results
   agents sessions --teams
 
+  # Show only live sessions across terminals, teams, cloud, and headless agents
+  agents sessions --active
+  agents sessions --active --json
+
 Notes:
   - --include and --exclude are mutually exclusive.
   - --first and --last are mutually exclusive.
@@ -874,6 +956,7 @@ Notes:
         .action(async (query, options) => {
         await sessionsAction(query, options);
     });
+    registerSessionsTailCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();