setup-agent 0.0.6 → 0.0.8

package/README.md

@@ -25,9 +25,11 @@ A setup opens `waiting` with its products and nothing else: no steps, no questio
 
 The URL is the browser's link to its agent, not one setup. A finished or cancelled setup stays on the link, and the browser's next setup replaces it with a new `checkout/create` carrying a new `id`: the plans, steps, inputs and log start over, the agent's presence carries across when it is still connected, and the stream prints `setup.created` with the new products. The agent keeps the stream running after `finished` or `cancelled` and blocks on `wait start`, which returns once the next setup begins planning; a setup already closed when the wait begins is skipped rather than reported.
 
+The browser sends the setup `id` and the displayed plan `revision` with each `checkout/plan` decision. The host rejects a mismatched setup or revision with `stale-plan`, so a queued decision cannot approve or revise a newer plan. Older clients may omit these fields and retain their existing behavior. The guard requires a host running this version of `setup-agent`.
+
 ## Inputs
 
-Inputs include `text`, `choice`, `model` and `entry-point`, plus the legacy `product` kind. A choice carries `options` (`id`, `label`, `description`, `icon`, `variants`), an optional `default` and a `help` note the browser renders as a "help me choose" disclosure. Option ids are unique, and neither option nor variant ids may contain `:`. The answer is the option id, `<option>:<variant>` when the option has variants (`langgraph:python`), or the user's own text when none of the options fit (including any text with more than one `:`); the stream marks that answer `custom`. An agent's own choice is multi-select unless asked with `--single`: the user checks any number of options (none may have variants), and the answer is a JSON array of those entries, which `wait` and the stream print as an array and `status` holds as text. `--single` is for options that exclude each other (one framework, one model, yes or no) and answers one id. Every one of the agent's own options must carry an `icon` from the pack `OPTION_ICONS` exports (`--icons "slack=message,email=mail"`); the CLI refuses the question otherwise. A preset option carries a brand mark instead. Every answer may carry a `note` from the user. A model input lists providers as its options; the browser collects the provider, its API key, the model and an optional reasoning effort, and the answer is that object as JSON (`{"provider","model","reasoningEffort"?}`); the API key is deposited separately and only ever reaches the env file the agent names through `env`.
+Inputs include `text`, `choice`, `model` and `entry-point`, plus the legacy `product` kind. A choice carries `options` (`id`, `label`, `description`, `icon`, `variants`), an optional `default` and a `help` note the browser renders as a "help me choose" disclosure. Option ids are unique, and neither option nor variant ids may contain `:`. The answer is the option id, `<option>:<variant>` when the option has variants (`langgraph:python`), or the user's own text when none of the options fit (including any text with more than one `:`); the stream marks that answer `custom`. An agent's own choice is multi-select unless asked with `--single`: the user checks any number of options (none may have variants), and the answer is a JSON array of those entries, which `wait` and the stream print as an array and `status` holds as text. `--single` is for options that exclude each other (one framework, one model, yes or no) and answers one id. Every one of the agent's own options must carry an `icon` from the pack `OPTION_ICONS` exports (`--icons "slack=message,email=mail"`); the CLI refuses the question otherwise. A preset option carries a brand mark instead. Every answer may carry a `note` from the user. A model input lists providers as its options; the browser collects the provider, its API key, the model and an optional reasoning effort, and the answer is that object as JSON (`{"provider","model","reasoningEffort"?}`); the API key is deposited separately and only ever reaches the env file the agent names through `env`. Only the CLI that asked can take it: `ask` keeps a redeem key in a private file under the user's state directory, or a per-user directory under the temp directory, and refuses a model question when neither can hold it, so `env` runs as the same user on the same machine.
 
 When the setup puts an assistant in the app, the agent asks for its entry point after discovering the app, with `ask "<prompt>" --entry-points '<JSON array>' [--default <id>]`. Each of 1–3 options includes a stable `id`, `label`, contextual `description`, and `entryPoint: { formFactor: "modal" | "sidebar" | "full-page", placement, trigger, recommended? }`. At most one option is recommended, and the agent marks it with `recommended` rather than `--default`, which would preselect it. Two alternatives can share a form factor when their placements differ. Entry-point questions accept exactly one option id, with an optional user note; variants, custom ids, a help note and multi-selection are refused. The agent describes the actual app's workflow, placement and opening action, then incorporates the user's selection into the approved plan.
 

package/dist/cli.d.ts

@@ -1,8 +1,15 @@
 import type { CheckoutClient } from "./client.js";
 import type { Checkout } from "./protocol.js";
 export declare const HELP: string;
-export declare const agentInstructions: (url: string) => string;
-export declare const INSTRUCTIONS: (url: string) => string;
+/**
+ * The normalized setup URL, or an error saying why it is refused. A setup URL
+ * is printed into shell commands and the coding agent's prompt, and the API
+ * key travels over it, so it must be https (http only on this machine), carry
+ * no credentials, query or fragment, and hold only address characters.
+ */
+export declare const parseSetupUrl: (value: string) => string;
+export declare const agentInstructions: (setupUrl: string) => string;
+export declare const INSTRUCTIONS: (setupUrl: string) => string;
 type Parsed = {
     positional: string[];
     flags: Map<string, string | true>;
@@ -65,7 +72,7 @@ export declare const upsertEnvLine: (content: string, key: string, value: string
  * secret consumes it and an unwritable destination must fail while it is
  * still deposited; it is read after, so lines written meanwhile survive.
  */
-export declare const writeEnvSecret: (file: string, key: string, take: () => Promise<string>) => Promise<void>;
+export declare const writeEnvSecret: (file: string, key: string, take: () => Promise<string>, projectRoot?: string) => Promise<void>;
 export declare const main: (argv: readonly string[]) => Promise<undefined>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAiB;AAmB/C,OAAO,KAAK,EAAE,QAAQ,EAAE,sBAAmB;AAE3C,eAAO,MAAM,IAAI,QAgChB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,KAAK,MAAM,WA2CZ,CAAC;AAEF,eAAO,MAAM,YAAY,QA7ClB,MAAM,WA6CgC,CAAC;AAE9C,KAAK,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,CAAC;AA6C1E,kGAAkG;AAClG,eAAO,MAAM,eAAe,GAAI,MAAK,MAAM,CAAC,UAAwB,uBACd,CAAC;AAyCvD,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,GAC7B,MAAK,MAAM,CAAC,UAAwB,EACpC,QAAO;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAkB,EACtD,SAAQ;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAmB,YAInC,CAAC;AA0FxB,KAAK,WAAW,GACZ;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,GAC7B;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7D;IACE,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2GAA2G;IAC3G,MAAM,CAAC,EAAE,IAAI,CAAC;CACf,GACD;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,wBAAwB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAKnD,eAAO,MAAM,UAAU,GACrB,QAAQ,QAAQ,CAAC,KAAK,EACtB,OAAO,QAAQ,CAAC,KAAK,KACpB,WAAW,EAqEb,CAAC;AA4CF,2LAA2L;AAC3L,eAAO,MAAM,YAAY,GACvB,QAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,6BAiBjD,CAAC;AAwDL,eAAO,MAAM,OAAO,GAClB,MAAM,SAAS,MAAM,EAAE,EACvB,OAAO,MAAM,CAAC,OAAO,CAAC,KACrB,QAAQ,CAAC,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CA+HxC,CAAC;AAQF,+EAA+E;AAC/E,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,WAWxE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,MAAM,MAAM,OAAO,CAAC,MAAM,CAAC,kBAa5B,CAAC;AAkBF,eAAO,MAAM,IAAI,GAAU,MAAM,SAAS,MAAM,EAAE,uBA+LjD,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -1,11 +1,14 @@
 import { connectCheckout } from "./client.js";
 import { INPUT_PRESETS, isPresetId, presetInput } from "./presets.js";
-import { AGENT_HEARTBEAT_MS, OPTION_ICONS, classifyChoiceAnswer, currentPlan, isAgentPresent, isClosed, isOptionIcon, isValidModelAnswer, parseEntryPointOptions, parseMultipleAnswer, stepProgress } from "./protocol.js";
+import { AGENT_HEARTBEAT_MS, OPTION_ICONS, classifyChoiceAnswer, currentPlan, isAgentPresent, isClosed, isLoopbackHostname, isOptionIcon, isValidModelAnswer, parseEntryPointOptions, parseMultipleAnswer, stepProgress } from "./protocol.js";
 import { spawn } from "node:child_process";
-import { open, readFile } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/promises";
+import { homedir, tmpdir, userInfo } from "node:os";
 import { createInterface } from "node:readline/promises";
-import { resolve } from "node:path";
-//#region src/cli.ts
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+// src/cli.ts
 const HELP = `setup-agent <url> [command]
 
 Commands (the url always comes first):
@@ -39,7 +42,33 @@ Commands (the url always comes first):
   done [--summary <text>] [--preview <url>]
                                     Mark every remaining step done and propose closing; the user closes it.
 `;
-const agentInstructions = (url) => `You are the coding agent for a setup the user opened in their browser. The browser shows this setup live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
+/** Characters a setup URL may hold: an origin and a path, nothing a shell or a reader treats as more than an address. */
+const SETUP_URL_PATTERN = /^https?:\/\/[A-Za-z0-9.-]+(?::[0-9]+)?(?:\/[A-Za-z0-9._~%/-]*)?$|^http:\/\/\[::1\](?::[0-9]+)?(?:\/[A-Za-z0-9._~%/-]*)?$/;
+/**
+* The normalized setup URL, or an error saying why it is refused. A setup URL
+* is printed into shell commands and the coding agent's prompt, and the API
+* key travels over it, so it must be https (http only on this machine), carry
+* no credentials, query or fragment, and hold only address characters.
+*/
+const parseSetupUrl = (value) => {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`"${value}" is not a URL`);
+	}
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) throw new Error("the setup URL must use https (http only on localhost)");
+	if (url.username !== "" || url.password !== "") throw new Error("the setup URL must not carry credentials");
+	if (url.search !== "" || url.hash !== "" || value.includes("?") || value.includes("#")) throw new Error("the setup URL must not have a query or fragment");
+	const href = url.href.replace(/\/$/, "");
+	if (!SETUP_URL_PATTERN.test(href)) throw new Error("the setup URL has characters a setup URL does not use");
+	return href;
+};
+/** `value` as one shell word, quoted only when it holds more than plain URL characters. */
+const shellWord = (value) => /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
+const agentInstructions = (setupUrl) => {
+	const url = shellWord(setupUrl);
+	return `You are the coding agent for a setup the user opened in their browser. The browser shows this setup live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
 
 First, start a persistent Monitor on
   npx setup-agent ${url} stream
@@ -82,6 +111,7 @@ Before that, start the project's dev server in the background when the project h
   npx setup-agent ${url} wait start
 which returns once that setup begins, then run "status" for its products, guides and instructions and go through plan and install again. A "setup.created" event while you are still working means the user replaced this setup: drop what you were doing and start over the same way.
 `;
+};
 const INSTRUCTIONS = agentInstructions;
 const parseArgs = (argv) => {
 	const positional = [];
@@ -181,7 +211,7 @@ const chooseLauncher = async () => {
 };
 const launchAgent = async (url) => {
 	const launcher = await chooseLauncher();
-	const prompt = `Run \`npx setup-agent ${url}\` and follow the instructions it prints.`;
+	const prompt = `Run \`npx setup-agent ${shellWord(url)}\` and follow the instructions it prints.`;
 	process.stdout.write(`\nStarting ${launcher.name}...\n\n`);
 	const child = spawn(launcher.command, launcher.args(prompt), { stdio: "inherit" });
 	const code = await new Promise((resolve) => {
@@ -485,6 +515,8 @@ const assertEnvKey = (key) => {
 /** Sets `key=value` in dotenv text, replacing an existing line for the key. */
 const upsertEnvLine = (content, key, value) => {
 	assertEnvKey(key);
+	const isLineBreaking = (code) => code < 32 || code >= 127 && code <= 159 || code === 8232 || code === 8233;
+	if ([...value].some((char) => isLineBreaking(char.charCodeAt(0)))) throw new Error(`the value for ${key} must be a single line`);
 	const line = `${key}=${value}`;
 	const lines = content === "" ? [] : content.replace(/\n$/, "").split("\n");
 	const index = lines.findIndex((entry) => /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(entry)?.[1] === key);
@@ -498,19 +530,98 @@ const upsertEnvLine = (content, key, value) => {
 * secret consumes it and an unwritable destination must fail while it is
 * still deposited; it is read after, so lines written meanwhile survive.
 */
-const writeEnvSecret = async (file, key, take) => {
+const writeEnvSecret = async (file, key, take, projectRoot = process.cwd()) => {
 	assertEnvKey(key);
-	const handle = await open(file, "a+", 384);
+	try {
+		if ((await lstat(file)).isSymbolicLink()) throw new Error(`${file} is a symbolic link; pass --file with its target to write there`);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	const projectRelative = relative(projectRoot, file);
+	if (projectRelative !== ".." && !projectRelative.startsWith(`..${sep}`) && !isAbsolute(projectRelative)) {
+		const root = await realpath(projectRoot);
+		const parent = await realpath(dirname(file));
+		const parentRelative = relative(root, parent);
+		if (parentRelative === ".." || parentRelative.startsWith(`..${sep}`) || isAbsolute(parentRelative)) throw new Error(`${file} has a parent directory outside the project`);
+	}
+	const handle = await open(file, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 384).catch((error) => {
+		if (error.code === "ELOOP") throw new Error(`${file} is a symbolic link; pass --file with its target to write there`);
+		throw error;
+	});
 	try {
 		await handle.chmod(384);
 		const value = await take();
 		const current = await handle.readFile("utf8");
+		const next = upsertEnvLine(current, key, value);
 		await handle.truncate(0);
-		await handle.writeFile(upsertEnvLine(current, key, value));
+		await handle.writeFile(next);
 	} finally {
 		await handle.close();
 	}
 };
+const redeemKeyDirectories = () => {
+	const stateHome = process.platform === "win32" ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local") : process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+	return [join(stateHome, "setup-agent"), join(tmpdir(), `setup-agent-${process.platform === "win32" ? userInfo().username : process.getuid()}`)];
+};
+const checkRedeemKeyDirectory = async (directory) => {
+	if (!isAbsolute(directory)) throw new Error("state home must be an absolute path");
+	const info = await lstat(directory);
+	if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`redeem key directory must not be a symbolic link: ${directory}`);
+	if (process.platform !== "win32") {
+		if (info.uid !== process.getuid()) throw new Error(`redeem key directory must be owned by the user: ${directory}`);
+		if ((info.mode & 63) !== 0) await chmod(directory, 448);
+	}
+};
+const prepareRedeemKeyDirectory = async (directory) => {
+	if (isAbsolute(directory)) await mkdir(directory, {
+		recursive: true,
+		mode: 448
+	});
+	await checkRedeemKeyDirectory(directory);
+};
+const saveRedeemKey = async (hash, key) => {
+	let lastError;
+	for (const directory of redeemKeyDirectories()) {
+		const file = join(directory, `${hash}.key`);
+		let created = false;
+		try {
+			await prepareRedeemKeyDirectory(directory);
+			const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
+			created = true;
+			try {
+				await handle.writeFile(key);
+			} finally {
+				await handle.close();
+			}
+			return file;
+		} catch (error) {
+			if (created) await unlink(file).catch(() => {});
+			lastError = error;
+		}
+	}
+	throw lastError;
+};
+const readRedeemKey = async (hash) => {
+	if (!/^[0-9a-f]{64}$/.test(hash)) return void 0;
+	for (const directory of redeemKeyDirectories()) try {
+		await checkRedeemKeyDirectory(directory);
+		const file = join(directory, `${hash}.key`);
+		const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+		try {
+			const info = await handle.stat();
+			if (!info.isFile() || process.platform !== "win32" && (info.mode & 63) !== 0) throw new Error("redeem key file must be private and regular");
+			const key = await handle.readFile("utf8");
+			if (createHash("sha256").update(key).digest("hex") === hash) return {
+				key,
+				file
+			};
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		continue;
+	}
+};
 const answerFields = (input, answer) => ({
 	answer: input.multiple && parseMultipleAnswer(answer) || answer,
 	...input.note !== void 0 && { note: input.note },
@@ -529,7 +640,12 @@ const main = async (argv) => {
 		process.stdout.write(HELP);
 		return process.exit(first === void 0 ? 1 : 0);
 	}
-	const url = first;
+	let url;
+	try {
+		url = parseSetupUrl(first);
+	} catch (error) {
+		return fail(error instanceof Error ? error.message : String(error));
+	}
 	if (command === "intro" && isDirectInvocation()) return launchAgent(url);
 	const client = await connectCheckout(url).catch((error) => fail(error instanceof Error ? error.message : String(error)));
 	const commands = client.commands;
@@ -599,7 +715,20 @@ const main = async (argv) => {
 				break;
 			}
 			case "ask": {
-				const { inputId } = await commands["agent/ask"](askSeed(rest, flags));
+				const seed = askSeed(rest, flags);
+				const redeemKey = seed.kind === "model" ? randomBytes(32).toString("hex") : void 0;
+				const redeemKeyHash = redeemKey === void 0 ? void 0 : createHash("sha256").update(redeemKey).digest("hex");
+				const keyFile = redeemKey === void 0 || redeemKeyHash === void 0 ? void 0 : await saveRedeemKey(redeemKeyHash, redeemKey).catch((error) => fail(`could not store the model redeem key: ${error instanceof Error ? error.message : String(error)}`));
+				let inputId;
+				try {
+					({inputId} = await commands["agent/ask"]({
+						...seed,
+						...redeemKeyHash !== void 0 && { redeemKeyHash }
+					}));
+				} catch (error) {
+					if (keyFile !== void 0) await unlink(keyFile).catch(() => {});
+					throw error;
+				}
 				if (!flags.has("wait")) {
 					print({
 						ok: true,
@@ -641,12 +770,22 @@ const main = async (argv) => {
 				if (isClosed(state)) fail("the setup is not open");
 				if (input.status !== "answered") fail(`input "${inputId}" is ${input.status}`);
 				if (input.kind !== "model" || !isValidModelAnswer(input, input.answer ?? "")) fail(`input "${inputId}" is not an llm-provider answer`);
+				const storedKey = input.redeemKeyHash === void 0 ? void 0 : await readRedeemKey(input.redeemKeyHash);
+				if (input.redeemKeyHash !== void 0 && storedKey === void 0) fail(`no local redeem key for "${inputId}"`);
 				const file = resolve(flagText(flags, "file") ?? ".env.local");
 				await writeEnvSecret(file, envKey, async () => {
-					const response = await fetch(`${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}?setup=${encodeURIComponent(setupId)}`);
+					const secretUrl = new URL(url);
+					if (secretUrl.protocol !== "https:" && !(secretUrl.protocol === "http:" && isLoopbackHostname(secretUrl.hostname))) fail("the key is only fetched over https");
+					const response = await fetch(`${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}?setup=${encodeURIComponent(setupId)}`, storedKey === void 0 ? void 0 : { headers: { "Setup-Agent-Redeem-Key": storedKey.key } });
+					if (response.status === 403) fail(`redeem key rejected for "${inputId}"`);
 					if (response.status === 404) fail(`the key for "${inputId}" was already taken or never deposited`);
 					if (!response.ok) fail(`could not fetch the key: ${response.status}`);
-					return response.text();
+					const key = await response.text();
+					if (!/^[A-Za-z0-9._~+/=:@%,-]+$/.test(key)) fail("the deposited key is not a valid API key");
+					return key;
+				});
+				if (storedKey !== void 0) await unlink(storedKey.file).catch((error) => {
+					if (error.code !== "ENOENT") process.stderr.write(`warning: could not remove a redeem key: ${error.message}\n`);
 				});
 				print({
 					ok: true,
@@ -689,7 +828,6 @@ const main = async (argv) => {
 		client.dispose();
 	}
 };
-//#endregion
-export { HELP, INSTRUCTIONS, agentInstructions, askSeed, detectAgentKind, diffEvents, isDirectInvocation, main, upsertEnvLine, waitForStart, writeEnvSecret };
+export { HELP, INSTRUCTIONS, agentInstructions, askSeed, detectAgentKind, diffEvents, isDirectInvocation, main, parseSetupUrl, upsertEnvLine, waitForStart, writeEnvSecret };
 
 //# sourceMappingURL=cli.js.map