gologin-web-access 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,12 @@
 - browser automation is now embedded directly in `gologin-web-access`, so one repo and one install contains both Web Unlocker and Cloud Browser flows
 - doctor now reports the embedded browser runtime source and version
 
+## 0.3.2 - 2026-04-03
+
+- added unified page outcome classification across `read`, `scrape-json`, and `batch-scrape`
+- structured and readable paths now distinguish `ok`, `empty`, `incomplete`, `authwall`, `challenge`, `blocked`, and `cookie_wall`
+- batch and extract-oriented flows now propagate next-step hints and fallback metadata more consistently for agents
+
 ## 0.1.0 - 2026-03-10
 
 Initial public release of Gologin Web Access.
@@ -14,6 +20,6 @@ Highlights:
 - Unified CLI entry point for Gologin Web Unlocker and Gologin Cloud Browser workflows
 - Scraping commands: `scrape`, `scrape-markdown`, `scrape-text`, `scrape-json`, `batch-scrape`
 - Browser commands: `open`, `snapshot`, `click`, `type`, `screenshot`, `close`, `sessions`, `current`
-- Clear two-key configuration model with `GOLOGIN_WEB_UNLOCKER_API_KEY` and `GOLOGIN_CLOUD_TOKEN`
+- Clear two-key configuration model with `GOLOGIN_WEB_UNLOCKER_API_KEY` and `GOLOGIN_TOKEN`
 - `doctor`, `config show`, and `config init` to reduce setup friction
 - Compatibility support for legacy env names used by existing Gologin tools

package/README.md

@@ -26,6 +26,13 @@ The point of the unified CLI is that both modes live in one product with one com
 
 ## Command Groups
 
+### Quick Picks
+
+- `read` for "read this docs page/article" or "tell me what is on this page"
+- `scrape-text` for plain text from one known page when you do not need headings/links metadata
+- `scrape-json` for structured title, description, headings, and links from one known page
+- `batch-scrape` for many known URLs at once; add `--output <path>` when the JSON may be large and add `--strict` only if partial success should fail the command
+
 ### Scraping / Read
 
 These commands use Gologin Web Unlocker:
@@ -35,7 +42,7 @@ These commands use Gologin Web Unlocker:
 - `gologin-web-access scrape-markdown <url> [--source auto|unlocker|browser]`
 - `gologin-web-access scrape-text <url> [--source auto|unlocker|browser]`
 - `gologin-web-access scrape-json <url> [--fallback none|browser]`
-- `gologin-web-access batch-scrape <url...> [--format html|markdown|text|json] [--fallback none|browser] [--source auto|unlocker|browser] [--only-main-content] [--retry <n>] [--backoff-ms <ms>] [--summary]`
+- `gologin-web-access batch-scrape <url...> [--format html|markdown|text|json] [--fallback none|browser] [--source auto|unlocker|browser] [--only-main-content] [--retry <n>] [--backoff-ms <ms>] [--summary] [--output <path>] [--strict]`
 - `gologin-web-access batch-extract <url...> --schema <schema.json> [--source auto|unlocker|browser] [--retry <n>] [--backoff-ms <ms>] [--summary] [--output <path>]`
 - `gologin-web-access search <query> [--limit <n>] [--country <cc>] [--language <lang>] [--source auto|unlocker|browser]`
 - `gologin-web-access map <url> [--limit <n>] [--max-depth <n>] [--concurrency <n>] [--strict]`
@@ -104,6 +111,9 @@ Use these when you need state, interaction, or multi-step browser flows.
 ## When To Use `scrape` vs `browser`
 
 - Use `scrape` commands when you need page content, extracted text, markdown, or simple structured output.
+- Use `read` as the default for docs and article reading when you want one high-level main-content command rather than choosing HTML/text/markdown yourself.
+- Use `scrape-text` when you already know you want plain text.
+- Use `scrape-json` when you want structured metadata and headings instead of full prose.
 - Use `search` when you need web discovery or SERP results before deciding what to scrape. It now tries multiple search paths automatically, validates that the response is a real SERP, and reuses a short local cache for repeated queries.
 - Use `map` when you need internal link discovery or a site inventory.
 - Use `crawl` when you need multi-page read-only extraction across a site.
@@ -153,18 +163,18 @@ If the browser surface grows substantially later, a nested namespace may become
 
 ## Credentials And Config
 
-This CLI uses two different Gologin credentials on purpose, because the underlying products are different.
+This CLI uses two different GoLogin credentials on purpose, because the underlying products are different.
 
 - `GOLOGIN_WEB_UNLOCKER_API_KEY`
   Required for Scraping / Read commands.
-- `GOLOGIN_CLOUD_TOKEN`
+- `GOLOGIN_TOKEN`
   Required for `gologin-web-access open` and for profile validation in `gologin-web-access doctor`.
 - `GOLOGIN_DEFAULT_PROFILE_ID`
   Optional default profile for browser flows.
 - `GOLOGIN_DAEMON_PORT`
   Optional local daemon port for browser workflows.
 
-Recommended full setup for agents is to configure both `GOLOGIN_WEB_UNLOCKER_API_KEY` and `GOLOGIN_CLOUD_TOKEN` before starting work, even if the current task looks read-only or browser-only.
+Recommended full setup for agents is to configure both `GOLOGIN_WEB_UNLOCKER_API_KEY` and `GOLOGIN_TOKEN` before starting work, even if the current task looks read-only or browser-only.
 
 Missing-key errors are command-group specific. Example:
 
@@ -174,7 +184,7 @@ Environment variables are the primary configuration mechanism:
 
 ```bash
 export GOLOGIN_WEB_UNLOCKER_API_KEY="wu_..."
-export GOLOGIN_CLOUD_TOKEN="gl_..."
+export GOLOGIN_TOKEN="gl_..."
 export GOLOGIN_DEFAULT_PROFILE_ID="profile_123"
 export GOLOGIN_DAEMON_PORT="4590"
 ```
@@ -188,8 +198,8 @@ gologin-web-access config init
 Useful variants:
 
 ```bash
-gologin-web-access config init --web-unlocker-api-key wu_... --cloud-token gl_...
-gologin-web-access config init --web-unlocker-key wu_... --cloud-token gl_...
+gologin-web-access config init --web-unlocker-api-key wu_... --token gl_...
+gologin-web-access config init --web-unlocker-key wu_... --token gl_...
 ```
 
 That writes `~/.gologin-web-access/config.json` once and the CLI will keep reading it on later runs.
@@ -211,7 +221,7 @@ Gologin Web Access will also read the older path `~/.gologin-web/config.json` if
 Backward-compatible aliases are also accepted for existing setups:
 
 - `GOLOGIN_WEBUNLOCKER_API_KEY`
-- `GOLOGIN_TOKEN`
+- `GOLOGIN_CLOUD_TOKEN`
 - `GOLOGIN_PROFILE_ID`
 
 Useful config commands:
@@ -259,7 +269,7 @@ gologin-web-access parse-document ./example.pdf
 ### Interact With A Site
 
 ```bash
-export GOLOGIN_CLOUD_TOKEN="gl_..."
+export GOLOGIN_TOKEN="gl_..."
 export GOLOGIN_DEFAULT_PROFILE_ID="profile_123"
 
 gologin-web-access open https://example.com
@@ -280,7 +290,7 @@ gologin-web-access close
 ### Search In A Real Browser
 
 ```bash
-export GOLOGIN_CLOUD_TOKEN="gl_..."
+export GOLOGIN_TOKEN="gl_..."
 
 gologin-web-access search-browser "gologin antidetect browser"
 gologin-web-access snapshot -i
@@ -295,11 +305,16 @@ gologin-web-access snapshot -i
 - `batch-extract` reuses the same extraction path across many URLs and returns one structured result per URL, including request and fallback metadata. Add `--output <path>` to save the full array directly.
 - `scrape-json` now returns both a flat `headings` array and `headingsByLevel` buckets for `h1` through `h6`.
 - `scrape-json --fallback browser` is available for JS-heavy pages where stateless extraction returns weak heading data.
+- `scrape-json` now also classifies the page outcome as `ok`, `empty`, `incomplete`, `authwall`, `challenge`, `blocked`, or `cookie_wall`, and includes `nextActionHint` when the result is weak or gated.
 - `scrape`, `scrape-markdown`, `scrape-text`, `scrape-json`, and `batch-scrape` accept `--retry`, `--backoff-ms`, and `--timeout-ms`.
 - `batch-scrape --only-main-content` lets markdown, text, and html batch runs use the same readable-content isolation path as `read`.
 - `crawl --only-main-content` uses the same readable-fragment extraction strategy for html, markdown, and text crawl output, but stays on the stateless unlocker path.
 - `batch-scrape --summary` prints a one-line success/failure summary to `stderr` after the JSON payload.
+- `batch-scrape` now returns exit code `0` on partial success by default and only fails the command when every URL failed. Add `--strict` if any single failed URL should make the whole batch exit non-zero.
+- `batch-scrape --output <path>` writes the full JSON to disk so shells and agent consoles cannot truncate a large payload silently.
 - `batch-scrape --format json` now returns the same structured scrape envelope as `scrape-json`, including `renderSource`, `fallbackAttempted`, `fallbackUsed`, and `request.attemptCount/retryCount/attempts`.
+- `batch-scrape --only-main-content` now propagates `outcome`, `outcomeReason`, `nextActionHint`, and fallback metadata per URL so agents can tell "weak page" from "gated page" without scraping log text.
+- `scrape-json` now surfaces explicit `BLOCKED_PAGE` failures when structured output clearly matches a challenge or block page, instead of silently looking like a valid empty result.
 - `search` now returns `requestedLimit`, `returnedCount`, `warnings`, `cacheTtlMs`, and per-result `position`.
 - `search` may return fewer results than the requested `--limit` when the upstream SERP contains fewer valid results; inspect `returnedCount`, `warnings`, and `attempts`.
 - `change-track` now accepts `--retry`, `--backoff-ms`, and `--timeout-ms`, and JSON output includes request metadata.

package/dist/cli.js

@@ -67,7 +67,7 @@ const wait_1 = require("./commands/wait");
 const doctor_1 = require("./doctor");
 const errors_1 = require("./lib/errors");
 const output_1 = require("./lib/output");
-const CLI_VERSION = "0.3.0";
+const CLI_VERSION = "0.3.2";
 async function main() {
     const program = new commander_1.Command();
     program
@@ -154,6 +154,12 @@ async function main() {
     configGroup.addCommand((0, configShow_1.buildConfigShowCommand)());
     configGroup.addCommand((0, configInit_1.buildConfigInitCommand)());
     program.addHelpText("after", `
+Quick picks:
+  read          Best default for "read this docs page/article" and main-content extraction
+  scrape-text   Plain text from one known page when you do not need headings/links metadata
+  scrape-json   Structured title, description, headings, and links from one known page
+  batch-scrape  Fetch many known URLs at once; add --output <path> for large results and --strict only when partial success should fail the command
+
 Command groups:
   Scraping: gologin-web-access scrape|read|scrape-markdown|scrape-text|scrape-json|batch-scrape|batch-extract|search|map|crawl|crawl-start|crawl-status|crawl-result|crawl-errors|extract|change-track|batch-change-track|parse-document
   Browser:  gologin-web-access open|search-browser|scrape-screenshot|tabs|tabopen|tabfocus|tabclose|snapshot|click|dblclick|focus|type|fill|hover|select|check|uncheck|press|scroll|scrollintoview|wait|get|back|forward|reload|find|cookies|cookies-import|cookies-clear|storage-export|storage-import|storage-clear|eval|upload|pdf|screenshot|close|sessions|current
@@ -161,7 +167,7 @@ Command groups:
 
 Key model:
   ${"GOLOGIN_WEB_UNLOCKER_API_KEY"} powers scraping commands.
-  ${"GOLOGIN_CLOUD_TOKEN"} powers browser commands.
+  ${"GOLOGIN_TOKEN"} powers browser commands.
   Recommended setup: configure both keys up front, even if the current task only needs one path.
 `);
     await program.parseAsync(process.argv);

package/dist/commands/batchScrape.js

@@ -1,6 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildBatchScrapeCommand = buildBatchScrapeCommand;
+exports.resolveBatchScrapeExitCode = resolveBatchScrapeExitCode;
+exports.shouldWarnAboutLargeBatchOutput = shouldWarnAboutLargeBatchOutput;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
 const output_1 = require("../lib/output");
@@ -17,7 +24,9 @@ function buildBatchScrapeCommand() {
         .option("--fallback <mode>", "Structured scrape fallback: none or browser", "none")
         .option("--source <source>", "Read source for --only-main-content mode: auto, unlocker, or browser", "auto")
         .option("--only-main-content", "For html, markdown, or text formats, isolate the most readable content block per page")
+        .option("--output <path>", "Write the full batch result JSON to a file")
         .option("--summary", "Print one-line summary stats to stderr after the JSON output")
+        .option("--strict", "Exit non-zero if any URL in the batch fails")
         .action(async (urls, options) => {
         const config = await (0, config_1.loadConfig)();
         const format = normalizeFormat(options.format);
@@ -38,7 +47,16 @@ function buildBatchScrapeCommand() {
                     url,
                     ok: true,
                     format,
-                    output,
+                    output: output.output,
+                    outcome: output.outcome,
+                    outcomeReason: output.outcomeReason,
+                    nextActionHint: output.nextActionHint,
+                    renderSource: output.renderSource,
+                    fallbackAttempted: output.fallbackAttempted,
+                    fallbackUsed: output.fallbackUsed,
+                    fallbackReason: output.fallbackReason,
+                    warning: output.warning,
+                    request: output.request,
                 };
             }
             catch (error) {
@@ -48,18 +66,31 @@ function buildBatchScrapeCommand() {
                     ok: false,
                     format,
                     error: error instanceof Error ? error.message : "Unknown error",
+                    code: extractErrorCode(error),
                     status: extractStatusCode(error),
+                    outcome: extractOutcome(error),
+                    nextActionHint: extractNextActionHint(error),
                     request,
                 };
             }
         });
-        (0, output_1.printJson)(results);
+        const payload = `${JSON.stringify(results, null, 2)}\n`;
+        if (options.output) {
+            const outputPath = (0, shared_1.resolveOutputPath)(options.output);
+            await fs_1.promises.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+            await fs_1.promises.writeFile(outputPath, payload, "utf8");
+            (0, output_1.printText)(outputPath);
+        }
+        else {
+            (0, output_1.printText)(payload);
+            if (shouldWarnAboutLargeBatchOutput(payload)) {
+                process.stderr.write("Batch output is large. If your shell or agent truncates stdout, rerun with --output <path> to keep the full JSON.\n");
+            }
+        }
         if (options.summary) {
             process.stderr.write(formatBatchSummary(results) + "\n");
         }
-        if (results.some((result) => !result.ok)) {
-            process.exitCode = 1;
-        }
+        process.exitCode = resolveBatchScrapeExitCode(results, Boolean(options.strict));
     })));
 }
 function normalizeFormat(value) {
@@ -77,31 +108,67 @@ async function formatOutput(url, config, apiKey, format, requestOptions, fallbac
         };
         switch (format) {
             case "html":
-                return (await (0, readSource_1.readHtmlContent)(url, config, apiKey, readOptions)).content;
+                return mapReadableBatchResult(await (0, readSource_1.readHtmlContent)(url, config, apiKey, readOptions));
             case "markdown":
-                return (await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions)).content;
+                return mapReadableBatchResult(await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions));
             case "text":
-                return (await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions)).content;
+                return mapReadableBatchResult(await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions));
             default:
                 break;
         }
     }
     switch (format) {
         case "html":
-            return (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content;
+            return {
+                output: (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content,
+            };
         case "markdown":
-            return (await (0, unlocker_1.scrapeMarkdown)(url, apiKey, requestOptions)).markdown;
+            return {
+                output: (await (0, unlocker_1.scrapeMarkdown)(url, apiKey, requestOptions)).markdown,
+            };
         case "text":
-            return (await (0, unlocker_1.scrapeText)(url, apiKey, requestOptions)).text;
+            return {
+                output: (await (0, unlocker_1.scrapeText)(url, apiKey, requestOptions)).text,
+            };
         case "json":
-            return await (0, structuredScrape_1.scrapeStructuredJson)(url, config, apiKey, {
+            return mapStructuredBatchResult(await (0, structuredScrape_1.scrapeStructuredJson)(url, config, apiKey, {
                 fallback,
                 request: requestOptions,
-            });
+            }));
         default:
-            return (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content;
+            return {
+                output: (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content,
+            };
     }
 }
+function mapReadableBatchResult(result) {
+    return {
+        output: result.content,
+        outcome: result.outcome,
+        outcomeReason: result.outcomeReason,
+        nextActionHint: result.nextActionHint,
+        renderSource: result.renderSource,
+        fallbackAttempted: result.fallbackAttempted,
+        fallbackUsed: result.fallbackUsed,
+        fallbackReason: result.fallbackReason,
+        warning: result.warning,
+        request: result.request,
+    };
+}
+function mapStructuredBatchResult(result) {
+    return {
+        output: result,
+        outcome: result.outcome,
+        outcomeReason: result.outcomeReason,
+        nextActionHint: result.nextActionHint,
+        renderSource: result.renderSource,
+        fallbackAttempted: result.fallbackAttempted,
+        fallbackUsed: result.fallbackUsed,
+        fallbackReason: result.fallbackReason,
+        warning: result.warning,
+        request: result.request,
+    };
+}
 async function mapWithConcurrency(items, concurrency, mapper) {
     const results = new Array(items.length);
     let nextIndex = 0;
@@ -120,6 +187,19 @@ function formatBatchSummary(results) {
     const failed = requested - ok;
     return `Summary: ${requested} requested, ${ok} ok, ${failed} failed.`;
 }
+function resolveBatchScrapeExitCode(results, strict) {
+    const okCount = results.filter((result) => result.ok).length;
+    if (okCount === 0) {
+        return 1;
+    }
+    if (strict && okCount !== results.length) {
+        return 1;
+    }
+    return 0;
+}
+function shouldWarnAboutLargeBatchOutput(payload) {
+    return payload.length >= 100_000;
+}
 function extractStatusCode(error) {
     if (typeof error === "object" &&
         error !== null &&
@@ -138,3 +218,30 @@ function extractRequestMeta(error) {
     }
     return undefined;
 }
+function extractErrorCode(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return undefined;
+}
+function extractOutcome(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "outcome" in error &&
+        typeof error.outcome === "string") {
+        return error.outcome;
+    }
+    return undefined;
+}
+function extractNextActionHint(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "nextActionHint" in error &&
+        typeof error.nextActionHint === "string") {
+        return error.nextActionHint;
+    }
+    return undefined;
+}

package/dist/commands/close.js

@@ -8,9 +8,13 @@ function buildCloseCommand() {
     return new commander_1.Command("close")
         .description("Close the current browser session or a specific session.")
         .option("--session <id>", "Session ID. Defaults to the current session.")
+        .option("--all", "Close every tracked browser session in the current daemon.")
         .action(async (options) => {
         const config = await (0, config_1.loadConfig)();
         const args = ["close"];
+        if (options.all) {
+            args.push("--all");
+        }
         if (options.session) {
             args.push("--session", options.session);
         }

package/dist/commands/configInit.js

@@ -8,10 +8,11 @@ const output_1 = require("../lib/output");
 const unlocker_1 = require("../lib/unlocker");
 function buildConfigInitCommand() {
     return new commander_1.Command("init")
-        .description("Write ~/.gologin-web-access/config.json with current values or placeholders. Recommended: persist both Web Unlocker and Cloud Browser credentials.")
+        .description("Write ~/.gologin-web-access/config.json with current values or placeholders. Recommended: persist both the Web Unlocker key and the GoLogin token.")
         .option("--web-unlocker-api-key <key>", "Persist a Web Unlocker API key")
         .option("--web-unlocker-key <key>", "Alias for --web-unlocker-api-key")
-        .option("--cloud-token <token>", "Persist a Cloud Browser token")
+        .option("--token <token>", "Persist a GoLogin token")
+        .option("--cloud-token <token>", "Backward-compatible alias for --token")
         .option("--default-profile-id <id>", "Persist a default Gologin profile ID")
         .option("--daemon-port <port>", "Persist a daemon port", String(config_1.DEFAULT_DAEMON_PORT))
         .option("--no-validate", "Skip live key validation after writing config")
@@ -20,7 +21,10 @@ function buildConfigInitCommand() {
         const webUnlockerApiKey = options.webUnlockerApiKey ?? options.webUnlockerKey ?? process.env[config_1.ENV_NAMES.webUnlockerApiKey];
         const result = await (0, config_1.initConfigFile)({
             webUnlockerApiKey,
-            cloudToken: options.cloudToken ?? process.env[config_1.ENV_NAMES.cloudToken],
+            cloudToken: options.token ??
+                options.cloudToken ??
+                process.env[config_1.ENV_NAMES.cloudToken] ??
+                process.env.GOLOGIN_CLOUD_TOKEN,
             defaultProfileId: options.defaultProfileId ?? process.env[config_1.ENV_NAMES.defaultProfileId],
             daemonPort: Number(options.daemonPort ?? process.env[config_1.ENV_NAMES.daemonPort] ?? config_1.DEFAULT_DAEMON_PORT),
         }, {
@@ -37,7 +41,7 @@ function buildConfigInitCommand() {
                 value: result.config.webUnlockerApiKey ? "written" : "left empty",
             },
             {
-                label: "Cloud token",
+                label: "GoLogin token",
                 value: result.config.cloudToken ? "written" : "left empty",
             },
             {
@@ -50,7 +54,7 @@ function buildConfigInitCommand() {
             },
         ]);
         if (!result.config.webUnlockerApiKey || !result.config.cloudToken) {
-            (0, output_1.printText)("Recommended next step: configure both GOLOGIN_WEB_UNLOCKER_API_KEY and GOLOGIN_CLOUD_TOKEN so agents can use scraping and browser flows without asking again.");
+            (0, output_1.printText)("Recommended next step: configure both GOLOGIN_WEB_UNLOCKER_API_KEY and GOLOGIN_TOKEN so agents can use scraping and browser flows without asking again.");
         }
         if (options.validate === false) {
             return;
@@ -66,7 +70,7 @@ function buildConfigInitCommand() {
         if (result.config.cloudToken) {
             const validation = await (0, cloudApi_1.validateCloudToken)(result.config.cloudToken);
             validationRows.push({
-                label: "Cloud token validation",
+                label: "GoLogin token validation",
                 value: validation.ok ? "ok" : `failed${validation.status ? ` (${validation.status})` : ""}: ${validation.detail}`,
             });
         }

package/dist/commands/read.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildReadCommand = buildReadCommand;
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const pageOutcome_1 = require("../lib/pageOutcome");
 const readSource_1 = require("../lib/readSource");
 const output_1 = require("../lib/output");
 const shared_1 = require("./shared");
@@ -27,7 +28,7 @@ function buildReadCommand() {
             : format === "markdown"
                 ? await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions)
                 : await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions);
-        emitReadNotice(result.fallbackAttempted, result.fallbackUsed, result.fallbackReason);
+        emitReadNotice(result);
         (0, output_1.printText)(result.content);
     })));
 }
@@ -37,15 +38,24 @@ function normalizeReadFormat(value) {
     }
     throw new Error(`Unsupported read format: ${value}`);
 }
-function emitReadNotice(fallbackAttempted, fallbackUsed, fallbackReason) {
-    if (!fallbackAttempted) {
-        return;
+function emitReadNotice(result) {
+    if (result.fallbackAttempted) {
+        if (result.fallbackUsed) {
+            process.stderr.write(`JS-rendered page detected, retrying with browser. ${result.fallbackReason ?? ""}\n`);
+        }
+        else if (result.fallbackReason) {
+            process.stderr.write(`${result.fallbackReason}\n`);
+        }
+    }
+    if (result.outcome !== "ok") {
+        process.stderr.write(`Outcome: ${result.outcome}\n`);
     }
-    if (fallbackUsed) {
-        process.stderr.write(`JS-rendered page detected, retrying with browser. ${fallbackReason ?? ""}\n`);
+    if (result.warning) {
+        process.stderr.write(`${result.warning}\n`);
         return;
     }
-    if (fallbackReason) {
-        process.stderr.write(`${fallbackReason}\n`);
+    const hint = (0, pageOutcome_1.describeNextActionHint)(result.nextActionHint);
+    if (hint && result.outcome !== "ok") {
+        process.stderr.write(`${hint}\n`);
     }
 }

package/dist/commands/scrapeJson.js

@@ -19,6 +19,15 @@ function buildScrapeJsonCommand() {
             profile: options.profile,
             request: (0, shared_1.normalizeUnlockerRequestOptions)(options),
         });
+        if (envelope.fallbackAttempted) {
+            const fallbackStatus = envelope.fallbackUsed
+                ? "Browser fallback succeeded and replaced the unlocker result."
+                : `Browser fallback was attempted but not used. ${envelope.fallbackReason ?? "It did not improve the structured output."}`;
+            process.stderr.write(`${fallbackStatus}\n`);
+        }
+        if (envelope.warning) {
+            process.stderr.write(`${envelope.warning}\n`);
+        }
         (0, output_1.printJson)(envelope);
     })));
 }

package/dist/commands/scrapeMarkdown.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildScrapeMarkdownCommand = buildScrapeMarkdownCommand;
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const pageOutcome_1 = require("../lib/pageOutcome");
 const readSource_1 = require("../lib/readSource");
 const shared_1 = require("./shared");
 const output_1 = require("../lib/output");
@@ -19,19 +20,28 @@ function buildScrapeMarkdownCommand() {
             source,
             request: (0, shared_1.normalizeUnlockerRequestOptions)(options),
         });
-        emitReadNotice(result.fallbackAttempted, result.fallbackUsed, result.fallbackReason);
+        emitReadNotice(result);
         (0, output_1.printText)(result.content);
     }));
 }
-function emitReadNotice(fallbackAttempted, fallbackUsed, fallbackReason) {
-    if (!fallbackAttempted) {
-        return;
+function emitReadNotice(result) {
+    if (result.fallbackAttempted) {
+        if (result.fallbackUsed) {
+            process.stderr.write(`JS-rendered page detected, retrying with browser. ${result.fallbackReason ?? ""}\n`);
+        }
+        else if (result.fallbackReason) {
+            process.stderr.write(`${result.fallbackReason}\n`);
+        }
+    }
+    if (result.outcome !== "ok") {
+        process.stderr.write(`Outcome: ${result.outcome}\n`);
     }
-    if (fallbackUsed) {
-        process.stderr.write(`JS-rendered page detected, retrying with browser. ${fallbackReason ?? ""}\n`);
+    if (result.warning) {
+        process.stderr.write(`${result.warning}\n`);
         return;
     }
-    if (fallbackReason) {
-        process.stderr.write(`${fallbackReason}\n`);
+    const hint = (0, pageOutcome_1.describeNextActionHint)(result.nextActionHint);
+    if (hint && result.outcome !== "ok") {
+        process.stderr.write(`${hint}\n`);
     }
 }

package/dist/commands/scrapeText.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildScrapeTextCommand = buildScrapeTextCommand;
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const pageOutcome_1 = require("../lib/pageOutcome");
 const readSource_1 = require("../lib/readSource");
 const shared_1 = require("./shared");
 const output_1 = require("../lib/output");
@@ -19,19 +20,28 @@ function buildScrapeTextCommand() {
             source,
             request: (0, shared_1.normalizeUnlockerRequestOptions)(options),
         });
-        emitReadNotice(result.fallbackAttempted, result.fallbackUsed, result.fallbackReason);
+        emitReadNotice(result);
         (0, output_1.printText)(result.content);
     }));
 }
-function emitReadNotice(fallbackAttempted, fallbackUsed, fallbackReason) {
-    if (!fallbackAttempted) {
-        return;
+function emitReadNotice(result) {
+    if (result.fallbackAttempted) {
+        if (result.fallbackUsed) {
+            process.stderr.write(`JS-rendered page detected, retrying with browser. ${result.fallbackReason ?? ""}\n`);
+        }
+        else if (result.fallbackReason) {
+            process.stderr.write(`${result.fallbackReason}\n`);
+        }
+    }
+    if (result.outcome !== "ok") {
+        process.stderr.write(`Outcome: ${result.outcome}\n`);
     }
-    if (fallbackUsed) {
-        process.stderr.write(`JS-rendered page detected, retrying with browser. ${fallbackReason ?? ""}\n`);
+    if (result.warning) {
+        process.stderr.write(`${result.warning}\n`);
         return;
     }
-    if (fallbackReason) {
-        process.stderr.write(`${fallbackReason}\n`);
+    const hint = (0, pageOutcome_1.describeNextActionHint)(result.nextActionHint);
+    if (hint && result.outcome !== "ok") {
+        process.stderr.write(`${hint}\n`);
     }
 }

package/dist/commands/sessions.js

@@ -7,8 +7,17 @@ const agentCli_1 = require("../lib/agentCli");
 function buildSessionsCommand() {
     return new commander_1.Command("sessions")
         .description("List active daemon-backed browser sessions.")
-        .action(async () => {
+        .option("--prune", "Close tracked sessions idle for too long before listing.")
+        .option("--older-than-ms <ms>", "Idle threshold used with --prune.")
+        .action(async (options) => {
         const config = await (0, config_1.loadConfig)();
-        await (0, agentCli_1.runAgentCommand)(["sessions"], config);
+        const args = ["sessions"];
+        if (options.prune) {
+            args.push("--prune");
+        }
+        if (options.olderThanMs) {
+            args.push("--older-than-ms", options.olderThanMs);
+        }
+        await (0, agentCli_1.runAgentCommand)(args, config);
     });
 }

package/dist/config.js

@@ -23,13 +23,13 @@ const CONFIG_FILENAME = "config.json";
 exports.DEFAULT_DAEMON_PORT = 4590;
 exports.ENV_NAMES = {
     webUnlockerApiKey: "GOLOGIN_WEB_UNLOCKER_API_KEY",
-    cloudToken: "GOLOGIN_CLOUD_TOKEN",
+    cloudToken: "GOLOGIN_TOKEN",
     defaultProfileId: "GOLOGIN_DEFAULT_PROFILE_ID",
     daemonPort: "GOLOGIN_DAEMON_PORT",
 };
 const LEGACY_ENV_NAMES = {
     webUnlockerApiKey: ["GOLOGIN_WEBUNLOCKER_API_KEY"],
-    cloudToken: ["GOLOGIN_TOKEN"],
+    cloudToken: ["GOLOGIN_CLOUD_TOKEN"],
     defaultProfileId: ["GOLOGIN_PROFILE_ID"],
     daemonPort: [],
 };