@phnx-labs/agents-cli 1.20.3 → 1.20.5

package/dist/lib/staleness/writers/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-(kind, agent) writer contract.
+ *
+ * The aggregator in `syncResourcesToVersion` (versions.ts) selects names per
+ * kind, then dispatches into a writer from `../registry.ts`. The writer owns
+ * everything kind-specific: the agent's storage format, the layered source
+ * search, the conversion/copy step. Writers MUST be reached only after a
+ * `supports(agent, kind, version).ok === true` precheck — they throw when
+ * called on a (kind, agent) pair that the capability matrix says is false.
+ *
+ * The shape is intentionally narrow. Writers don't accept ambient state; the
+ * caller passes the names already resolved against availability. Selection is
+ * a string[] for most kinds, a PermissionsSelection object for permissions,
+ * and a RulesSelection object for rules — see kind-specific writer modules.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceKind } from './kinds.js';
+export interface WriteArgs<Sel> {
+    /** Agent version (e.g. "1.2.3") — passed for version-gated capability checks and side files. */
+    version: string;
+    /** Absolute path to the version's home dir, i.e. `~/.agents/.history/versions/<agent>/<version>/home`. */
+    versionHome: string;
+    /** Kind-specific selection payload. */
+    selection: Sel;
+    /** Current working directory — used by writers that consult project-layer state. */
+    cwd: string;
+}
+export interface WriteResult {
+    /** Names actually written. Empty array = write produced nothing (not an error). */
+    synced: string[];
+}
+export interface ResourceWriter<Sel = string[]> {
+    readonly kind: ResourceKind;
+    readonly agent: AgentId;
+    write(args: WriteArgs<Sel>): WriteResult;
+}

package/dist/lib/staleness/writers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/staleness/writers/workflows.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Workflows writer — copies each workflow directory into
+ * `<versionHome>/workflows/<name>/` via `syncWorkflowToVersion`.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const workflowsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/workflows.js

@@ -0,0 +1,31 @@
+import { capableAgents } from '../../capabilities.js';
+import { listInstalledWorkflows, syncWorkflowToVersion } from '../../workflows.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildWorkflowsWriter(agent) {
+    return {
+        kind: 'workflows',
+        agent,
+        write({ versionHome, selection }) {
+            const all = listInstalledWorkflows();
+            const synced = [];
+            for (const name of selection) {
+                const wf = all.get(name);
+                if (!wf)
+                    continue;
+                try {
+                    const r = syncWorkflowToVersion(wf.path, name, agent, versionHome);
+                    if (r.success)
+                        synced.push(name);
+                }
+                catch { /* per-item failure: skip */ }
+            }
+            return { synced };
+        },
+    };
+}
+export const workflowsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('workflows'))
+        m[agent] = buildWorkflowsWriter(agent);
+    return m;
+});

package/dist/lib/state.d.ts

@@ -1,28 +1,34 @@
 /**
  * Filesystem layout and persistent state for agents-cli.
  *
- * Two roots:
- *  - ~/.agents-system/ — system repo (npm-shipped resources, read-only defaults)
- *  - ~/.agents/        — user repo (resources + agents.yaml + operational state)
+ * Single root at ~/.agents/ with three internal buckets:
  *
- * Inside ~/.agents/, top-level paths hold ONLY resources + agents.yaml.
- * Operational state lives in two sibling buckets:
- *
- *  - ~/.agents/.history/ — durable runtime data (sessions, versions, runs,
+ *   ~/.agents/           — user repo: user-authored resources + agents.yaml
+ *                          (git-tracked via `agents repo push`).
+ *   ~/.agents/.system/   — system repo: npm-shipped resources, regenerable.
+ *                          Don't hand-edit; maintained by npm install /
+ *                          `agents repo pull system`.
+ *   ~/.agents/.history/  — durable runtime data (sessions, versions, runs,
  *                          teams/agents, trash, backups). Backed up by
  *                          `agents repo push`.
- *  - ~/.agents/.cache/   — regenerable runtime data (shims, packages, helpers
+ *   ~/.agents/.cache/    — regenerable runtime data (shims, packages, helpers
  *                          for daemon/pty, terminals, cloud, drive, browser
  *                          chrome-data, logs, companion). Gitignored.
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
+ *
+ * Legacy layout (pre-fold): system repo lived at ~/.agents-system/ as a peer
+ * of ~/.agents/. runMigration() folds it into ~/.agents/.system/ on first run
+ * and leaves a back-compat symlink at the old path.
  */
 import type { Meta } from './types.js';
-/** Root of the system data directory (~/.agents-system/). */
+/** Root of the system data directory (~/.agents/.system/). */
 export declare function getAgentsDir(): string;
-/** Root of the system data directory (~/.agents-system/). */
+/** Root of the system data directory (~/.agents/.system/). */
 export declare function getSystemAgentsDir(): string;
+/** Legacy system-repo location (~/.agents-system/). Exported for migration only. */
+export declare function getLegacySystemAgentsDir(): string;
 /** Root of the user repo (~/.agents/). Always present after ensureAgentsDir(). */
 export declare function getUserAgentsDir(): string;
 /**
@@ -55,7 +61,7 @@ export declare function getMcpDir(): string;
 export declare function getPermissionsDir(): string;
 /** Path to subagent definition directories — system repo. */
 export declare function getSubagentsDir(): string;
-/** Path to ~/.agents-system/hooks/promptcuts.yaml (system defaults). */
+/** Path to ~/.agents/.system/hooks/promptcuts.yaml (system defaults). */
 export declare function getPromptcutsPath(): string;
 /**
  * Resolve the effective promptcuts file: user file if it exists, otherwise
@@ -101,6 +107,15 @@ export declare function getCacheDir(): string;
 export declare function getPackagesDir(): string;
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export declare function getRoutinesDir(): string;
+/**
+ * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
+ * or null when no project `.agents/` is found by walking up from cwd.
+ *
+ * Project routines participate in `list`/`view`/`run` for inspection but are
+ * NOT fired by the daemon (which runs from $HOME and only loads user routines).
+ * Opt-in firing for project routines is tracked as a follow-up.
+ */
+export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export declare function getRunsDir(): string;
 /** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
@@ -117,6 +132,12 @@ export declare function getBinDir(): string;
 export declare function getBackupsDir(): string;
 /** Path to plugin bundles (~/.agents/plugins/) — user-authored resource. */
 export declare function getPluginsDir(): string;
+/** Path to system plugin bundles (~/.agents/.system/plugins/) — npm-shipped, read-only defaults. */
+export declare function getSystemPluginsDir(): string;
+/** Path to an extra repo's plugin bundles (~/.agents-<alias>/plugins/). */
+export declare function getExtraPluginsDir(alias: string): string;
+/** Path to a project-scoped plugins directory (<project>/.agents/plugins/), or null when none. */
+export declare function getProjectPluginsDir(cwd?: string): string | null;
 /** Path to synced remote session data (~/.agents/.cache/drive/). */
 export declare function getDriveDir(): string;
 /** Path to soft-deleted resources (~/.agents/.history/trash/). */
@@ -149,6 +170,8 @@ export declare function getHelpersDir(): string;
 export declare function getDaemonDir(): string;
 /** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
 export declare function getPtyDir(): string;
+/** Path to tmux scratch (~/.agents/.cache/helpers/tmux/) — shared server socket + per-session meta JSONs. */
+export declare function getTmuxDir(): string;
 /** Path to remote-resource auto-pull cache (~/.agents/.cache/.fetch/). */
 export declare function getFetchCacheDir(): string;
 /** Path to the CLI version cache file (~/.agents/.cache/.cli-version-cache.json). */

package/dist/lib/state.js

@@ -1,22 +1,26 @@
 /**
  * Filesystem layout and persistent state for agents-cli.
  *
- * Two roots:
- *  - ~/.agents-system/ — system repo (npm-shipped resources, read-only defaults)
- *  - ~/.agents/        — user repo (resources + agents.yaml + operational state)
+ * Single root at ~/.agents/ with three internal buckets:
  *
- * Inside ~/.agents/, top-level paths hold ONLY resources + agents.yaml.
- * Operational state lives in two sibling buckets:
- *
- *  - ~/.agents/.history/ — durable runtime data (sessions, versions, runs,
+ *   ~/.agents/           — user repo: user-authored resources + agents.yaml
+ *                          (git-tracked via `agents repo push`).
+ *   ~/.agents/.system/   — system repo: npm-shipped resources, regenerable.
+ *                          Don't hand-edit; maintained by npm install /
+ *                          `agents repo pull system`.
+ *   ~/.agents/.history/  — durable runtime data (sessions, versions, runs,
  *                          teams/agents, trash, backups). Backed up by
  *                          `agents repo push`.
- *  - ~/.agents/.cache/   — regenerable runtime data (shims, packages, helpers
+ *   ~/.agents/.cache/    — regenerable runtime data (shims, packages, helpers
  *                          for daemon/pty, terminals, cloud, drive, browser
  *                          chrome-data, logs, companion). Gitignored.
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
+ *
+ * Legacy layout (pre-fold): system repo lived at ~/.agents-system/ as a peer
+ * of ~/.agents/. runMigration() folds it into ~/.agents/.system/ on first run
+ * and leaves a back-compat symlink at the old path.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -26,10 +30,16 @@ import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic
 import { SEEDED_REGISTRIES } from './types.js';
 const HOME = process.env.HOME ?? os.homedir();
 // ─── Root directories ─────────────────────────────────────────────────────────
-/** System repo — npm-shipped, read-only from user commands. */
-const SYSTEM_AGENTS_DIR = path.join(HOME, '.agents-system');
 /** User repo — user-authored resources and agents.yaml. Always-on. */
 const USER_AGENTS_DIR = path.join(HOME, '.agents');
+/** System repo — npm-shipped, read-only from user commands. Lives inside the user repo. */
+const SYSTEM_AGENTS_DIR = path.join(USER_AGENTS_DIR, '.system');
+/**
+ * Legacy system-repo location (pre-fold). Exported so the migrator can fold
+ * it into SYSTEM_AGENTS_DIR. No runtime code outside the migrator should
+ * reference this — use SYSTEM_AGENTS_DIR.
+ */
+const LEGACY_SYSTEM_AGENTS_DIR = path.join(HOME, '.agents-system');
 // ─── Meta file (agents.yaml lives in the user repo) ──────────────────────────
 const META_FILE = path.join(USER_AGENTS_DIR, 'agents.yaml');
 /** Legacy location — used only for one-shot migration in readMeta(). */
@@ -43,6 +53,7 @@ const SYSTEM_MCP_DIR = path.join(SYSTEM_AGENTS_DIR, 'mcp');
 const SYSTEM_PERMISSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'permissions');
 const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
 const SYSTEM_WORKFLOWS_DIR = path.join(SYSTEM_AGENTS_DIR, 'workflows');
+const SYSTEM_PLUGINS_DIR = path.join(SYSTEM_AGENTS_DIR, 'plugins');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
 const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
@@ -81,6 +92,7 @@ const BROWSER_RUNTIME_DIR = path.join(CACHE_DIR, 'browser');
 const HELPERS_DIR = path.join(CACHE_DIR, 'helpers');
 const DAEMON_DIR = path.join(HELPERS_DIR, 'daemon');
 const PTY_DIR = path.join(HELPERS_DIR, 'pty');
+const TMUX_DIR = path.join(HELPERS_DIR, 'tmux');
 const FETCH_CACHE_DIR = path.join(CACHE_DIR, '.fetch');
 const CLI_VERSION_CACHE_FILE = path.join(CACHE_DIR, '.cli-version-cache.json');
 const MODELS_CACHE_FILE = path.join(CACHE_DIR, '.models-cache.json');
@@ -103,14 +115,18 @@ const META_HEADER = `# agents-cli metadata
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────
-/** Root of the system data directory (~/.agents-system/). */
+/** Root of the system data directory (~/.agents/.system/). */
 export function getAgentsDir() {
     return SYSTEM_AGENTS_DIR;
 }
-/** Root of the system data directory (~/.agents-system/). */
+/** Root of the system data directory (~/.agents/.system/). */
 export function getSystemAgentsDir() {
     return SYSTEM_AGENTS_DIR;
 }
+/** Legacy system-repo location (~/.agents-system/). Exported for migration only. */
+export function getLegacySystemAgentsDir() {
+    return LEGACY_SYSTEM_AGENTS_DIR;
+}
 /** Root of the user repo (~/.agents/). Always present after ensureAgentsDir(). */
 export function getUserAgentsDir() {
     return USER_AGENTS_DIR;
@@ -187,7 +203,7 @@ export function getMcpDir() { return SYSTEM_MCP_DIR; }
 export function getPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
 /** Path to subagent definition directories — system repo. */
 export function getSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
-/** Path to ~/.agents-system/hooks/promptcuts.yaml (system defaults). */
+/** Path to ~/.agents/.system/hooks/promptcuts.yaml (system defaults). */
 export function getPromptcutsPath() { return SYSTEM_PROMPTCUTS_FILE; }
 /**
  * Resolve the effective promptcuts file: user file if it exists, otherwise
@@ -261,6 +277,20 @@ export function getCacheDir() { return CACHE_DIR; }
 export function getPackagesDir() { return PACKAGES_DIR; }
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export function getRoutinesDir() { return ROUTINES_DIR; }
+/**
+ * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
+ * or null when no project `.agents/` is found by walking up from cwd.
+ *
+ * Project routines participate in `list`/`view`/`run` for inspection but are
+ * NOT fired by the daemon (which runs from $HOME and only loads user routines).
+ * Opt-in firing for project routines is tracked as a follow-up.
+ */
+export function getProjectRoutinesDir(cwd = process.cwd()) {
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return null;
+    return path.join(projectAgentsDir, 'routines');
+}
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
 /** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
@@ -277,6 +307,19 @@ export function getBinDir() { return BIN_DIR; }
 export function getBackupsDir() { return BACKUPS_DIR; }
 /** Path to plugin bundles (~/.agents/plugins/) — user-authored resource. */
 export function getPluginsDir() { return PLUGINS_DIR; }
+/** Path to system plugin bundles (~/.agents/.system/plugins/) — npm-shipped, read-only defaults. */
+export function getSystemPluginsDir() { return SYSTEM_PLUGINS_DIR; }
+/** Path to an extra repo's plugin bundles (~/.agents-<alias>/plugins/). */
+export function getExtraPluginsDir(alias) {
+    return path.join(getExtraRepoDir(alias), 'plugins');
+}
+/** Path to a project-scoped plugins directory (<project>/.agents/plugins/), or null when none. */
+export function getProjectPluginsDir(cwd = process.cwd()) {
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return null;
+    return path.join(projectAgentsDir, 'plugins');
+}
 /** Path to synced remote session data (~/.agents/.cache/drive/). */
 export function getDriveDir() { return DRIVE_DIR; }
 /** Path to soft-deleted resources (~/.agents/.history/trash/). */
@@ -309,6 +352,8 @@ export function getHelpersDir() { return HELPERS_DIR; }
 export function getDaemonDir() { return DAEMON_DIR; }
 /** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
 export function getPtyDir() { return PTY_DIR; }
+/** Path to tmux scratch (~/.agents/.cache/helpers/tmux/) — shared server socket + per-session meta JSONs. */
+export function getTmuxDir() { return TMUX_DIR; }
 /** Path to remote-resource auto-pull cache (~/.agents/.cache/.fetch/). */
 export function getFetchCacheDir() { return FETCH_CACHE_DIR; }
 /** Path to the CLI version cache file (~/.agents/.cache/.cli-version-cache.json). */

package/dist/lib/subagents.d.ts

@@ -73,8 +73,6 @@ export declare function removeSubagentFromAgent(subagentName: string, agent: Age
  * Check if subagent content matches between source and installed
  */
 export declare function subagentContentMatches(installedDir: string, sourceDir: string): boolean;
-/** Agents that support the subagent system (Claude via flattened .md, OpenClaw via directory copy). */
-export declare const SUBAGENT_CAPABLE_AGENTS: AgentId[];
 /**
  * List subagents installed to a specific agent's home
  * Claude: scans ~/.claude/agents/{name}.md

package/dist/lib/subagents.js

@@ -9,6 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
+import { capableAgents } from './capabilities.js';
 import { getSubagentsDir, getUserSubagentsDir, getTrashSubagentsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { safeJoin } from './paths.js';
@@ -333,8 +334,9 @@ export function subagentContentMatches(installedDir, sourceDir) {
     }
     return true;
 }
-/** Agents that support the subagent system (Claude via flattened .md, OpenClaw via directory copy). */
-export const SUBAGENT_CAPABLE_AGENTS = ['claude', 'openclaw'];
+// SUBAGENT_CAPABLE_AGENTS removed — use `capableAgents('subagents')` from
+// lib/capabilities.ts. The capability matrix on AgentConfig is the single
+// source of truth.
 /**
  * List subagents installed to a specific agent's home
  * Claude: scans ~/.claude/agents/{name}.md
@@ -408,8 +410,6 @@ export function listSubagentsForAgent(agentId, home) {
     }
     return subagents;
 }
-// Agents that support subagents
-const SUBAGENTS_CAPABLE_AGENTS = ['claude', 'openclaw'];
 /**
  * Compare a version home's subagents against discovered subagents.
  * Returns orphan subagent names.
@@ -461,9 +461,9 @@ export function diffVersionSubagents(agent, version) {
  */
 export function iterSubagentsCapableVersions(filter) {
     const pairs = [];
-    const agents = filter?.agent ? [filter.agent] : SUBAGENTS_CAPABLE_AGENTS;
+    const agents = filter?.agent ? [filter.agent] : capableAgents('subagents');
     for (const agent of agents) {
-        if (!SUBAGENTS_CAPABLE_AGENTS.includes(agent))
+        if (!capableAgents('subagents').includes(agent))
             continue;
         const versions = listInstalledVersions(agent);
         for (const version of versions) {

package/dist/lib/teams/agents.js

@@ -172,7 +172,7 @@ export function captureProcessStartTime(pid) {
     }
 }
 /** Agent types the team runner supports. */
-const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode', 'grok', 'antigravity'];
+const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode', 'grok', 'antigravity', 'kimi'];
 // Suffix appended to all prompts to ensure agents provide a summary
 const PROMPT_SUFFIX = `
 

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;