agentic-browser 1.6.1 → 2.0.0

package/README.md

@@ -111,8 +111,8 @@ agentic-browser agent start --user-profile default
 agentic-browser agent start --headless
 agentic-browser agent start --user-agent "MyBot/1.0"
 agentic-browser agent status
-agentic-browser agent run navigate '{"url":"https://example.com"}'
-agentic-browser agent run interact '{"action":"click","selector":"#login"}'
+agentic-browser agent navigate https://example.com
+agentic-browser agent click "#login"
 agentic-browser agent content --mode text
 agentic-browser agent content --mode html --selector main
 agentic-browser agent elements
@@ -132,7 +132,7 @@ agentic-browser agent elements --roles button,link,input --visible-only --limit
 agentic-browser agent elements --selector "#main-content"
 ```
 
-Returns a JSON array of elements with CSS selectors and fallback selectors usable in `agent run interact`:
+Returns a JSON array of elements with CSS selectors and fallback selectors usable in the typed agent commands like `agent click`, `agent type`, and `agent select`:
 
 ```json
 {
@@ -255,7 +255,7 @@ agentic-browser memory:stats
 
 1. `agent start` — launch Chrome and persist session.
 2. `agent elements` — discover what's on the page.
-3. `agent run navigate/interact` — execute actions using discovered selectors.
+3. `agent navigate`, `agent click`, `agent type`, `agent select`, and related typed commands — execute actions using discovered selectors.
 4. `agent content` — read page content after actions.
 5. `agent memory-search` — reuse known selectors for repeated tasks.
 6. `agent stop` — terminate when done.
@@ -265,7 +265,7 @@ agentic-browser memory:stats
 - Exactly **one** managed session is supported at a time.
 - Session state is persisted in `.agentic-browser/`.
 - All commands print exactly one JSON line to `stdout`.
-- `payloadJson` must be valid JSON.
+- The typed `agent` commands are the preferred interface for LLMs. Use low-level `command:run` only when you need raw JSON payload control.
 - Parse only `stdout` as result object and use exit code for success/failure.
 
 ## Programmatic API

package/dist/cli/index.mjs

@@ -64,7 +64,7 @@ async function agentStop(runtime) {
 		sessionId
 	};
 }
-async function agentRun(runtime, input) {
+async function executeAgentCommand(runtime, input) {
 	const sessionId = requireSessionId(runtime);
 	await ensureReady(runtime, sessionId);
 	const attempt = () => runtime.api.executeCommand(sessionId, {
@@ -75,22 +75,75 @@ async function agentRun(runtime, input) {
 	try {
 		const first = await attempt();
 		if (first.resultStatus === "failed") throw new Error(first.resultMessage ?? "Command failed");
-		return {
-			ok: true,
-			action: "run",
-			...first
-		};
+		return first;
 	} catch {
 		await runtime.api.restartSession(sessionId);
 		const second = await attempt();
 		if (second.resultStatus === "failed") throw new Error(second.resultMessage ?? "Command failed after retry");
-		return {
-			ok: true,
-			action: "run",
-			...second
-		};
+		return second;
 	}
 }
+async function agentNavigate(runtime, input) {
+	const result = await executeAgentCommand(runtime, {
+		type: "navigate",
+		payload: { url: input.url }
+	});
+	let cookieBanner;
+	if (result.resultStatus === "success") try {
+		const sessionId = requireSessionId(runtime);
+		const dismissed = await runtime.api.dismissCookieBanner(sessionId);
+		if (dismissed.dismissed) cookieBanner = dismissed;
+	} catch {}
+	return {
+		ok: true,
+		action: "navigate",
+		...result,
+		cookieBanner
+	};
+}
+async function agentInteract(runtime, input) {
+	const result = await executeAgentCommand(runtime, {
+		type: "interact",
+		payload: input
+	});
+	return {
+		ok: true,
+		action: input.action,
+		...result
+	};
+}
+async function agentRestart(runtime) {
+	return {
+		ok: true,
+		action: "restart",
+		...await executeAgentCommand(runtime, {
+			type: "restart",
+			payload: {}
+		})
+	};
+}
+async function agentTerminate(runtime) {
+	const result = await executeAgentCommand(runtime, {
+		type: "terminate",
+		payload: {}
+	});
+	saveState(runtime, { sessionId: null });
+	return {
+		ok: true,
+		action: "terminate",
+		...result
+	};
+}
+async function agentDismissCookies(runtime) {
+	const sessionId = requireSessionId(runtime);
+	await ensureReady(runtime, sessionId);
+	return {
+		ok: true,
+		action: "cookies",
+		sessionId,
+		...await runtime.api.dismissCookieBanner(sessionId)
+	};
+}
 async function agentContent(runtime, input) {
 	const sessionId = requireSessionId(runtime);
 	await ensureReady(runtime, sessionId);
@@ -243,6 +296,7 @@ async function main() {
 	const runtime = createCliRuntime();
 	const program = new Command();
 	program.name("agentic-browser").description("Agentic browser CLI");
+	const collect = (value, previous = []) => [...previous, value];
 	program.command("session:start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").option("--headless", "run Chrome in headless mode (no visible window)").option("--user-agent <string>", "override the browser user-agent string").action(async (options) => {
 		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
 		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
@@ -328,13 +382,109 @@ async function main() {
 		const result = await agentStop(runtime);
 		console.log(JSON.stringify(result));
 	});
-	agent.command("run").argument("<type>", "navigate|interact|restart|terminate").argument("<payloadJson>", "JSON payload").action(async (type, payloadJson) => {
-		const result = await agentRun(runtime, {
-			type,
-			payload: JSON.parse(payloadJson)
+	agent.command("navigate").argument("<url>").action(async (url) => {
+		const result = await agentNavigate(runtime, { url });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("click").argument("<selector>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "click",
+			selector,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("type").argument("<selector>").argument("<text>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, text, options) => {
+		const result = await agentInteract(runtime, {
+			action: "type",
+			selector,
+			text,
+			fallbackSelectors: options.fallback
 		});
 		console.log(JSON.stringify(result));
 	});
+	agent.command("press").argument("<key>").action(async (key) => {
+		const result = await agentInteract(runtime, {
+			action: "press",
+			key
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("wait").argument("<selector>").option("--timeout <ms>", "timeout in milliseconds", "2000").action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "waitFor",
+			selector,
+			timeoutMs: Number.parseInt(options.timeout, 10)
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("hover").argument("<selector>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "hover",
+			selector,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("select").argument("<selector>").argument("<value>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, value, options) => {
+		const result = await agentInteract(runtime, {
+			action: "select",
+			selector,
+			value,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("toggle").argument("<selector>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "toggle",
+			selector,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("scroll").option("--x <pixels>", "horizontal scroll delta", "0").option("--y <pixels>", "vertical scroll delta", "0").option("--selector <selector>", "scroll a specific element instead of the page").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (options) => {
+		const result = await agentInteract(runtime, {
+			action: "scroll",
+			selector: options.selector,
+			fallbackSelectors: options.fallback,
+			scrollX: Number.parseInt(options.x, 10),
+			scrollY: Number.parseInt(options.y, 10)
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("back").action(async () => {
+		const result = await agentInteract(runtime, { action: "goBack" });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("forward").action(async () => {
+		const result = await agentInteract(runtime, { action: "goForward" });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("refresh").action(async () => {
+		const result = await agentInteract(runtime, { action: "refresh" });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("dialog").option("--dismiss", "dismiss the current dialog").option("--value <text>", "prompt response text").action(async (options) => {
+		const result = await agentInteract(runtime, {
+			action: "dialog",
+			text: options.dismiss ? "dismiss" : void 0,
+			value: options.value
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("cookies").action(async () => {
+		const result = await agentDismissCookies(runtime);
+		console.log(JSON.stringify(result));
+	});
+	agent.command("restart").action(async () => {
+		const result = await agentRestart(runtime);
+		console.log(JSON.stringify(result));
+	});
+	agent.command("terminate").action(async () => {
+		const result = await agentTerminate(runtime);
+		console.log(JSON.stringify(result));
+	});
 	agent.command("content").option("--mode <mode>", "title|text|html|a11y", "text").option("--selector <selector>", "optional CSS selector").action(async (options) => {
 		const result = await agentContent(runtime, options);
 		console.log(JSON.stringify(result));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-browser",
-  "version": "1.6.1",
+  "version": "2.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",