From d02df19469c438641b5d7b94896f3213494e1170 Mon Sep 17 00:00:00 2001
From: Evan Reichard <evan@reichard.io>
Date: Sat, 2 May 2026 20:10:20 -0400
Subject: [PATCH] feat: change --timeout from milliseconds to seconds

Accept seconds (including decimals like 0.5) instead of milliseconds
for the --timeout flag. Converts to ms internally. Default is now 10
(seconds) instead of 10000. Error messages display seconds.

Update AGENTS.md, tests, and skill docs to match.
---
 AGENTS.md     |  2 +-
 src/index.ts  | 20 ++++++++++----------
 test/smoke.js |  4 ++--
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9c72e3d..8518000 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,7 +30,7 @@ Do not attempt a live Kagi test unless `KAGI_TOKEN` is available.
 - Browser execution should be headless by default.
 - Use `--no-headless` as the opt-out.
 - Keep `--url=<server>` support for connecting to an existing WebDriver server.
-- `--timeout=<ms>` is a top-level option for command waits and defaults to `10000`.
+- `--timeout=<seconds>` is a top-level option for command waits and defaults to `10`.
 - `--wait-js=<code>` and `--wait-until=<state>` are top-level wait options available to every `glimpse` subcommand.
 - `--js=<code>` and `--script=<file>` are top-level options available to every `glimpse` subcommand and run before command-specific behavior.
 - Prefer structured JSON output for objects/arrays.
diff --git a/src/index.ts b/src/index.ts
index c9a5916..4e2d487 100755
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,7 +6,7 @@ import { searchKagi, type SearchResult } from "./providers/kagi.js";
 import { readFileSync, writeFileSync } from "node:fs";
 import TurndownService from "turndown";
 
-const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_TIMEOUT_S = 10;
 const POLL_INTERVAL_MS = 200;
 const startTime = Date.now();
 const runContext: { targetUrl?: string; currentUrl?: string } = {};
@@ -34,7 +34,7 @@ const waitJs = getOption("--wait-js");
 const waitUntil = getOption("--wait-until") ?? "none";
 const configPath = getOption("--config");
 let appConfig: GlimpseConfig = {};
-let timeoutMs = DEFAULT_TIMEOUT_MS;
+let timeoutMs: number;
 
 function getOption(name: string) {
   const prefix = `${name}=`;
@@ -97,7 +97,7 @@ Common Options:
   --help                      Show this help
   --no-headless               Show Firefox instead of running headless
   --url=<server>              Connect to an existing WebDriver server
-  --timeout=<ms>              Maximum wait time in milliseconds (default: 10000)
+  --timeout=<seconds>         Maximum wait time in seconds (default: 10)
   --wait-js=<code>            Poll JS until it returns a truthy value
   --wait-until=<state>        Wait for readiness: none, interactive, complete (default: none)
   --js=<code>                 Execute inline JS before command logic
@@ -145,15 +145,15 @@ function usage() {
 function parseTimeout() {
   const value = getOption("--timeout");
   if (value === undefined) {
-    return DEFAULT_TIMEOUT_MS;
+    return DEFAULT_TIMEOUT_S * 1000;
   }
 
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== value) {
-    cliError("INVALID_OPTION", "--timeout must be a positive integer.");
+  const parsed = Number.parseFloat(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    cliError("INVALID_OPTION", "--timeout must be a positive number.");
   }
 
-  return parsed;
+  return Math.round(parsed * 1000);
 }
 
 function validateCommonOptions() {
@@ -214,7 +214,7 @@ async function waitForReadyState(driver: WebDriver) {
   } catch {
     cliError(
       "WAIT_TIMEOUT",
-      `Timed out after ${timeoutMs}ms waiting for --wait-until=${waitUntil}`,
+      `Timed out after ${timeoutMs / 1000}s waiting for --wait-until=${waitUntil}`,
     );
   }
 }
@@ -243,7 +243,7 @@ async function waitForJs(driver: WebDriver) {
 
   cliError(
     "WAIT_TIMEOUT",
-    `Timed out after ${timeoutMs}ms waiting for --wait-js`,
+    `Timed out after ${timeoutMs / 1000}s waiting for --wait-js`,
   );
 }
 
diff --git a/test/smoke.js b/test/smoke.js
index 5944a61..15976a8 100755
--- a/test/smoke.js
+++ b/test/smoke.js
@@ -254,7 +254,7 @@ test(
 
     assert.equal(output.ok, false);
     assert.equal(output.error.code, "INVALID_OPTION");
-    assert.match(output.error.message, /--timeout must be a positive integer/);
+    assert.match(output.error.message, /--timeout must be a positive number/);
     assert.equal(typeof output.elapsedMs, "number");
   },
 );
@@ -290,7 +290,7 @@ test("wait-js timeout returns wait timeout", ["wait", "errors"], () => {
     dataHtml("<title>Hello</title>"),
     "--no-reader",
     "--wait-js=return false",
-    "--timeout=1",
+    "--timeout=0.001",
   ]);
 
   assert.equal(output.ok, false);