@agentrq/acp-gateway 0.2.2 → 0.2.4

package/dist/auth.js

@@ -0,0 +1,189 @@
+/**
+ * auth.ts
+ *
+ * ACP authentication support: reading the login methods an agent advertises
+ * during `initialize`, recognising the protocol's `auth_required` failure, and
+ * running either kind of login on the user's behalf.
+ *
+ * See https://agentclientprotocol.com/protocol/v1/authentication
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+/** JSON-RPC code ACP reserves for "the user must authenticate first". */
+export const AUTH_REQUIRED_CODE = -32000;
+/**
+ * `type` discriminates the two kinds of auth method on the wire, and the
+ * protocol treats a missing `type` as `agent`.
+ */
+export function authMethodType(method) {
+    return method.type === "terminal" ? "terminal" : "agent";
+}
+/** Renders the agent's login options as a numbered list for the terminal. */
+export function describeAuthMethods(methods) {
+    if (!methods?.length) {
+        return "The agent advertises no authentication methods — no login is needed.";
+    }
+    return methods
+        .map((m, i) => {
+        const kind = authMethodType(m) === "terminal" ? " [terminal login]" : "";
+        const description = m.description ? ` — ${m.description}` : "";
+        return `  ${i + 1}. ${m.name} (${m.id})${kind}${description}`;
+    })
+        .join("\n");
+}
+/** Pulls `code`/`message` out of a JSON-RPC failure in either shape it arrives in. */
+function errorParts(err) {
+    if (!err || typeof err !== "object")
+        return { message: "" };
+    const candidate = err;
+    const source = candidate.error && typeof candidate.error === "object"
+        ? candidate.error
+        : candidate;
+    return {
+        code: typeof source.code === "number" ? source.code : undefined,
+        message: typeof source.message === "string" ? source.message : "",
+    };
+}
+/**
+ * Tells an "authenticate first" refusal apart from any other failure.
+ *
+ * ACP carries `auth_required` on the reserved code -32000, which agents also
+ * use for unrelated errors (a denied permission, for one), so the message has
+ * to agree before we send the user through a login.
+ */
+export function isAuthRequiredError(err) {
+    const { code, message } = errorParts(err);
+    return code === AUTH_REQUIRED_CODE && /auth/i.test(message);
+}
+/**
+ * Chooses the login method to run without asking anyone.
+ *
+ * An explicitly named id always wins. Otherwise `agent` methods come first:
+ * the agent drives those itself, so they work in an unattended gateway, while
+ * a `terminal` method needs a human at a TTY.
+ */
+export function pickAuthMethod(methods, { preferredId, allowTerminal = false } = {}) {
+    if (!methods?.length)
+        return undefined;
+    if (preferredId)
+        return methods.find((m) => m.id === preferredId);
+    return (methods.find((m) => authMethodType(m) === "agent") ??
+        (allowTerminal ? methods.find((m) => authMethodType(m) === "terminal") : undefined));
+}
+/** Asks on stderr so the gateway's stdout stays free for its own output. */
+async function askOnTerminal(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Asks the user which login to use, the way an editor would on first run.
+ *
+ * A single method needs no question. An empty answer takes the first method,
+ * and an unrecognised one re-asks rather than logging in with something the
+ * user did not choose.
+ */
+export async function promptForAuthMethod(methods, ask = askOnTerminal) {
+    if (!methods.length)
+        return undefined;
+    if (methods.length === 1)
+        return methods[0];
+    console.error(`\n[auth] The agent requires a login. Available methods:\n${describeAuthMethods(methods)}`);
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const answer = (await ask(`[auth] Choose a method [1-${methods.length}, default 1]: `)).trim();
+        if (!answer)
+            return methods[0];
+        const byIndex = Number(answer);
+        if (Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= methods.length) {
+            return methods[byIndex - 1];
+        }
+        const byId = methods.find((m) => m.id === answer);
+        if (byId)
+            return byId;
+        console.error(`[auth] "${answer}" is not one of the listed methods.`);
+    }
+    return undefined;
+}
+/**
+ * Runs a `terminal` login by re-launching the configured agent interactively.
+ *
+ * The protocol has the client reproduce its own agent invocation with the
+ * method's extra args and env, hand the process the user's terminal, and read
+ * success off the exit status.
+ */
+export async function runTerminalAuth(method, launch) {
+    const extra = method.args ?? [];
+    const extraEnv = method.env ?? {};
+    const args = [...launch.args, ...extra];
+    console.error(`[auth] Running terminal login: ${launch.command} ${args.join(" ")}\n` +
+        `[auth] Complete the login in your terminal; the gateway resumes when it exits.`);
+    const child = spawn(launch.command, args, {
+        stdio: "inherit",
+        env: { ...process.env, ...launch.env, ...extraEnv },
+    });
+    await new Promise((resolve, reject) => {
+        child.on("error", (err) => reject(new Error(`Terminal login "${method.id}" failed to start: ${err.message}`)));
+        child.on("exit", (code, signal) => {
+            if (code === 0)
+                return resolve();
+            reject(new Error(`Terminal login "${method.id}" failed (code=${code}, signal=${signal}).`));
+        });
+    });
+}
+/** Runs whichever kind of login the chosen method calls for. */
+export async function runAuthMethod(connection, method, launch) {
+    if (authMethodType(method) === "terminal") {
+        await runTerminalAuth(method, launch);
+    }
+    else {
+        // A `terminal` method must never reach `authenticate` — the agent does not
+        // implement one for it.
+        await connection.authenticate({ methodId: method.id });
+    }
+    console.error(`[auth] Logged in with "${method.name}" (${method.id}).`);
+}
+/**
+ * Logs in: picks a method — asking the user when one is there to ask — and
+ * runs it. Returns the method used, or undefined when the agent advertises no
+ * login at all.
+ */
+export async function login({ connection, methods, launch, preferredId, interactive = false, ask, }) {
+    if (!methods?.length) {
+        console.error("[auth] The agent advertises no authentication methods; nothing to log in to.");
+        return undefined;
+    }
+    let method = pickAuthMethod(methods, { preferredId, allowTerminal: interactive });
+    if (preferredId && !method) {
+        throw new Error(`Unknown authentication method "${preferredId}". Available:\n${describeAuthMethods(methods)}`);
+    }
+    if (!preferredId && interactive) {
+        method = await promptForAuthMethod(methods, ask);
+    }
+    if (!method) {
+        throw new Error(`No usable authentication method. Available:\n${describeAuthMethods(methods)}\n` +
+            `Terminal logins need an interactive terminal; re-run acp-gateway from one, ` +
+            `or pass --auth-method <id>.`);
+    }
+    await runAuthMethod(connection, method, launch);
+    return method;
+}
+/** Whether the agent said it implements `logout` during `initialize`. */
+export function supportsLogout(agentCapabilities) {
+    const auth = agentCapabilities?.auth;
+    return auth?.logout !== undefined && auth?.logout !== null;
+}
+/** Ends the agent's authenticated state, if it implements logout. */
+export async function logout(connection, agentCapabilities) {
+    if (!supportsLogout(agentCapabilities)) {
+        console.error("[auth] The agent does not support logout.");
+        return false;
+    }
+    await connection.logout({});
+    console.error("[auth] Logged out.");
+    return true;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,7 +7,8 @@
  */
 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";
@@ -33,36 +34,51 @@ export function mapMcpServers(configs) {
     });
 }
 import { AgentRQACPClient } from "./acpClient.js";
+import { describeAuthMethods, isAuthRequiredError, login, logout, supportsLogout, } from "./auth.js";
+import { resolveAgentLaunch } from "./agentInstall.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 = {};
+/**
+ * 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 },
     });
     // 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);
+        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})`);
+        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);
@@ -80,14 +96,62 @@ 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),
     };
-    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);
     const sessionInfo = {
@@ -95,6 +159,7 @@ export async function getOrCreateSession(taskId, acpCmdArgs, configs, agentrqCon
         connection,
         acpClient,
         sessionId: sessionResult.sessionId,
+        initResult,
     };
     activeSessions.set(key, sessionInfo);
     return sessionInfo;
@@ -237,33 +302,311 @@ 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,
+        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 "--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 "--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 auth command against the agent and shuts it down again.
+ *
+ * These commands exist so a login can be done deliberately — before any task
+ * arrives — rather than only when a session is refused.
+ */
+export async function runAuthCommand(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 === "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.
+  --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.
+
+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 --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;
     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 runAuthCommand(command, acpCmdArgs, agentrqConfig, mcpBridge, authMethodId);
+        }
+        finally {
+            await mcpBridge.close();
+        }
+        process.exit(0);
+    }
     await mcpBridge.connect();
     try {
         // Bridge: MCP -> ACP