@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/teams/api.js

@@ -55,6 +55,84 @@ function recentToolCalls(events, max = 10) {
         timestamp: typeof event.timestamp === 'string' ? event.timestamp : null,
     }));
 }
+/** Max files to name per category in the summary. Counts are always exact. */
+const SUMMARY_MAX_FILE_NAMES = 6;
+/** Max messages in the summary. */
+const SUMMARY_MAX_MESSAGES = 3;
+/** Max chars per message body in the summary. */
+const SUMMARY_MESSAGE_MAX_CHARS = 400;
+/**
+ * Reduce a file path to just its basename for compact rendering. Keeps the
+ * orchestrator oriented ("you touched types.ts") without dumping the full
+ * absolute path every time. The full paths are still in `AgentStatusDetail`
+ * for the verbose path.
+ */
+function basenameOf(p) {
+    const ix = p.lastIndexOf('/');
+    return ix < 0 ? p : p.slice(ix + 1);
+}
+/**
+ * Trim long assistant messages to a fixed budget. We collapse leading
+ * whitespace so the budget covers actual content, not indent.
+ */
+function trimMessage(msg, max = SUMMARY_MESSAGE_MAX_CHARS) {
+    const s = msg.replace(/^\s+/, '');
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + '…';
+}
+/** Pull at most `max` basenames out of a path list, preserving order. */
+function compactFileList(paths, max = SUMMARY_MAX_FILE_NAMES) {
+    const seen = new Set();
+    const names = [];
+    for (const p of paths) {
+        const base = basenameOf(p);
+        if (seen.has(base))
+            continue;
+        seen.add(base);
+        names.push(base);
+        if (names.length >= max)
+            break;
+    }
+    return { count: paths.length, names };
+}
+/**
+ * Project a full AgentStatusDetail down to a compact AgentStatusSummary.
+ * Drops `prompt` entirely (caller knows what they queued), folds file lists
+ * to basenames + counts, caps `last_messages` to 3 × {@link SUMMARY_MESSAGE_MAX_CHARS}.
+ */
+export function toAgentStatusSummary(detail) {
+    return {
+        agent_id: detail.agent_id,
+        name: detail.name ?? null,
+        agent_type: detail.agent_type,
+        status: detail.status,
+        duration: detail.duration,
+        tool_count: detail.tool_count,
+        has_errors: detail.has_errors,
+        pr_url: detail.pr_url ?? null,
+        files: {
+            modified: compactFileList(detail.files_modified),
+            created: compactFileList(detail.files_created),
+            deleted: compactFileList(detail.files_deleted),
+            read: { count: detail.files_read.length },
+        },
+        bash_commands: detail.bash_commands,
+        last_messages: detail.last_messages
+            .slice(-SUMMARY_MAX_MESSAGES)
+            .map((m) => trimMessage(m)),
+        cursor: detail.cursor,
+    };
+}
+/** Project a full TaskStatusResult down to the compact summary shape. */
+export function toTaskStatusSummary(result) {
+    return {
+        task_name: result.task_name,
+        agents: result.agents.map(toAgentStatusSummary),
+        summary: result.summary,
+        cursor: result.cursor,
+    };
+}
 /** Spawn a new teammate in a task and return its initial metadata. */
 export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
     const defaultMode = manager.getDefaultMode();

package/dist/lib/teams/parsers.d.ts

@@ -1,5 +1,5 @@
 /** Supported agent CLI types for team spawning. */
-export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity';
+export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity' | 'kimi';
 /** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export declare function normalizeEvents(agentType: AgentType, raw: any): any[];
 /** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */

package/dist/lib/tmux/binary.d.ts

@@ -0,0 +1,67 @@
+/**
+ * tmux binary discovery + spawn helpers.
+ *
+ * Every shell-out goes through `runTmux()` so:
+ *  - args are passed as an array, never interpolated into a shell string (no
+ *    quoting bugs like swarmify's `command.replace(/'/g, "'\\''")` hack);
+ *  - the socket arg is positioned correctly (`-S <sock>` MUST come before the
+ *    subcommand);
+ *  - stdout/stderr capture is consistent for the session module to parse.
+ */
+/**
+ * Locate the tmux binary on PATH. Cached after first call — tmux either is or
+ * isn't installed for the duration of the process.
+ *
+ * Returns null when tmux is not installed.
+ */
+export declare function findTmuxBinary(): string | null;
+/** True when tmux is installed somewhere on PATH. */
+export declare function isTmuxInstalled(): boolean;
+/** Best-effort tmux version string (e.g. "tmux 3.6a"). Returns null when not installed or version probe fails. */
+export declare function getTmuxVersion(): string | null;
+/**
+ * Throw a user-friendly error when tmux isn't installed. Command handlers call
+ * this first thing so the error message is the same shape every time.
+ */
+export declare function assertTmuxAvailable(): string;
+export declare class TmuxUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare class TmuxCommandError extends Error {
+    readonly stderr: string;
+    readonly stdout: string;
+    readonly code: number | null;
+    constructor(message: string, stderr: string, stdout: string, code: number | null);
+}
+export interface RunTmuxOptions {
+    /** Socket path (default: shared server socket). */
+    socket?: string;
+    /** Args after `tmux -S <socket>` — e.g. `['has-session', '-t', 'foo']`. */
+    args: string[];
+    /** Throw on nonzero exit. Defaults true. */
+    throwOnError?: boolean;
+    /** Child process env. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Run a tmux command and capture stdout/stderr. The socket arg is hoisted in
+ * front of `args` so callers never have to remember the `-S` position.
+ *
+ * For interactive `attach`, use `attachTmux()` instead — this helper is for
+ * scripted commands where you want output back as strings.
+ */
+export declare function runTmux(opts: RunTmuxOptions): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+/**
+ * Foreground attach. Replaces this process's stdio with tmux's so the user is
+ * fully inside tmux. Returns the tmux exit code (which the caller should mirror
+ * via process.exit so detach/Ctrl-D propagates cleanly).
+ */
+export declare function attachTmux(opts: {
+    socket: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+}): Promise<number>;

package/dist/lib/tmux/binary.js

@@ -0,0 +1,141 @@
+/**
+ * tmux binary discovery + spawn helpers.
+ *
+ * Every shell-out goes through `runTmux()` so:
+ *  - args are passed as an array, never interpolated into a shell string (no
+ *    quoting bugs like swarmify's `command.replace(/'/g, "'\\''")` hack);
+ *  - the socket arg is positioned correctly (`-S <sock>` MUST come before the
+ *    subcommand);
+ *  - stdout/stderr capture is consistent for the session module to parse.
+ */
+import { spawn, spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+let cachedBin;
+/**
+ * Locate the tmux binary on PATH. Cached after first call — tmux either is or
+ * isn't installed for the duration of the process.
+ *
+ * Returns null when tmux is not installed.
+ */
+export function findTmuxBinary() {
+    if (cachedBin !== undefined)
+        return cachedBin;
+    // Try `which` first (respects PATH); fall back to common Homebrew/Linux paths
+    // so a stripped CI shell with a sparse PATH still works.
+    const fromWhich = spawnSync('sh', ['-c', 'command -v tmux'], { encoding: 'utf8' });
+    if (fromWhich.status === 0) {
+        const out = fromWhich.stdout.trim();
+        if (out && existsSync(out)) {
+            cachedBin = out;
+            return cachedBin;
+        }
+    }
+    for (const p of ['/opt/homebrew/bin/tmux', '/usr/local/bin/tmux', '/usr/bin/tmux']) {
+        if (existsSync(p)) {
+            cachedBin = p;
+            return cachedBin;
+        }
+    }
+    cachedBin = null;
+    return null;
+}
+/** True when tmux is installed somewhere on PATH. */
+export function isTmuxInstalled() {
+    return findTmuxBinary() !== null;
+}
+/** Best-effort tmux version string (e.g. "tmux 3.6a"). Returns null when not installed or version probe fails. */
+export function getTmuxVersion() {
+    const bin = findTmuxBinary();
+    if (!bin)
+        return null;
+    const res = spawnSync(bin, ['-V'], { encoding: 'utf8' });
+    if (res.status !== 0)
+        return null;
+    return res.stdout.trim() || null;
+}
+/**
+ * Throw a user-friendly error when tmux isn't installed. Command handlers call
+ * this first thing so the error message is the same shape every time.
+ */
+export function assertTmuxAvailable() {
+    const bin = findTmuxBinary();
+    if (!bin) {
+        const platform = process.platform;
+        const hint = platform === 'darwin'
+            ? 'Install with: brew install tmux'
+            : platform === 'linux'
+                ? 'Install with: apt install tmux  (or dnf/yum/pacman equivalent)'
+                : 'Install tmux from https://github.com/tmux/tmux';
+        throw new TmuxUnavailableError(`tmux is not installed. ${hint}`);
+    }
+    return bin;
+}
+export class TmuxUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TmuxUnavailableError';
+    }
+}
+export class TmuxCommandError extends Error {
+    stderr;
+    stdout;
+    code;
+    constructor(message, stderr, stdout, code) {
+        super(message);
+        this.name = 'TmuxCommandError';
+        this.stderr = stderr;
+        this.stdout = stdout;
+        this.code = code;
+    }
+}
+/**
+ * Run a tmux command and capture stdout/stderr. The socket arg is hoisted in
+ * front of `args` so callers never have to remember the `-S` position.
+ *
+ * For interactive `attach`, use `attachTmux()` instead — this helper is for
+ * scripted commands where you want output back as strings.
+ */
+export async function runTmux(opts) {
+    const bin = assertTmuxAvailable();
+    const fullArgs = [];
+    if (opts.socket)
+        fullArgs.push('-S', opts.socket);
+    fullArgs.push(...opts.args);
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, fullArgs, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: opts.env ?? process.env,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (b) => { stdout += b.toString('utf8'); });
+        child.stderr?.on('data', (b) => { stderr += b.toString('utf8'); });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            const exitCode = code ?? -1;
+            const throwOnError = opts.throwOnError !== false;
+            if (throwOnError && exitCode !== 0) {
+                reject(new TmuxCommandError(`tmux ${fullArgs.join(' ')} failed (exit ${exitCode}): ${stderr.trim() || stdout.trim()}`, stderr, stdout, exitCode));
+                return;
+            }
+            resolve({ stdout, stderr, code: exitCode });
+        });
+    });
+}
+/**
+ * Foreground attach. Replaces this process's stdio with tmux's so the user is
+ * fully inside tmux. Returns the tmux exit code (which the caller should mirror
+ * via process.exit so detach/Ctrl-D propagates cleanly).
+ */
+export function attachTmux(opts) {
+    const bin = assertTmuxAvailable();
+    const fullArgs = ['-S', opts.socket, ...opts.args];
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, fullArgs, {
+            stdio: 'inherit',
+            env: opts.env ?? process.env,
+        });
+        child.on('error', reject);
+        child.on('close', (code) => resolve(code ?? 0));
+    });
+}

package/dist/lib/tmux/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public entry-point for the tmux integration. Consumers outside the CLI
+ * (swarmify extension, `agents teams` multiplexer mode, future MCP wrapper)
+ * should import from here.
+ */
+export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
+export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
+export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, type SessionMeta, type CreateSessionOptions, type ListedSession, type SplitOptions, type SendOptions, type CaptureOptions, } from './session.js';

package/dist/lib/tmux/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public entry-point for the tmux integration. Consumers outside the CLI
+ * (swarmify extension, `agents teams` multiplexer mode, future MCP wrapper)
+ * should import from here.
+ */
+export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
+export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
+export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, } from './session.js';

package/dist/lib/tmux/paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Filesystem paths for the tmux integration.
+ *
+ * Layout under ~/.agents/.cache/helpers/tmux/:
+ *   server.sock        — shared tmux server socket hosting all named sessions
+ *   <name>.json        — per-session provenance (cmd, cwd, created_at, source)
+ *
+ * A single shared server is simpler than per-session sockets: one round-trip
+ * for `tmux ls`, one place to clean up, and no extra tmux servers eating
+ * memory. Per-session isolation can still be opted into via `--socket`.
+ */
+/** Default shared server socket — every `agents tmux *` command targets this unless overridden. */
+export declare function getDefaultSocketPath(): string;
+/** Per-session provenance JSON. tmux itself is the source of truth for liveness; this file is metadata only. */
+export declare function getSessionMetaPath(name: string): string;
+/** Ensure the tmux scratch dir exists with restrictive permissions (sockets are user-private). */
+export declare function ensureTmuxDir(): string;

package/dist/lib/tmux/paths.js

@@ -0,0 +1,30 @@
+/**
+ * Filesystem paths for the tmux integration.
+ *
+ * Layout under ~/.agents/.cache/helpers/tmux/:
+ *   server.sock        — shared tmux server socket hosting all named sessions
+ *   <name>.json        — per-session provenance (cmd, cwd, created_at, source)
+ *
+ * A single shared server is simpler than per-session sockets: one round-trip
+ * for `tmux ls`, one place to clean up, and no extra tmux servers eating
+ * memory. Per-session isolation can still be opted into via `--socket`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getTmuxDir } from '../state.js';
+/** Default shared server socket — every `agents tmux *` command targets this unless overridden. */
+export function getDefaultSocketPath() {
+    return path.join(getTmuxDir(), 'server.sock');
+}
+/** Per-session provenance JSON. tmux itself is the source of truth for liveness; this file is metadata only. */
+export function getSessionMetaPath(name) {
+    return path.join(getTmuxDir(), `${name}.json`);
+}
+/** Ensure the tmux scratch dir exists with restrictive permissions (sockets are user-private). */
+export function ensureTmuxDir() {
+    const dir = getTmuxDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}

package/dist/lib/tmux/session.d.ts

@@ -0,0 +1,122 @@
+/**
+ * tmux session lifecycle.
+ *
+ * Public surface used by both `agents tmux` commands and external consumers
+ * (swarmify, `agents teams` with a future multiplexer mode). Every state
+ * change goes through here so the CLI surface stays a thin parser.
+ *
+ * Liveness model: tmux itself owns liveness. The `<name>.json` meta files are
+ * pure provenance — `listSessions()` always reconciles them against
+ * `tmux list-sessions` and prunes stale entries on the fly.
+ */
+/** Provenance written alongside each live tmux session. */
+export interface SessionMeta {
+    name: string;
+    socket: string;
+    createdAt: number;
+    /** Initial command launched in the first pane (informational — tmux owns the actual process). */
+    cmd?: string;
+    /** Working directory the session was created in. */
+    cwd?: string;
+    /** Who created this session — useful for `agents sessions --active` attribution. */
+    source: 'cli' | 'extension' | 'teams' | 'external';
+    /** Free-form labels callers can stamp (e.g. `{ agent: 'claude', vscodePid: 1234 }`). */
+    labels?: Record<string, string>;
+}
+export interface CreateSessionOptions {
+    name: string;
+    cmd?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    socket?: string;
+    source?: SessionMeta['source'];
+    labels?: Record<string, string>;
+    /** When the named session already exists, kill it before creating. */
+    replace?: boolean;
+    /** When the named session already exists, return it instead of failing. */
+    attachExisting?: boolean;
+    /** Initial window dimensions for the detached session. tmux clamps to client size on attach. */
+    width?: number;
+    height?: number;
+}
+export interface ListedSession {
+    name: string;
+    socket: string;
+    /** Unix epoch seconds reported by tmux (`session_created`). */
+    createdAtTmux: number;
+    windows: number;
+    attached: boolean;
+    meta?: SessionMeta;
+}
+export declare class TmuxSessionError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Reject invalid session names early — tmux's error for `.`/`:` is cryptic. */
+export declare function assertValidSessionName(name: string): void;
+/** Slugify an arbitrary string into a valid session name. Useful for swarmify auto-generated names. */
+export declare function slugifyName(input: string): string;
+/** True when a session by this name currently exists on the given socket. */
+export declare function hasSession(name: string, socket?: string): Promise<boolean>;
+/**
+ * Create a new detached session. Throws when the name is already taken unless
+ * `replace` or `attachExisting` is set.
+ */
+export declare function createSession(opts: CreateSessionOptions): Promise<SessionMeta>;
+/** Kill one named session. Idempotent — killing a non-existent session is a no-op. */
+export declare function killSession(name: string, socket?: string): Promise<boolean>;
+/**
+ * Kill every session on the shared server AND the server itself, then prune
+ * meta files. Wipes the socket so the next `new` starts from a clean slate.
+ */
+export declare function killAll(socket?: string): Promise<number>;
+/**
+ * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
+ *  - tmux session with no meta → returned without `meta` (external session)
+ *  - meta file with no tmux session → meta deleted (stale)
+ */
+export declare function listSessions(opts?: {
+    socket?: string;
+}): Promise<ListedSession[]>;
+export interface SplitOptions {
+    name: string;
+    direction: 'h' | 'v';
+    cmd?: string;
+    cwd?: string;
+    socket?: string;
+}
+/**
+ * Split the active pane of a session. Returns the new pane's tmux pane id
+ * (e.g. `%3`) so callers can target it later via `send`/`capture`.
+ */
+export declare function splitPane(opts: SplitOptions): Promise<string>;
+export interface SendOptions {
+    name: string;
+    /** Pane id (e.g. `%2`) or pane index (`0`, `1`) — appended after the session name when targeting a specific pane. */
+    pane?: string;
+    /** The literal characters to type into the pane. */
+    keys: string;
+    /** When true, do NOT append Enter at the end. */
+    noEnter?: boolean;
+    /**
+     * When true, treat `keys` as a single literal string (-l flag). When false
+     * (default), tmux interprets named keys like `C-c`, `Enter`, `Escape`.
+     */
+    raw?: boolean;
+    socket?: string;
+}
+/** Send keystrokes to a session's active pane (or a specific pane via :pane). */
+export declare function sendKeys(opts: SendOptions): Promise<void>;
+export interface CaptureOptions {
+    name: string;
+    pane?: string;
+    /** Number of lines from history to include (default: visible screen only). */
+    lines?: number;
+    /** Keep ANSI escape sequences (default strips them). */
+    ansi?: boolean;
+    socket?: string;
+}
+/** Capture pane contents as a string. The cleaned form is what humans see. */
+export declare function capturePane(opts: CaptureOptions): Promise<string>;
+/** Read a session's provenance JSON, if present. */
+export declare function readSessionMeta(name: string): SessionMeta | null;