@agentrq/acp-gateway 0.2.3 → 0.2.5

package/dist/index.js

@@ -7,22 +7,49 @@
  */
 import { spawn } from "node:child_process";
 import { Writable, Readable } from "node:stream";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import * as acp from "@agentclientprotocol/sdk";
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
-import { loadMcpConfig, pickAgentrqServer } from "./config.js";
+import { loadMcpConfig, pickAgentrqServer, } from "./config.js";
 import { MCPBridge } from "./mcpClient.js";
-export function mapMcpServers(configs) {
-    return configs.map((cfg) => {
-        if (cfg.type === "http") {
-            return {
-                type: "http",
-                name: cfg.name,
-                url: cfg.url,
-                headers: Object.entries(cfg.headers || {}).map(([name, value]) => ({ name, value })),
-            };
+/**
+ * What the agent said about a transport, if anything.
+ *
+ * stdio is the one transport every agent must support. For the others the
+ * answer is only trustworthy when the agent actually stated it: an agent that
+ * advertises no MCP capabilities at all is far more likely to be terse than to
+ * be unable to reach an HTTP server, and dropping its servers on that reading
+ * would take the workspace's own MCP server away from it.
+ */
+function transportSupport(transport, agentCapabilities) {
+    if (transport === "stdio")
+        return "required";
+    const declared = agentCapabilities?.mcpCapabilities?.[transport];
+    if (declared === true)
+        return "declared";
+    if (declared === false)
+        return "refused";
+    return "unstated";
+}
+export function mapMcpServers(configs, agentCapabilities) {
+    return configs
+        .filter((cfg) => {
+        const support = transportSupport(cfg.type, agentCapabilities);
+        if (support === "refused") {
+            console.error(`[acp] ⚠️  Not passing MCP server "${cfg.name}" to the agent: it is ${cfg.type}, ` +
+                `and the agent says it does not support that transport. Passing it anyway ` +
+                `risks the agent refusing the whole session.`);
+            return false;
         }
-        else {
+        if (support === "unstated") {
+            console.error(`[acp] MCP server "${cfg.name}" is ${cfg.type}, which the agent does not ` +
+                `advertise either way — passing it and letting the agent decide.`);
+        }
+        return true;
+    })
+        .map((cfg) => {
+        if (cfg.type === "stdio") {
             return {
                 name: cfg.name,
                 command: cfg.command,
@@ -30,45 +57,78 @@ export function mapMcpServers(configs) {
                 env: Object.entries(cfg.env || {}).map(([name, value]) => ({ name, value })),
             };
         }
+        return {
+            type: cfg.type,
+            name: cfg.name,
+            url: cfg.url,
+            headers: Object.entries(cfg.headers || {}).map(([name, value]) => ({ name, value })),
+        };
     });
 }
-import { AgentRQACPClient } from "./acpClient.js";
+import { AgentRQACPClient, DEFAULT_PERMISSION_TIMEOUT_MS } from "./acpClient.js";
+import { describeAuthMethods, isAuthRequiredError, login, logout, supportsLogout, } from "./auth.js";
+import { resolveAgentLaunch } from "./agentInstall.js";
+import { describeAgentInfo } from "./agentInfo.js";
+import { describeAgents, fetchRegistry, hostPlatformTarget, } from "./registry.js";
 import { extractTaskIdFromMeta, extractTaskIdFromText, } from "./taskIdentity.js";
 const lastTaskContent = new Map();
 export const activeSessions = new Map();
-export async function getOrCreateSession(taskId, acpCmdArgs, configs, agentrqConfig, mcpBridge) {
-    const key = taskId || "default";
-    const existing = activeSessions.get(key);
-    if (existing) {
-        return existing;
-    }
+/** Login preferences taken from the CLI, consulted whenever an agent demands auth. */
+export const authConfig = {};
+/** How long tool calls wait for a human, taken from the CLI at startup. */
+export const permissionConfig = {};
+/**
+ * Whether a human is sitting in front of this process.
+ *
+ * Terminal logins hand the agent our own stdio, and the "which login method?"
+ * prompt needs someone to answer it — neither works when the gateway runs
+ * unattended under a supervisor.
+ */
+export function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+/**
+ * Spawns an ACP agent, wires the JSON-RPC streams to it and completes the
+ * `initialize` handshake, returning the connection plus what the agent said
+ * about itself — including the login methods it advertises.
+ */
+export async function openAgentConnection({ acpCmdArgs, mcpBridge, env, label, taskId, onExit, }) {
     const [cmd, ...cmdArgs] = acpCmdArgs;
-    console.error(`[acp] Spawning agent for task ${key}: ${cmd} ${cmdArgs.join(" ")}`);
+    console.error(`[acp] Spawning agent for ${label}: ${cmd} ${cmdArgs.join(" ")}`);
     const agentProcess = spawn(cmd, cmdArgs, {
         stdio: ["pipe", "pipe", "inherit"],
-        env: { ...process.env, ...agentrqConfig.env },
+        env: { ...process.env, ...env },
+    });
+    const acpClient = new AgentRQACPClient(mcpBridge, () => taskId, {
+        permissionTimeoutMs: permissionConfig.timeoutMs,
     });
     // Guard against unhandled child-process failures. Without these listeners a
     // crashed agent (e.g. on network loss) leaves a broken stdin pipe; the next
     // write raises EPIPE as an uncaught error and takes the gateway down with it.
     agentProcess.on("error", (err) => {
-        console.error(`[acp] Agent process error for task ${key}:`, err.message);
-        activeSessions.delete(key);
+        console.error(`[acp] Agent process error for ${label}:`, err.message);
+        acpClient.cancelPendingPermissions(`agent process for ${label} failed`);
+        onExit?.();
     });
     agentProcess.on("exit", (code, signal) => {
-        console.error(`[acp] Agent process for task ${key} exited (code=${code}, signal=${signal})`);
-        activeSessions.delete(key);
+        console.error(`[acp] Agent process for ${label} exited (code=${code}, signal=${signal})`);
+        // Nothing will act on these answers now, but the tool calls waiting on them
+        // are holding task-queue slots that would never be given back.
+        acpClient.cancelPendingPermissions(`agent process for ${label} exited`);
+        onExit?.();
     });
     // stdin can emit EPIPE when the child dies mid-write; swallow it so it
     // doesn't surface as an uncaught exception.
     agentProcess.stdin?.on("error", (err) => {
-        console.error(`[acp] Agent stdin error for task ${key}:`, err.message);
+        console.error(`[acp] Agent stdin error for ${label}:`, err.message);
     });
     const input = Writable.toWeb(agentProcess.stdin);
     const output = Readable.toWeb(agentProcess.stdout);
-    const acpClient = new AgentRQACPClient(mcpBridge, () => taskId);
     const stream = acp.ndJsonStream(input, output);
     const connection = new acp.ClientSideConnection((_agent) => acpClient, stream);
+    // Stopping a turn is only possible once the connection exists, and the
+    // connection is built around the client — so it is handed over afterwards.
+    acpClient.setSessionCanceller((sessionId) => connection.cancel({ sessionId }));
     const initResult = await connection.initialize({
         protocolVersion: acp.PROTOCOL_VERSION,
         clientCapabilities: {
@@ -80,21 +140,73 @@ export async function getOrCreateSession(taskId, acpCmdArgs, configs, agentrqCon
                 form: {},
                 url: {},
             },
+            // Only claim terminal logins when we can actually hand the agent a
+            // terminal; otherwise the agent may offer a method we cannot run.
+            auth: {
+                terminal: isInteractiveTerminal(),
+            },
         },
     });
-    console.error(`[acp] Connected to agent for task ${key} (protocol v${initResult.protocolVersion})`);
+    console.error(`[acp] Connected to agent for ${label} (protocol v${initResult.protocolVersion})`);
+    if (initResult.authMethods?.length) {
+        console.error(`[auth] Agent offers these login methods:\n${describeAuthMethods(initResult.authMethods)}`);
+    }
+    return { process: agentProcess, connection, acpClient, initResult };
+}
+/**
+ * Starts a session, logging in first if the agent refuses without one.
+ *
+ * Agents only report `auth_required` when the session is requested, so this is
+ * where a first-run login belongs: authenticate once, then retry.
+ */
+export async function createSessionWithAuth(connection, params, auth) {
+    try {
+        return await connection.newSession(params);
+    }
+    catch (err) {
+        if (!isAuthRequiredError(err))
+            throw err;
+        console.error("[auth] Agent requires authentication before a session can start.");
+        await login({ ...auth, connection: connection });
+        return await connection.newSession(params);
+    }
+}
+export async function getOrCreateSession(taskId, acpCmdArgs, configs, agentrqConfig, mcpBridge) {
+    const key = taskId || "default";
+    const existing = activeSessions.get(key);
+    if (existing) {
+        return existing;
+    }
+    const [cmd, ...cmdArgs] = acpCmdArgs;
+    const { process: agentProcess, connection, acpClient, initResult } = await openAgentConnection({
+        acpCmdArgs,
+        mcpBridge,
+        env: agentrqConfig.env,
+        label: `task ${key}`,
+        taskId,
+        onExit: () => activeSessions.delete(key),
+    });
     const newSessionParams = {
         cwd: process.cwd(),
-        mcpServers: mapMcpServers(configs),
+        mcpServers: mapMcpServers(configs, initResult.agentCapabilities),
     };
-    const sessionResult = await connection.newSession(newSessionParams);
+    const sessionResult = await createSessionWithAuth(connection, newSessionParams, {
+        methods: initResult.authMethods,
+        launch: { command: cmd, args: cmdArgs, env: agentrqConfig.env },
+        preferredId: authConfig.methodId,
+        interactive: isInteractiveTerminal(),
+    });
     console.error(`[acp] Created session ${sessionResult.sessionId} for task ${key}`);
     await enforceHumanApprovalMode(connection, sessionResult);
+    // The mode is pinned once here, but agents may move themselves back out of
+    // it, so keep watching for the rest of the session's life.
+    acpClient.setModeChangeHandler((changedSessionId, modeId) => handleAgentModeChange(connection, changedSessionId, modeId, sessionResult.modes));
     const sessionInfo = {
         process: agentProcess,
         connection,
         acpClient,
         sessionId: sessionResult.sessionId,
+        initResult,
     };
     activeSessions.set(key, sessionInfo);
     return sessionInfo;
@@ -155,6 +267,50 @@ export async function enforceHumanApprovalMode(connection, sessionResult) {
         console.error(`[acp] ⚠️  Failed to set session mode to "${modeId}" — tool calls may execute without agentrq approval:`, err);
     }
 }
+/**
+ * How many times the gateway will drag one session back into a mode that asks
+ * the human. An agent that keeps switching back is not going to stop, and an
+ * unbounded fight with it would be an endless stream of setSessionMode calls.
+ */
+const MAX_MODE_REENFORCEMENTS = 3;
+/** sessionId → how many times its mode has already been put back. */
+const modeReenforcements = new Map();
+/**
+ * Puts a session back into a mode that asks the human, after the agent moved
+ * itself out of one.
+ *
+ * Agents may change modes on their own. If one moves into a mode that approves
+ * tool calls on the user's behalf, every later tool call — including
+ * destructive ones — executes without ever reaching agentrq, and nothing
+ * anywhere says so.
+ */
+export async function handleAgentModeChange(connection, sessionId, currentModeId, modes) {
+    const available = modes?.availableModes;
+    if (!available?.length)
+        return;
+    const mode = available.find((m) => m.id === currentModeId);
+    // A mode the agent never advertised cannot be vouched for either, so it is
+    // treated the same as one that approves on our behalf.
+    if (mode && !AUTO_APPROVING_MODE.test(describeMode(mode))) {
+        modeReenforcements.delete(sessionId);
+        return;
+    }
+    const attempts = modeReenforcements.get(sessionId) ?? 0;
+    if (attempts >= MAX_MODE_REENFORCEMENTS) {
+        console.error(`[acp] ⚠️  Agent keeps returning session ${sessionId} to mode "${currentModeId}", ` +
+            `which approves tool calls without asking. Giving up after ` +
+            `${MAX_MODE_REENFORCEMENTS} attempts — tool calls may now execute without ` +
+            `agentrq approval.`);
+        return;
+    }
+    modeReenforcements.set(sessionId, attempts + 1);
+    console.error(`[acp] ⚠️  Agent moved session ${sessionId} into "${currentModeId}", which approves ` +
+        `tool calls without asking. Putting it back.`);
+    await enforceHumanApprovalMode(connection, {
+        sessionId,
+        modes: { availableModes: available, currentModeId },
+    });
+}
 export function createAcpSessionSwitcher(connection, params, initialSessionId) {
     let currentSessionId = initialSessionId;
     const taskSessionMap = new Map();
@@ -237,33 +393,337 @@ export class TaskQueue {
         return this.queue.length;
     }
 }
+/**
+ * Parses the gateway's own flags — everything before the `--` that introduces
+ * the agent command.
+ */
+export function parseGatewayArgs(args) {
+    const options = {
+        maxConcurrency: 2,
+        permissionTimeoutMs: DEFAULT_PERMISSION_TIMEOUT_MS,
+        command: "run",
+        allowUnverifiedAgent: false,
+        rest: [],
+    };
+    for (let i = 0; i < args.length; i++) {
+        // A following token is this flag's value only when it isn't a flag itself,
+        // so `--login` can stand alone or take a method id.
+        const next = args[i + 1];
+        const value = next !== undefined && !next.startsWith("-") ? next : undefined;
+        switch (args[i]) {
+            case "--max-concurrency":
+            case "--maxConcurrency": {
+                const parsed = parseInt(value ?? "", 10);
+                if (!isNaN(parsed)) {
+                    options.maxConcurrency = parsed;
+                    i++;
+                }
+                break;
+            }
+            case "--permission-timeout": {
+                const minutes = parseInt(value ?? "", 10);
+                if (!isNaN(minutes) && minutes >= 0) {
+                    options.permissionTimeoutMs = minutes * 60_000;
+                    i++;
+                }
+                break;
+            }
+            case "--auth-method":
+                if (value) {
+                    options.authMethodId = value;
+                    i++;
+                }
+                break;
+            case "--login":
+                options.command = "login";
+                if (value) {
+                    options.authMethodId = value;
+                    i++;
+                }
+                break;
+            case "--logout":
+                options.command = "logout";
+                break;
+            case "--list-auth-methods":
+                options.command = "list-auth-methods";
+                break;
+            case "--agent":
+                if (value) {
+                    options.agentId = value;
+                    i++;
+                }
+                break;
+            case "--list-agents":
+                options.command = "list-agents";
+                break;
+            case "--agent-info":
+                options.command = "agent-info";
+                break;
+            case "--allow-unverified-agent":
+                options.allowUnverifiedAgent = true;
+                break;
+            case "--registry-url":
+                if (value) {
+                    options.registryUrl = value;
+                    i++;
+                }
+                break;
+            case "--help":
+            case "-h":
+                options.command = "help";
+                break;
+            default:
+                // Anything unrecognised belongs to the agent command, which may be
+                // given without a `--` separator.
+                options.rest.push(args[i]);
+        }
+    }
+    return options;
+}
+/**
+ * Prints every agent the registry publishes, and how each one can be run here.
+ */
+export async function runListAgents(registryUrl, fetchImpl = fetch) {
+    const registry = await fetchRegistry(registryUrl, fetchImpl);
+    const target = hostPlatformTarget();
+    console.log(`ACP registry v${registry.version} — ${registry.agents.length} agents ` +
+        `(this machine: ${target ?? `${process.platform}/${process.arch}, unsupported`})\n`);
+    console.log(describeAgents(registry, target));
+    console.log(`\nRun one with: acp-gateway --agent <id>`);
+}
+/**
+ * Works out which command actually starts the agent.
+ *
+ * `--agent <id>` resolves through the registry — installing the agent when the
+ * only distribution is a binary — and otherwise the command given after `--`
+ * is used as-is.
+ */
+export async function resolveAgentCommand(options, explicitCommand, fetchImpl = fetch) {
+    if (!options.agentId)
+        return { command: explicitCommand };
+    const registry = await fetchRegistry(options.registryUrl, fetchImpl);
+    const spec = await resolveAgentLaunch({
+        id: options.agentId,
+        registry,
+        platformTarget: hostPlatformTarget(),
+        allowUnverified: options.allowUnverifiedAgent,
+        fetchImpl,
+    });
+    console.error(`[registry] Running "${options.agentId}" via ${spec.kind}: ${spec.command} ${spec.args.join(" ")}`);
+    return { command: [spec.command, ...spec.args], env: spec.env };
+}
+/**
+ * Whether a command can actually be run.
+ *
+ * A path is checked directly; a bare name is looked for along PATH, honouring
+ * PATHEXT on Windows where an executable is rarely named without a suffix.
+ */
+export function isRunnable(command, env = process.env, platform = process.platform) {
+    if (command.includes("/") || (platform === "win32" && command.includes("\\"))) {
+        return existsSync(command);
+    }
+    const extensions = platform === "win32" ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    const separator = platform === "win32" ? ";" : ":";
+    return (env.PATH ?? "")
+        .split(separator)
+        .filter(Boolean)
+        .some((dir) => extensions.some((ext) => existsSync(path.join(dir, command + ext))));
+}
+/**
+ * Refuses to start with an agent that cannot be run.
+ *
+ * The agent is not spawned until the first task arrives, so without this a
+ * mistyped command — or a registry id passed as if it were one — starts a
+ * gateway that looks healthy and only fails much later, out of sight.
+ */
+export function assertAgentRunnable(command, usedRegistryId) {
+    if (isRunnable(command))
+        return;
+    const hint = usedRegistryId
+        ? `The registry says to run it as "${command}", which is not installed.`
+        : `If "${command}" is an ACP registry agent id, run it with --agent ${command} ` +
+            `(--list-agents shows what is published).`;
+    throw new Error(`Agent command "${command}" was not found. ${hint}`);
+}
+/**
+ * Runs a one-shot command against the agent and shuts it down again.
+ *
+ * These commands exist so a login — or a look at what the agent supports — can
+ * be done deliberately, before any task arrives, rather than only when a
+ * session is refused.
+ */
+export async function runAgentCommand(command, acpCmdArgs, agentrqConfig, mcpBridge, authMethodId) {
+    const [cmd, ...cmdArgs] = acpCmdArgs;
+    const agent = await openAgentConnection({
+        acpCmdArgs,
+        mcpBridge,
+        env: agentrqConfig.env,
+        label: command,
+    });
+    try {
+        const connection = agent.connection;
+        const { authMethods, agentCapabilities } = agent.initResult;
+        if (command === "agent-info") {
+            console.log(describeAgentInfo(agent.initResult, acpCmdArgs.join(" ")));
+            return;
+        }
+        if (command === "list-auth-methods") {
+            console.log(`Authentication methods for "${acpCmdArgs.join(" ")}":\n${describeAuthMethods(authMethods)}`);
+            if (supportsLogout(agentCapabilities)) {
+                console.log("\nThe agent also supports --logout.");
+            }
+            return;
+        }
+        if (command === "logout") {
+            await logout(connection, agentCapabilities);
+            return;
+        }
+        await login({
+            connection,
+            methods: authMethods,
+            launch: { command: cmd, args: cmdArgs, env: agentrqConfig.env },
+            preferredId: authMethodId,
+            interactive: isInteractiveTerminal(),
+        });
+    }
+    finally {
+        agent.process.kill();
+    }
+}
+/**
+ * The full help text.
+ *
+ * Shown for `--help`, and when the gateway is run with nothing to do — at
+ * which point the reason someone is looking at the terminal is that they do
+ * not yet know what to type.
+ */
+export function helpText(version = pkg.version) {
+    return `acp-gateway ${version} — bridges an ACP agent to an agentrq workspace.
+
+USAGE
+  acp-gateway [options] -- <agent-command> [agent-args...]
+  acp-gateway [options] --agent <registry-id>
+
+  The agent is either a command you supply after \`--\`, or an id from the ACP
+  registry. Everything after \`--\` is passed to the agent untouched.
+
+AGENT
+  --agent <registry-id>       Run an agent from the ACP registry, installing it
+                              if needed, instead of a command you supply.
+  --list-agents               List every agent in the registry, and how each one
+                              can run on this machine. Exits.
+  --agent-info                What the agent says it supports — session
+                              lifecycle, prompt content, MCP transports and
+                              logins. Only a live handshake can tell you. Exits.
+  --allow-unverified-agent    Install a registry binary that publishes no
+                              checksum. Off by default: without a checksum there
+                              is no way to tell what was downloaded.
+  --registry-url <url>        Read a different registry index, for pinning it or
+                              for testing.
+
+AUTHENTICATION
+  --list-auth-methods         List the login methods the agent offers. Exits.
+  --login [method-id]         Log in to the agent. With no id, and a terminal to
+                              ask in, you are asked which method to use. Exits.
+  --logout                    Log out of the agent, where it supports it. Exits.
+  --auth-method <id>          The method to use when the agent demands a login
+                              mid-run. Defaults to choosing one automatically.
+
+BRIDGE
+  --max-concurrency <number>  How many tasks may prompt the agent at once.
+                              Defaults to 2.
+  --permission-timeout <min>  How long a tool call waits for someone to approve
+                              it before the turn is cancelled. Defaults to 30.
+                              0 waits indefinitely, which is what a wedged
+                              gateway looks like — use it knowingly.
+
+OTHER
+  --help, -h                  Show this help. Exits.
+
+EXAMPLES
+  acp-gateway --agent gemini                     Run Gemini from the registry
+  acp-gateway -- gemini --acp                    Run an agent you installed
+  acp-gateway --list-agents                      See what the registry offers
+  acp-gateway --agent-info --agent gemini        See what that agent supports
+  acp-gateway --login -- gemini --acp            Log in before running anything
+  acp-gateway --max-concurrency 4 -- gemini --acp
+
+The workspace comes from .mcp.json, searched for in the current directory and up
+to three directories above it.`;
+}
+export function printHelp() {
+    console.log(helpText());
+}
 async function main() {
-    console.log(`Starting [acp-gateway] ${pkg.name} v${pkg.version}`);
     const args = process.argv.slice(2);
-    // Find where the command starts (after -- if provided, or just all args)
+    // Everything after `--` is the agent command. Without a separator the
+    // gateway's own options are still recognised and whatever is left over is
+    // the command, so `acp-gateway --agent gemini` needs no trailing `--`.
     const cmdStartIndex = args.indexOf("--");
-    const acpCmdArgs = cmdStartIndex !== -1 ? args.slice(cmdStartIndex + 1) : args;
-    if (acpCmdArgs.length === 0) {
-        console.log("Usage: acp-gateway [--max-concurrency <number>] -- <acp-server-command> [args...]");
-        console.log("Example: acp-gateway --max-concurrency 4 -- gemini --acp");
+    const gatewayArgs = cmdStartIndex !== -1 ? args.slice(0, cmdStartIndex) : args;
+    const options = parseGatewayArgs(gatewayArgs);
+    const explicitCommand = cmdStartIndex !== -1 ? args.slice(cmdStartIndex + 1) : options.rest;
+    const { maxConcurrency, command, authMethodId } = options;
+    if (command === "help") {
+        printHelp();
+        process.exit(0);
+    }
+    // Listing the registry needs neither a workspace nor an agent.
+    if (command === "list-agents") {
+        await runListAgents(options.registryUrl);
+        process.exit(0);
+    }
+    // Nothing to run: the reason someone is looking at the terminal now is that
+    // they do not yet know what to type, so show the help rather than an error
+    // about a workspace they have not got to yet.
+    if (!options.agentId && explicitCommand.length === 0) {
+        printHelp();
         process.exit(1);
     }
+    console.log(`Starting [acp-gateway] ${pkg.name} v${pkg.version}`);
     // 1. Load MCP Config
     const configs = loadMcpConfig();
     const agentrqConfig = pickAgentrqServer(configs);
-    // Parse max concurrency from CLI args, falling back to default of 2
-    let maxConcurrency = 2;
-    const gatewayArgs = cmdStartIndex !== -1 ? args.slice(0, cmdStartIndex) : [];
-    const maxConcurrencyIdx = gatewayArgs.findIndex((arg) => arg === "--max-concurrency" || arg === "--maxConcurrency");
-    if (maxConcurrencyIdx !== -1 && maxConcurrencyIdx + 1 < gatewayArgs.length) {
-        const val = parseInt(gatewayArgs[maxConcurrencyIdx + 1], 10);
-        if (!isNaN(val)) {
-            maxConcurrency = val;
-        }
+    // 2. Work out what actually starts the agent — a registry id, or the command
+    // the user gave.
+    // These failures are all things the user can act on — an unknown registry
+    // id, no build for this platform, an unverifiable download, a mistyped
+    // command — so they get a sentence rather than a stack trace.
+    const fail = (err) => {
+        console.error(`[acp-gateway] ${err instanceof Error ? err.message : err}`);
+        return process.exit(1);
+    };
+    const resolved = await resolveAgentCommand(options, explicitCommand).catch(fail);
+    const acpCmdArgs = resolved.command;
+    try {
+        assertAgentRunnable(acpCmdArgs[0], Boolean(options.agentId));
+    }
+    catch (err) {
+        fail(err);
+    }
+    if (resolved.env) {
+        // The registry entry's env is part of how that agent must be launched, so
+        // it travels with the command into every session spawned from it.
+        agentrqConfig.env = { ...agentrqConfig.env, ...resolved.env };
     }
+    authConfig.methodId = authMethodId;
+    permissionConfig.timeoutMs = options.permissionTimeoutMs;
     const taskQueue = new TaskQueue(maxConcurrency);
-    // 2. Initialize MCP Bridge
+    // 3. Initialize MCP Bridge
     const mcpBridge = new MCPBridge(agentrqConfig);
+    // Auth commands talk to the agent and exit; they never start bridging tasks.
+    // They run before the bridge connects, so a first-time login still works when
+    // the workspace is unreachable — `callTool` connects on demand if the login
+    // actually needs to reach agentrq.
+    if (command !== "run") {
+        try {
+            await runAgentCommand(command, acpCmdArgs, agentrqConfig, mcpBridge, authMethodId);
+        }
+        finally {
+            await mcpBridge.close();
+        }
+        process.exit(0);
+    }
     await mcpBridge.connect();
     try {
         // Bridge: MCP -> ACP
@@ -287,6 +747,7 @@ async function main() {
                         prompt: [{ type: "text", text: content }],
                     });
                     await sessionInfo.acpClient.flushReply(sessionInfo.sessionId);
+                    await sessionInfo.acpClient.reportStopReason(sessionInfo.sessionId, result.stopReason);
                     console.error(`\n[acp] Agent completed task. Reason: ${result.stopReason}`);
                 }
                 catch (err) {
@@ -374,6 +835,7 @@ export async function checkForNextTask(mcpBridge, acpCmdArgsOrConnection, config
                     prompt: [{ type: "text", text }],
                 });
                 await acpClientToUse.flushReply(sessionIdToUse);
+                await acpClientToUse.reportStopReason(sessionIdToUse, promptResult.stopReason);
                 console.error(`\n[acp] Agent completed with: ${promptResult.stopReason}`);
             };
             if (taskQueue) {