agent-transport-system 0.7.95 → 0.7.96

package/dist/ats.js

@@ -31,7 +31,7 @@ import { Box, Container, Editor, Key, ProcessTerminal, TUI, Text, getEditorKeybi
 import { ReadStream, WriteStream } from "node:tty";
 
 //#region package.json
-var version = "0.7.95";
+var version = "0.7.96";
 var package_default = {
 	$schema: "https://www.schemastore.org/package.json",
 	name: "agent-transport-system",
@@ -82581,6 +82581,16 @@ function toErrorMessage$7(error) {
 //#endregion
 //#region src/space/web-url.ts
 function buildSpaceWebUrl(baseUrl, spaceId, options) {
+	const url = new URL(resolveGatewayWebOrigin(baseUrl));
+	const surface = options?.surface ?? "public";
+	url.pathname = surface === "app" ? `/app/spaces/${encodeURIComponent(spaceId)}` : `/spaces/${encodeURIComponent(spaceId)}`;
+	url.search = "";
+	const profileId = normalizeOptionalText$5(options?.profileId);
+	if (surface === "app" && profileId) url.searchParams.set("profileId", profileId);
+	url.hash = "";
+	return url.toString();
+}
+function resolveGatewayWebOrigin(baseUrl) {
 	const url = new URL(baseUrl);
 	if (isLoopbackHostname$2(url.hostname) && url.port === "8080") url.port = "3000";
 	if (url.hostname === "gateway.ats.sh") {
@@ -82588,13 +82598,10 @@ function buildSpaceWebUrl(baseUrl, spaceId, options) {
 		url.port = "";
 		url.protocol = "https:";
 	}
-	const surface = options?.surface ?? "public";
-	url.pathname = surface === "app" ? `/app/spaces/${encodeURIComponent(spaceId)}` : `/spaces/${encodeURIComponent(spaceId)}`;
+	url.pathname = "";
 	url.search = "";
-	const profileId = normalizeOptionalText$5(options?.profileId);
-	if (surface === "app" && profileId) url.searchParams.set("profileId", profileId);
 	url.hash = "";
-	return url.toString();
+	return url.origin;
 }
 function isLoopbackHostname$2(hostname) {
 	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
@@ -97785,6 +97792,69 @@ function requireValidSetupBootstrapWrite(input) {
 	return parsed.data;
 }
 
+//#endregion
+//#region src/guides/local-agents-guide-url.ts
+const LOCAL_AGENTS_GUIDE_PATH = "/guides/local-agents";
+const LOCAL_AGENTS_GUIDE_AGENT_NAMES = "Codex, Claude Code, or OpenCode";
+function buildLocalAgentsGuideUrl(baseUrl) {
+	const url = new URL(resolveGatewayWebOrigin(baseUrl));
+	url.pathname = LOCAL_AGENTS_GUIDE_PATH;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
+function buildNoLocalAgentsNoticeLines(input) {
+	return [
+		`ATS did not find ${LOCAL_AGENTS_GUIDE_AGENT_NAMES} on this computer.`,
+		"Install and sign in to one of them if you want this computer to run local agents from ATS.",
+		`Guide: ${input.guideUrl}`
+	];
+}
+function appendLocalAgentsGuideUrl(input) {
+	return `${input.message} Install guide: ${input.guideUrl}`;
+}
+async function confirmContinueWithoutLocalAgents(input) {
+	return await runInteractivePrompt({
+		initialState: { guideUrl: input.guideUrl },
+		fallbackResult: "continue",
+		renderLines: renderLocalAgentsGuidePromptLines,
+		handleKeypress: handleLocalAgentsGuidePromptKeypress
+	}, input.streams);
+}
+function renderLocalAgentsGuidePromptLines(state, status) {
+	if (status === "submitted") return ["Continuing setup without local agents."];
+	if (status === "cancelled") return ["Setup cancelled."];
+	return [...buildNoLocalAgentsNoticeLines({ guideUrl: state.guideUrl }), "Continue setting up the ATS service without any local agents? [Y/n]"];
+}
+function handleLocalAgentsGuidePromptKeypress(input) {
+	if (input.key.name === "return" || input.key.name === "enter") return {
+		type: "result",
+		status: "submitted",
+		result: "continue",
+		state: input.state
+	};
+	const value = String(input.str ?? "").trim().toLowerCase();
+	if (value === "y") return {
+		type: "result",
+		status: "submitted",
+		result: "continue",
+		state: input.state
+	};
+	if (value === "n" || input.key.name === "escape") return {
+		type: "result",
+		status: "cancelled",
+		result: "cancelled",
+		state: input.state
+	};
+	if (input.key.ctrl && input.key.name === "c") return {
+		type: "result",
+		status: "cancelled",
+		result: "cancelled",
+		state: input.state
+	};
+	return { type: "ignore" };
+}
+
 //#endregion
 //#region src/local-service/reporting/selected-agent-controller-reporting.ts
 function resolveSelectedAgentControllerReadiness(input) {
@@ -97895,6 +97965,64 @@ function normalizeId(value) {
 	return value.trim();
 }
 
+//#endregion
+//#region src/ui/controlling-terminal.ts
+const CONTROLLING_TERMINAL_PATH = "/dev/tty";
+function hasUsableProcessTerminal() {
+	return process$1.stdin.isTTY === true && process$1.stdout.isTTY === true && typeof process$1.stdin.setRawMode === "function";
+}
+function closeFdSafely(fd) {
+	if (fd === null) return;
+	try {
+		closeSync(fd);
+	} catch {}
+}
+function resolveControllingTerminalSession() {
+	if (hasUsableProcessTerminal()) return {
+		streams: {
+			input: process$1.stdin,
+			output: process$1.stdout
+		},
+		close: () => void 0
+	};
+	if (process$1.platform === "win32") return null;
+	let readFd = null;
+	let writeFd = null;
+	let input = null;
+	let output = null;
+	try {
+		readFd = openSync(CONTROLLING_TERMINAL_PATH, "r");
+		input = new ReadStream(readFd);
+		readFd = null;
+		writeFd = openSync(CONTROLLING_TERMINAL_PATH, "w");
+		output = new WriteStream(writeFd);
+		writeFd = null;
+		if (input.isTTY !== true || output.isTTY !== true || typeof input.setRawMode !== "function") {
+			input.destroy();
+			output.destroy();
+			return null;
+		}
+		const ttyInput = input;
+		const ttyOutput = output;
+		return {
+			streams: {
+				input: ttyInput,
+				output: ttyOutput
+			},
+			close: () => {
+				ttyInput.destroy();
+				ttyOutput.destroy();
+			}
+		};
+	} catch {
+		if (input) input.destroy();
+		else closeFdSafely(readFd);
+		if (output) output.destroy();
+		else closeFdSafely(writeFd);
+		return null;
+	}
+}
+
 //#endregion
 //#region src/ui/setup-progress.ts
 function createSetupProgressReporter(input) {
@@ -98525,64 +98653,6 @@ async function writeConnectedComputerEnrollmentToServiceContract(input) {
 	});
 }
 
-//#endregion
-//#region src/ui/controlling-terminal.ts
-const CONTROLLING_TERMINAL_PATH = "/dev/tty";
-function hasUsableProcessTerminal() {
-	return process$1.stdin.isTTY === true && process$1.stdout.isTTY === true && typeof process$1.stdin.setRawMode === "function";
-}
-function closeFdSafely(fd) {
-	if (fd === null) return;
-	try {
-		closeSync(fd);
-	} catch {}
-}
-function resolveControllingTerminalSession() {
-	if (hasUsableProcessTerminal()) return {
-		streams: {
-			input: process$1.stdin,
-			output: process$1.stdout
-		},
-		close: () => void 0
-	};
-	if (process$1.platform === "win32") return null;
-	let readFd = null;
-	let writeFd = null;
-	let input = null;
-	let output = null;
-	try {
-		readFd = openSync(CONTROLLING_TERMINAL_PATH, "r");
-		input = new ReadStream(readFd);
-		readFd = null;
-		writeFd = openSync(CONTROLLING_TERMINAL_PATH, "w");
-		output = new WriteStream(writeFd);
-		writeFd = null;
-		if (input.isTTY !== true || output.isTTY !== true || typeof input.setRawMode !== "function") {
-			input.destroy();
-			output.destroy();
-			return null;
-		}
-		const ttyInput = input;
-		const ttyOutput = output;
-		return {
-			streams: {
-				input: ttyInput,
-				output: ttyOutput
-			},
-			close: () => {
-				ttyInput.destroy();
-				ttyOutput.destroy();
-			}
-		};
-	} catch {
-		if (input) input.destroy();
-		else closeFdSafely(readFd);
-		if (output) output.destroy();
-		else closeFdSafely(writeFd);
-		return null;
-	}
-}
-
 //#endregion
 //#region src/commands/prepare-session-executor.ts
 const PREPARE_TOKEN_HEADER = "x-ats-prepare-token";
@@ -98720,12 +98790,15 @@ async function runPrepareSessionExecutorOnce(input) {
 }
 async function resolveAgentSelection(input) {
 	if (input.input.localAgentSelection) {
+		const guideUrl = buildLocalAgentsGuideUrl(input.input.gatewayUrl);
 		const localAgentIds = resolveTerminalSelectedLocalAgentIds({
+			guideUrl,
 			selection: input.input.localAgentSelection,
 			snapshot: input.snapshot
 		});
 		if (hasAgentSelectionBeenSaved(input.snapshot) && haveSameLocalAgentIds(input.snapshot.selectedLocalAgentIds, localAgentIds)) return input.snapshot;
 		return await writeTerminalAgentSelection({
+			...localAgentIds.length === 0 && input.input.localAgentSelection.mode !== "none" ? { emptySelectionGuideUrl: guideUrl } : {},
 			input: input.input,
 			localAgentIds,
 			stream: input.stream,
@@ -98748,10 +98821,7 @@ const PROMPT_LOCAL_AGENT_SELECTION_MESSAGE = "Choose the local agents to connect
 async function resolveTerminalInteractiveLocalAgentSelection(input) {
 	const selectableEntries = resolveSelectableLocalAgentCatalogEntries(input.snapshot);
 	if (selectableEntries.length === 0) {
-		emitPrepareProgressLine(input.input, {
-			state: "success",
-			text: "No supported local agents found. Setup will continue without local agents."
-		});
+		await confirmZeroLocalAgentPrepareSessionIfNeeded({ input: input.input });
 		return [];
 	}
 	const allSelectableIds = selectableEntries.map((entry) => entry.agentId);
@@ -98783,6 +98853,35 @@ async function resolveTerminalInteractiveLocalAgentSelection(input) {
 		terminal.close();
 	}
 }
+async function confirmZeroLocalAgentPrepareSessionIfNeeded(input) {
+	const guideUrl = buildLocalAgentsGuideUrl(input.input.gatewayUrl);
+	const terminal = input.input.runtime.resolvedView === "human" ? resolveControllingTerminalSession() : null;
+	if (!terminal) {
+		emitPrepareNoLocalAgentsNotice({
+			guideUrl,
+			input: input.input
+		});
+		return;
+	}
+	try {
+		if (await confirmContinueWithoutLocalAgents({
+			guideUrl,
+			streams: terminal.streams
+		}) === "continue") return;
+		emitHumanStatus(input.input, "Setup cancelled", ["Install an agent CLI, then re-run the setup command from ATS Web.", `Guide: ${guideUrl}`]);
+		throw new Error("ATS setup was cancelled before choosing local agents.");
+	} finally {
+		terminal.close();
+	}
+}
+function emitPrepareNoLocalAgentsNotice(input) {
+	const [summary, ...details] = buildNoLocalAgentsNoticeLines({ guideUrl: input.guideUrl });
+	emitPrepareProgressLine(input.input, {
+		state: "success",
+		text: summary ? `${summary} Setup will continue without local agents.` : "Setup will continue without local agents."
+	});
+	for (const detail of details) emitPrepareProgressDetail(input.input, detail);
+}
 function resolveSelectableLocalAgentCatalogEntries(snapshot) {
 	return (snapshot.localAgentCatalog?.entries ?? []).filter((entry) => entry.selectable);
 }
@@ -98796,10 +98895,17 @@ function resolveTerminalSelectedLocalAgentIds(input) {
 	const missingIds = selectedIds.filter((agentId) => !selectableById.has(agentId));
 	if (missingIds.length > 0) {
 		const selectableIds = [...selectableById.keys()];
-		throw new Error([`ATS cannot select local agent ${missingIds.join(", ")} for setup.`, selectableIds.length > 0 ? `Selectable local agents: ${selectableIds.join(", ")}.` : "No selectable local agents were found on this computer."].join(" "));
+		throw new Error([`ATS cannot select local agent ${missingIds.join(", ")} for setup.`, selectableIds.length > 0 ? `Selectable local agents: ${selectableIds.join(", ")}.` : formatNoSelectableLocalAgentsFound(input.guideUrl)].join(" "));
 	}
 	return selectedIds;
 }
+function formatNoSelectableLocalAgentsFound(guideUrl) {
+	const message = "No selectable local agents were found on this computer.";
+	return guideUrl ? appendLocalAgentsGuideUrl({
+		guideUrl,
+		message
+	}) : message;
+}
 function assertCompletedPrepareSessionMatchesTerminalSelection(input) {
 	const localAgentIds = resolveTerminalSelectedLocalAgentIds(input);
 	if (haveSameLocalAgentIds(input.snapshot.selectedLocalAgentIds, localAgentIds)) return;
@@ -98819,13 +98925,20 @@ async function writeTerminalAgentSelection(input) {
 	});
 	emitPrepareProgressLine(input.input, {
 		state: "success",
-		text: input.localAgentIds.length === 0 ? "Selected: no local agents" : `Selected: ${formatSelectedLocalAgentNames({
+		text: input.localAgentIds.length === 0 ? formatSelectedNoLocalAgents(input.emptySelectionGuideUrl) : `Selected: ${formatSelectedLocalAgentNames({
 			localAgentIds: input.localAgentIds,
 			snapshot: selectedSnapshot
 		})}`
 	});
 	return selectedSnapshot;
 }
+function formatSelectedNoLocalAgents(guideUrl) {
+	const message = "Selected: no local agents";
+	return guideUrl ? appendLocalAgentsGuideUrl({
+		guideUrl,
+		message
+	}) : message;
+}
 async function reportLocalAgentCatalogForSelection(input) {
 	const connectionEpoch = requireConnectionEpoch(input.snapshot);
 	emitHumanSection(input.input, "Local agents");
@@ -100502,11 +100615,21 @@ async function runSetupUnlocked(input) {
 		readiness: initialReadiness,
 		view: runtime.resolvedView
 	});
+	const localAgentsGuideUrl = buildLocalAgentsGuideUrl(gatewayUrl);
 	const selectedLocalAgentIds = resolveSetupLocalAgentIds({
+		guideUrl: localAgentsGuideUrl,
 		localAgent: input.localAgent,
 		localAgents: input.localAgents,
 		readiness: initialReadiness
 	});
+	await confirmZeroLocalAgentSetupIfNeeded({
+		explicitSelection: hasExplicitLocalAgentSelection(input),
+		guideUrl: localAgentsGuideUrl,
+		localAgentsMode: input.localAgents,
+		presenter,
+		runtime,
+		selectedLocalAgentIds
+	});
 	if (selectedLocalAgentIds.length > 0) assertStartLocalAgentsEnableCompleted(await runWithSetupSpinner({
 		code: "setup.progress.local_agents.enabling",
 		message: setupCopy.cliProgressConnectingLocalAgents,
@@ -100648,12 +100771,79 @@ function resolveSetupLocalAgentIds(input) {
 		const missingIds = localAgentIds.filter((agentId) => !selectableById.has(agentId));
 		if (missingIds.length > 0) {
 			const selectableIds = [...selectableById.keys()];
-			throw new Error([`ATS cannot set up local agent ${missingIds.join(", ")} on this computer.`, selectableIds.length > 0 ? `Available local agents: ${selectableIds.join(", ")}.` : "No available local agents were found on this computer."].join(" "));
+			throw new Error([`ATS cannot set up local agent ${missingIds.join(", ")} on this computer.`, selectableIds.length > 0 ? `Available local agents: ${selectableIds.join(", ")}.` : formatNoAvailableLocalAgentsFound(input.guideUrl)].join(" "));
 		}
 		return localAgentIds;
 	}
 	return [...selectableById.keys()].sort((left, right) => left.localeCompare(right));
 }
+async function confirmZeroLocalAgentSetupIfNeeded(input) {
+	if (input.selectedLocalAgentIds.length > 0 || normalizeOptionalString$1(input.localAgentsMode) === "none") return;
+	if (input.explicitSelection) {
+		emitSetupNoLocalAgentsWarning(input);
+		return;
+	}
+	const terminal = input.runtime.resolvedView === "human" ? resolveControllingTerminalSession() : null;
+	if (!terminal) {
+		emitSetupNoLocalAgentsWarning(input);
+		return;
+	}
+	try {
+		if (await confirmContinueWithoutLocalAgents({
+			guideUrl: input.guideUrl,
+			streams: terminal.streams
+		}) === "continue") return;
+		emitSetupNoLocalAgentsCancelled(input);
+		throw new Error("ATS setup was cancelled before choosing local agents.");
+	} finally {
+		terminal.close();
+	}
+}
+function emitSetupNoLocalAgentsWarning(input) {
+	const lines = buildNoLocalAgentsNoticeLines({ guideUrl: input.guideUrl });
+	if (input.runtime.resolvedView === "human") {
+		renderInfoCard({
+			presenter: input.presenter,
+			title: "No Local Agents Found",
+			codePrefix: "setup.local_agents.none",
+			rows: lines.map((line) => ({
+				label: "",
+				value: line
+			})),
+			sanitize: true,
+			minContentWidth: 56
+		});
+		return;
+	}
+	for (const [index, line] of lines.entries()) input.presenter.line({
+		code: `setup.local_agents.none.${index + 1}`,
+		text: line
+	});
+}
+function emitSetupNoLocalAgentsCancelled(input) {
+	if (input.runtime.resolvedView !== "human") return;
+	renderInfoCard({
+		presenter: input.presenter,
+		title: "Setup Cancelled",
+		codePrefix: "setup.local_agents.cancelled",
+		rows: [{
+			label: "",
+			value: "Install an agent CLI, then re-run the setup command from ATS Web."
+		}, {
+			label: "",
+			value: `Guide: ${input.guideUrl}`
+		}],
+		sanitize: true,
+		minContentWidth: 56
+	});
+}
+function formatNoAvailableLocalAgentsFound(guideUrl) {
+	const message = "No available local agents were found on this computer.";
+	return guideUrl ? appendLocalAgentsGuideUrl({
+		guideUrl,
+		message
+	}) : message;
+}
 function assertStartLocalAgentsEnableCompleted(result) {
 	if (result.status !== "completed") throw new Error("ATS setup cannot continue until selected local agents are available on this computer.");
 	const blockingError = result.summary.errors[0] ?? null;
@@ -100736,6 +100926,7 @@ async function resolveDelegatedSetupCompletionFacts(input) {
 		selectedLocalAgentIds: []
 	};
 	const selectedLocalAgentIds = sessionSelectedLocalAgentIds ? [...sessionSelectedLocalAgentIds] : resolveSetupLocalAgentIds({
+		guideUrl: buildLocalAgentsGuideUrl(input.gatewayUrl),
 		localAgent: input.setupInput.localAgent,
 		localAgents: input.setupInput.localAgents,
 		readiness: await collectStartLocalReadiness({ auth: {
@@ -100822,6 +101013,7 @@ function emitSetupComplete(input) {
 	if (input.view === "human") {
 		const setupCopy = getSetupFlowCopy("setup");
 		const serviceGuidance = buildSetupServiceGuidance({ cliCommandPrefix });
+		const localAgentsGuideUrl = buildLocalAgentsGuideUrl(input.gatewayUrl);
 		renderInfoCard({
 			presenter: input.presenter,
 			title: setupCopy.cliCompletionTitle,
@@ -100829,13 +101021,30 @@ function emitSetupComplete(input) {
 			compact: true,
 			minContentWidth: 44,
 			sanitize: true,
-			rows: [{
-				label: "Agents",
-				value: formatSetupCompleteLocalAgents(input.selectedLocalAgentIds)
-			}, ...input.bootstrap.status === "completed" ? [] : [{
-				label: "Space",
-				value: formatSetupBootstrapHumanSummary(input.bootstrap)
-			}]]
+			rows: [
+				{
+					label: "Agents",
+					value: formatSetupCompleteLocalAgents({
+						guideUrl: localAgentsGuideUrl,
+						selectedLocalAgentIds: input.selectedLocalAgentIds
+					})
+				},
+				...input.selectedLocalAgentIds.length === 0 ? [{
+					label: "Install guide",
+					value: localAgentsGuideUrl
+				}] : [],
+				...input.bootstrap.status === "completed" ? [] : [{
+					label: "Space",
+					value: formatSetupBootstrapHumanSummary(input.bootstrap)
+				}]
+			]
+		});
+		if (input.selectedLocalAgentIds.length === 0) input.presenter.line({
+			code: "setup.complete.local_agents.guide",
+			text: `Open guide: ${formatTerminalHyperlink({
+				label: "Local agent install guide",
+				url: localAgentsGuideUrl
+			})} (${localAgentsGuideUrl})`
 		});
 		renderSetupServiceGuidanceCard({
 			atsServiceRuntimeIdentity: input.atsServiceRuntimeIdentity,
@@ -100992,9 +101201,9 @@ async function finalizeLocalComponentsSetupSnapshot() {
 	await writeInstalledLocalComponentsSnapshot({ source: "setup" });
 	return await resolveLocalComponentsStatus();
 }
-function formatSetupCompleteLocalAgents(selectedLocalAgentIds) {
-	if (selectedLocalAgentIds.length === 0) return "No local agents selected";
-	return `${selectedLocalAgentIds.length} detected: ${selectedLocalAgentIds.join(", ")}`;
+function formatSetupCompleteLocalAgents(input) {
+	if (input.selectedLocalAgentIds.length === 0) return `No local agents connected. Install one from the guide: ${input.guideUrl}`;
+	return `${input.selectedLocalAgentIds.length} detected: ${input.selectedLocalAgentIds.join(", ")}`;
 }
 function formatSetupCompleteSpaceSetupHint(input) {
 	if (input.bootstrap.status === "completed") return `${input.bootstrap.welcomingSpace.outcome === "reused" ? "Reused" : "Created"} ${input.bootstrap.welcomingSpace.name}`;