@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/dist/lib/terminal/run-surface.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `agents run … --terminal` — re-open this exact run as a tab in a real terminal.
+ *
+ * A GUI caller (the menu bar's "New Session") cannot host a TUI, so it has to
+ * hand the run to a terminal. It used to do that by hardcoding AppleScript at
+ * Terminal.app; now it appends `--terminal` and the CLI decides WHICH terminal
+ * from the user's own live sessions (preferred.ts) and opens the tab through the
+ * launch engine — the same engine `sessions resume` and `sessions focus` use.
+ *
+ * The re-invocation is the caller's own argv with the `--terminal` flag removed,
+ * so every other flag (`--mode`, `--cwd`, a `--` passthrough) rides along
+ * untouched and there is no second place that knows how to spell a run.
+ */
+import type { Backend, EngineContext } from './types.js';
+import type { ActiveSession } from '../session/active.js';
+import { type LaunchBackendChoice, type SessionHostSample } from './preferred.js';
+/** Backends a user may name in `--terminal <backend>`. */
+export declare const TERMINAL_FLAG_BACKENDS: Backend[];
+/**
+ * Validate a `--terminal <value>`. Returns the backend, or an error message
+ * naming the valid ids — never a silent fallback to auto-detection, which would
+ * open a terminal the user did not ask for.
+ */
+export declare function parseTerminalFlag(value: unknown): {
+    backend?: Backend;
+    error?: string;
+};
+/**
+ * The argv to re-invoke, with `--terminal` (and the value commander consumed for
+ * it) removed. `consumedValue` is the parsed option value when it is a string —
+ * that is the only token after the flag that belongs to it, so a prompt or a
+ * following flag is never eaten.
+ */
+export declare function stripTerminalFlag(argv: string[], consumedValue?: string): string[];
+/** `agents run …` as a shell-safe command line for the surface to exec. */
+export declare function buildRunCommand(argv: string[]): string[];
+/**
+ * Turn live sessions into the samples the resolver reads, filling in the app
+ * each tmux-hosted session is currently VIEWED in.
+ *
+ * This step is what makes detection work for the common case: `agents run`
+ * wraps interactive runs in tmux, so a session the user started in Ghostty is
+ * attributed `host: 'tmux'` on the discovery path and would otherwise name no
+ * terminal at all. `resolveViewingIn` walks the attached tmux client's pid up to
+ * its host app — the same resolver `agents sessions` uses to print
+ * "viewing in Ghostty tab 2". Sessions that are detached (no client attached)
+ * legitimately have no viewer and keep their `tmux` host.
+ *
+ * One inherited nuance: `resolveViewingIn` labels a client whose app it cannot
+ * identify `'terminal'` (viewing-in.ts:87), so a tmux session viewed from an
+ * unrecognized emulator resolves to Terminal.app rather than falling through.
+ * That lands on the same every-Mac floor the fallback chain ends at anyway, so
+ * it costs nothing here — but it is a default, not a detection.
+ *
+ * Best-effort: any probe failure degrades to the plain host, never throws.
+ */
+export declare function toHostSamples(sessions: ActiveSession[]): Promise<SessionHostSample[]>;
+export interface OpenRunSurfaceParams {
+    /** This process's argv after the program name (i.e. `['run','claude',…]`). */
+    argv: string[];
+    /** The parsed `--terminal` value, when the user named a backend. */
+    forced?: Backend;
+    /** The value commander consumed for `--terminal`, so it can be stripped. */
+    consumedValue?: string;
+    cwd: string;
+    /** Live sessions, used to detect the terminal the user actually works in. */
+    sessions: SessionHostSample[];
+    ctx: EngineContext;
+}
+export interface OpenRunSurfaceResult {
+    ok: boolean;
+    choice?: LaunchBackendChoice;
+    /** Human line describing the terminal that was chosen. */
+    description?: string;
+    error?: string;
+}
+/**
+ * Open the run as a tab in the resolved terminal. Never throws — a failure comes
+ * back as `ok: false` with the reason, so the caller can tell the user rather
+ * than exiting silently.
+ */
+export declare function openRunInTerminal(params: OpenRunSurfaceParams): Promise<OpenRunSurfaceResult>;

package/dist/lib/terminal/run-surface.js

@@ -0,0 +1,146 @@
+import { BACKENDS } from './backends/index.js';
+import { openSurface } from './engine.js';
+import { getCliLaunch } from '../cli-entry.js';
+import { shellQuote } from './quote.js';
+import { resolveLaunchBackend, describeBackendChoice, } from './preferred.js';
+/** Backends a user may name in `--terminal <backend>`. */
+export const TERMINAL_FLAG_BACKENDS = Object.keys(BACKENDS);
+/**
+ * Validate a `--terminal <value>`. Returns the backend, or an error message
+ * naming the valid ids — never a silent fallback to auto-detection, which would
+ * open a terminal the user did not ask for.
+ */
+export function parseTerminalFlag(value) {
+    if (value === undefined || value === true || value === '')
+        return {};
+    const raw = String(value);
+    if (TERMINAL_FLAG_BACKENDS.includes(raw))
+        return { backend: raw };
+    // `--terminal [backend]` takes an OPTIONAL value, and commander assigns the
+    // next non-option token to it — so `agents run claude --terminal "fix the bug"`
+    // lands the prompt here. Say that, or the user just sees their prompt called a
+    // bad backend name and has no idea why.
+    const looksLikeAPrompt = /\s/.test(raw) || raw.length > 24;
+    const hint = looksLikeAPrompt
+        ? ` That looks like a prompt: put it BEFORE the flag — agents run <agent> "${raw.length > 40 ? `${raw.slice(0, 40)}…` : raw}" --terminal.`
+        : '';
+    return {
+        error: `Unknown --terminal backend '${raw}'. Use one of: ${TERMINAL_FLAG_BACKENDS.join(', ')} (or pass --terminal alone to auto-detect).${hint}`,
+    };
+}
+/**
+ * The argv to re-invoke, with `--terminal` (and the value commander consumed for
+ * it) removed. `consumedValue` is the parsed option value when it is a string —
+ * that is the only token after the flag that belongs to it, so a prompt or a
+ * following flag is never eaten.
+ */
+export function stripTerminalFlag(argv, consumedValue) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        // Everything past a bare `--` is forwarded verbatim to the agent's own CLI
+        // (`agents run kimi -- --terminal`), so it is not ours to rewrite.
+        if (tok === '--') {
+            out.push(...argv.slice(i));
+            break;
+        }
+        if (tok === '--terminal') {
+            if (consumedValue !== undefined && argv[i + 1] === consumedValue)
+                i++;
+            continue;
+        }
+        if (tok.startsWith('--terminal='))
+            continue;
+        out.push(tok);
+    }
+    return out;
+}
+/** `agents run …` as a shell-safe command line for the surface to exec. */
+export function buildRunCommand(argv) {
+    const { command, args } = getCliLaunch(argv);
+    return [command, ...args].map(shellQuote);
+}
+/**
+ * Turn live sessions into the samples the resolver reads, filling in the app
+ * each tmux-hosted session is currently VIEWED in.
+ *
+ * This step is what makes detection work for the common case: `agents run`
+ * wraps interactive runs in tmux, so a session the user started in Ghostty is
+ * attributed `host: 'tmux'` on the discovery path and would otherwise name no
+ * terminal at all. `resolveViewingIn` walks the attached tmux client's pid up to
+ * its host app — the same resolver `agents sessions` uses to print
+ * "viewing in Ghostty tab 2". Sessions that are detached (no client attached)
+ * legitimately have no viewer and keep their `tmux` host.
+ *
+ * One inherited nuance: `resolveViewingIn` labels a client whose app it cannot
+ * identify `'terminal'` (viewing-in.ts:87), so a tmux session viewed from an
+ * unrecognized emulator resolves to Terminal.app rather than falling through.
+ * That lands on the same every-Mac floor the fallback chain ends at anyway, so
+ * it costs nothing here — but it is a default, not a detection.
+ *
+ * Best-effort: any probe failure degrades to the plain host, never throws.
+ */
+export async function toHostSamples(sessions) {
+    const samples = sessions.map((s) => ({
+        host: s.host,
+        lastActivityMs: s.lastActivityMs,
+        startedAtMs: s.startedAtMs,
+    }));
+    const tmuxIdx = sessions
+        .map((s, i) => ({ s, i }))
+        .filter(({ s }) => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
+    if (tmuxIdx.length === 0)
+        return samples;
+    try {
+        const { enumerateGhosttyTabs } = await import('../session/ghostty-tabs.js');
+        const { mapPanesToTargets, listClients } = await import('../tmux/session.js');
+        const { resolveViewingIn } = await import('../session/viewing-in.js');
+        // One Ghostty enumeration shared across sockets, as the sessions renderer does.
+        const ghosttySurfaces = await enumerateGhosttyTabs();
+        const sockets = new Set(tmuxIdx.map(({ s }) => s.provenance.mux.socket));
+        for (const socket of sockets) {
+            const paneToTarget = await mapPanesToTargets(socket);
+            if (paneToTarget.size === 0)
+                continue;
+            const clients = await listClients(socket);
+            for (const { s, i } of tmuxIdx) {
+                if (s.provenance.mux.socket !== socket)
+                    continue;
+                const viewing = await resolveViewingIn(s, clients, { paneToTarget, ghosttySurfaces });
+                if (viewing)
+                    samples[i].viewingApp = viewing.app;
+            }
+        }
+    }
+    catch {
+        // tmux/Ghostty probes are best-effort; fall back to the plain host values.
+    }
+    return samples;
+}
+/**
+ * Open the run as a tab in the resolved terminal. Never throws — a failure comes
+ * back as `ok: false` with the reason, so the caller can tell the user rather
+ * than exiting silently.
+ */
+export async function openRunInTerminal(params) {
+    const choice = params.forced
+        ? { backend: params.forced, source: 'forced' }
+        : resolveLaunchBackend(params.ctx, params.sessions);
+    if (!choice) {
+        return {
+            ok: false,
+            error: 'No terminal this machine can drive (need iTerm, Ghostty, Terminal.app, VSCodium, or a tmux session). Run without --terminal.',
+        };
+    }
+    if (params.forced && !BACKENDS[choice.backend].isAvailable(params.ctx)) {
+        return { ok: false, error: `--terminal ${choice.backend} is not available here.` };
+    }
+    const command = buildRunCommand(stripTerminalFlag(params.argv, params.consumedValue));
+    const result = await openSurface({
+        backend: choice.backend,
+        layout: 'tab',
+        cwd: params.cwd,
+        command,
+    });
+    return { ok: result.ok, choice, description: describeBackendChoice(choice), error: result.error };
+}

package/dist/lib/terminal/types.d.ts

@@ -8,7 +8,7 @@
  * is attended and live. See docs/terminal-engine.md.
  */
 /** An interactive terminal backend the engine can drive. */
-export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent';
+export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent' | 'terminal';
 /** Which way a split pane grows. `right` = side-by-side; `down` = stacked. */
 export type SplitDirection = 'right' | 'down';
 /** Where a surface lands: a new tab, or a split of the current pane. */

package/dist/lib/types.d.ts

@@ -62,7 +62,7 @@ export interface BudgetConfig {
     require_confirm_over?: number;
 }
 /** Preview features that users can opt into via `agents beta`. */
-export type BetaFeatureName = 'drive' | 'factory' | 'session-sync';
+export type BetaFeatureName = 'drive' | 'factory' | 'session-sync' | 'projects';
 /** Subset of chalk color names used for agent-specific terminal output. */
 export type ChalkColor = 'magenta' | 'green' | 'blue' | 'cyan' | 'yellowBright' | 'redBright' | 'whiteBright' | 'blueBright' | 'greenBright' | 'magentaBright' | 'cyanBright';
 /** Static configuration for a single agent -- paths, capabilities, and format conventions. */
@@ -873,10 +873,11 @@ export interface Meta {
     };
     /**
      * Owner/channel notification config for `agents send` / `agents notify`.
-     * `owner` is the default recipient for `agents notify` (channel + target).
-     * `transports` maps a user-facing channel name to the provider that actually
-     * delivers it — explicit, one provider per channel, no fallback. Omitted keys
-     * default to name-identity (channel `slack` -> provider `slack`).
+     * `owner` is the address expanded by `--to owner` and by `agents notify`
+     * (channel + target). `transports` maps a user-facing channel name to the
+     * provider that actually delivers it — explicit, one provider per channel,
+     * no fallback. Omitted keys default to name-identity (channel `slack` ->
+     * provider `slack`).
      */
     notify?: {
         owner?: {

package/dist/lib/versions.d.ts

@@ -464,6 +464,12 @@ export interface SyncResult {
     subagents: string[];
     plugins: string[];
     workflows: string[];
+    /**
+     * Project files the sync left alone because the workspace already has them
+     * (repo-relative). Reported once, grouped, by the command that rendered the
+     * sync — never one line per file from down here.
+     */
+    projectSkipped: string[];
 }
 /**
  * Enumerate the DotAgent repo names that resources can be scoped to:

package/dist/lib/versions.js

@@ -2420,7 +2420,7 @@ export function mergeRepoScopedSelections(repos, cwd = process.cwd()) {
  */
 export function syncResourcesToVersion(agent, version, selection, options = {}) {
     if (isAgentHardDeprecated(agent)) {
-        return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
+        return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [] };
     }
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
@@ -2431,7 +2431,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // care about the ORIGINAL intent: a caller passing no selection means
     // "full sync; persist the staleness manifest after."
     const userPassedSelection = selection !== undefined;
-    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
+    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [] };
     const cwd = options.cwd || process.cwd();
     const projectAgentsDir = options.projectDir || getProjectAgentsDir(cwd);
     const userAgentsDir = getUserAgentsDir();
@@ -2499,7 +2499,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
     }
     if (projectAgentsDir) {
-        syncProjectResourcesToAgent(agent, version, projectAgentsDir);
+        result.projectSkipped = syncProjectResourcesToAgent(agent, version, projectAgentsDir).skipped;
     }
     // Fast guard: skip the entire sync when the caller requested a full sync and
     // nothing has changed since the last full sync. Pattern-derived selections
@@ -2508,7 +2508,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (!userPassedSelection && !options.force) {
         const manifest = loadManifest(agent, version);
         if (manifest && !isStale(manifest, agent, version, cwd)) {
-            return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
+            // Nothing synced, but the project sync above already ran — carry its
+            // skipped files out so the caller can still report them.
+            return { ...result };
         }
     }
     // Helper: remove a path (symlink or real) if it exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.91",
+  "version": "1.20.93",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -99,6 +99,7 @@
     "marked-terminal": "7.3.0",
     "ora": "9.4.1",
     "proper-lockfile": "4.1.2",
+    "shlex": "3.0.0",
     "simple-git": "3.36.0",
     "smol-toml": "1.7.0",
     "ws": "^8.21.0",