@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/commands/sessions-resume.js

@@ -1,12 +1,14 @@
 /**
- * `agents sessions resume` — multi-select sessions and fan each one out into a
- * terminal surface via the terminal launch engine (src/lib/terminal).
+ * `agents sessions resume` — the one resume surface.
  *
- * Unlike the single-select picker behind bare `agents sessions` (which resumes
- * one session in place), this opens a checkbox picker, then asks where the
- * chosen sessions should resume. By default each session opens in its own tab in
- * the terminal you're in — iTerm / Ghostty / tmux, locally or on a remote host
- * via --host. `--splits` opts into packing two sessions side by side per tab.
+ * - Strict single-session: `sessions resume <id> [prompt]` with optional
+ *   --mode/--headless/--interactive/--cwd/--quiet/--here (formerly top-level
+ *   `agents resume`). Identity resolution + owner-device hop live in resume.ts.
+ * - Multi-select: bare `sessions resume` opens a checkbox picker and fans each
+ *   pick into a terminal tab/split via the terminal launch engine.
+ * - Direct id/alias always takes the strict path; live-pane attach is
+ *   `sessions focus`.
+ * - `--device` opens the terminal surface on the session origin only.
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -25,29 +27,42 @@ import { spawn } from 'node:child_process';
 import { looksLikeSessionId } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
+import { runStrictResume, wantsStrictResume } from './resume.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
     const cmd = sessionsCmd
         .command('resume')
-        .argument('[query]', 'Session id/tmux alias to reopen directly, or text that filters the picker')
-        .description('Reopen one session by canonical identity, or multi-select history into terminal tabs/splits.')
+        .argument('[query]', 'Session id/tmux alias/label for strict resume, or text that filters the picker')
+        .argument('[prompt]', 'Optional follow-up prompt (strict resume with original harness/version/device)')
+        .description('Resume a session by id (strict), or multi-select history into terminal tabs/splits.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .option('--all', 'Include sessions from every directory (not just current project)')
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
-        .option('--host <alias>', 'Open on the session origin host over SSH; the host must match every selected session')
+        .option('--device <alias>', 'Open on the session origin device over SSH; the device must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
         .option('--tmux', 'Force the tmux backend')
         .option('--vscodium', 'Force the VSCodium agent-terminal backend (swarm-ext)')
         .option('--terminal-app', 'Force macOS Terminal.app (no split support — panes become tabs)')
+        .option('--splits', 'Pack two sessions side by side per tab (default: one tab per session)')
+        .option('-m, --mode <mode>', 'Strict resume: override the recorded launch mode')
+        .option('-i, --interactive', 'Strict resume: interactive even when a prompt is provided')
+        .option('--headless', 'Strict resume: headless (a prompt is required)')
+        .option('--cwd <path>', 'Strict resume: override the recorded working directory')
+        .option('-q, --quiet', 'Strict resume: suppress routing banners')
+        .option('--here', 'Strict resume: run on this machine even if the session belongs to another device')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
-        .option('--attach-only', 'With an id/alias: attach a living pane only — never resume a copy')
-        .option('--splits', 'Pack two sessions side by side per tab (default: one tab per session)');
+        .option('--attach-only', 'With an id/alias: attach a living pane only — never resume a copy');
     setHelpSections(cmd, {
         examples: `
+      # Strict resume by full id (former top-level agents resume)
+      agents sessions resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897
+      agents sessions resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
+      agents sessions resume ag-codex-c1f3d813 --mode edit
+
       # Pick several sessions; each opens in its own tab
       agents sessions resume
 
@@ -65,9 +80,11 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       agents sessions resume --ghostty
       agents sessions resume --vscodium
       agents sessions resume --splits
-      agents sessions resume --host zion --tmux
+      agents sessions resume --device zion --tmux
     `,
         notes: `
+      - Strict path (id/tmux alias/label + optional prompt/--mode/--headless/--here): restores original harness, version, device, account, cwd, and mode. Searches the fleet; a local full-id hit resumes with zero SSH. Replaces the former top-level agents sessions resume.
+      - Attach a live pane without forking: agents sessions focus <id>.
       - This is the ONE verb for getting back in. It detects the state: a live tmux pane is attached, a headless session comes to the foreground, an ended one recovers on its owning device.
       - A UUID/prefix or ag-<agent>-<suffix> alias bypasses the picker. A live alias attaches by name even when the session index cannot attribute it.
       - Retired spellings still work for one release and print the replacement: sessions attach, sessions go, reconnect.
@@ -75,23 +92,40 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       - With no identity selector, space toggles a session, enter confirms, and tab toggles the preview pane.
       - Layout: one tab per session by default. --splits packs session pairs side by side in each tab.
       - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux/--vscodium.
-      - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --host too).
-      - --host <alias> opens the terminal surface on that host only when it is the selected sessions' origin; recovery never migrates a session to another device.
+      - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --device too).
+      - --device <alias> opens the terminal surface on that device only when it is the selected sessions' origin; recovery never migrates a session to another device.
       - Recovery runs on the session's origin device: exact healthy origin uses native resume; otherwise a healthy version of the same harness receives /continue <id>.
     `,
     });
-    cmd.action(async (query, options) => {
-        await sessionsResumeAction(query, options);
+    cmd.action(async (query, prompt, options) => {
+        await sessionsResumeAction(query, prompt, options);
     });
 }
-async function sessionsResumeAction(query, options) {
-    if (!isInteractiveTerminal()) {
-        console.error(chalk.red('sessions resume needs an interactive terminal.'));
-        process.exitCode = 1;
+async function sessionsResumeAction(query, prompt, options) {
+    const strictOpts = {
+        mode: options.mode,
+        interactive: options.interactive,
+        headless: options.headless,
+        cwd: options.cwd,
+        quiet: options.quiet,
+        here: options.here,
+    };
+    // Direct id/alias (or label with prompt/strict flags) → strict resume
+    // (former top-level `agents sessions resume`). `--attach-only` / `--local`
+    // must go through sessions focus so they cannot silently fork a copy
+    // (AGI EXT still shells `sessions resume <id> --local`).
+    if (query && (isDirectResumeSelector(query) || wantsStrictResume(prompt, strictOpts))) {
+        if (resumeUsesLifecycleDispatch(query, prompt, options)) {
+            const hosts = options.device ? [options.device] : [];
+            await dispatchSessionLifecycleInPlace(query.trim(), hosts, !!options.attachOnly, !!options.local);
+            return;
+        }
+        await runStrictResume(query.trim(), prompt, strictOpts);
         return;
     }
-    if (query && isDirectResumeSelector(query)) {
-        await dispatchSessionLifecycleInPlace(query.trim(), options.host ? [options.host] : [], options.attachOnly === true, options.local === true);
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('sessions resume needs an interactive terminal (or pass a session id for strict resume).'));
+        process.exitCode = 1;
         return;
     }
     const { agent, version } = parseAgentFilter(options.agent);
@@ -138,8 +172,8 @@ async function sessionsResumeAction(query, options) {
     }
     if (!chosen || chosen.length === 0)
         return;
-    if (options.host) {
-        const requestedHost = options.host;
+    if (options.device) {
+        const requestedHost = options.device;
         const mismatches = chosen
             .map((session) => resumeHostMismatch(session, requestedHost))
             .filter((message) => message !== null);
@@ -153,7 +187,7 @@ async function sessionsResumeAction(query, options) {
     // 2. Route every selection through the owning device's recovery resolver.
     const items = [];
     for (const s of chosen) {
-        const command = buildSessionRecoveryCommand(s, !!options.host);
+        const command = buildSessionRecoveryCommand(s, !!options.device);
         const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
         items.push({ session: s, cwd, command });
     }
@@ -183,7 +217,7 @@ async function sessionsResumeAction(query, options) {
     // 5b. Fan out through the engine. Full-width tabs are the default for batch
     // recovery; callers can explicitly opt into pairs of side-by-side panes.
     const packing = resolveResumePacking(options);
-    const where = options.host ? `${backend} on ${options.host}` : backend;
+    const where = options.device ? `${backend} on ${options.device}` : backend;
     // Terminal.app has no scriptable split, so its buildSplit opens a tab. Say so
     // when the user actually asked for panes — the layout silently not happening
     // is worse than one line of warning.
@@ -199,7 +233,7 @@ async function sessionsResumeAction(query, options) {
         agent: it.session.agent || undefined,
         sessionId: it.session.id || undefined,
         title: it.session.label || it.session.topic || undefined,
-    })), { backend, host: options.host, packing });
+    })), { backend, host: options.device, packing });
     let opened = 0;
     results.forEach((r, i) => {
         const s = items[i].session;
@@ -220,21 +254,35 @@ export function isDirectResumeSelector(query) {
     const selector = query.trim();
     return looksLikeSessionId(selector) || isAgentTmuxAlias(selector);
 }
-/** Re-enter through the top-level command so fleet routing and harness policy
+/** Re-enter through sessions resume so fleet routing and harness policy
  * stay centralized. The child inherits this terminal for a real interactive resume. */
 export async function resumeSelectorInPlace(selector) {
-    await spawnCliInPlace(['resume', selector]);
+    await spawnCliInPlace(['sessions', 'resume', selector]);
 }
 /** Direct identities use focus as the lifecycle dispatcher: it rechecks the
  * live fleet, attaches a healthy pane, and falls through to `agents resume`
  * only when the process is no longer attachable. */
+/** True when `sessions resume <id> --attach-only|--local` must go through
+ *  `sessions focus` instead of `runStrictResume` (which can fork a copy). */
+export function resumeUsesLifecycleDispatch(query, prompt, options) {
+    if (!query || !isDirectResumeSelector(query))
+        return false;
+    if (!options.attachOnly && !options.local)
+        return false;
+    return !wantsStrictResume(prompt, {
+        mode: options.mode,
+        interactive: options.interactive,
+        headless: options.headless,
+        here: options.here,
+    });
+}
 export async function dispatchSessionLifecycleInPlace(selector, hosts = [], attachOnly = false, local = false) {
     await spawnCliInPlace(buildSessionLifecycleArgs(selector, hosts, attachOnly, local));
 }
 export function buildSessionLifecycleArgs(selector, hosts = [], attachOnly = false, local = false) {
     return [
         'sessions', 'focus', selector,
-        ...hosts.flatMap(host => ['--host', host]),
+        ...hosts.flatMap(host => ['--device', host]),
         ...(attachOnly ? ['--attach-only'] : []),
         ...(local ? ['--local'] : []),
     ];
@@ -257,7 +305,7 @@ export function resumeHostMismatch(session, requestedHost, self = machineId()) {
     const origin = sessionOriginDevice(session, self);
     return sessionRecoveryDestinationMatches(session, requestedHost, self)
         ? null
-        : `Session ${session.shortId} originated on ${origin}; --host ${requestedHost} cannot move recovery to another device.`;
+        : `Session ${session.shortId} originated on ${origin}; --device ${requestedHost} cannot move recovery to another device.`;
 }
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
@@ -274,7 +322,7 @@ export async function resolveBackend(options, ctx, count) {
     if (forced)
         return forced;
     // Remote defaults to tmux (headless, no GUI session assumptions); override with a backend flag.
-    if (options.host)
+    if (options.device)
         return 'tmux';
     const available = availableBackends(ctx);
     if (available.length === 0)

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

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+import { type PublishOptions } from '../lib/share/publish.js';
+interface ShareOptions {
+    public?: boolean;
+    slug?: string;
+    label?: string;
+    expire?: string;
+    reasoning: string;
+    force?: boolean;
+    cover?: boolean;
+}
+/** `session-<shortId>` — stable per session, so re-sharing updates the same URL. */
+export declare function defaultSessionSlug(session: SessionMeta): string;
+/**
+ * Map the command's flags onto {@link PublishOptions}.
+ *
+ * Extracted so the defaults are testable directly. `unlisted` in particular is the
+ * security-relevant one — it inverts the parent command's public-by-default
+ * behavior, and a test that re-implements this mapping would still pass with it
+ * flipped.
+ */
+export declare function buildSharePublishOptions(session: SessionMeta, options: Pick<ShareOptions, 'public' | 'slug' | 'label' | 'expire' | 'force' | 'cover'>): PublishOptions;
+export declare function registerSessionsShareCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-share.js

@@ -0,0 +1,166 @@
+/**
+ * `agents sessions share <id>` — publish one session transcript as a link.
+ *
+ * Composes three pieces that already existed but were never wired together:
+ * `renderSessionMarkdownDocument()` (redacted transcript),
+ * `renderSessionHtmlDocument()` (self-contained branded page), and
+ * `publishFile()` (the R2-backed share Worker). Before this, sharing a session
+ * meant three commands and a detour through the external artifacts-cli.
+ *
+ * Unlisted by default, unlike `agents artifacts share`. A transcript carries file
+ * paths, command output, error text, and whatever a tool printed — strictly more
+ * than a plan does — so it does not belong in the public `/<user>` gallery unless
+ * the operator asks for it with `--public`. The URL itself stays world-readable:
+ * unlisted is a capability URL, not a secret.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { knownSecretValuesFromEnv } from '../lib/redact.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { renderSessionHtmlDocument } from '../lib/session/share-html.js';
+import { publishFile, redactEmails } from '../lib/share/publish.js';
+import { renderSessionMarkdownDocument } from './sessions-render.js';
+import { selectSessions } from './sessions-export.js';
+import { parseAgentFilter } from './sessions.js';
+function parseReasoning(value) {
+    if (value === 'omit' || value === 'fold' || value === 'include')
+        return value;
+    throw new Error(`Unknown reasoning mode "${value}". Expected omit, fold, or include.`);
+}
+/** `session-<shortId>` — stable per session, so re-sharing updates the same URL. */
+export function defaultSessionSlug(session) {
+    return `session-${session.shortId || session.id}`;
+}
+/**
+ * Map the command's flags onto {@link PublishOptions}.
+ *
+ * Extracted so the defaults are testable directly. `unlisted` in particular is the
+ * security-relevant one — it inverts the parent command's public-by-default
+ * behavior, and a test that re-implements this mapping would still pass with it
+ * flipped.
+ */
+export function buildSharePublishOptions(session, options) {
+    return {
+        slug: options.slug ?? defaultSessionSlug(session),
+        unlisted: options.public !== true,
+        expire: options.expire,
+        force: options.force === true,
+        cover: options.cover !== false,
+        label: options.label,
+        meta: { kind: 'session' },
+    };
+}
+export function registerSessionsShareCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('share <session>')
+        .description('Publish one session as a redacted, self-contained web page and print the link.')
+        .option('--public', 'List the page in your public share gallery (default: unlisted capability URL)')
+        .option('--slug <slug>', 'URL slug under your namespace (default: session-<shortId>)')
+        .option('--label <text>', 'Display title in the gallery and `agents artifacts share list`')
+        .option('--expire <spec>', 'Auto-expire window: 30d, 12h, a date, or never (default: 30d)')
+        .option('--reasoning <mode>', 'Reasoning visibility: omit, fold, or include', 'omit')
+        .option('--force', 'Publish despite the sensitive-content scan flagging the transcript')
+        .option('--no-cover', 'Skip generating the Open Graph preview image');
+    setHelpSections(cmd, {
+        examples: `# Share a session — prints an unlisted, redacted link
+agents sessions share a1b2c3d4
+
+# Put it in your public gallery at share.agents-cli.sh/<you>
+agents sessions share a1b2c3d4 --public --label "How the retry bug got fixed"
+
+# Keep the model's reasoning in collapsible sections
+agents sessions share a1b2c3d4 --reasoning fold
+
+# A link that does not decay
+agents sessions share a1b2c3d4 --expire never`,
+        notes: `Requires a share endpoint: 'agents artifacts share status' shows it, 'agents artifacts setup'
+provisions one, 'agents artifacts share join <baseUrl>' uses an existing one.
+
+Unlisted by default — the URL is world-readable but the page stays out of your public
+gallery and out of 'agents artifacts share list'. Pass --public to list it.
+
+Secrets are redacted and the same pre-publish scan as 'agents artifacts share' runs on the
+page, so a transcript carrying emails or credential-shaped strings is refused
+unless you pass --force. --no-redact (the sessions-level flag) disables redaction
+and is a bad idea for anything you publish.
+
+Re-running with the same session updates the same URL and keeps the prior version
+as a revision ('agents artifacts share revisions <slug>').
+
+Manage published sessions with 'agents artifacts share list' and
+'agents artifacts share delete <slug>'.`,
+    });
+    cmd.action(async (selector, options, command) => {
+        const globals = command.optsWithGlobals();
+        const reasoning = parseReasoning(options.reasoning);
+        const limit = Math.max(1, Number.parseInt(globals.limit || '100', 10) || 100);
+        const agent = parseAgentFilter(globals.agent).agent;
+        const sessions = selectSessions(await discoverSessions({
+            all: globals.all !== false,
+            since: globals.since,
+            limit,
+            agent: agent ?? undefined,
+        }), [selector]);
+        if (sessions.length === 0) {
+            process.stderr.write(chalk.yellow(`No session matched "${selector}".\n`));
+            process.exitCode = 1;
+            return;
+        }
+        // One link per share: several sessions in one page would give the reader no
+        // way to reference just the one that matters, and the slug could only name one.
+        if (sessions.length > 1) {
+            process.stderr.write(chalk.yellow(`"${selector}" matched ${sessions.length} sessions. Share one at a time — pass a full or unique session id.\n`));
+            process.exitCode = 1;
+            return;
+        }
+        const session = sessions[0];
+        const redact = globals.redact !== false;
+        const markdown = renderSessionMarkdownDocument(session, {
+            redact,
+            reasoning,
+            knownSecrets: redact ? knownSecretValuesFromEnv() : undefined,
+        });
+        // Emails on top of what the renderer masks. Almost every real transcript
+        // carries a few — git author addresses, `gh api user`, a pasted log — and
+        // publishToEndpoint refuses a body containing any (RUSH-2428). Masking them
+        // means the published page genuinely does not carry them; the alternative,
+        // telling people to pass --force, would train everyone to bypass the gate
+        // that also catches real credentials.
+        //
+        // Applied to the RENDERED PAGE, not the Markdown, so the text that is masked
+        // is exactly the text `scanShareContent` will scan. Markdown escaping stands
+        // between the two: `foo\@example.com` hides from the pattern in the Markdown
+        // and reappears as a live address once marked drops the backslash.
+        const page = renderSessionHtmlDocument(session, markdown, { redacted: redact });
+        const html = redact ? redactEmails(page) : page;
+        // A real file on disk is what publishFile() takes, and the OG capturer opens
+        // it in a browser. 0600 + a per-run directory keeps the intermediate off a
+        // world-readable /tmp path while it exists.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-session-share-'));
+        const file = path.join(dir, `${defaultSessionSlug(session)}.html`);
+        try {
+            fs.writeFileSync(file, html, { mode: 0o600 });
+            const result = await publishFile(file, buildSharePublishOptions(session, options));
+            if (globals.json) {
+                process.stdout.write(JSON.stringify({
+                    session: session.id,
+                    agent: session.agent,
+                    redacted: redact,
+                    ...result,
+                }, null, 2) + '\n');
+                return;
+            }
+            process.stdout.write(`${result.url}\n`);
+            const bits = [result.unlisted ? 'unlisted' : 'public', redact ? 'redacted' : chalk.red('NOT redacted')];
+            if (result.expiresAt)
+                bits.push(`expires ${result.expiresAt.slice(0, 10)}`);
+            process.stderr.write(chalk.dim(`${bits.join(' · ')}\n`));
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+}

package/dist/commands/sessions-stats.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryResourceUsageStats, resourceUsageCoverage, } from '../lib/session/db.js';
 import { listResources } from '../lib/resources.js';
-import { discoverPlugins } from '../lib/plugins.js';
+import { discoverPlugins } from '../lib/plugins/plugins.js';
 import { setHelpSections } from '../lib/help.js';
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth } from '../lib/session/width.js';
 const DEFAULT_TOP = 20;
@@ -100,7 +100,7 @@ async function statsAction(cmd) {
     const kind = normalizeKind(opts.kind);
     const sinceMs = opts.since ? parseTimeFilter(opts.since) : undefined;
     const top = resolveTop(opts.top);
-    // Warm the incremental index (like `agents cost`) so recent sessions' usage is
+    // Warm the incremental index (like `agents insights cost`) so recent sessions' usage is
     // current before we read. Historical gaps still need the explicit backfill.
     await discoverSessions({ all: true, since: opts.since, limit: 1 });
     const filter = {};