@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/index.js

@@ -1,12 +1,17 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --no-warnings=ExperimentalWarning
+/**
+ * CLI entry point for agents-cli.
+ *
+ * Registers all commands, handles update checks, auto-corrects typos,
+ * and launches the first-run interactive init when appropriate.
+ */
 import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { select } from '@inquirer/prompts';
+import { confirm, select } from '@inquirer/prompts';
 // Force exit on Ctrl+C when no interactive prompt is handling it.
 process.on('SIGINT', () => process.exit(130));
 // Ignore SIGPIPE — prevents exit code 13 crashes in piped environments
@@ -19,8 +24,7 @@ const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
 // Import command registrations
 import { registerPullCommand } from './commands/pull.js';
-import { registerPushCommand } from './commands/push.js';
-import { registerForkCommand } from './commands/fork.js';
+import { registerRepoCommands } from './commands/repo.js';
 import { registerInitCommand, runInit } from './commands/init.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerViewCommand } from './commands/view.js';
@@ -36,19 +40,26 @@ import { registerDaemonCommands } from './commands/daemon.js';
 import { registerRoutinesCommands } from './commands/routines.js';
 import { registerRunCommand } from './commands/exec.js';
 import { registerModelsCommand } from './commands/models.js';
+import { registerPruneCommand } from './commands/prune.js';
+import { registerDoctorCommand } from './commands/doctor.js';
 import { registerSubagentsCommands } from './commands/subagents.js';
 import { registerPluginsCommands } from './commands/plugins.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerRefreshMemoryCommand } from './commands/refresh-memory.js';
-import { registerSessionsCommands } from './commands/sessions.js';
 import { registerDriveCommands } from './commands/drive.js';
 import { registerPtyCommands } from './commands/pty.js';
-import { registerTeamsCommands } from './commands/teams.js';
 import { registerProfilesCommands } from './commands/profiles.js';
 import { registerSecretsCommands } from './commands/secrets.js';
-import { registerCloudCommands } from './commands/cloud.js';
+import { registerFactoryCommands } from './commands/factory.js';
+import { registerUsageCommand } from './commands/usage.js';
+import { registerAliasCommand } from './commands/alias.js';
+import { registerBetaCommands } from './commands/beta.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { isPromptCancelled } from './commands/utils.js';
+import { getAgentsDir } from './lib/state.js';
+import { AGENTS } from './lib/agents.js';
+import { getGlobalDefault } from './lib/versions.js';
+import { addShimsToPath, ensureShimCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, } from './lib/shims.js';
 const program = new Command();
 program
     .name('agents')
@@ -69,13 +80,13 @@ Quick start:
   agents init                     First-time setup (interactive)
   agents view                     See what's installed
   agents run <agent> ["prompt"]   Run an agent (interactive without prompt, headless with)
-  agents cloud run <prompt>       Dispatch a task to the cloud (Rush, Codex, Factory)
   agents sessions                 Browse past sessions across all agents
 
 Agent versions:
   add <agent>[@version]           Install an agent CLI (e.g. agents add codex)
   remove <agent>[@version]        Uninstall a version
   use <agent>@<version>           Set the default version
+  prune [target]                  Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs
   view [agent[@version]]          List versions, or inspect one in detail
 
 Agent configuration (synced across versions):
@@ -94,7 +105,6 @@ Packages:
 
 Run agents:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
-  cloud                           Dispatch tasks to cloud providers (Rush, Codex, Factory)
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   sessions                        Browse and replay past runs
@@ -104,6 +114,7 @@ Credentials:
   secrets                         Keychain-backed env bundles injected at spawn
 
 Helpers:
+  beta                            Enable preview features like drive and factory
   pty                             Drive interactive terminal programs (REPLs, TUIs)
 
 Automation tips:
@@ -114,19 +125,20 @@ Automation tips:
   Non-TTY shells apply defaults   Omitted required selections fail with a plain hint
 
 Config sync (portable setup via git):
-  pull [gh:user/repo]             Clone or pull a shared .agents config repo
-  push                            Commit and push your local config
-  fork                            Fork the default config repo to your GitHub
+  pull                            Clone or pull the system repo at ~/.agents-system/
+  repo init --path <dir>          Scaffold your own editable repo from a template
+  repo add <path|gh:user/repo>    Merge an extra repo after the system repo
 
 Options:
   -V, --version                   Show version number
   -h, --help                      Show help
 
-Config lives in ~/.agents/. Run 'agents <command> --help' for details.
+System config lives in ~/.agents-system/. Run 'agents <command> --help' for details.
 `;
     }
     return originalHelpInformation();
 };
+/** Compare two semver version strings. Returns 1 if a > b, -1 if a < b, 0 if equal. */
 function compareVersions(a, b) {
     const partsA = a.split('.').map(Number);
     const partsB = b.split('.').map(Number);
@@ -138,6 +150,7 @@ function compareVersions(a, b) {
     }
     return 0;
 }
+/** Fetch and display changelog entries between two versions from unpkg. */
 async function showWhatsNew(fromVersion, toVersion) {
     try {
         const response = await fetch(`https://unpkg.com/@phnx-labs/agents-cli@${toVersion}/CHANGELOG.md`);
@@ -183,7 +196,8 @@ async function showWhatsNew(fromVersion, toVersion) {
     }
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const UPDATE_CHECK_FILE = path.join(os.homedir(), '.agents', '.update-check');
+const UPDATE_CHECK_FILE = path.join(getAgentsDir(), '.update-check');
+/** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
 function readUpdateCache() {
     try {
         return JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, 'utf-8'));
@@ -193,11 +207,13 @@ function readUpdateCache() {
         return null;
     }
 }
+/** Determine whether enough time has elapsed since the last registry fetch. */
 function shouldFetchLatest(cache) {
     if (!cache)
         return true;
     return Date.now() - cache.lastCheck > UPDATE_CHECK_INTERVAL_MS;
 }
+/** Persist the latest known version and current timestamp to the update-check cache. */
 function saveUpdateCheck(latestVersion) {
     try {
         const dir = path.dirname(UPDATE_CHECK_FILE);
@@ -209,6 +225,7 @@ function saveUpdateCheck(latestVersion) {
         /* best-effort cache update */
     }
 }
+/** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
     if (!process.stdout.isTTY) {
         console.error(chalk.yellow(`Update available: ${VERSION} -> ${latestVersion}. Run: npm install -g @phnx-labs/agents-cli@latest`));
@@ -239,19 +256,19 @@ async function promptUpgrade(latestVersion) {
         return;
     }
     if (answer === 'now') {
-        const { exec, spawnSync } = await import('child_process');
+        const { execFile, spawnSync } = await import('child_process');
         const { promisify } = await import('util');
-        const execAsync = promisify(exec);
+        const execFileAsync = promisify(execFile);
         const spinner = ora('Upgrading...').start();
         try {
-            await execAsync('npm install -g @phnx-labs/agents-cli@latest');
+            await execFileAsync('npm', ['install', '-g', '@phnx-labs/agents-cli@latest']);
             spinner.succeed(`Upgraded to ${latestVersion}`);
             await showWhatsNew(VERSION, latestVersion);
             console.log();
             // Re-exec with new version and exit
             const result = spawnSync('agents', process.argv.slice(2), {
                 stdio: 'inherit',
-                shell: true,
+                shell: false,
             });
             process.exit(result.status ?? 0);
         }
@@ -277,7 +294,7 @@ function refreshUpdateCacheInBackground() {
         /* network error, try again next invocation */
     });
 }
-/** Synchronous cache read — prompt if cached latestVersion is newer. Triggers background refresh if cache is stale. */
+/** Check for available updates using the local cache. Triggers a background refresh if stale. */
 async function checkForUpdates() {
     const cache = readUpdateCache();
     // Kick off network refresh in background if stale. Does not block.
@@ -298,6 +315,75 @@ async function checkForUpdates() {
         }
     }
 }
+async function maybeBootstrapShimIntegration(requestedCommand) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return;
+    }
+    if (requestedCommand === 'sync' || requestedCommand === 'refresh-memory') {
+        return;
+    }
+    const installedAgents = listAgentsWithInstalledVersions();
+    if (installedAgents.length === 0) {
+        return;
+    }
+    const createdOrUpdated = [];
+    for (const agent of installedAgents) {
+        const status = ensureShimCurrent(agent);
+        if (status !== 'current') {
+            createdOrUpdated.push(`${status === 'created' ? 'Created' : 'Updated'} ${AGENTS[agent].cliCommand} shim`);
+        }
+    }
+    for (const notice of createdOrUpdated) {
+        console.log(chalk.green(notice));
+    }
+    const defaultAgents = installedAgents.filter((agent) => getGlobalDefault(agent));
+    const shadowed = defaultAgents
+        .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
+        .filter((item) => Boolean(item.shadowedBy));
+    // Also check for shell aliases that shadow the shim
+    const aliased = defaultAgents.filter((agent) => hasAliasShadowingShim(agent));
+    // If shims are in PATH and nothing is binary-shadowing, we're done.
+    // Shell aliases that call the same command with extra flags are intentional
+    // customization and don't break shim integration.
+    if (shadowed.length === 0 && isShimsInPath()) {
+        return;
+    }
+    const affected = [];
+    for (const { agent, shadowedBy } of shadowed) {
+        affected.push(`${AGENTS[agent].cliCommand} -> ${shadowedBy}`);
+    }
+    for (const agent of aliased) {
+        if (!shadowed.some((s) => s.agent === agent)) {
+            affected.push(`${AGENTS[agent].cliCommand} (alias)`);
+        }
+    }
+    if (affected.length === 0) {
+        // PATH issue - show all installed agents
+        affected.push(...installedAgents.map((agent) => AGENTS[agent].cliCommand));
+    }
+    const shouldRepair = await confirm({
+        message: `Repair shim integration now? ${affected.join(', ')}`,
+        default: true,
+    });
+    if (!shouldRepair) {
+        console.log(chalk.yellow('Shim integration still needs attention.'));
+        console.log(chalk.gray(getPathSetupInstructions()));
+        return;
+    }
+    const pathResult = addShimsToPath();
+    if (!pathResult.success) {
+        console.log(chalk.yellow('Could not repair shim PATH setup automatically.'));
+        console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
+        return;
+    }
+    if (pathResult.alreadyPresent) {
+        console.log(chalk.yellow('Shim PATH entry is already in your shell config, but this shell has not reloaded it yet.'));
+    }
+    else {
+        console.log(chalk.green(`Repaired shim PATH setup in ~/${pathResult.rcFile}`));
+    }
+    console.log(chalk.gray(getPathSetupInstructions()));
+}
 // Register all commands
 registerViewCommand(program);
 registerStatusCommand(program);
@@ -337,6 +423,8 @@ registerDaemonCommands(program);
 registerRoutinesCommands(program);
 registerRunCommand(program);
 registerModelsCommand(program);
+registerPruneCommand(program);
+registerDoctorCommand(program);
 // Deprecated 'exec' alias for 'run'
 program
     .command('exec', { hidden: true })
@@ -348,14 +436,15 @@ program
     args[0] = 'run';
     await program.parseAsync(['node', 'agents', ...args]);
 });
-registerTeamsCommands(program);
 registerProfilesCommands(program);
 registerSecretsCommands(program);
-registerSessionsCommands(program);
+registerBetaCommands(program);
 registerSyncCommand(program);
 registerRefreshMemoryCommand(program);
 registerDriveCommands(program);
-registerCloudCommands(program);
+registerFactoryCommands(program);
+registerUsageCommand(program);
+registerAliasCommand(program);
 registerPtyCommands(program);
 // Deprecated 'jobs' and 'cron' aliases for 'routines'
 for (const alias of ['jobs', 'cron']) {
@@ -394,10 +483,10 @@ program
             return;
         }
         spinner.text = `Upgrading ${VERSION} -> ${latestVersion}...`;
-        const { exec: execCb } = await import('child_process');
+        const { execFile } = await import('child_process');
         const { promisify } = await import('util');
-        const execAsync = promisify(execCb);
-        await execAsync('npm install -g @phnx-labs/agents-cli@latest');
+        const execFileAsync = promisify(execFile);
+        await execFileAsync('npm', ['install', '-g', '@phnx-labs/agents-cli@latest']);
         spinner.succeed(`Upgraded to ${latestVersion}`);
         await showWhatsNew(VERSION, latestVersion);
     }
@@ -407,13 +496,10 @@ program
     }
 });
 registerPullCommand(program);
-registerPushCommand(program);
-registerForkCommand(program);
+registerRepoCommands(program);
 registerInitCommand(program);
 applyGlobalHelpConventions(program);
-/**
- * Calculate Levenshtein edit distance between two strings.
- */
+/** Calculate the Levenshtein edit distance between two strings. */
 function levenshtein(a, b) {
     const m = a.length;
     const n = b.length;
@@ -461,10 +547,44 @@ program.on('command:*', (operands) => {
 });
 // Run update check on EVERY invocation before parsing
 await checkForUpdates();
+// Surface any "behind upstream" notices from the previous detached sync, then
+// fire-and-forget the next background sync. System repo gets a real fast-forward
+// pull (read-only locally, safe). User repo and extras get fetch-only + a
+// status marker that we'll print on the *next* invocation.
+const { spawnDetachedSync } = await import('./lib/auto-pull.js');
+spawnDetachedSync();
 // First-run experience: no args + no config yet + TTY -> launch interactive init.
 // Skipped when stdin/stdout isn't a terminal (CI, pipes) or when user passes any args.
 const passedArgs = process.argv.slice(2);
-const metaFilePath = path.join(os.homedir(), '.agents', 'agents.yaml');
+const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
+/**
+ * Lazily register command trees that pull in the SQLite-backed session/cloud
+ * stack. This keeps lightweight commands like `agents view` from loading the
+ * DB layer during CLI startup.
+ */
+async function registerLazyCommands() {
+    switch (requestedCommand) {
+        case 'sessions': {
+            const { registerSessionsCommands } = await import('./commands/sessions.js');
+            registerSessionsCommands(program);
+            break;
+        }
+        case 'teams': {
+            const { registerTeamsCommands } = await import('./commands/teams.js');
+            registerTeamsCommands(program);
+            break;
+        }
+        case 'cloud': {
+            const { registerCloudCommands } = await import('./commands/cloud.js');
+            registerCloudCommands(program);
+            break;
+        }
+        default:
+            break;
+    }
+}
+await registerLazyCommands();
+const metaFilePath = path.join(getAgentsDir(), 'agents.yaml');
 const firstRun = passedArgs.length === 0 &&
     !fs.existsSync(metaFilePath) &&
     process.stdin.isTTY &&
@@ -480,5 +600,23 @@ if (firstRun) {
     }
     process.exit(0);
 }
-await program.parseAsync();
-//# sourceMappingURL=index.js.map
+// Commands that require the system repo to be cloned first.
+const SYSTEM_REPO_COMMANDS = new Set([
+    'view', 'status', 'skills', 'rules', 'commands', 'hooks',
+    'mcp', 'permissions', 'versions', 'packages', 'sync',
+    'subagents', 'repo', 'plugins', 'doctor',
+]);
+if (!firstRun && requestedCommand && SYSTEM_REPO_COMMANDS.has(requestedCommand)) {
+    const { ensureInitialized } = await import('./commands/init.js');
+    await ensureInitialized(program);
+}
+try {
+    await maybeBootstrapShimIntegration(requestedCommand);
+    await program.parseAsync();
+}
+catch (err) {
+    if (err instanceof Error && err.name === 'ExitPromptError') {
+        process.exit(130);
+    }
+    throw err;
+}

package/dist/lib/acp/client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent Client Protocol (ACP) client wrapper for agents-cli.
+ *
+ * Spawns an ACP-capable agent CLI as a stdio subprocess and drives it through
+ * initialize -> newSession -> prompt, streaming `session/update` notifications
+ * back to the caller as async iterables.
+ *
+ * Also implements the Client interface (fs read/write, terminal exec) so the
+ * agent can request filesystem and shell operations through us. `--mode plan`
+ * rejects all write/terminal requests; `edit`/`full` allow them.
+ */
+import { type SessionNotification } from '@zed-industries/agent-client-protocol';
+import type { AgentId } from '../types.js';
+import type { ExecMode } from '../exec.js';
+export interface AcpRunOptions {
+    agent: AgentId;
+    prompt: string;
+    cwd: string;
+    mode: ExecMode;
+    /** Optional: callback invoked for every session/update notification. */
+    onUpdate?: (n: SessionNotification) => void;
+}
+export interface AcpRunResult {
+    stopReason: string;
+    sessionId: string;
+}
+/**
+ * Runs a single prompt turn against an ACP-capable agent and streams updates
+ * to `onUpdate`. Resolves when the turn completes (StopReason is returned).
+ */
+export declare function runAcp(opts: AcpRunOptions): Promise<AcpRunResult>;

package/dist/lib/acp/client.js

@@ -0,0 +1,117 @@
+/**
+ * Agent Client Protocol (ACP) client wrapper for agents-cli.
+ *
+ * Spawns an ACP-capable agent CLI as a stdio subprocess and drives it through
+ * initialize -> newSession -> prompt, streaming `session/update` notifications
+ * back to the caller as async iterables.
+ *
+ * Also implements the Client interface (fs read/write, terminal exec) so the
+ * agent can request filesystem and shell operations through us. `--mode plan`
+ * rejects all write/terminal requests; `edit`/`full` allow them.
+ */
+import { spawn } from 'child_process';
+import { Readable, Writable } from 'stream';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { ClientSideConnection, ndJsonStream, } from '@zed-industries/agent-client-protocol';
+import { getAcpSpec, supportsAcp } from './harnesses.js';
+const PROTOCOL_VERSION = 1;
+/**
+ * Runs a single prompt turn against an ACP-capable agent and streams updates
+ * to `onUpdate`. Resolves when the turn completes (StopReason is returned).
+ */
+export async function runAcp(opts) {
+    if (!supportsAcp(opts.agent)) {
+        throw new Error(`Agent '${opts.agent}' does not support ACP. Use direct exec instead.`);
+    }
+    const spec = getAcpSpec(opts.agent);
+    const child = spawn(spec.command, spec.args, {
+        cwd: opts.cwd,
+        stdio: ['pipe', 'pipe', 'inherit'],
+        env: process.env,
+    });
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+    const client = buildClient(opts);
+    const connection = new ClientSideConnection(() => client, stream);
+    const initResp = await connection.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: {
+            fs: { readTextFile: true, writeTextFile: true },
+            terminal: true,
+        },
+    });
+    if (initResp.protocolVersion < PROTOCOL_VERSION) {
+        throw new Error(`Agent '${opts.agent}' speaks ACP protocol v${initResp.protocolVersion}, need v${PROTOCOL_VERSION}.`);
+    }
+    const session = await connection.newSession({
+        cwd: opts.cwd,
+        mcpServers: [],
+    });
+    try {
+        const resp = await connection.prompt({
+            sessionId: session.sessionId,
+            prompt: [{ type: 'text', text: opts.prompt }],
+        });
+        return { stopReason: resp.stopReason, sessionId: session.sessionId };
+    }
+    finally {
+        child.kill('SIGTERM');
+    }
+}
+function buildClient(opts) {
+    const { mode, onUpdate, cwd } = opts;
+    const canWrite = mode !== 'plan';
+    return {
+        async sessionUpdate(params) {
+            if (onUpdate)
+                onUpdate(params);
+        },
+        async readTextFile(params) {
+            const abs = resolveInCwd(cwd, params.path);
+            const content = await fs.readFile(abs, 'utf8');
+            const sliced = sliceByLines(content, params.line, params.limit);
+            return { content: sliced };
+        },
+        async writeTextFile(params) {
+            if (!canWrite) {
+                throw new Error(`File writes are denied in plan mode: ${params.path}`);
+            }
+            const abs = resolveInCwd(cwd, params.path);
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            await fs.writeFile(abs, params.content, 'utf8');
+            return {};
+        },
+        async requestPermission(params) {
+            const optionId = mode === 'full'
+                ? (params.options.find(o => o.kind === 'allow_always')?.optionId
+                    ?? params.options[0]?.optionId)
+                : params.options.find(o => o.kind === 'allow_once')?.optionId;
+            if (!optionId) {
+                return { outcome: { outcome: 'cancelled' } };
+            }
+            return { outcome: { outcome: 'selected', optionId } };
+        },
+        async createTerminal(params) {
+            if (!canWrite) {
+                throw new Error(`Terminal commands are denied in plan mode: ${params.command}`);
+            }
+            throw new Error('Terminal support not yet implemented in agents-cli ACP client.');
+        },
+    };
+}
+function resolveInCwd(cwd, target) {
+    const abs = path.resolve(cwd, target);
+    const rel = path.relative(cwd, abs);
+    if (rel.startsWith('..')) {
+        throw new Error(`Path '${target}' escapes session cwd '${cwd}'`);
+    }
+    return abs;
+}
+function sliceByLines(content, startLine, limit) {
+    if (startLine == null && limit == null)
+        return content;
+    const lines = content.split('\n');
+    const from = Math.max(0, (startLine ?? 1) - 1);
+    const to = limit != null ? from + limit : lines.length;
+    return lines.slice(from, to).join('\n');
+}

package/dist/lib/acp/harnesses.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
+ *
+ * Each entry describes how to launch a coding agent CLI as an ACP server
+ * (stdio JSON-RPC). Unsupported harnesses (amp, roo, goose-stdio) are omitted;
+ * callers should fall back to the legacy direct-exec path for those.
+ *
+ * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.
+ */
+import type { AgentId } from '../types.js';
+export interface AcpHarnessSpec {
+    /** Command + args to spawn the agent in ACP server mode. */
+    command: string;
+    args: string[];
+    /** Human-hint for `teams doctor` when the spawn fails. */
+    installHint: string;
+    /** Confidence: "verified" = tested in this repo, "documented" = per vendor docs. */
+    confidence: 'verified' | 'documented';
+    /** Source URL for the invocation. */
+    source: string;
+}
+export declare const ACP_HARNESSES: Partial<Record<AgentId, AcpHarnessSpec>>;
+/** Returns the ACP spawn spec for an agent, or undefined if the harness does not speak ACP. */
+export declare function getAcpSpec(agent: AgentId): AcpHarnessSpec | undefined;
+/** True if the harness is known to support ACP (directly or via adapter). */
+export declare function supportsAcp(agent: AgentId): boolean;

package/dist/lib/acp/harnesses.js

@@ -0,0 +1,65 @@
+/**
+ * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
+ *
+ * Each entry describes how to launch a coding agent CLI as an ACP server
+ * (stdio JSON-RPC). Unsupported harnesses (amp, roo, goose-stdio) are omitted;
+ * callers should fall back to the legacy direct-exec path for those.
+ *
+ * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.
+ */
+export const ACP_HARNESSES = {
+    gemini: {
+        command: 'gemini',
+        args: ['--experimental-acp'],
+        installHint: 'npm i -g @google/gemini-cli',
+        confidence: 'documented',
+        source: 'https://agentclientprotocol.com/get-started/agents',
+    },
+    claude: {
+        command: 'npx',
+        args: ['-y', '@zed-industries/claude-agent-acp'],
+        installHint: 'npm i -g @zed-industries/claude-agent-acp',
+        confidence: 'documented',
+        source: 'https://www.npmjs.com/package/@zed-industries/claude-agent-acp',
+    },
+    codex: {
+        command: 'npx',
+        args: ['-y', '@zed-industries/codex-acp'],
+        installHint: 'npm i -g @zed-industries/codex-acp',
+        confidence: 'documented',
+        source: 'https://www.npmjs.com/package/@zed-industries/codex-acp',
+    },
+    cursor: {
+        command: 'cursor-agent',
+        args: ['acp'],
+        installHint: 'curl https://cursor.com/install -fsS | bash',
+        confidence: 'documented',
+        source: 'https://cursor.com/docs/cli/acp',
+    },
+    opencode: {
+        command: 'opencode',
+        args: ['acp'],
+        installHint: 'npm i -g opencode-ai',
+        confidence: 'documented',
+        source: 'https://opencode.ai/docs/acp/',
+    },
+    openclaw: {
+        command: 'openclaw',
+        args: ['acp'],
+        installHint: 'see https://docs.openclaw.ai',
+        confidence: 'documented',
+        source: 'https://docs.openclaw.ai/tools/acp-agents',
+    },
+    // goose: ACP over HTTP via `goosed`, not a clean stdio subcommand.
+    // copilot, kiro: excluded for now (not installed in the reference environment,
+    //                no local verification possible).
+    // amp, roo: not on the ACP agents list.
+};
+/** Returns the ACP spawn spec for an agent, or undefined if the harness does not speak ACP. */
+export function getAcpSpec(agent) {
+    return ACP_HARNESSES[agent];
+}
+/** True if the harness is known to support ACP (directly or via adapter). */
+export function supportsAcp(agent) {
+    return ACP_HARNESSES[agent] !== undefined;
+}

package/dist/lib/acp/run.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Headless ACP runner.
+ *
+ * Glue between the `agents run <agent> "prompt" --acp` command and the ACP
+ * client. Emits either a human-readable stream of agent messages or newline-
+ * delimited JSON events, depending on `--json`.
+ */
+import type { AgentId } from '../types.js';
+import type { ExecMode } from '../exec.js';
+export interface HeadlessAcpOptions {
+    agent: AgentId;
+    prompt: string;
+    cwd: string;
+    mode: ExecMode;
+    json: boolean;
+}
+/** Runs a prompt turn over ACP, streaming output to stdout per `json` mode. */
+export declare function runAcpHeadless(opts: HeadlessAcpOptions): Promise<number>;