setup-agent 0.0.8 → 0.1.0

package/dist/stream.d.ts

@@ -0,0 +1,93 @@
+import type { AskReason } from "./browser.js";
+import type { CheckoutClient } from "./client.js";
+import type { TerminalQuestion } from "./needs.js";
+import type { Checkout } from "./protocol.js";
+export type StreamEvent = {
+    event: "planning.started";
+} | {
+    event: "message.created";
+    messageId: string;
+    text: string;
+} | {
+    event: "input.answered";
+    inputId: string;
+    prompt: string;
+    /** The entries of a multiple choice answer, else the answer text. */
+    answer: string | string[];
+    note?: string;
+    /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */
+    custom?: true;
+} | {
+    event: "input.dismissed";
+    inputId: string;
+    prompt: string;
+} | {
+    event: "plan.approved";
+    revision: number;
+} | {
+    event: "plan.changes-requested";
+    revision: number;
+    feedback: string;
+} | {
+    event: "finished";
+    next: string;
+} | {
+    event: "cancelled";
+    next: string;
+} | {
+    event: "setup.created";
+    products: string[];
+} | {
+    event: "browser.opened";
+    /** The need the tab opened for: an input id, plan or finish. */
+    id: string;
+    url: string;
+    message: string;
+} | ({
+    event: "input.needed";
+    id: string;
+    reason: AskReason;
+    message: string;
+    /** The command that answers it, with the answer's shape in angle brackets. */
+    answer: string;
+} & TerminalQuestion);
+export declare const diffEvents: (before: Checkout.State, after: Checkout.State) => StreamEvent[];
+export declare const answerFields: (input: Checkout.Input, answer: string) => {
+    custom?: true;
+    note?: string;
+    answer: string | string[];
+};
+/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */
+export declare const setupPageUrl: (setupAppUrl: string, linkId: string, setupId: string) => string;
+/** `value` as one shell word, quoted only when it holds more than plain URL characters. */
+export declare const shellWord: (value: string) => string;
+export type FollowSetupOptions = {
+    /** Writes one line of events; the default prints a JSON array to stdout. */
+    print?: (events: StreamEvent[]) => void;
+    /** The agent the stream reports in its hello; detected by default. */
+    agent?: {
+        cwd?: string;
+        kind?: string;
+    };
+    /** Opens the setup page when the setup waits on the user; without it, the stream never opens one. */
+    browser?: {
+        setupAppUrl: string;
+        linkId: string;
+        /** The command that answers a need, before the need id: `npx assistant-ui@latest setup <url> answer`. */
+        answerCommand: string;
+        open?: (url: string) => void;
+        /** False for `--no-open`: the agent is told to ask instead. */
+        canOpen?: boolean;
+        now?: () => number;
+    };
+};
+/**
+ * Follows a setup as the agent: says hello, keeps the agent present with
+ * heartbeats, prints what changed as stream events, and opens the browser
+ * only when the setup waits on the user. Resolves with `stop`, which says
+ * goodbye; the caller disposes the client.
+ */
+export declare const followSetup: (client: Pick<CheckoutClient, "state" | "subscribe" | "commands">, { print, agent, browser }?: FollowSetupOptions) => Promise<{
+    stop: () => Promise<void>;
+}>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

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

package/dist/stream.js

@@ -0,0 +1,184 @@
+import { detectAgentKind } from "./agents.js";
+import { AGENT_HEARTBEAT_MS, classifyChoiceAnswer, parseMultipleAnswer } from "./protocol.js";
+import { formatTerminalQuestion, terminalQuestion } from "./needs.js";
+import { createBrowserGate } from "./browser.js";
+import spawn from "cross-spawn";
+// src/stream.ts
+const STAY_CONNECTED = "This setup is over, not your connection. Keep the stream running, tell the user you are connected and waiting for their next setup, and run wait start.";
+const diffEvents = (before, after) => {
+	const events = [];
+	if (before.status === "waiting" && after.status === "planning") events.push({ event: "planning.started" });
+	for (const entry of after.log) if (entry.role === "user" && entry.acknowledgedAt === void 0 && !before.log.some((previous) => previous.id === entry.id)) events.push({
+		event: "message.created",
+		messageId: entry.id,
+		text: entry.text
+	});
+	for (const input of after.inputs) {
+		if (before.inputs.find((candidate) => candidate.id === input.id)?.status === input.status) continue;
+		if (input.status === "answered") {
+			const answer = input.answer ?? "";
+			events.push({
+				event: "input.answered",
+				inputId: input.id,
+				prompt: input.prompt,
+				...answerFields(input, answer)
+			});
+		} else if (input.status === "dismissed" && after.status !== "cancelled") events.push({
+			event: "input.dismissed",
+			inputId: input.id,
+			prompt: input.prompt
+		});
+	}
+	for (const plan of after.plans) {
+		if (before.plans.find((candidate) => candidate.revision === plan.revision)?.status === plan.status || plan.status === "proposed") continue;
+		if (plan.status === "approved") events.push({
+			event: "plan.approved",
+			revision: plan.revision
+		});
+		else events.push({
+			event: "plan.changes-requested",
+			revision: plan.revision,
+			feedback: plan.feedback ?? ""
+		});
+	}
+	if (before.status !== "done" && after.status === "done") events.push({
+		event: "finished",
+		next: STAY_CONNECTED
+	});
+	if (before.status !== "cancelled" && after.status === "cancelled") events.push({
+		event: "cancelled",
+		next: STAY_CONNECTED
+	});
+	if (after.id !== null && after.id !== before.id) events.push({
+		event: "setup.created",
+		products: after.products.map((product) => product.slug)
+	});
+	return events;
+};
+const answerFields = (input, answer) => ({
+	answer: input.multiple && parseMultipleAnswer(answer) || answer,
+	...input.note !== void 0 && { note: input.note },
+	...input.kind === "choice" && classifyChoiceAnswer(input, answer) === "custom" && { custom: true }
+});
+/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */
+const setupPageUrl = (setupAppUrl, linkId, setupId) => `${setupAppUrl.replace(/\/$/, "")}/#link=${linkId}&setup=${setupId}`;
+/**
+* Opens `url` in the user's default browser without waiting for it.
+* `SETUP_AGENT_BROWSER` names another program to run with the URL instead,
+* such as a test driver.
+*/
+const openUrl = (url) => {
+	const custom = process.env.SETUP_AGENT_BROWSER?.trim();
+	const [command, args] = custom ? [custom, [url]] : process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+	const child = spawn(command, args, {
+		detached: true,
+		stdio: "ignore"
+	});
+	child.on("error", () => {});
+	child.unref();
+};
+/** `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 ASK_MESSAGES = {
+	"recently-opened": (question, { agoSeconds }) => `A browser tab for setup was opened ${agoSeconds}s ago. Wait for the user there, or ask the user directly in the terminal: ${question}`,
+	"browser-closed": (question) => `The user closed the setup tab. Ask the user directly in the terminal: ${question}`,
+	"no-browser": (question, { page }) => `No browser tab is open for this setup. Ask the user directly in the terminal, or give them ${page}: ${question}`
+};
+/** What the agent reads when setup opened the browser, or when it should ask the user itself. */
+const gateEvent = (action, answerCommand, page) => {
+	const { need } = action;
+	if (action.type === "open") return {
+		event: "browser.opened",
+		id: need.id,
+		url: action.url,
+		message: `Opened the setup in the user's browser for ${need.kind === "input" ? `"${need.input.prompt.trim() || "Your agent needs an answer."}"` : need.kind === "plan" ? "the plan review" : "closing the setup"}. Tell the user once that it is waiting there, and give them ${action.url} in case it did not open. The answer arrives on this stream.`
+	};
+	const question = terminalQuestion(need);
+	return {
+		event: "input.needed",
+		id: need.id,
+		reason: action.reason,
+		message: ASK_MESSAGES[action.reason](formatTerminalQuestion(question), {
+			agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1e3),
+			page
+		}),
+		...question,
+		answer: `${answerCommand} ${need.id} <${question.answerFormat}>`
+	};
+};
+/**
+* Follows a setup as the agent: says hello, keeps the agent present with
+* heartbeats, prints what changed as stream events, and opens the browser
+* only when the setup waits on the user. Resolves with `stop`, which says
+* goodbye; the caller disposes the client.
+*/
+const followSetup = async (client, { print, agent, browser } = {}) => {
+	const write = print ?? ((events) => {
+		process.stdout.write(`${JSON.stringify(events)}\n`);
+	});
+	const page = (state) => browser && state.id !== null ? setupPageUrl(browser.setupAppUrl, browser.linkId, state.id) : void 0;
+	const gate = browser && createBrowserGate({
+		url: page,
+		...browser.canOpen !== void 0 && { canOpen: browser.canOpen },
+		...browser.now !== void 0 && { now: browser.now }
+	});
+	let previous = client.state;
+	if (previous === void 0) throw new Error("the setup has no state");
+	let pending = diffEvents({
+		...previous,
+		log: []
+	}, previous);
+	let timer;
+	const flush = () => {
+		clearTimeout(timer);
+		timer = void 0;
+		if (pending.length > 0) write(pending);
+		pending = [];
+	};
+	const runGate = (state) => {
+		for (const action of gate?.update(state) ?? []) {
+			if (action.type === "open") (browser.open ?? openUrl)(action.url);
+			pending.push(gateEvent(action, browser.answerCommand, page(state) ?? ""));
+		}
+	};
+	const unsubscribe = client.subscribe(() => {
+		const next = client.state;
+		if (next === void 0) return;
+		pending.push(...diffEvents(previous, next));
+		previous = next;
+		runGate(next);
+		if (pending.length > 0 && timer === void 0) timer = setTimeout(flush, 200);
+	});
+	runGate(previous);
+	flush();
+	const tick = gate && setInterval(() => {
+		runGate(previous);
+		flush();
+	}, 1e3);
+	const kind = agent?.kind ?? detectAgentKind();
+	try {
+		await client.commands["agent/hello"]({
+			cwd: agent?.cwd ?? process.cwd(),
+			...kind !== void 0 && { kind }
+		});
+	} catch (error) {
+		clearInterval(tick);
+		clearTimeout(timer);
+		unsubscribe();
+		throw error;
+	}
+	const heartbeat = setInterval(() => {
+		client.commands["agent/heartbeat"]().catch(() => {});
+	}, AGENT_HEARTBEAT_MS);
+	let stopped;
+	return { stop: () => stopped ??= (async () => {
+		clearInterval(heartbeat);
+		clearInterval(tick);
+		unsubscribe();
+		flush();
+		await client.commands["agent/bye"]().catch(() => {});
+	})() };
+};
+export { answerFields, diffEvents, followSetup, setupPageUrl, shellWord };
+
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","names":[],"sources":["../src/stream.ts"],"sourcesContent":["import spawn from \"cross-spawn\";\nimport { detectAgentKind } from \"./agents\";\nimport { createBrowserGate } from \"./browser\";\nimport type { AskReason, BrowserGateAction } from \"./browser\";\nimport type { CheckoutClient } from \"./client\";\nimport { formatTerminalQuestion, terminalQuestion } from \"./needs\";\nimport type { TerminalQuestion } from \"./needs\";\nimport {\n  AGENT_HEARTBEAT_MS,\n  classifyChoiceAnswer,\n  parseMultipleAnswer,\n} from \"./protocol\";\nimport type { Checkout } from \"./protocol\";\n\nexport type StreamEvent =\n  | { event: \"planning.started\" }\n  | { event: \"message.created\"; messageId: string; text: string }\n  | {\n      event: \"input.answered\";\n      inputId: string;\n      prompt: string;\n      /** The entries of a multiple choice answer, else the answer text. */\n      answer: string | string[];\n      note?: string;\n      /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */\n      custom?: true;\n    }\n  | { event: \"input.dismissed\"; inputId: string; prompt: string }\n  | { event: \"plan.approved\"; revision: number }\n  | { event: \"plan.changes-requested\"; revision: number; feedback: string }\n  | { event: \"finished\"; next: string }\n  | { event: \"cancelled\"; next: string }\n  | { event: \"setup.created\"; products: string[] }\n  | {\n      event: \"browser.opened\";\n      /** The need the tab opened for: an input id, plan or finish. */\n      id: string;\n      url: string;\n      message: string;\n    }\n  | ({\n      event: \"input.needed\";\n      id: string;\n      reason: AskReason;\n      message: string;\n      /** The command that answers it, with the answer's shape in angle brackets. */\n      answer: string;\n    } & TerminalQuestion);\n\nconst STAY_CONNECTED =\n  \"This setup is over, not your connection. Keep the stream running, tell the user you are connected and waiting for their next setup, and run wait start.\";\n\nexport const diffEvents = (\n  before: Checkout.State,\n  after: Checkout.State,\n): StreamEvent[] => {\n  const events: StreamEvent[] = [];\n  if (before.status === \"waiting\" && after.status === \"planning\") {\n    events.push({ event: \"planning.started\" });\n  }\n  for (const entry of after.log) {\n    if (\n      entry.role === \"user\" &&\n      entry.acknowledgedAt === undefined &&\n      !before.log.some((previous) => previous.id === entry.id)\n    ) {\n      events.push({\n        event: \"message.created\",\n        messageId: entry.id,\n        text: entry.text,\n      });\n    }\n  }\n  for (const input of after.inputs) {\n    const previous = before.inputs.find(\n      (candidate) => candidate.id === input.id,\n    );\n    if (previous?.status === input.status) continue;\n    if (input.status === \"answered\") {\n      const answer = input.answer ?? \"\";\n      events.push({\n        event: \"input.answered\",\n        inputId: input.id,\n        prompt: input.prompt,\n        ...answerFields(input, answer),\n      });\n    } else if (input.status === \"dismissed\" && after.status !== \"cancelled\") {\n      events.push({\n        event: \"input.dismissed\",\n        inputId: input.id,\n        prompt: input.prompt,\n      });\n    }\n  }\n  for (const plan of after.plans) {\n    const previous = before.plans.find(\n      (candidate) => candidate.revision === plan.revision,\n    );\n    if (previous?.status === plan.status || plan.status === \"proposed\") {\n      continue;\n    }\n    if (plan.status === \"approved\") {\n      events.push({ event: \"plan.approved\", revision: plan.revision });\n    } else {\n      events.push({\n        event: \"plan.changes-requested\",\n        revision: plan.revision,\n        feedback: plan.feedback ?? \"\",\n      });\n    }\n  }\n  if (before.status !== \"done\" && after.status === \"done\") {\n    events.push({ event: \"finished\", next: STAY_CONNECTED });\n  }\n  if (before.status !== \"cancelled\" && after.status === \"cancelled\") {\n    events.push({ event: \"cancelled\", next: STAY_CONNECTED });\n  }\n  if (after.id !== null && after.id !== before.id) {\n    events.push({\n      event: \"setup.created\",\n      products: after.products.map((product) => product.slug),\n    });\n  }\n  return events;\n};\n\nexport const answerFields = (input: Checkout.Input, answer: string) => ({\n  answer: (input.multiple && parseMultipleAnswer(answer)) || answer,\n  ...(input.note !== undefined && { note: input.note }),\n  ...(input.kind === \"choice\" &&\n    classifyChoiceAnswer(input, answer) === \"custom\" && {\n      custom: true as const,\n    }),\n});\n\n/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */\nexport const setupPageUrl = (\n  setupAppUrl: string,\n  linkId: string,\n  setupId: string,\n) => `${setupAppUrl.replace(/\\/$/, \"\")}/#link=${linkId}&setup=${setupId}`;\n\n/**\n * Opens `url` in the user's default browser without waiting for it.\n * `SETUP_AGENT_BROWSER` names another program to run with the URL instead,\n * such as a test driver.\n */\nconst openUrl = (url: string) => {\n  const custom = process.env.SETUP_AGENT_BROWSER?.trim();\n  const [command, args] = custom\n    ? [custom, [url]]\n    : process.platform === \"darwin\"\n      ? [\"open\", [url]]\n      : process.platform === \"win32\"\n        ? [\"rundll32\", [\"url.dll,FileProtocolHandler\", url]]\n        : [\"xdg-open\", [url]];\n  const child = spawn(command, args, { detached: true, stdio: \"ignore\" });\n  child.on(\"error\", () => {});\n  child.unref();\n};\n\n/** `value` as one shell word, quoted only when it holds more than plain URL characters. */\nexport const shellWord = (value: string) =>\n  /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value)\n    ? value\n    : `'${value.replaceAll(\"'\", `'\\\\''`)}'`;\n\nconst ASK_MESSAGES: Record<\n  AskReason,\n  (question: string, context: { agoSeconds: number; page: string }) => string\n> = {\n  \"recently-opened\": (question, { agoSeconds }) =>\n    `A browser tab for setup was opened ${agoSeconds}s ago. Wait for the user there, or ask the user directly in the terminal: ${question}`,\n  \"browser-closed\": (question) =>\n    `The user closed the setup tab. Ask the user directly in the terminal: ${question}`,\n  \"no-browser\": (question, { page }) =>\n    `No browser tab is open for this setup. Ask the user directly in the terminal, or give them ${page}: ${question}`,\n};\n\n/** What the agent reads when setup opened the browser, or when it should ask the user itself. */\nconst gateEvent = (\n  action: BrowserGateAction,\n  answerCommand: string,\n  page: string,\n): StreamEvent => {\n  const { need } = action;\n  if (action.type === \"open\")\n    return {\n      event: \"browser.opened\",\n      id: need.id,\n      url: action.url,\n      message: `Opened the setup in the user's browser for ${need.kind === \"input\" ? `\"${need.input.prompt.trim() || \"Your agent needs an answer.\"}\"` : need.kind === \"plan\" ? \"the plan review\" : \"closing the setup\"}. Tell the user once that it is waiting there, and give them ${action.url} in case it did not open. The answer arrives on this stream.`,\n    };\n  const question = terminalQuestion(need);\n  return {\n    event: \"input.needed\",\n    id: need.id,\n    reason: action.reason,\n    message: ASK_MESSAGES[action.reason](formatTerminalQuestion(question), {\n      agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1000),\n      page,\n    }),\n    ...question,\n    answer: `${answerCommand} ${need.id} <${question.answerFormat}>`,\n  };\n};\n\nexport type FollowSetupOptions = {\n  /** Writes one line of events; the default prints a JSON array to stdout. */\n  print?: (events: StreamEvent[]) => void;\n  /** The agent the stream reports in its hello; detected by default. */\n  agent?: { cwd?: string; kind?: string };\n  /** Opens the setup page when the setup waits on the user; without it, the stream never opens one. */\n  browser?: {\n    setupAppUrl: string;\n    linkId: string;\n    /** The command that answers a need, before the need id: `npx assistant-ui@latest setup <url> answer`. */\n    answerCommand: string;\n    open?: (url: string) => void;\n    /** False for `--no-open`: the agent is told to ask instead. */\n    canOpen?: boolean;\n    now?: () => number;\n  };\n};\n\n/**\n * Follows a setup as the agent: says hello, keeps the agent present with\n * heartbeats, prints what changed as stream events, and opens the browser\n * only when the setup waits on the user. Resolves with `stop`, which says\n * goodbye; the caller disposes the client.\n */\nexport const followSetup = async (\n  client: Pick<CheckoutClient, \"state\" | \"subscribe\" | \"commands\">,\n  { print, agent, browser }: FollowSetupOptions = {},\n) => {\n  const write =\n    print ??\n    ((events: StreamEvent[]) => {\n      process.stdout.write(`${JSON.stringify(events)}\\n`);\n    });\n  const page = (state: Checkout.State) =>\n    browser && state.id !== null\n      ? setupPageUrl(browser.setupAppUrl, browser.linkId, state.id)\n      : undefined;\n  const gate =\n    browser &&\n    createBrowserGate({\n      url: page,\n      ...(browser.canOpen !== undefined && { canOpen: browser.canOpen }),\n      ...(browser.now !== undefined && { now: browser.now }),\n    });\n  let previous = client.state;\n  if (previous === undefined) throw new Error(\"the setup has no state\");\n  let pending = diffEvents({ ...previous, log: [] }, previous);\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const flush = () => {\n    clearTimeout(timer);\n    timer = undefined;\n    if (pending.length > 0) write(pending);\n    pending = [];\n  };\n  const runGate = (state: Checkout.State) => {\n    for (const action of gate?.update(state) ?? []) {\n      if (action.type === \"open\") (browser!.open ?? openUrl)(action.url);\n      pending.push(\n        gateEvent(action, browser!.answerCommand, page(state) ?? \"\"),\n      );\n    }\n  };\n  const unsubscribe = client.subscribe(() => {\n    const next = client.state;\n    if (next === undefined) return;\n    pending.push(...diffEvents(previous!, next));\n    previous = next;\n    runGate(next);\n    if (pending.length > 0 && timer === undefined)\n      timer = setTimeout(flush, 200);\n  });\n  runGate(previous);\n  flush();\n  // Presence lapses without a state change, so the gate also looks every second.\n  const tick =\n    gate &&\n    setInterval(() => {\n      runGate(previous!);\n      flush();\n    }, 1_000);\n  const kind = agent?.kind ?? detectAgentKind();\n  try {\n    await client.commands[\"agent/hello\"]({\n      cwd: agent?.cwd ?? process.cwd(),\n      ...(kind !== undefined && { kind }),\n    });\n  } catch (error) {\n    clearInterval(tick);\n    clearTimeout(timer);\n    unsubscribe();\n    throw error;\n  }\n  const heartbeat = setInterval(() => {\n    void client.commands[\"agent/heartbeat\"]().catch(() => {});\n  }, AGENT_HEARTBEAT_MS);\n  let stopped: Promise<void> | undefined;\n  return {\n    stop: () =>\n      (stopped ??= (async () => {\n        clearInterval(heartbeat);\n        clearInterval(tick);\n        unsubscribe();\n        flush();\n        await client.commands[\"agent/bye\"]().catch(() => {});\n      })()),\n  };\n};\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "setup-agent",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "A live setup shared between a browser and the coding agent installing the products in it, on Statewire",
   "license": "MIT",
   "homepage": "https://www.assistant-ui.com/",
@@ -25,6 +25,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "default": "./dist/sdk.js"
+    },
     "./host": {
       "types": "./dist/host.d.ts",
       "default": "./dist/host.js"
@@ -43,11 +47,21 @@
     "README.md"
   ],
   "dependencies": {
-    "@assistant-ui/tap": "^0.9.25",
+    "cross-spawn": "^7.0.6",
     "statewire": "^0.22.1"
   },
+  "peerDependencies": {
+    "@assistant-ui/tap": "^0.9.25"
+  },
+  "peerDependenciesMeta": {
+    "@assistant-ui/tap": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@assistant-ui/tap": "0.9.25",
     "@assistant-ui/x-buildutils": "0.0.32",
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "react": "^19.3.1",

package/src/agents.test.ts

@@ -0,0 +1,137 @@
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, onTestFinished } from "vitest";
+import {
+  CODING_AGENTS,
+  detectAgentKind,
+  findCommand,
+  isDirectInvocation,
+  runCodingAgent,
+} from "./agents";
+
+describe("CODING_AGENTS", () => {
+  it("lists the twenty most used coding agents once each", () => {
+    expect(CODING_AGENTS).toHaveLength(20);
+    const kinds = CODING_AGENTS.map((agent) => agent.kind);
+    expect(new Set(kinds).size).toBe(kinds.length);
+    expect(kinds.slice(0, 4)).toEqual(["claude", "codex", "cursor", "gemini"]);
+  });
+
+  it("starts an agent with the prompt as its first message", () => {
+    const byKind = Object.fromEntries(
+      CODING_AGENTS.map((agent) => [agent.kind, agent]),
+    );
+    expect(byKind.claude!.launch!.args("go")).toEqual(["go"]);
+    expect(byKind.gemini!.launch!.args("go")).toEqual(["-i", "go"]);
+    expect(byKind.opencode!.launch!.args("go")).toEqual(["--prompt", "go"]);
+    expect(byKind.windsurf!.launch).toBeUndefined();
+  });
+});
+
+describe("detectAgentKind", () => {
+  it("reads the agent from AI_AGENT first", () => {
+    expect(detectAgentKind({ AI_AGENT: "claude-code_2-1-3_agent" })).toBe(
+      "claude",
+    );
+    expect(detectAgentKind({ AI_AGENT: "github-copilot" })).toBe("copilot");
+    expect(detectAgentKind({ AI_AGENT: "some-new-agent" })).toBe("other");
+    expect(detectAgentKind({ AI_AGENT: " " })).toBeUndefined();
+    expect(detectAgentKind({ AI_AGENT: "claudette" })).toBe("other");
+    expect(detectAgentKind({ AI_AGENT: "codex" })).toBe("codex");
+    expect(
+      detectAgentKind({
+        AI_AGENT: "claude-code_2-1-3_agent",
+        CODEX_THREAD_ID: "t",
+      }),
+    ).toBe("claude");
+  });
+
+  it("reads the variables each agent exports to its shell", () => {
+    expect(detectAgentKind({ CODEX_THREAD_ID: "t" })).toBe("codex");
+    expect(detectAgentKind({ QWEN_CODE: "1" })).toBe("qwen");
+    expect(detectAgentKind({ OPENCODE_CLIENT: "cli" })).toBe("opencode");
+    expect(detectAgentKind({ AUGMENT_AGENT: "1" })).toBe("augment");
+  });
+
+  it("treats a person at a terminal inside an editor, or with Goose configured, as no agent", () => {
+    expect(detectAgentKind({ GOOSE_PROVIDER: "openai" })).toBeUndefined();
+    expect(
+      detectAgentKind({ CURSOR_TRACE_ID: "x", TERM_PROGRAM: "vscode" }),
+    ).toBe(undefined);
+    expect(
+      isDirectInvocation(
+        { CURSOR_TRACE_ID: "x" },
+        { isTTY: true },
+        { isTTY: true },
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("findCommand and runCodingAgent", () => {
+  const binDirectory = async () => {
+    const directory = await mkdtemp(join(tmpdir(), "setup-agent-bin-"));
+    onTestFinished(() => rm(directory, { recursive: true, force: true }));
+    const script = join(directory, "fake-agent");
+    await writeFile(
+      script,
+      '#!/bin/sh\n[ "$1" = "-i" ] && [ "$2" = "hello" ] && exit 7\nexit 1\n',
+    );
+    await chmod(script, 0o755);
+    const second = join(directory, "other-agent");
+    await writeFile(second, "#!/bin/sh\nexit 0\n");
+    await chmod(second, 0o755);
+    return directory;
+  };
+
+  it.skipIf(process.platform === "win32")(
+    "finds the first installed command and runs it with the prompt",
+    async () => {
+      const directory = await binDirectory();
+      const path = process.env.PATH;
+      process.env.PATH = `${directory}:${path}`;
+      onTestFinished(() => {
+        process.env.PATH = path;
+      });
+      expect(findCommand(["missing-agent", "fake-agent"])).toBe("fake-agent");
+      expect(findCommand(["other-agent", "fake-agent"])).toBe("other-agent");
+      expect(findCommand(["fake-agent", "other-agent"])).toBe("fake-agent");
+      expect(findCommand(["fake-agent"], { PATH: "" })).toBeUndefined();
+      expect(findCommand(["missing-agent"])).toBeUndefined();
+      const code = await runCodingAgent(
+        {
+          kind: "fake",
+          name: "Fake",
+          launch: {
+            commands: ["fake-agent"],
+            args: (prompt) => ["-i", prompt],
+            install: "",
+          },
+        },
+        "hello",
+      );
+      expect(code).toBe(7);
+    },
+  );
+
+  it("reports an agent it cannot start as not installed", async () => {
+    expect(
+      await runCodingAgent(
+        {
+          kind: "fake",
+          name: "Fake",
+          launch: {
+            commands: ["no-such-agent-xyz"],
+            args: () => [],
+            install: "",
+          },
+        },
+        "hello",
+      ),
+    ).toBeUndefined();
+    expect(await runCodingAgent({ kind: "zed", name: "Zed" }, "hi")).toBe(
+      undefined,
+    );
+  });
+});