agent-yes 1.85.0 → 1.87.0

package/dist/{subcommands-BwWcA9uo.js → subcommands-BltyYaEs.js}

@@ -1,5 +1,6 @@
-import "./logger-B9h0djqx.js";
 import { r as readGlobalPids } from "./globalPidIndex-Cr-g75QF.js";
+import { a as resolveRemoteSpec, i as readRemotes } from "./remotes-CFrho898.js";
+import ms from "ms";
 import yargs from "yargs";
 import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises";
 import { homedir } from "os";
@@ -126,7 +127,9 @@ const SUBCOMMANDS = new Set([
 	"head",
 	"send",
 	"restart",
-	"note"
+	"note",
+	"serve",
+	"remote"
 ]);
 const IDLE_THRESHOLD_MS = 60 * 1e3;
 function isSubcommand(name) {
@@ -153,6 +156,14 @@ async function runSubcommand(argv) {
 			case "send": return await cmdSend(rest);
 			case "restart": return await cmdRestart(rest);
 			case "note": return await cmdNote(rest);
+			case "serve": {
+				const { cmdServe } = await import("./serve-8dWQHSBu.js");
+				return cmdServe(rest);
+			}
+			case "remote": {
+				const { cmdRemote } = await import("./remotes-kfUzk-JT.js");
+				return cmdRemote(rest);
+			}
 			default: return null;
 		}
 	} catch (err) {
@@ -199,6 +210,254 @@ async function resolveOne(keyword, opts) {
 	const lines = matches.slice(0, 10).map((r) => `  ${r.pid}  ${r.cli}  ${r.cwd}`).join("\n");
 	throw new Error(`keyword "${keyword}" matched ${matches.length} agents — disambiguate by pid or pass --latest:\n${lines}`);
 }
+async function remoteGet(remote, pathname) {
+	return fetch(`${remote.url}${pathname}`, { headers: { Authorization: `Bearer ${remote.token}` } });
+}
+async function remotePost(remote, pathname, body) {
+	return fetch(`${remote.url}${pathname}`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${remote.token}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(body)
+	});
+}
+async function runRemoteLs(remote, opts) {
+	const params = new URLSearchParams();
+	if (remote.keyword) params.set("keyword", remote.keyword);
+	if (opts.all) params.set("all", "1");
+	if (opts.active) params.set("active", "1");
+	const res = await remoteGet(remote, `/api/ls?${params}`);
+	if (!res.ok) {
+		process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+		return 1;
+	}
+	const records = await res.json();
+	if (records.length === 0) {
+		process.stderr.write(remote.keyword ? `no agents matched "${remote.keyword}" on ${remote.url}\n` : `no running agents on ${remote.url}\n`);
+		return 0;
+	}
+	process.stderr.write(`[remote ${remote.url}]\n`);
+	const termWidth = process.stdout.columns ?? 120;
+	const widths = {
+		pid: Math.max(3, ...records.map((r) => String(r.pid).length)),
+		cli: Math.max(3, ...records.map((r) => String(r.cli).length)),
+		status: Math.max(6, ...records.map((r) => String(r.status).length)),
+		cwd: Math.max(3, ...records.map((r) => String(r.cwd).length))
+	};
+	const fixedWidth = widths.pid + widths.cli + widths.status + widths.cwd + 8;
+	const promptBudget = Math.max(20, termWidth - fixedWidth - 1);
+	const header = [
+		"PID".padEnd(widths.pid),
+		"CLI".padEnd(widths.cli),
+		"STATUS".padEnd(widths.status),
+		"CWD".padEnd(widths.cwd),
+		"PROMPT"
+	].join("  ") + "\n";
+	process.stdout.write(header);
+	for (const r of records) {
+		const label = r.prompt ? truncate(`→ ${r.prompt}`, promptBudget) : "";
+		process.stdout.write([
+			String(r.pid).padEnd(widths.pid),
+			String(r.cli).padEnd(widths.cli),
+			String(r.status).padEnd(widths.status),
+			String(r.cwd).padEnd(widths.cwd),
+			label
+		].join("  ") + "\n");
+	}
+	return 0;
+}
+async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4) {
+	const keyword = remote.keyword ?? "";
+	if (!keyword) {
+		process.stderr.write("remote tail/cat/head requires a keyword (e.g. token@host:port:keyword)\n");
+		return 1;
+	}
+	if (mode === "tail" && follow) {
+		const ac = new AbortController();
+		process.on("SIGINT", () => ac.abort());
+		const deadline = Date.now() + reconnectTimeoutMs;
+		let delay = 1e3;
+		let attempt = 0;
+		process.stderr.write(`[remote ${remote.url}  ${keyword}]\nfollowing... (Ctrl-C to stop, timeout: ${Math.round(reconnectTimeoutMs / 1e3)}s)\n`);
+		while (!ac.signal.aborted) try {
+			const res = await fetch(`${remote.url}/api/tail/${encodeURIComponent(keyword)}`, {
+				headers: {
+					Authorization: `Bearer ${remote.token}`,
+					Accept: "text/event-stream"
+				},
+				signal: ac.signal
+			});
+			if (!res.ok) {
+				if (res.status === 401 || res.status === 404) {
+					process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+					return 1;
+				}
+				throw new Error(`HTTP ${res.status}`);
+			}
+			if (attempt > 0) process.stderr.write("remote: reconnected\n");
+			delay = 1e3;
+			const reader = res.body.getReader();
+			const dec = new TextDecoder();
+			let buf = "";
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buf += dec.decode(value, { stream: true });
+				const lines = buf.split("\n");
+				buf = lines.pop() ?? "";
+				for (const line of lines) {
+					if (!line.startsWith("data: ")) continue;
+					try {
+						const text = JSON.parse(line.slice(6));
+						process.stdout.write(text);
+						if (!text.endsWith("\n")) process.stdout.write("\n");
+					} catch {}
+				}
+			}
+			break;
+		} catch (e) {
+			if (e.name === "AbortError" || ac.signal.aborted) return 0;
+			if (Date.now() >= deadline) {
+				process.stderr.write(`remote: timeout after ${Math.round(reconnectTimeoutMs / 1e3)}s, giving up\n`);
+				return 1;
+			}
+			process.stderr.write(`remote: disconnected (${e.message}), retrying in ${delay / 1e3}s…\n`);
+			await new Promise((resolve, reject) => {
+				const t = setTimeout(resolve, delay);
+				ac.signal.addEventListener("abort", () => {
+					clearTimeout(t);
+					reject(/* @__PURE__ */ new Error("abort"));
+				});
+			}).catch(() => {});
+			if (ac.signal.aborted) return 0;
+			delay = Math.min(delay * 2, 3e4);
+			attempt++;
+		}
+		return 0;
+	}
+	const params = new URLSearchParams({
+		mode,
+		n: String(n)
+	});
+	const res = await remoteGet(remote, `/api/read/${encodeURIComponent(keyword)}?${params}`);
+	if (!res.ok) {
+		process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+		return 1;
+	}
+	const text = await res.text();
+	process.stderr.write(`[remote ${remote.url}  ${keyword}]\n`);
+	process.stdout.write(text);
+	if (!text.endsWith("\n")) process.stdout.write("\n");
+	return 0;
+}
+async function runRemoteSend(remote, msg, code) {
+	const keyword = remote.keyword ?? "";
+	if (!keyword) {
+		process.stderr.write("remote send requires a keyword (e.g. token@host:port:keyword)\n");
+		return 1;
+	}
+	const res = await remotePost(remote, "/api/send", {
+		keyword,
+		msg,
+		code
+	});
+	if (!res.ok) {
+		process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+		return 1;
+	}
+	const data = await res.json();
+	process.stdout.write(`sent to remote pid ${data.pid} (${remote.url}  ${keyword})\n`);
+	return 0;
+}
+async function runRemoteStatus(remote) {
+	const keyword = remote.keyword ?? "";
+	if (!keyword) {
+		process.stderr.write("remote status requires a keyword (e.g. token@host:port:keyword)\n");
+		return 1;
+	}
+	const res = await remoteGet(remote, `/api/status/${encodeURIComponent(keyword)}`);
+	if (!res.ok) {
+		process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+		return 1;
+	}
+	process.stdout.write(JSON.stringify(await res.json(), null, 2) + "\n");
+	return 0;
+}
+async function fetchRemoteRecordsRaw(url, token, opts) {
+	const params = new URLSearchParams();
+	if (opts.all) params.set("all", "1");
+	if (opts.active) params.set("active", "1");
+	if (opts.keyword) params.set("keyword", opts.keyword);
+	try {
+		const res = await fetch(`${url}/api/ls?${params}`, {
+			headers: { Authorization: `Bearer ${token}` },
+			signal: AbortSignal.timeout(5e3)
+		});
+		if (!res.ok) return [];
+		return await res.json();
+	} catch {
+		return [];
+	}
+}
+async function runAllRemotesLs(opts) {
+	const remotes = await readRemotes();
+	const localOpts = {
+		all: opts.all,
+		active: opts.active,
+		json: true,
+		latest: false,
+		cwdScope: null
+	};
+	const [localResult, ...remoteResults] = await Promise.allSettled([listRecords(opts.keyword, localOpts).then((recs) => ({
+		host: "local",
+		records: recs
+	})), ...Array.from(remotes.entries()).map(([alias, cfg]) => fetchRemoteRecordsRaw(cfg.url, cfg.token, opts).then((records) => ({
+		host: alias,
+		records
+	})))]);
+	const rows = [];
+	if (localResult.status === "fulfilled") for (const r of localResult.value.records) rows.push({
+		host: "local",
+		rec: r
+	});
+	for (const res of remoteResults) if (res.status === "fulfilled") for (const r of res.value.records) rows.push({
+		host: res.value.host,
+		rec: r
+	});
+	if (rows.length === 0) {
+		process.stderr.write("no running agents\n");
+		return 0;
+	}
+	const termWidth = process.stdout.columns ?? 120;
+	const hostW = Math.max(4, ...rows.map((r) => r.host.length));
+	const pidW = Math.max(3, ...rows.map((r) => String(r.rec.pid).length));
+	const cliW = Math.max(3, ...rows.map((r) => String(r.rec.cli).length));
+	const statusW = Math.max(6, ...rows.map((r) => String(r.rec.status).length));
+	const cwdW = Math.max(3, ...rows.map((r) => shortenPath(String(r.rec.cwd)).length));
+	const promptBudget = Math.max(20, termWidth - hostW - pidW - cliW - statusW - cwdW - 10 - 1);
+	process.stdout.write([
+		"HOST".padEnd(hostW),
+		"PID".padEnd(pidW),
+		"CLI".padEnd(cliW),
+		"STATUS".padEnd(statusW),
+		"CWD".padEnd(cwdW),
+		"PROMPT"
+	].join("  ") + "\n");
+	for (const { host, rec } of rows) {
+		const label = rec.prompt ? truncate(`→ ${rec.prompt}`, promptBudget) : "";
+		process.stdout.write([
+			host.padEnd(hostW),
+			String(rec.pid).padEnd(pidW),
+			String(rec.cli).padEnd(cliW),
+			String(rec.status).padEnd(statusW),
+			shortenPath(String(rec.cwd)).padEnd(cwdW),
+			label
+		].join("  ") + "\n");
+	}
+	return 0;
+}
 async function cmdLs(rest) {
 	const y = yargs(rest).usage("Usage: ay ls [keyword] [options]\n       ay list [keyword] [options]\n       ay ps   [keyword] [options]\n\nList running agents. Optionally filter by keyword (pid, cwd substring, or prompt substring).").option("all", {
 		type: "boolean",
@@ -219,18 +478,34 @@ async function cmdLs(rest) {
 	}).option("cwd", {
 		type: "string",
 		description: "Restrict to agents whose cwd starts with dir"
+	}).option("all-remotes", {
+		type: "boolean",
+		default: false,
+		description: "Include agents from all configured remotes (remotes.yaml)"
 	}).option("help", {
 		alias: "h",
 		type: "boolean",
 		default: false,
 		description: "Show this help"
-	}).example("ay ls", "list running agents").example("ay ls --all", "include exited agents").example("ay ls --json", "machine-readable output").example("ay ls symval", "filter by cwd/prompt keyword").help(false).version(false).exitProcess(false);
+	}).example("ay ls", "list running agents").example("ay ls --all-remotes", "include all configured remote machines").example("ay ls --all", "include exited agents").example("ay ls --json", "machine-readable output").example("ay ls symval", "filter by cwd/prompt keyword").help(false).version(false).exitProcess(false);
 	const argv = await y.parseAsync();
 	if (argv.help || argv.h) {
 		process.stdout.write(await y.getHelp() + "\n");
 		return 0;
 	}
+	if (argv["all-remotes"]) return runAllRemotesLs({
+		all: argv.all,
+		active: argv.active,
+		keyword: argv._[0] !== void 0 ? String(argv._[0]) : void 0
+	});
 	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	if (keyword) {
+		const remote = await resolveRemoteSpec(keyword);
+		if (remote) return runRemoteLs(remote, {
+			all: argv.all,
+			active: argv.active
+		});
+	}
 	const opts = {
 		all: argv.all,
 		active: argv.active,
@@ -309,6 +584,7 @@ async function cmdLs(rest) {
 		if (alive) {
 			hints.push(`  ay status ${alive.pid}                # JSON status snapshot\n`);
 			hints.push(`  ay status ${alive.pid} --watch        # stream changes as JSON\n`);
+			hints.push(`  ay status ${alive.pid} --wait-idle    # block until state == idle\n`);
 			hints.push(`  ay tail ${alive.pid}                  # view latest output\n`);
 			hints.push(`  ay tail -f ${alive.pid}               # follow live output\n`);
 			hints.push(`  ay send ${alive.pid} "next: ..."      # send a prompt (keyword: pid, cwd, or prompt substring)\n`);
@@ -360,6 +636,10 @@ async function cmdRead(rest, { mode }) {
 	}).option("cwd", {
 		type: "string",
 		description: "Restrict to agents under this dir"
+	}).option("reconnect-timeout", {
+		type: "number",
+		default: 120,
+		description: "Seconds before giving up reconnecting remote SSE (default: 120)"
 	}).help(false).version(false).exitProcess(false).parseAsync();
 	const opts = {
 		all: argv.all,
@@ -369,6 +649,13 @@ async function cmdRead(rest, { mode }) {
 		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
 	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	if (keyword) {
+		const remote = await resolveRemoteSpec(keyword);
+		const nFlag2 = argv.n;
+		const n2 = nFlag2 !== void 0 && Number.isFinite(nFlag2) && nFlag2 > 0 ? Math.floor(nFlag2) : mode === "cat" ? 0 : 96;
+		const reconnectTimeoutMs = (argv["reconnect-timeout"] ?? 120) * 1e3;
+		if (remote) return runRemoteRead(remote, mode, argv.follow, n2, reconnectTimeoutMs);
+	}
 	const follow = argv.follow;
 	const nFlag = argv.n;
 	const n = nFlag !== void 0 && Number.isFinite(nFlag) && nFlag > 0 ? Math.floor(nFlag) : mode === "cat" ? 0 : 96;
@@ -555,7 +842,12 @@ async function cmdSend(rest) {
 	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
 	const rawMessage = argv._.slice(1).map(String).join(" ");
 	if (!keyword) throw new Error("usage: ay send <keyword> <msg|-> [--code=enter|esc|ctrl-c|ctrl-y|tab|none]");
-	const trailing = controlCodeFromName(argv.code.toLowerCase());
+	const codeName = argv.code.toLowerCase();
+	{
+		const remote = await resolveRemoteSpec(keyword);
+		if (remote) return runRemoteSend(remote, rawMessage, codeName);
+	}
+	const trailing = controlCodeFromName(codeName);
 	const record = await resolveOne(keyword, opts);
 	const fifoPath = record.fifo_file;
 	if (!fifoPath) throw new Error(`pid ${record.pid}: no fifo_file recorded — agent was not started with --stdpush (or was spawned by Rust which doesn't yet support FIFO IPC; see ROADMAP item 10)`);
@@ -722,6 +1014,13 @@ async function cmdStatus(rest) {
 		type: "boolean",
 		default: false,
 		description: "Stream changes as JSON"
+	}).option("wait-idle", {
+		type: "boolean",
+		default: false,
+		description: "Block until state == idle. Exit 0 idle, 1 stopped, 2 timeout"
+	}).option("timeout", {
+		type: "string",
+		description: "Timeout for --wait-idle (e.g. 30s, 5m). Default: no timeout"
 	}).option("interval", {
 		type: "number",
 		default: 2,
@@ -742,10 +1041,17 @@ async function cmdStatus(rest) {
 		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
 	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
-	if (!keyword) throw new Error("usage: ay status <keyword> [--watch] [--interval=N]");
+	if (!keyword) throw new Error("usage: ay status <keyword> [--watch | --wait-idle] [--timeout=Ns]");
+	{
+		const remote = await resolveRemoteSpec(keyword);
+		if (remote) return runRemoteStatus(remote);
+	}
 	const watch = argv.watch;
+	const waitIdle = argv["wait-idle"];
 	const intervalFlag = argv.interval;
 	const intervalMs = Math.max(500, (Number.isFinite(intervalFlag) ? intervalFlag : 2) * 1e3);
+	const timeoutMs = typeof argv.timeout === "string" && argv.timeout.length > 0 ? ms(argv.timeout) ?? NaN : null;
+	if (timeoutMs !== null && !Number.isFinite(timeoutMs)) throw new Error(`invalid --timeout value: ${argv.timeout}`);
 	const record = await resolveOne(keyword, opts);
 	const emit = (snap, ts) => {
 		const out = ts !== void 0 ? {
@@ -754,6 +1060,25 @@ async function cmdStatus(rest) {
 		} : snap;
 		process.stdout.write(JSON.stringify(out) + "\n");
 	};
+	if (waitIdle) {
+		const startedAt = Date.now();
+		for (;;) {
+			const snap = await snapshotStatus(record);
+			if (snap.state === "idle") {
+				emit(snap);
+				return 0;
+			}
+			if (snap.state === "stopped") {
+				emit(snap);
+				return 1;
+			}
+			if (timeoutMs !== null && Date.now() - startedAt >= timeoutMs) {
+				emit(snap);
+				return 2;
+			}
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+	}
 	if (!watch) {
 		emit(await snapshotStatus(record));
 		return 0;
@@ -783,5 +1108,5 @@ async function cmdStatus(rest) {
 }
 
 //#endregion
-export { isSubcommand, runSubcommand };
-//# sourceMappingURL=subcommands-BwWcA9uo.js.map
+export { matchKeyword as a, resolveOne as c, writeToIpc as d, listRecords as i, runSubcommand as l, isPidAlive as n, readNotes as o, isSubcommand as r, renderRawLog as s, controlCodeFromName as t, snapshotStatus as u };
+//# sourceMappingURL=subcommands-BltyYaEs.js.map

package/dist/{tray-CH_G7aXM.js → tray-DHuD0nEk.js}

@@ -175,4 +175,4 @@ async function startTray() {
 
 //#endregion
 export { ensureTray, startTray };
-//# sourceMappingURL=tray-CH_G7aXM.js.map
+//# sourceMappingURL=tray-DHuD0nEk.js.map

package/dist/{ts-D0ddYVke.js → ts-CSMhtgoi.js}

@@ -1,5 +1,5 @@
 import { n as logger, t as addTransport } from "./logger-B9h0djqx.js";
-import { r as getInstalledPackage } from "./versionChecker-ftOiNICT.js";
+import { r as getInstalledPackage } from "./versionChecker-gyE00XVe.js";
 import { i as shouldUseLock, r as releaseLock, t as acquireLock } from "./runningLock-C22d9SRJ.js";
 import { t as PidStore } from "./pidStore-C1JXxoPi.js";
 import { r as readGlobalPids } from "./globalPidIndex-Cr-g75QF.js";
@@ -1693,4 +1693,4 @@ function sleep(ms) {
 
 //#endregion
 export { removeControlCharacters as a, AgentContext as i, agentYes as n, config as r, CLIS_CONFIG as t };
-//# sourceMappingURL=ts-D0ddYVke.js.map
+//# sourceMappingURL=ts-CSMhtgoi.js.map

package/dist/{versionChecker-ftOiNICT.js → versionChecker-gyE00XVe.js}

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 
 //#region package.json
 var name = "agent-yes";
-var version = "1.85.0";
+var version = "1.87.0";
 
 //#endregion
 //#region ts/versionChecker.ts
@@ -221,4 +221,4 @@ async function displayVersion() {
 
 //#endregion
 export { versionString as i, displayVersion as n, getInstalledPackage as r, checkAndAutoUpdate as t };
-//# sourceMappingURL=versionChecker-ftOiNICT.js.map
+//# sourceMappingURL=versionChecker-gyE00XVe.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-yes",
-  "version": "1.85.0",
+  "version": "1.87.0",
   "description": "A wrapper tool that automates interactions with various AI CLI tools by automatically handling common prompts and responses.",
   "keywords": [
     "ai",

package/ts/remotes.ts

@@ -0,0 +1,161 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import path from "path";
+import yaml from "yaml";
+
+function remotesPath(): string {
+  const dir = process.env.AGENT_YES_HOME ?? path.join(homedir(), ".agent-yes");
+  return path.join(dir, "remotes.yaml");
+}
+
+export interface RemoteConfig {
+  url: string; // e.g. "http://192.168.1.5:7432"
+  token: string;
+}
+
+export interface ResolvedRemote {
+  url: string;
+  token: string;
+  keyword?: string;
+}
+
+export async function readRemotes(): Promise<Map<string, RemoteConfig>> {
+  let raw: string;
+  try {
+    raw = await readFile(remotesPath(), "utf-8");
+  } catch {
+    return new Map();
+  }
+  const doc = yaml.parse(raw) ?? {};
+  const remotes = doc.remotes ?? {};
+  const map = new Map<string, RemoteConfig>();
+  for (const [alias, cfg] of Object.entries(remotes)) {
+    if (cfg && typeof (cfg as any).url === "string" && typeof (cfg as any).token === "string") {
+      map.set(alias, { url: (cfg as any).url, token: (cfg as any).token });
+    }
+  }
+  return map;
+}
+
+export async function writeRemoteAlias(alias: string, config: RemoteConfig): Promise<void> {
+  const remotes = await readRemotes();
+  remotes.set(alias, config);
+  const doc: Record<string, any> = {};
+  for (const [k, v] of remotes) doc[k] = v;
+  await mkdir(path.dirname(remotesPath()), { recursive: true });
+  await writeFile(remotesPath(), yaml.stringify({ remotes: doc }));
+}
+
+export async function deleteRemoteAlias(alias: string): Promise<void> {
+  const remotes = await readRemotes();
+  remotes.delete(alias);
+  const doc: Record<string, any> = {};
+  for (const [k, v] of remotes) doc[k] = v;
+  await writeFile(remotesPath(), yaml.stringify({ remotes: doc }));
+}
+
+/** Parse token@host:port[:keyword] — the `@` is a hard signal this is remote. */
+export function parseDirectRemoteSpec(
+  spec: string,
+): { token: string; host: string; port: number; keyword?: string; baseUrl: string } | null {
+  const m = /^([^@]+)@([^:@]+):(\d+)(?::(.+))?$/.exec(spec);
+  if (!m) return null;
+  const host = m[2]!;
+  const port = parseInt(m[3]!, 10);
+  return {
+    token: m[1]!,
+    host,
+    port,
+    keyword: m[4] || undefined,
+    baseUrl: `http://${host}:${port}`,
+  };
+}
+
+/**
+ * Resolve a spec to connection details.
+ * Accepts:
+ *   token@host:port[:keyword]   — direct
+ *   alias[:keyword]             — looked up in ~/.agent-yes/remotes.yaml
+ * Returns null if the spec doesn't match any remote.
+ */
+export async function resolveRemoteSpec(spec: string): Promise<ResolvedRemote | null> {
+  const direct = parseDirectRemoteSpec(spec);
+  if (direct) {
+    return { url: direct.baseUrl, token: direct.token, keyword: direct.keyword };
+  }
+
+  // alias[:keyword]
+  const colonIdx = spec.indexOf(":");
+  const alias = colonIdx >= 0 ? spec.slice(0, colonIdx) : spec;
+  const keyword = colonIdx >= 0 ? spec.slice(colonIdx + 1) || undefined : undefined;
+
+  const remotes = await readRemotes();
+  const cfg = remotes.get(alias);
+  if (!cfg) return null;
+  return { url: cfg.url, token: cfg.token, keyword };
+}
+
+// ---------------------------------------------------------------------------
+// ay remote subcommand
+// ---------------------------------------------------------------------------
+
+export async function cmdRemote(rest: string[]): Promise<number> {
+  const sub = rest[0];
+
+  if (!sub || sub === "ls" || sub === "list") {
+    const remotes = await readRemotes();
+    if (remotes.size === 0) {
+      process.stdout.write("no remotes configured\n");
+      process.stderr.write(
+        "\n" +
+          "  ay remote add <alias> <url> <token>   # add a remote\n" +
+          "  ay serve                               # start server (prints token)\n",
+      );
+      return 0;
+    }
+    for (const [alias, cfg] of remotes) {
+      const preview = cfg.token.length > 8 ? cfg.token.slice(0, 8) + "..." : cfg.token;
+      process.stdout.write(`${alias}\t${cfg.url}\ttoken:${preview}\n`);
+    }
+    return 0;
+  }
+
+  if (sub === "add") {
+    const [, alias, url, token] = rest;
+    if (!alias || !url || !token) {
+      process.stderr.write("usage: ay remote add <alias> <url> <token>\n");
+      process.stderr.write(
+        "  example: ay remote add work-mac http://192.168.1.5:7432 mytoken123\n",
+      );
+      return 1;
+    }
+    await writeRemoteAlias(alias, { url, token });
+    process.stdout.write(`remote '${alias}' added → ${url}\n`);
+    process.stderr.write(`\n  ay ls ${alias}            # list agents on ${alias}\n`);
+    return 0;
+  }
+
+  if (sub === "rm" || sub === "remove" || sub === "delete") {
+    const alias = rest[1];
+    if (!alias) {
+      process.stderr.write("usage: ay remote rm <alias>\n");
+      return 1;
+    }
+    const remotes = await readRemotes();
+    if (!remotes.has(alias)) {
+      process.stderr.write(`remote '${alias}' not found\n`);
+      return 1;
+    }
+    await deleteRemoteAlias(alias);
+    process.stdout.write(`remote '${alias}' removed\n`);
+    return 0;
+  }
+
+  process.stderr.write(`ay remote: unknown subcommand '${sub}'\n`);
+  process.stderr.write(
+    "  ay remote ls                           # list configured remotes\n" +
+      "  ay remote add <alias> <url> <token>   # add a remote\n" +
+      "  ay remote rm <alias>                   # remove a remote\n",
+  );
+  return 1;
+}