@vibecodr/cli 1.0.13 → 1.0.15

package/dist/legacy/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/legacy/cli/run.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA+CtD,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAoED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CzF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/legacy/cli/run.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgDtD,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAoED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CzF"}

package/dist/legacy/cli/run.js

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { ConfigStore, DEFAULT_API_URL, resolveConfigDir } from "../config/store.js";
@@ -18,6 +19,7 @@ const DEFAULT_AUTH_API_URL = "https://api.vibecodr.space";
 const GRANT_REFRESH_SKEW_SECONDS = 60;
 const ARTIFACT_OUTPUT_WORKSPACE_MESSAGE = "Artifact output is workspace-bounded so downloaded bytes can only be written to files you intentionally target inside this workspace. Use --local for ./vibecodr-proof, --out ./artifacts, --out ./artifacts/report.pdf, or cd to the intended workspace and use --out .";
 const ARTIFACT_INPUT_WORKSPACE_MESSAGE = "Artifact upload sources are workspace-bounded so the CLI only reads files you intentionally target inside this workspace. Move the file into this workspace, or cd to the workspace that contains it.";
+const WORKSPACE_SCRATCH_PROOF_DIR = ".vibecodr/browser-artifacts";
 export async function runCli(argv, options = {}) {
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
@@ -190,11 +192,19 @@ async function commandTry(context, parsed) {
     const { profile } = await context.store.getProfile(context.globals.profile);
     const client = createClient(context, profile, await resolveToken(context, true));
     const proofDir = getStringFlag(parsed.flags, "out") ?? "vibecodr-proof";
+    const proofOutput = await prepareAutoProofOutput(context, {
+        positionals: [],
+        flags: {
+            ...parsed.flags,
+            out: proofDir
+        }
+    });
+    const resolvedProofDir = getStringFlag(proofOutput.parsed.flags, "out") ?? proofDir;
     const browserParsed = {
         positionals: ["https://example.com"],
         flags: {
             ...parsed.flags,
-            out: proofDir,
+            out: resolvedProofDir,
             filename: "browser-read.md",
             pollIntervalMs: getStringFlag(parsed.flags, "pollIntervalMs") ?? "250"
         }
@@ -204,7 +214,7 @@ async function commandTry(context, parsed) {
         flags: {
             ...parsed.flags,
             command: "node -e \"console.log('vibecodr computer ok')\"",
-            out: proofDir,
+            out: resolvedProofDir,
             filename: "computer-run.json",
             pollIntervalMs: getStringFlag(parsed.flags, "pollIntervalMs") ?? "250"
         }
@@ -217,7 +227,7 @@ async function commandTry(context, parsed) {
         proof: "failed",
         usage: "failed"
     };
-    const warnings = [];
+    const warnings = [...proofOutput.warnings];
     const browserPayload = buildToolTestPayload("browser.extract_markdown", browserParsed.positionals[0], browserParsed);
     const browserWork = await client.request("POST", "tools/test", { body: browserPayload });
     const browserResult = await followSubmittedWork(context, client, "browser.extract_markdown", browserWork, browserParsed);
@@ -253,12 +263,12 @@ async function commandTry(context, parsed) {
     const ready = Object.values(checks).every((status) => status === "ok");
     return {
         message: ready
-            ? `Vibecodr Agent Computer check passed.\nProof saved: ${path.resolve(context.cwd, proofDir)}`
-            : `Vibecodr Agent Computer check finished with attention needed.\nProof path: ${path.resolve(context.cwd, proofDir)}`,
+            ? `Vibecodr Agent Computer check passed.\nProof saved: ${path.resolve(context.cwd, resolvedProofDir)}`
+            : `Vibecodr Agent Computer check finished with attention needed.\nProof path: ${path.resolve(context.cwd, resolvedProofDir)}`,
         data: {
             ready,
             checks,
-            proofPath: path.resolve(context.cwd, proofDir)
+            proofPath: path.resolve(context.cwd, resolvedProofDir)
         },
         warnings,
         humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
@@ -650,12 +660,145 @@ async function commandBrowser(context, subcommand, rest) {
             const normalized = normalizeBrowserSnapshotOptions(parsed);
             return submitHostedCapability(context, "browser.snapshot", normalized, "Captured a hosted Browser snapshot.", { autoFollow: true });
         }
+        case "notes":
         case "ask": {
-            const normalized = normalizeBrowserAskOptions(parsed);
-            return submitHostedCapability(context, "browser.ask", normalized, "Captured a hosted Browser snapshot with your note attached.", { autoFollow: true });
+            const normalized = normalizeBrowserNotesOptions(parsed);
+            return submitHostedCapability(context, "browser.notes", normalized, "Captured a hosted Browser snapshot with your note attached.", { autoFollow: true });
+        }
+        case "session":
+            return commandBrowserSession(context, rest[0], rest.slice(1));
+        default:
+            throw unknownSubcommandError("browser", subcommand, ["render", "screenshot", "read", "markdown", "pdf", "crawl", "snapshot", "notes", "session"], "Use vibecodr browser screenshot <https-url>, browser read <https-url>, browser snapshot <https-url> --local, or browser session open <https-url>.");
+    }
+}
+async function commandBrowserSession(context, subcommand, rest) {
+    const parsed = parseCommandOptions(rest);
+    const { profile } = await context.store.getProfile(context.globals.profile);
+    const client = createClient(context, profile, await resolveToken(context, true));
+    switch (subcommand) {
+        case "open": {
+            const target = parsed.positionals[0];
+            if (!target) {
+                throw new CliError("input.url_required", "browser session open requires an HTTPS URL target.", 2);
+            }
+            const body = { url: validateBrowserUrl(target) };
+            const timeoutMs = validatePositiveInt(getStringFlag(parsed.flags, "timeoutMs"), "--timeout-ms", 1000, 3_600_000);
+            const idleTimeoutMs = validatePositiveInt(getStringFlag(parsed.flags, "idleTimeoutMs"), "--idle-timeout-ms", 1000, 600_000);
+            if (timeoutMs !== undefined)
+                body.timeoutMs = timeoutMs;
+            if (idleTimeoutMs !== undefined)
+                body.idleTimeoutMs = idleTimeoutMs;
+            const response = await client.request("POST", "browser/sessions", { body });
+            return {
+                message: browserSessionMessage(response, "Opened Agent Browser session."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "observe": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("GET", `browser/sessions/${encodePathSegment(sessionId)}`);
+            return {
+                message: browserSessionMessage(response, "Observed Agent Browser session."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "goto":
+        case "navigate":
+        case "click":
+        case "type":
+        case "scroll":
+        case "wait": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const body = browserSessionActionBody(subcommand, parsed);
+            const response = await client.request("POST", `browser/sessions/${encodePathSegment(sessionId)}/actions`, { body });
+            return {
+                message: browserSessionMessage(response, `Ran Agent Browser ${subcommand}.`),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "auth":
+        case "auth-request": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("POST", `browser/sessions/${encodePathSegment(sessionId)}/auth${browserSessionLiveViewQuery(parsed, context.globals.debug)}`);
+            const handoffUrl = browserSessionHandoffUrlFromResponse(response);
+            const skipOpen = getBooleanFlag(parsed.flags, "noOpen") ||
+                parsed.flags.open === false ||
+                context.globals.json ||
+                context.globals.quiet ||
+                context.globals.noInput;
+            let opened = false;
+            if (handoffUrl && !skipOpen) {
+                opened = await maybeOpenBrowser(context, parsed, handoffUrl);
+            }
+            return {
+                message: browserSessionMessage(response, opened ? "Opened Agent Browser for you to control." : "Agent Browser control link ready."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "live":
+        case "watch":
+        case "view": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("POST", `browser/sessions/${encodePathSegment(sessionId)}/live${browserSessionLiveViewQuery(parsed, context.globals.debug)}`);
+            const handoffUrl = browserSessionHandoffUrlFromResponse(response);
+            const skipOpen = getBooleanFlag(parsed.flags, "noOpen") ||
+                parsed.flags.open === false ||
+                context.globals.json ||
+                context.globals.quiet ||
+                context.globals.noInput;
+            let opened = false;
+            if (handoffUrl && !skipOpen) {
+                opened = await maybeOpenBrowser(context, parsed, handoffUrl);
+            }
+            return {
+                message: browserSessionMessage(response, opened ? "Opened Agent Browser live view." : "Agent Browser live view ready."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "auth-status": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("GET", `browser/sessions/${encodePathSegment(sessionId)}/auth`);
+            return {
+                message: browserSessionMessage(response, "Read Agent Browser live-control status."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "auth-complete":
+        case "auth-done": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("POST", `browser/sessions/${encodePathSegment(sessionId)}/auth/complete`);
+            return {
+                message: browserSessionMessage(response, "Gave Agent Browser control back to the agent."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "auth-revoke": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("POST", `browser/sessions/${encodePathSegment(sessionId)}/auth/revoke`);
+            return {
+                message: browserSessionMessage(response, "Ended Agent Browser live link."),
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
+        }
+        case "close": {
+            const sessionId = validateBrowserSessionId(parsed.positionals[0]);
+            const response = await client.request("DELETE", `browser/sessions/${encodePathSegment(sessionId)}`);
+            return {
+                message: "Closed Agent Browser session.",
+                data: response,
+                humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
+            };
         }
         default:
-            throw unknownSubcommandError("browser", subcommand, ["render", "screenshot", "read", "markdown", "pdf", "crawl", "snapshot", "ask"], "Use vibecodr browser screenshot <https-url>, browser read <https-url>, or browser snapshot <https-url> --local.");
+            throw unknownSubcommandError("browser session", subcommand, ["open", "observe", "goto", "click", "type", "scroll", "wait", "live", "auth", "auth-status", "auth-complete", "auth-revoke", "close"], "Use vibecodr browser session open <https-url>, live <sessionId>, observe <sessionId>, click <sessionId> --selector <css>, or close <sessionId>.");
     }
 }
 async function commandComputer(context, subcommand, rest) {
@@ -735,13 +878,16 @@ async function submitHostedCapability(context, capabilityInput, parsed, successM
         throw new CliError("input.local_requires_wait", "--local saves the completed output, so it cannot be combined with --no-wait.", 2);
     }
     const payload = buildToolTestPayload(capability, parsed.positionals[0], parsed, context.globals.timeoutMs === 30_000 ? undefined : context.globals.timeoutMs);
+    const proofOutput = options.autoFollow === true && !shouldSkipWait(parsed)
+        ? await prepareAutoProofOutput(context, parsed)
+        : { parsed, warnings: [] };
     const { profile } = await context.store.getProfile(context.globals.profile);
     const client = createClient(context, profile, await resolveToken(context, true));
     const response = await client.request("POST", "tools/test", {
         body: payload
     });
     if (options.autoFollow === true && !shouldSkipWait(parsed)) {
-        return followSubmittedWork(context, client, capability, response, parsed);
+        return followSubmittedWork(context, client, capability, response, proofOutput.parsed, proofOutput.warnings);
     }
     return {
         message: successMessage ?? (capability === "usage.read" ? "Read usage and limits from hosted Vibecodr." : `Submitted ${capability} test to hosted Vibecodr.`),
@@ -751,12 +897,13 @@ async function submitHostedCapability(context, capabilityInput, parsed, successM
 function shouldSkipWait(parsed) {
     return getBooleanFlag(parsed.flags, "noWait") || parsed.flags.wait === false;
 }
-async function followSubmittedWork(context, client, capability, submitted, parsed) {
+async function followSubmittedWork(context, client, capability, submitted, parsed, warnings = []) {
     const jobId = jobIdFromWork(submitted);
     if (!jobId) {
         return {
             message: completedCapabilityMessage(capability),
             data: publicWorkResult(capability, submitted, parsed),
+            warnings,
             humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
         };
     }
@@ -770,21 +917,24 @@ async function followSubmittedWork(context, client, capability, submitted, parse
     return {
         message: formatCompletedWorkMessage(capability, terminal, proof),
         data: publicWorkResult(capability, terminal, parsed, proof),
+        warnings,
         humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
     };
 }
 async function commandWorkFollow(context, parsed) {
     const jobId = validateEntityId(requiredPositional(parsed, 0, "work follow requires a job id."), "job id");
+    const proofOutput = await prepareAutoProofOutput(context, parsed);
     const { profile } = await context.store.getProfile(context.globals.profile);
     const client = createClient(context, profile, await resolveToken(context, true));
-    const job = await pollWorkUntilTerminal(client, jobId, parsed);
+    const job = await pollWorkUntilTerminal(client, jobId, proofOutput.parsed);
     const artifactId = artifactIdFromWork(job);
-    const proof = artifactId && shouldSaveArtifact(parsed)
-        ? await saveArtifact(context, client, artifactId, parsedWithLocalOutput(parsed))
+    const proof = artifactId && shouldSaveArtifact(proofOutput.parsed)
+        ? await saveArtifact(context, client, artifactId, proofOutput.parsed)
         : undefined;
     return {
         message: formatCompletedWorkMessage(undefined, job, proof),
-        data: publicWorkResult(undefined, job, parsed, proof),
+        data: publicWorkResult(undefined, job, proofOutput.parsed, proof),
+        warnings: proofOutput.warnings,
         humanData: getBooleanFlag(parsed.flags, "details") ? "show" : "hide"
     };
 }
@@ -880,6 +1030,60 @@ function parsedWithLocalOutput(parsed) {
         }
     };
 }
+async function prepareAutoProofOutput(context, parsed) {
+    if (!shouldSaveArtifact(parsed)) {
+        return { parsed, warnings: [] };
+    }
+    const withLocalOutput = parsedWithLocalOutput(parsed);
+    const out = getStringFlag(withLocalOutput.flags, "out") ?? ".";
+    const outPath = path.resolve(context.cwd, out);
+    try {
+        await ensureOutputPathAllowed(context.cwd, outPath);
+        return { parsed: withLocalOutput, warnings: [] };
+    }
+    catch (error) {
+        const cliError = toCliError(error);
+        if (cliError.code !== "file.outside_workspace" || !isPathOutside(path.resolve(context.cwd), outPath)) {
+            throw error;
+        }
+    }
+    const fallbackOut = await allocateScratchProofOutputDir(context.cwd);
+    return {
+        parsed: {
+            ...withLocalOutput,
+            flags: {
+                ...withLocalOutput.flags,
+                out: fallbackOut
+            }
+        },
+        warnings: [
+            `Output path is outside this workspace, so hosted artifacts cannot be written there. Writing to ${formatCliPath(fallbackOut)} instead. This scratch folder is gitignored; use --out ./path-inside-workspace to choose another workspace path.`
+        ]
+    };
+}
+async function allocateScratchProofOutputDir(cwd) {
+    const root = path.join(cwd, WORKSPACE_SCRATCH_PROOF_DIR);
+    await fs.mkdir(root, { recursive: true });
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const relative = `${WORKSPACE_SCRATCH_PROOF_DIR}/${timestamp}-${randomUUID().slice(0, 8)}`;
+        const absolute = path.resolve(cwd, relative);
+        try {
+            await fs.mkdir(absolute, { recursive: false });
+            return relative;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    throw new CliError("file.scratch_output_failed", "Could not create a workspace scratch output directory for hosted artifacts.", 5);
+}
+function formatCliPath(input) {
+    const normalized = input.split(path.sep).join("/");
+    return normalized.startsWith("./") || normalized.startsWith("../") ? normalized : `./${normalized}`;
+}
 function formatCompletedWorkMessage(capability, work, proof) {
     const status = workStatus(work) ?? "completed";
     if (status === "completed") {
@@ -999,14 +1203,14 @@ function userToolName(capability) {
 function normalizeBrowserSnapshotOptions(parsed) {
     const [url, ...extraParts] = parsed.positionals;
     if (extraParts.length > 0 || parsed.flags.instructions !== undefined || parsed.flags.note !== undefined) {
-        throw new CliError("input.snapshot_is_not_prompted", "browser snapshot captures the page state; it does not prompt an agent or model. Remove the note/instructions, or use `vibecodr browser ask <url> --note \"...\"` for the advanced compatibility lane.", 2);
+        throw new CliError("input.snapshot_is_not_prompted", "browser snapshot captures the page state; it does not prompt an agent or model. Remove the note/instructions, or use `vibecodr browser notes <url> --note \"...\"` to save a note with the snapshot.", 2);
     }
     return {
         positionals: url === undefined ? [] : [url],
         flags: parsed.flags
     };
 }
-function normalizeBrowserAskOptions(parsed) {
+function normalizeBrowserNotesOptions(parsed) {
     const [url, ...instructionParts] = parsed.positionals;
     const flags = { ...parsed.flags };
     const note = getStringFlag(flags, "note");
@@ -1019,13 +1223,132 @@ function normalizeBrowserAskOptions(parsed) {
         flags.instructions = instructionParts.join(" ");
     }
     if (getStringFlag(flags, "instructions") === undefined) {
-        throw new CliError("input.ask_note_required", "browser ask is an advanced compatibility alias and needs a note. For a normal capture, use `vibecodr browser snapshot <url> --local`.", 2);
+        throw new CliError("input.notes_note_required", "browser notes needs a note. For a normal capture, use `vibecodr browser snapshot <url> --local`.", 2);
     }
     return {
         positionals: url === undefined ? [] : [url],
         flags
     };
 }
+function validateBrowserSessionId(input) {
+    return validateEntityId(input ?? "", "Agent Browser session id");
+}
+function browserSessionActionBody(subcommand, parsed) {
+    if (subcommand === "goto" || subcommand === "navigate") {
+        const target = getStringFlag(parsed.flags, "url") ?? parsed.positionals[1];
+        if (!target) {
+            throw new CliError("input.url_required", `browser session ${subcommand} requires an HTTPS URL target.`, 2);
+        }
+        return { action: "navigate", url: validateBrowserUrl(target) };
+    }
+    if (subcommand === "click") {
+        return { action: "click", selector: requiredBrowserSessionSelector(parsed, "browser session click requires --selector <css>.") };
+    }
+    if (subcommand === "type") {
+        const text = getStringFlag(parsed.flags, "text") ?? parsed.positionals.slice(2).join(" ").trim();
+        if (!text) {
+            throw new CliError("input.text_required", "browser session type requires --text <text>.", 2);
+        }
+        return {
+            action: "type",
+            selector: requiredBrowserSessionSelector(parsed, "browser session type requires --selector <css>."),
+            text: text.slice(0, 2_000)
+        };
+    }
+    if (subcommand === "scroll") {
+        const deltaY = validateIntegerRange(getStringFlag(parsed.flags, "deltaY") ?? parsed.positionals[1], "--delta-y", -10_000, 10_000);
+        return deltaY === undefined ? { action: "scroll" } : { action: "scroll", deltaY };
+    }
+    if (subcommand === "wait") {
+        const ms = validateIntegerRange(getStringFlag(parsed.flags, "ms") ?? parsed.positionals[1], "--ms", 1, 30_000);
+        return ms === undefined ? { action: "wait" } : { action: "wait", ms };
+    }
+    throw new CliError("input.invalid_browser_session_action", "Unknown Agent Browser session action.", 2);
+}
+function browserSessionLiveViewQuery(parsed, globalDebug = false) {
+    const mode = browserSessionLiveViewMode(parsed, globalDebug);
+    return mode === "devtools" ? "?view=devtools" : "";
+}
+function browserSessionLiveViewMode(parsed, globalDebug = false) {
+    const raw = (getStringFlag(parsed.flags, "view") ?? getStringFlag(parsed.flags, "mode") ?? "").trim().toLowerCase();
+    const debug = globalDebug || getBooleanFlag(parsed.flags, "debug") || getBooleanFlag(parsed.flags, "devtools");
+    if (debug && (raw === "tab" || raw === "browser")) {
+        throw new CliError("input.invalid_live_view_mode", "Use either --debug/--devtools or --view tab, not both.", 2);
+    }
+    if (debug || raw === "devtools" || raw === "debug" || raw === "inspector") {
+        return "devtools";
+    }
+    if (!raw || raw === "tab" || raw === "browser") {
+        return "tab";
+    }
+    throw new CliError("input.invalid_live_view_mode", "Agent Browser live view mode must be tab or devtools.", 2);
+}
+function requiredBrowserSessionSelector(parsed, message) {
+    const selector = getStringFlag(parsed.flags, "selector") ?? parsed.positionals[1];
+    if (!selector || selector.trim().length === 0) {
+        throw new CliError("input.selector_required", message, 2);
+    }
+    return selector.trim().slice(0, 500);
+}
+function validateIntegerRange(input, label, min, max) {
+    if (input === undefined) {
+        return undefined;
+    }
+    const value = Number(input);
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new CliError("input.invalid_number", `${label} must be an integer from ${min} to ${max}.`, 2);
+    }
+    return value;
+}
+function browserSessionMessage(response, fallback) {
+    if (!isRecord(response)) {
+        return fallback;
+    }
+    const session = isRecord(response.session) ? response.session : undefined;
+    const id = typeof session?.id === "string" ? session.id : typeof response.id === "string" ? response.id : undefined;
+    const observation = isRecord(response.observation) ? response.observation : undefined;
+    const screenshot = isRecord(observation?.screenshot) ? observation?.screenshot : undefined;
+    const auth = isRecord(response.auth) ? response.auth : isRecord(session?.auth) ? session?.auth : undefined;
+    const lines = [fallback];
+    if (id) {
+        lines.push(`Session: ${id}`);
+        lines.push(`Observe: vibecodr browser session observe ${id}`);
+        lines.push(`Watch live: vibecodr browser session live ${id}`);
+        lines.push(`Need to sign in or steer? vibecodr browser session auth ${id}`);
+        lines.push(`Close: vibecodr browser session close ${id}`);
+    }
+    if (auth && typeof auth.status === "string") {
+        lines.push(`Control: ${browserSessionControlLabel(auth.status)}`);
+    }
+    const handoffUrl = browserSessionHandoffUrlFromResponse(response);
+    if (handoffUrl) {
+        lines.push(`Open live page: ${handoffUrl}`);
+    }
+    if (typeof screenshot?.id === "string") {
+        lines.push(`Screenshot proof: vibecodr proof show ${screenshot.id}`);
+    }
+    return lines.join("\n");
+}
+function browserSessionControlLabel(status) {
+    if (status === "human_control")
+        return "you are controlling the browser";
+    if (status === "auth_ready")
+        return "agent can continue";
+    if (status === "revoked")
+        return "live link ended";
+    if (status === "handoff_expired")
+        return "watch link expired";
+    if (status === "public")
+        return "agent is browsing";
+    return status;
+}
+function browserSessionHandoffUrlFromResponse(response) {
+    if (!isRecord(response)) {
+        return undefined;
+    }
+    const auth = isRecord(response.auth) ? response.auth : undefined;
+    return typeof auth?.handoffUrl === "string" ? auth.handoffUrl : undefined;
+}
 function normalizeComputerCommandOptions(parsed, missingMessage) {
     const command = getStringFlag(parsed.flags, "command") ?? parsed.positionals.join(" ").trim();
     if (!command) {
@@ -1894,6 +2217,26 @@ function usageBar(percent) {
     return `[${"#".repeat(filled)}${"-".repeat(width - filled)}]`;
 }
 function buildToolTestPayload(capability, target, parsed, globalToolTimeoutMs) {
+    if (capability.startsWith("browser.session_")) {
+        const input = {};
+        if (capability === "browser.session_open") {
+            if (!target) {
+                throw new CliError("input.url_required", "browser.session_open requires an HTTPS URL target.", 2);
+            }
+            input.url = validateBrowserUrl(target);
+            const timeoutMs = validatePositiveInt(getStringFlag(parsed.flags, "timeoutMs"), "--timeout-ms", 1000, 3_600_000);
+            const idleTimeoutMs = validatePositiveInt(getStringFlag(parsed.flags, "idleTimeoutMs"), "--idle-timeout-ms", 1000, 600_000);
+            if (timeoutMs !== undefined)
+                input.timeoutMs = timeoutMs;
+            if (idleTimeoutMs !== undefined)
+                input.idleTimeoutMs = idleTimeoutMs;
+        }
+        else {
+            input.sessionId = validateBrowserSessionId(target);
+            Object.assign(input, browserSessionToolTestActionInput(capability, parsed));
+        }
+        return { capability, input };
+    }
     if (capability.startsWith("browser.")) {
         if (!target) {
             throw new CliError("input.url_required", `${capability} requires an HTTPS URL target.`, 2);
@@ -1975,6 +2318,37 @@ function buildToolTestPayload(capability, target, parsed, globalToolTimeoutMs) {
     }
     return { capability, input: {} };
 }
+function browserSessionToolTestActionInput(capability, parsed) {
+    if (capability === "browser.session_observe" || capability === "browser.session_close") {
+        return {};
+    }
+    if (capability === "browser.session_navigate") {
+        const target = getStringFlag(parsed.flags, "url") ?? parsed.positionals[1];
+        if (!target) {
+            throw new CliError("input.url_required", "browser.session_navigate requires an HTTPS URL target.", 2);
+        }
+        return { url: validateBrowserUrl(target) };
+    }
+    if (capability === "browser.session_click") {
+        return { selector: requiredBrowserSessionSelector(parsed, "browser.session_click requires --selector <css>.") };
+    }
+    if (capability === "browser.session_type") {
+        const text = getStringFlag(parsed.flags, "text") ?? parsed.positionals.slice(2).join(" ").trim();
+        if (!text) {
+            throw new CliError("input.text_required", "browser.session_type requires --text <text>.", 2);
+        }
+        return { selector: requiredBrowserSessionSelector(parsed, "browser.session_type requires --selector <css>."), text };
+    }
+    if (capability === "browser.session_scroll") {
+        const deltaY = validateIntegerRange(getStringFlag(parsed.flags, "deltaY") ?? parsed.positionals[1], "--delta-y", -10_000, 10_000);
+        return deltaY === undefined ? {} : { deltaY };
+    }
+    if (capability === "browser.session_wait") {
+        const ms = validateIntegerRange(getStringFlag(parsed.flags, "ms") ?? parsed.positionals[1], "--ms", 1, 30_000);
+        return ms === undefined ? {} : { ms };
+    }
+    return {};
+}
 function buildScheduledQaPayload(target, parsed, globalToolTimeoutMs) {
     const capability = normalizeScheduledQaCliCapability(getStringFlag(parsed.flags, "capability") ?? getStringFlag(parsed.flags, "tool") ?? "browser.render_url");
     const timeoutInput = getStringFlag(parsed.flags, "timeoutMs") ?? (globalToolTimeoutMs === undefined ? undefined : String(globalToolTimeoutMs));
@@ -2796,6 +3170,9 @@ Usage:
   vibecodr computer status
   vibecodr computer run "<command>" [--timeout-ms <ms>] [--network public|off] [--local|--out ./proof] [--no-wait] [--details]
   vibecodr computer test "<command>" [--timeout-ms <ms>] [--network public|off] [--local|--out ./proof] [--no-wait] [--details]
+
+Notes:
+  Automatic output saves are workspace-bounded. If --out points outside this workspace, vibecodr writes to ./.vibecodr/browser-artifacts/<run> instead.
 `;
         case "browser":
             return `vibecodr browser
@@ -2809,14 +3186,32 @@ Usage:
   vibecodr browser pdf <https-url> [--local|--out ./proof] [--no-wait] [--details]
   vibecodr browser crawl <https-url> [--max-pages n] [--max-depth n] [--local|--out ./proof]
   vibecodr browser snapshot <https-url> [--local|--out ./proof]
-
-Advanced compatibility:
-  vibecodr browser ask <https-url> --note <text> [--local|--out ./proof]
+  vibecodr browser session open <https-url> [--timeout-ms <ms>] [--idle-timeout-ms <ms>]
+  vibecodr browser session observe <sessionId>
+  vibecodr browser session goto <sessionId> <https-url>
+  vibecodr browser session click <sessionId> --selector <css>
+  vibecodr browser session type <sessionId> --selector <css> --text <text>
+  vibecodr browser session scroll <sessionId> [--delta-y 800]
+  vibecodr browser session wait <sessionId> [--ms 1000]
+  vibecodr browser session live <sessionId> [--no-open] [--debug|--view devtools]
+  vibecodr browser session auth <sessionId> [--no-open] [--debug|--view devtools]
+  vibecodr browser session auth-status <sessionId>
+  vibecodr browser session auth-complete <sessionId>
+  vibecodr browser session auth-revoke <sessionId>
+  vibecodr browser session close <sessionId>
+
+Attach a note:
+  vibecodr browser notes <https-url> --note <text> [--local|--out ./proof]
 
 Notes:
   Add --local to save completed output into ./vibecodr-proof automatically.
+  Automatic output saves are workspace-bounded. If --out points outside this workspace, vibecodr writes to ./.vibecodr/browser-artifacts/<run> instead.
   browser snapshot captures page state; it does not prompt an agent or model.
-  browser ask saves your note with the snapshot; it is not a chat answerer.
+  browser notes saves your note with the snapshot.
+  browser session opens a real hosted Agent Browser the agent can observe and control until it is closed or idle.
+  browser session live opens the watch-and-intercede page without pausing the agent.
+  browser session auth opens the same live page with human control already active for login, MFA, CAPTCHA, or other human-only steps.
+  Add --debug or --view devtools only when an agent/developer needs the inspector panel instead of the plain browser tab.
 `;
         case "work":
             return `vibecodr work
@@ -2828,6 +3223,9 @@ Usage:
   vibecodr work show <jobId>
   vibecodr work follow <jobId> [--local|--out ./proof] [--details]
   vibecodr work cancel <jobId> --yes
+
+Notes:
+  Automatic output saves are workspace-bounded. If --out points outside this workspace, vibecodr writes to ./.vibecodr/browser-artifacts/<run> instead.
 `;
         case "proof":
             return `vibecodr proof