@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/tmux/session.js

@@ -0,0 +1,305 @@
+/**
+ * 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.
+ */
+import * as fs from 'fs';
+import { runTmux, TmuxCommandError } from './binary.js';
+import { ensureTmuxDir, getDefaultSocketPath, getSessionMetaPath } from './paths.js';
+/** Tmux session names must not contain `.` or `:` — those are reserved for window/pane addressing. */
+const VALID_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+export class TmuxSessionError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'TmuxSessionError';
+    }
+}
+/** Reject invalid session names early — tmux's error for `.`/`:` is cryptic. */
+export function assertValidSessionName(name) {
+    if (!VALID_NAME.test(name)) {
+        throw new TmuxSessionError(`Invalid session name: "${name}". Use 1-64 characters from [A-Za-z0-9_-]. tmux disallows '.' and ':'.`);
+    }
+}
+/** Slugify an arbitrary string into a valid session name. Useful for swarmify auto-generated names. */
+export function slugifyName(input) {
+    const s = input.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
+    return s || `s-${Date.now()}`;
+}
+/** True when a session by this name currently exists on the given socket. */
+export async function hasSession(name, socket) {
+    assertValidSessionName(name);
+    const sock = socket ?? getDefaultSocketPath();
+    const res = await runTmux({
+        socket: sock,
+        args: ['has-session', '-t', `=${name}`],
+        throwOnError: false,
+    });
+    return res.code === 0;
+}
+/**
+ * Create a new detached session. Throws when the name is already taken unless
+ * `replace` or `attachExisting` is set.
+ */
+export async function createSession(opts) {
+    assertValidSessionName(opts.name);
+    ensureTmuxDir();
+    const socket = opts.socket ?? getDefaultSocketPath();
+    if (opts.cwd && !fs.existsSync(opts.cwd)) {
+        throw new TmuxSessionError(`cwd does not exist: ${opts.cwd}`);
+    }
+    const existed = await hasSession(opts.name, socket);
+    if (existed) {
+        if (opts.attachExisting) {
+            const meta = readSessionMeta(opts.name);
+            return meta ?? {
+                name: opts.name,
+                socket,
+                createdAt: Date.now(),
+                source: opts.source ?? 'cli',
+            };
+        }
+        if (!opts.replace) {
+            throw new TmuxSessionError(`Session "${opts.name}" already exists. Use --replace to overwrite or --attach-existing to reuse it.`);
+        }
+        await killSession(opts.name, socket);
+    }
+    // Set remain-on-exit BEFORE the child command can finish — a fast-exiting
+    // cmd (e.g. `echo BRIEF && true`) would otherwise collapse the only session,
+    // exit the server, and the follow-up `set-option` would race with "no
+    // server running". Server-wide (`-g`) is applied in the same tmux
+    // invocation as new-session so they share one server lifetime.
+    const args = ['set-option', '-g', 'remain-on-exit', 'on', ';', 'new-session', '-d', '-s', opts.name];
+    if (opts.width)
+        args.push('-x', String(opts.width));
+    if (opts.height)
+        args.push('-y', String(opts.height));
+    if (opts.cwd)
+        args.push('-c', opts.cwd);
+    // Separator + child command. tmux passes the rest verbatim to exec, so no
+    // shell escaping is required — array args end-to-end.
+    if (opts.cmd) {
+        args.push('--', 'sh', '-c', opts.cmd);
+    }
+    await runTmux({ socket, args, env: opts.env });
+    const meta = {
+        name: opts.name,
+        socket,
+        createdAt: Date.now(),
+        cmd: opts.cmd,
+        cwd: opts.cwd,
+        source: opts.source ?? 'cli',
+        labels: opts.labels,
+    };
+    writeSessionMeta(meta);
+    return meta;
+}
+/** Kill one named session. Idempotent — killing a non-existent session is a no-op. */
+export async function killSession(name, socket) {
+    assertValidSessionName(name);
+    const sock = socket ?? getDefaultSocketPath();
+    const existed = await hasSession(name, sock);
+    if (!existed) {
+        removeSessionMeta(name);
+        return false;
+    }
+    try {
+        await runTmux({ socket: sock, args: ['kill-session', '-t', `=${name}`] });
+    }
+    catch (err) {
+        if (err instanceof TmuxCommandError && err.code !== 0) {
+            // Already dead by the time the kill landed — treat as success.
+        }
+        else {
+            throw err;
+        }
+    }
+    removeSessionMeta(name);
+    return true;
+}
+/**
+ * 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 async function killAll(socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    let count = 0;
+    try {
+        const sessions = await listSessions({ socket: sock });
+        count = sessions.length;
+        await runTmux({ socket: sock, args: ['kill-server'], throwOnError: false });
+    }
+    catch {
+        // Server already gone — that's a successful kill-all.
+    }
+    // Clear meta files for every session we knew about.
+    const dir = ensureTmuxDir();
+    for (const f of fs.readdirSync(dir)) {
+        if (f.endsWith('.json')) {
+            try {
+                fs.unlinkSync(`${dir}/${f}`);
+            }
+            catch { /* race-tolerant */ }
+        }
+    }
+    // Stale socket can survive kill-server on some platforms — sweep it.
+    try {
+        fs.unlinkSync(sock);
+    }
+    catch { /* may not exist */ }
+    return count;
+}
+/**
+ * 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 async function listSessions(opts = {}) {
+    const socket = opts.socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(socket)) {
+        // No server has ever run — clean orphan metas defensively.
+        pruneAllMetas();
+        return [];
+    }
+    // Pipe-separated format so we don't need to parse tmux's variable-width default output.
+    const fmt = '#{session_name}|#{session_created}|#{session_windows}|#{session_attached}';
+    const res = await runTmux({
+        socket,
+        args: ['list-sessions', '-F', fmt],
+        throwOnError: false,
+    });
+    // tmux returns nonzero with "no server running" or "no sessions" — both mean empty.
+    if (res.code !== 0) {
+        if (/no server running|no sessions|error connecting/i.test(res.stderr)) {
+            pruneAllMetas();
+            return [];
+        }
+        throw new TmuxCommandError(`tmux list-sessions failed: ${res.stderr}`, res.stderr, res.stdout, res.code);
+    }
+    const lines = res.stdout.split('\n').map(l => l.trim()).filter(Boolean);
+    const out = [];
+    const liveNames = new Set();
+    for (const line of lines) {
+        const [name, createdRaw, windowsRaw, attachedRaw] = line.split('|');
+        if (!name)
+            continue;
+        liveNames.add(name);
+        out.push({
+            name,
+            socket,
+            createdAtTmux: parseInt(createdRaw, 10) || 0,
+            windows: parseInt(windowsRaw, 10) || 1,
+            attached: attachedRaw === '1',
+            meta: readSessionMeta(name) ?? undefined,
+        });
+    }
+    // Drop metas with no matching live session.
+    pruneOrphanMetas(liveNames);
+    return out;
+}
+/**
+ * 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 async function splitPane(opts) {
+    assertValidSessionName(opts.name);
+    const socket = opts.socket ?? getDefaultSocketPath();
+    if (opts.cwd && !fs.existsSync(opts.cwd)) {
+        throw new TmuxSessionError(`cwd does not exist: ${opts.cwd}`);
+    }
+    // tmux split-window directions: -h splits the pane left/right (sibling on the
+    // right); -v splits top/bottom. swarmify treats H as "below" and V as "side"
+    // — keep tmux semantics (h=left/right, v=top/bottom) and document it.
+    // Pane-target ops use the bare name (no =) — the '=' exact-match modifier is
+    // a session-only feature; pane targets reject it with "can't find pane".
+    // Slug validation already guarantees the name is unambiguous.
+    const args = ['split-window', `-${opts.direction}`, '-t', opts.name, '-P', '-F', '#{pane_id}'];
+    if (opts.cwd)
+        args.push('-c', opts.cwd);
+    if (opts.cmd)
+        args.push('--', 'sh', '-c', opts.cmd);
+    const res = await runTmux({ socket, args });
+    return res.stdout.trim();
+}
+/** Send keystrokes to a session's active pane (or a specific pane via :pane). */
+export async function sendKeys(opts) {
+    assertValidSessionName(opts.name);
+    const socket = opts.socket ?? getDefaultSocketPath();
+    // Bare name (no =) for pane targets — see note in splitPane.
+    const target = opts.pane ? `${opts.name}.${opts.pane}` : opts.name;
+    const args = ['send-keys', '-t', target];
+    if (opts.raw)
+        args.push('-l');
+    args.push(opts.keys);
+    if (!opts.noEnter)
+        args.push('Enter');
+    await runTmux({ socket, args });
+}
+/** Capture pane contents as a string. The cleaned form is what humans see. */
+export async function capturePane(opts) {
+    assertValidSessionName(opts.name);
+    const socket = opts.socket ?? getDefaultSocketPath();
+    // Bare name (no =) for pane targets — see note in splitPane.
+    const target = opts.pane ? `${opts.name}.${opts.pane}` : opts.name;
+    const args = ['capture-pane', '-p', '-t', target];
+    if (opts.ansi)
+        args.push('-e');
+    if (opts.lines && opts.lines > 0) {
+        // -S -N means "start N lines back from current view"; we use -S -<lines> -E -.
+        args.push('-S', `-${opts.lines}`);
+    }
+    const res = await runTmux({ socket, args });
+    return res.stdout;
+}
+/** Read a session's provenance JSON, if present. */
+export function readSessionMeta(name) {
+    try {
+        const raw = fs.readFileSync(getSessionMetaPath(name), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeSessionMeta(meta) {
+    ensureTmuxDir();
+    fs.writeFileSync(getSessionMetaPath(meta.name), JSON.stringify(meta, null, 2), { mode: 0o600 });
+}
+function removeSessionMeta(name) {
+    try {
+        fs.unlinkSync(getSessionMetaPath(name));
+    }
+    catch { /* may not exist */ }
+}
+function pruneOrphanMetas(liveNames) {
+    const dir = ensureTmuxDir();
+    for (const f of fs.readdirSync(dir)) {
+        if (!f.endsWith('.json'))
+            continue;
+        const name = f.slice(0, -5);
+        if (!liveNames.has(name)) {
+            try {
+                fs.unlinkSync(`${dir}/${f}`);
+            }
+            catch { /* race-tolerant */ }
+        }
+    }
+}
+function pruneAllMetas() {
+    const dir = ensureTmuxDir();
+    for (const f of fs.readdirSync(dir)) {
+        if (f.endsWith('.json')) {
+            try {
+                fs.unlinkSync(`${dir}/${f}`);
+            }
+            catch { /* race-tolerant */ }
+        }
+    }
+}

package/dist/lib/types.d.ts

@@ -6,9 +6,22 @@
  * formats for each supported agent.
  */
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
+/** Per-agent run strategy config. */
+export interface AgentRunConfig {
+    strategy?: RunStrategy;
+}
+/** Default launch options applied by `agents run` when flags are omitted. */
+export interface RunDefaults {
+    mode?: Mode;
+    model?: string;
+}
+/** `run:` section in agents.yaml. Agent keys keep strategy; `defaults` stores selector rules. */
+export type RunConfig = Partial<Record<AgentId, AgentRunConfig>> & {
+    defaults?: Record<string, RunDefaults>;
+};
 /** Preview features that users can opt into via `agents beta`. */
 export type BetaFeatureName = 'drive' | 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */
@@ -40,6 +53,9 @@ export interface AgentConfig {
         skills: Capability;
         commands: Capability;
         plugins: Capability;
+        subagents: Capability;
+        rules: RulesCapability;
+        workflows: Capability;
         /**
          * Permission modes this agent natively supports. Modes outside this set
          * are gated by buildExecCommand: `auto` silently degrades to `edit`,
@@ -64,8 +80,12 @@ export type Capability = boolean | {
     since?: string;
     until?: string;
 };
+/** Rules sync writes one composed instructions file per supported agent. */
+export type RulesCapability = false | {
+    file: string;
+};
 /** Names of every gateable capability on AgentConfig. */
-export type CapabilityName = 'hooks' | 'mcp' | 'allowlist' | 'skills' | 'commands' | 'plugins';
+export type CapabilityName = 'hooks' | 'mcp' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows';
 /**
  * Permission modes controlling agent autonomy.
  *   plan  read-only investigation; no writes, no shell side-effects
@@ -189,9 +209,7 @@ export interface InstalledHook {
 /** Package manifest (agents.yaml) found inside a cloned config repo or package. */
 export interface Manifest {
     agents?: Partial<Record<AgentId, string>>;
-    run?: Partial<Record<AgentId, {
-        strategy?: RunStrategy;
-    }>>;
+    run?: RunConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };
@@ -237,14 +255,14 @@ export interface InstalledSkill {
     scope: 'user' | 'project';
     agent: AgentId;
 }
-/** Git remote metadata for the ~/.agents-system/ config repository. */
+/** Git remote metadata for the ~/.agents/.system/ config repository. */
 export interface RepoInfo {
     source: string;
     branch: string;
     commit: string;
     lastSync: string;
 }
-/** Canonical system repo cloned into ~/.agents-system/. */
+/** Canonical system repo cloned into ~/.agents/.system/. */
 export declare const DEFAULT_SYSTEM_REPO = "gh:phnx-labs/.agents-system";
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export declare function systemRepoSlug(repo?: string): string;
@@ -351,7 +369,7 @@ export interface ResolvedPackage {
 export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';
 /**
  * A resource selection pattern stored in agents.yaml versions:
- *   "system:*"      — all resources from ~/.agents-system/
+ *   "system:*"      — all resources from ~/.agents/.system/
  *   "user:*"        — all resources from ~/.agents/
  *   "rush:*"        — all resources from ~/.agents-rush/  (extra repo alias)
  *   "project:*"     — all resources from .agents/ in the project root
@@ -416,6 +434,50 @@ export interface DiscoveredPlugin {
     hasMcp: boolean;
     /** Whether the plugin root contains a settings.json with non-permission keys to merge. */
     hasSettings: boolean;
+    /**
+     * Marketplace this plugin was discovered in (from marketplaceNameFor() of the
+     * owning MarketplaceSpec): "agents-cli" (user repo), "agents-<alias>" (extra
+     * repo), or "agents-project" (project repo). Absent on hand-built plugins
+     * (e.g. workflow-scoped) — those default to the user marketplace on sync.
+     */
+    marketplace?: string;
+}
+/**
+ * Identifies one DotAgents repo that contributes a plugin marketplace. Each
+ * repo synthesizes its own catalog and registers under its own name:
+ *   user    — ~/.agents/plugins/         → "agents-cli"   (the canonical name)
+ *   extra   — ~/.agents-<alias>/plugins/ → "agents-<alias>" (e.g. "agents-extras")
+ *   project — <cwd>/.agents/plugins/     → "agents-project"
+ *
+ * `root` on the extra/project variants is the absolute path to that repo's
+ * plugins/ directory (the source side). The user variant needs no path — it is
+ * always ~/.agents/plugins/ via getPluginsDir().
+ */
+export type MarketplaceSpec = {
+    kind: 'user';
+} | {
+    kind: 'extra';
+    alias: string;
+    root: string;
+} | {
+    kind: 'project';
+    root: string;
+} | {
+    kind: 'system';
+    root: string;
+};
+/**
+ * A marketplace found on the source side (before any per-version sync), with
+ * its resolved name, source plugins directory, and catalog description.
+ */
+export interface DiscoveredMarketplace {
+    spec: MarketplaceSpec;
+    /** e.g. "agents-cli", "agents-extras", "agents-project". */
+    name: string;
+    /** Absolute path to the source plugins/ directory on disk. */
+    pluginsRoot: string;
+    /** Human description embedded in the synthesized catalog. */
+    description: string;
 }
 /** Frontmatter fields parsed from a subagent's agent.md file. */
 export interface SubagentFrontmatter {
@@ -450,12 +512,10 @@ export interface ExtraRepoConfig {
     path?: string;
     enabled: boolean;
 }
-/** Top-level structure of ~/.agents-system/agents.yaml -- the CLI's persistent state. */
+/** Top-level structure of ~/.agents/.system/agents.yaml -- the CLI's persistent state. */
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
-    run?: Partial<Record<AgentId, {
-        strategy?: RunStrategy;
-    }>>;
+    run?: RunConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };
@@ -528,7 +588,7 @@ export interface BrowserProfileConfig {
     /** Optional SSH host where logDir lives, e.g. "user@remote-host". */
     logHost?: string;
 }
-/** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */
+/** Options controlling which agents and resources are synced during `agents repo refresh` / `agents use`. */
 export interface SyncOptions {
     agents?: AgentId[];
     yes?: boolean;

package/dist/lib/types.js

@@ -7,7 +7,7 @@
  */
 /** Every canonical mode in declaration order. Useful for iteration / validation. */
 export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
-/** Canonical system repo cloned into ~/.agents-system/. */
+/** Canonical system repo cloned into ~/.agents/.system/. */
 export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export function systemRepoSlug(repo = DEFAULT_SYSTEM_REPO) {

package/dist/lib/usage.js

@@ -4,7 +4,7 @@
  * Fetches live usage data from the Anthropic OAuth API (Claude) or parses
  * rate-limit events from Codex session logs. Results are normalized into a
  * common UsageSnapshot shape, cached to disk, and rendered as terminal
- * progress bars for the `agents view` and `agents status` commands.
+ * progress bars for the `agents view` command.
  */
 import { execFile } from 'child_process';
 import { createHash } from 'crypto';

package/dist/lib/versions.d.ts

@@ -166,10 +166,10 @@ export declare function installVersion(agent: AgentId, version: string, onProgre
     error?: string;
 }>;
 /**
- * Soft-delete a version directory by moving it to ~/.agents-system/trash/versions/.
+ * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.
  * Returns the trash path on success or null on failure / no source.
  *
- * Trash layout: ~/.agents-system/trash/versions/<agent>/<version>/<timestamp>/
+ * Trash layout: ~/.agents/.system/trash/versions/<agent>/<version>/<timestamp>/
  * The timestamp suffix lets a user soft-delete the same version twice (after
  * re-install) without collision and gives a chronological audit trail.
  *
@@ -182,7 +182,7 @@ export declare function softDeleteVersionDir(agent: AgentId, version: string): s
  * Remove a specific version of an agent.
  *
  * Soft-delete only: moves the entire version directory (including `home/`)
- * to ~/.agents-system/trash/versions/. Recoverable via `agents trash restore`.
+ * to ~/.agents/.system/trash/versions/. Recoverable via `agents trash restore`.
  * Nothing is hard-deleted.
  */
 export declare function removeVersion(agent: AgentId, version: string): boolean;
@@ -227,7 +227,7 @@ export declare function resolveVersionAlias(agent: AgentId, raw: string | undefi
  */
 export declare function resolveVersionAliasLoose(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**
- * Get version specified in a project-root agents.yaml (not the user ~/.agents-system/agents.yaml).
+ * Get version specified in a project-root agents.yaml (not the user ~/.agents/.system/agents.yaml).
  */
 export declare function getProjectVersion(agent: AgentId, startPath: string): string | null;
 /**