@inetafrica/open-claudia 3.5.20 → 3.5.24

package/.env.example

@@ -74,12 +74,17 @@ USAGE_ALERT_COOLDOWN_MS=1800000
 # when a window's use passes these percentages, once per window (off = never).
 LIMIT_WARN_PERCENTS=80,95
 # A message a usage limit stopped is picked up when the limit resets, unless
-# the person writes again first: on (default) | off.
+# the person writes again first: on (default) | off. Scheduled runs and the
+# dream's AI step always wait for the reset.
 LIMIT_PICKUP=on
-# Seconds after the reset before it runs (default 120); a reset further out
-# than LIMIT_PICKUP_MAX_WAIT_H hours (default 192) is not waited for.
+# Seconds after the reset before waiting work runs (default 120); a reset
+# further out than LIMIT_PICKUP_MAX_WAIT_H hours (default 192) is not waited
+# for. One rule for chat messages, scheduled runs and the dream.
 LIMIT_PICKUP_DELAY_S=120
 LIMIT_PICKUP_MAX_WAIT_H=192
+# Messages sent while a conversation is busy run together as one turn when it
+# ends (on, default); off runs them one at a time.
+QUEUE_BATCH=on
 MEMORY_RECALL_MAX_CHARS=9000
 # Default recall engine when a chat hasn't picked one with /engine: classic | discoverer
 RECALL_ENGINE=classic

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 3.5.24
+
+The Browser app's address bar, and Chrome in its own container (Sumeet, 9 Oct 21:27 EAT on his phone: "I can't change the url on the mobile app"). A canary build for the Browser canary bot first; the fleet waits for his OK.
+
+- **The driver can change the page.** `POST /api/browser/navigate` (open, back, forward, reload) for the person who has taken over, from Agent Space's address bar. Public internet addresses only (`core/browser-address.js`): http or https, no user name or password; no localhost, single-label, .local, .internal, .svc or .home.arpa name; no private, loopback, link-local, shared, benchmarking, multicast or reserved IP, typed in any form the URL parser reads or found in any of the name's DNS answers (3 s at most). It needs the driver's live lock and extends it, runs in order with the driver's input, gives the page 20 s, and logs origin and path only. Teach me records it as a step ("Go to …"). `GET /api/browser/control` says `navigate: true`.
+- **One way to run agent-browser on the bot's own sessions** (`core/agent-browser-cli.js`): Teach me's element lookup and the address bar run it with the agent's environment and only `--session`, `--json` and a command, so no launch setting can ride along. On a bot pod a session reached with other launch settings is relaunched and loses its page.
+- **The agent gets agent-browser's settings.** Every `AGENT_BROWSER_*` variable now reaches the agent process (provider credentials and control-plane tokens are still stripped after), so its own browser commands and the Browser app share one set of launch settings. On a pod the agent used to run agent-browser without the image's `AGENT_BROWSER_EXECUTABLE_PATH`.
+- **Container mode.** With Agent Space's browser container (`AGENT_BROWSER_CDP`, `AGENT_BROWSER_PIN_TAB`), Chrome runs in its own container without the bot's files or keys and every agent-browser call attaches to it, each session pinned to its own tab. One Chrome window paints only its front tab, so opening a viewer brings that session's tab forward (Chrome's `/json/activate`, loopback only). The prompt now says how this bot's Chrome really runs, and no longer claims agent-browser adds `--no-sandbox` by itself.
+- **Tests:** `test-browser-address.js` (new), `test-browser-control.js`, `test-browser-teach.js`, `test-web-browser-app.js`, `test-browser-view.js`, `test-kazee-bot-apps.js`, `test-provider-env-isolation.js`.
+
+## 3.5.23
+
+Usage limits as one rule, /stop as a real cancel, the queue's ✕ and run-together, and background checks on Haiku 5.5 and Sonnet 5.5 (Sumeet, 9 Oct 15:56 EAT: "yeh release and upgrade all the bots, include rahil for the updates going forward"). 3.5.20 below, the Browser app, only ever went out as a canary build, so this is the first release that brings it to everyone. 3.5.21 and 3.5.22 were tagged with the same changes but never published: 3.5.21's build stopped on the new /stop and queue test, which needed the fake agent its neighbours run on (CI has no Claude or Codex installed), and 3.5.22's builds stopped on two timing checks that busy build machines pushed past their limits (the boot matrix's 30 s per boot, the /stop test's 3 s and 2.5 s windows); those checks now allow more time.
+
+Usage limits as one runtime rule (Sumeet, 9 Oct 2026 after the 07:00 dream failed on his bots: "it should use whatever the active model is … if the Claude model's out of usage … we can't assume that the other will be available … do the standard wake up, the delay until the bot's session has been replenished … the handling of session limits working as a foundational concept rather than just being hacks"). On 9 Oct the 07:00 dream's AI step failed on 18 of 24 fleet bots: Codex bots dreamed on a signed-out Claude, used-up limits failed instead of waiting, and Claude Code's refresh-lock race was final. No chats failed.
+
+- **Work a usage limit stops waits for the reset, the same way everywhere.** One rule (`core/usage-limits.js` `limitRetryAt`: 2 minutes after the reset, `LIMIT_PICKUP_DELAY_S`; never a reset more than `LIMIT_PICKUP_MAX_WAIT_H`, 192 h, away) now serves a chat message (the 3.5.18 pick-up), a scheduled run and the dream. Never on the other provider: it may not be signed in, or be used up too.
+- **A scheduled run a limit stops waits for the reset.** A wake-up, watch or cron that hit a limit used to retry every 30 s and give up after its attempts ("gave up and will not fire"). It now waits in the jobs store until the reset ("⏳ Claude's weekly limit is used up, so this scheduled run waits. I'll run it at 11:02, when it resets."), without using up an attempt; a cron's ticks meanwhile start nothing; the run after the reset is told it waited, and a reset that is used up again waits again, at most 5 times.
+- **The dream's AI step waits for the reset.** The automatic filing and graph upkeep run on time; the AI-led merges and self-review run after the reset ("⏳ Codex's weekly limit is used up, so the AI-led merges wait for its reset: I'll run them tomorrow at 11:02."), on a timer kept in the dream state, so a restart keeps it. A sign-in that died says so plainly ("Claude's sign-in on this bot has expired (send /login to sign in again)").
+- **Background work with nobody behind it runs on the bot's own provider.** The dream, introspection and other checks outside any chat now use the provider the owner chats on (`/backend`, `/login`), else the one a new chat starts on. They used to take the first provider that did not look signed out, which on a Codex bot was a signed-out Claude.
+- **A signed-out Claude reads as signed out.** `claude auth status` prints `{"loggedIn": false}` (Claude Code 2.1), which no check matched, so the bot read it as "unknown" and still chose Claude.
+- **One reading of a provider's failure for chats and background calls** (`providerFailureCode`). Background calls now see a plan limit as `PROVIDER_USAGE_LIMIT` with its reset time (it was a plain `UTILITY_PROVIDER_ERROR`). A dead sign-in ("Failed to authenticate: OAuth session expired and could not be refreshed", "OAuth access token is invalid", Codex's "Your authentication token has expired") is a sign-in error in chats and background calls alike, so a chat gets the /login help instead of a raw error. Claude Code's refresh-lock race ("another Claude Code process is refreshing it") gets one more try, 20 s later, in work nobody waits on (the dream, memory review, sub-agents); a chat's own checks go without rather than hold the reply up.
+- **A limit is recorded for every waiter.** Any run a limit stops (a chat turn, a scheduled run, a background call) records the provider as used up until its reset (`usage-limits.json` `blocks`); background calls do not start it until then, and any run on it that works clears the record. Chat turns never read the record: they always try, so the provider stays the judge. A weekly Opus limit stops only Opus calls.
+- **Tests:** `test-limit-waits.js` (new: background calls through the fake Claude CLI, scheduled runs, the dream and its timer, provider choice with nobody behind a call, the signed-out status), `test-usage-limits.js` (the rule and the record), `test-provider-events.js` (Claude Code 2.1.280's own sign-in and refresh-race wording); the fake agent CLI gains a `provider-error` scenario (`FAKE_AGENT_ERROR_TEXT`, `FAKE_AGENT_ERROR_ONCE_FILE`).
+
+/stop and the queue (Sumeet, 9 Oct 14:18 EAT, with a screenshot of home pi: "it doesn't seem to understand i cancelled something … one for a queued message a small card with delete queued … i can delete message 2 and 4 arbitrarily from the queue … when the turn finishes … get all the messages that are queued at once? no point of them coming in series is there?").
+
+- **A /stop is a cancel, not a cut.** /stop kills the provider mid-turn. On the next message Claude Code resumes the session and writes the stopped turn into the history the way a restart's cut reads ("[Request interrupted by user for tool use]", then "Continue from where you left off."), and the system prompt (since 3.5.11) says to finish work a restart cut off. So the stopped request came back: home pi answered the message after "/stop" on "ok play big bang" with "Big Bang didn't start … Just say if you still want it." /stop now marks the conversation in its turn-journal file (kept across a restart), and the conversation's next turn opens with a note that the person stopped that request and it is cancelled; the system prompt says so too. A stop before the provider started, or of a compaction, leaves no note; `/new`, `/end` and a project change drop it.
+- **Each "Queued." notice has a ✕ Remove from queue button.** It takes that one message out of the queue, so of four queued messages the second and fourth can go while the others stay ("Removed from the queue: "…""). Only the person who sent it, or the owner, can remove it; a message that already started says so.
+- **Queued messages run together.** When a turn ends, the messages the person sent meanwhile run as one turn ("3 messages arrived while you were busy … where a later one changes or cancels an earlier one, the later one wins"), in order, with every image and file, the reply answering the newest. They used to run one turn each, in series, each without the others. Only the same person's plain chat messages in the same session, project, provider and model join (a scheduled run, a side chat's follow-up, a limit pick-up and a live call run on their own), at most 10 per turn. `QUEUE_BATCH=off` runs them one at a time again.
+- **Tests:** `test-stop-queue.js` (new: the note after a /stop, once, kept on disk, not after `/new` or a stop before the provider started; three queued messages as one turn with no journal leftovers; ✕ on two of four; who may press; what joins a batch), `test-turn-journal.js` (the stop survives a restart's boot pass); the fake agent CLI logs every `[[tag:…]]` in a prompt and `FAKE_AGENT_PROMPT_PROBES` matches.
+
+Background checks on Claude Haiku 5.5 and Sonnet 5.5 (Sumeet, 9 Oct 14:51 EAT: "check if anything using haiku and have it shifted to the new haiku 5.5", then 15:36: "sonnet should also be just 5.5").
+
+- **The low tier is Claude Haiku 5.5** (`claude-haiku-5-5`, was `claude-haiku-4-5-20251001`): the recall router and its warm walker, the recall filter, passive group replies, thread titles, the memory duplicate check and the agency deliberation. List price $0.10 / $0.50 per million tokens for prompts up to 100,000 tokens ($0.50 / $2.50 above), against $1 / $5 for Haiku 4.5. Checked live through the utility agent and Claude Code 2.1.280: a structured duplicate-check reply and a plain thread title, about 5 s each. The /model picker offers Haiku 5.5 instead of 4.5; a typed `/model claude-haiku-4-5-20251001` still works.
+- **The medium tier is Claude Sonnet 5.5** (`claude-sonnet-5-5`, was `claude-sonnet-4-6`): the post-turn memory reviewer, the tool-rule guard and `open-claudia agent` sub-agents. List price $2 / $10 per million tokens, cache reads $0.10, against $3 / $15 and $0.30 for Sonnet 4.6; Sonnet 5.5 uses the newer tokenizer (about 30% more tokens for the same text), so a call costs roughly 15% less on fresh input and output and over half less on cache reads. The /model picker offers Sonnet 5.5 instead of 4.6; a typed `/model claude-sonnet-4-6` still works. A weekly Sonnet limit still stops only Sonnet work.
+
 ## 3.5.20
 
 The Browser app in Kazee Chat, bot apps v1 (Sumeet, 9 Oct 12:02 EAT: "fine go ahead and push but also ensure you clear the images after they all done"). Kazee Chat opens it through Agent Space, which calls these pod routes with the control token.

package/README.md

@@ -346,7 +346,7 @@ Unsupported optional controls return a provider-specific explanation and do not
 
 ## Utility provider policy
 
-Background intelligence—sub-agents, recall, memory review, dream/introspection, and the external-person enforcer—uses one provider-selection policy. A per-purpose override is checked first, then `UTILITY_PROVIDER` (default `active`), the active foreground provider when a chat exists, and `DEFAULT_PROVIDER` for global jobs. Providers translate the neutral `low`, `medium`, and `high` tiers to their own models; exact per-provider model overrides remain available.
+Background intelligence—sub-agents, recall, memory review, dream/introspection, and the external-person enforcer—uses one provider-selection policy. A per-purpose override is checked first, then `UTILITY_PROVIDER` (default `active`): the speaker's provider when a chat exists, and for work with nobody behind it (the dream, introspection) the provider the owner chats on, else `DEFAULT_PROVIDER`, else the one a new chat starts on. A provider a usage limit has used up is not started for background work until its reset; such work waits for the reset (the dream) or goes without (a recall check), and never moves to the other provider. Providers translate the neutral `low`, `medium`, and `high` tiers to their own models; exact per-provider model overrides remain available.
 
 Foreground turns never silently fall back to a different provider. Utility work uses `PROVIDER_FALLBACKS` only when the operator explicitly supplies an ordered list, starts a fresh provider session, and records the provider/model used. The relationship enforcer may try that configured list, but total failure always fails closed and asks the owner to decide.
 
@@ -455,7 +455,8 @@ All stored in `~/.open-claudia/`:
 | `USAGE_ALERT_BASELINE_TURNS` / `USAGE_ALERT_MIN_BASELINE_TURNS` / `USAGE_ALERT_COOLDOWN_MS` | No | Tune token-rate baseline size, minimum sample size, and alert cooldown |
 | `LIMIT_WARN_PERCENTS` | No | Plan-limit warnings in the chat: comma-separated percentages of a 5-hour or weekly window (default `80,95`, `off` disables). Each is said once per window, after the reply that crossed it; never to an outside contact |
 | `LIMIT_PICKUP` | No | `on` (default) or `off`. A message a Claude or Codex usage limit stopped is picked up when the limit resets; the person writing again in that conversation, `/stop`, `/new` or `/end` drops it, and a new limit hit arms it again |
-| `LIMIT_PICKUP_DELAY_S` / `LIMIT_PICKUP_MAX_WAIT_H` | No | Seconds after the reset before the pick-up runs (default `120`); resets further out than this many hours (default `192`) are not waited for |
+| `LIMIT_PICKUP_DELAY_S` / `LIMIT_PICKUP_MAX_WAIT_H` | No | Seconds after the reset before waiting work runs (default `120`); resets further out than this many hours (default `192`) are not waited for. One rule for a picked-up message, a scheduled run a limit stopped (it waits instead of failing) and the dream's AI step |
+| `QUEUE_BATCH` | No | `on` (default) or `off`. Messages a person sends while their conversation is busy run together as one turn when it ends (the same person's plain chat messages, at most 10); `off` runs them one at a time. Each "Queued." notice has a ✕ Remove from queue button either way |
 | `MEMORY_RECALL_MAX_CHARS` | No | Hard cap for auto-injected pack/entity memory per turn (default `9000`, `off` disables auto recall injection) |
 | `RECALL_ENGINE` | No | Default recall engine when a chat hasn't set one via `/engine` (`classic` or `discoverer`, default `discoverer`) |
 | `RECALL_GRAPH_DB` / `RECALL_METRICS` | No | Override the discoverer graph DB path; `off` on metrics disables per-turn recall logging |
@@ -468,11 +469,11 @@ All stored in `~/.open-claudia/`:
 | `TRANSCRIPT_MAX_ENTRY_CHARS` | No | Max chars per transcript entry (default `12000`) |
 | `TRANSCRIPTS_DIR` / `PACKS_DIR` / `ENTITIES_DIR` | No | Override storage directories |
 | `PACK_REVIEW` | No | `off` disables the post-turn pack/entity reviewer (default on) |
-| `PACK_REVIEW_MODEL` | No | Model for the reviewer (default `haiku`) |
+| `PACK_REVIEW_MODEL` | No | Model for the reviewer (default: the provider's medium tier, `claude-sonnet-5-5` on Claude). Background checks without a model of their own use the low tier: `claude-haiku-5-5` on Claude |
 | `PACK_MATCH_THRESHOLD` / `ENTITY_MATCH_THRESHOLD` | No | Router match score thresholds (default `2`) |
 | `DREAM` | No | `off` disables the nightly memory consolidation pass (default on) |
 | `DREAM_CRON` | No | Schedule for the dream pass (default `0 4 * * *`) |
-| `DREAM_PROVIDER` | No | Provider for dream and introspection (`claude` or `codex`); otherwise scheduled work resolves through `DEFAULT_PROVIDER` |
+| `DREAM_PROVIDER` | No | Provider for dream and introspection (`claude` or `codex`); otherwise the provider the owner chats on, then `DEFAULT_PROVIDER` |
 | `DREAM_MODEL_CLAUDE` / `DREAM_MODEL_CODEX` | No | Exact per-provider dream model override; legacy `DREAM_MODEL` remains a Claude-only compatibility alias |
 | `DREAM_TIER` | No | Provider-owned model tier for the dream pass: `low`, `medium`, or `high` (default) |
 | `DREAM_FULL_SWEEP_DAYS` | No | Days between full-corpus dream sweeps; other nights are cheap deltas over recently-touched packs (default `30`) |

package/core/actions.js

@@ -918,6 +918,10 @@ async function handleAction(envelope) {
   if (d.startsWith("rq:")) {
     return require("./turn-journal").handleRunDropped(d, envelope, { isOwner: isChatOwner(envelope.channelId) });
   }
+  // The ✕ on a "Queued." notice: take that message out of the queue.
+  if (d.startsWith("qx:")) {
+    return require("./runner").handleQueueRemove(d, envelope, { isOwner: isChatOwner(envelope.channelId) });
+  }
   if (d.startsWith("grd:")) {
     // Guardrail capture buttons (Track C). Owner-only: standing rules layer
     // above lessons and are never editable by an external speaker.

package/core/agent-browser-cli.js

@@ -0,0 +1,98 @@
+// The bot's own agent-browser CLI calls on a session its agent already has open: Teach me's element
+// lookup (core/browser-teach.js) and the Browser app's address bar (core/browser-control.js).
+//
+// agent-browser keeps one browser per session and remembers the settings it was launched with
+// (the executable, its launch args, the idle timeout). A command that arrives with other launch
+// settings restarts that browser, and the person's page is lost. So every call from here runs
+// with the environment the bot's own agent-browser commands get, and never with a launch flag
+// (--args, --idle-timeout, --executable-path, --headed, --cdp, ...): only what the CLI needs goes
+// along (PATH, HOME, TMPDIR, LANG, LC_ALL, USER and every AGENT_BROWSER_* variable), none of the
+// bot's tokens, and no XDG_RUNTIME_DIR (the agent's own commands run without it). The session is
+// found by its socket folder, the one it was listed from: AGENT_BROWSER_SOCKET_DIR. Without that
+// folder nothing runs, since agent-browser starts a new browser for a session it cannot find.
+
+const childProcess = require("child_process");
+const { SESSION_NAME } = require("./browser-view");
+
+const ENV_KEYS = new Set(["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "USER"]);
+const DEFAULT_TIMEOUT_MS = 20 * 1000;
+// After a kill the CLI's output can stay open (a child of its own holding it); the call settles
+// this long after its time is up all the same, so a session's queue never waits on it for good.
+const SETTLE_GRACE_MS = 2000;
+const MAX_BUFFER = 512 * 1024;
+// The only dash argument a command may carry: eval's -b (a base64 script follows).
+const COMMAND_FLAGS = new Set(["-b"]);
+
+function agentBrowserBin() {
+  return process.env.OC_AGENT_BROWSER_BIN || "agent-browser";
+}
+
+function agentBrowserEnv(session) {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (ENV_KEYS.has(key) || key.startsWith("AGENT_BROWSER_")) env[key] = value;
+  }
+  if (session && session.dir) env.AGENT_BROWSER_SOCKET_DIR = session.dir;
+  return env;
+}
+
+// ["--session", <name>, ("--json"), <command>, <its arguments>...]. The command's own arguments
+// (an address, a script) are never flags, so no launch setting can ride along; null when the
+// session name or the command is not one of these.
+function commandArgs(session, command, { json = false } = {}) {
+  const name = String((session && session.name) || "");
+  if (!SESSION_NAME.test(name) || name.startsWith("-")) return null;
+  if (!Array.isArray(command) || !command.length || !/^[a-z]+$/.test(String(command[0]))) return null;
+  for (const arg of command.slice(1)) {
+    if (typeof arg !== "string" || (arg.startsWith("-") && !COMMAND_FLAGS.has(arg))) return null;
+  }
+  return ["--session", name, ...(json ? ["--json"] : []), ...command];
+}
+
+// Run `agent-browser --session <name> [--json] <command...>` on that session:
+// { ok, stdout, timedOut }. Never rejects. A call past timeoutMs is killed (SIGKILL).
+function runAgentBrowser(session, command, { json = false, timeoutMs = DEFAULT_TIMEOUT_MS, maxBuffer = MAX_BUFFER, execFile = childProcess.execFile } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let guard = null;
+    const done = (ok, stdout, timedOut) => {
+      if (settled) return;
+      settled = true;
+      if (guard) clearTimeout(guard);
+      resolve({ ok, stdout: ok ? String(stdout || "") : "", timedOut });
+    };
+    const args = commandArgs(session, command, { json });
+    if (!args || !session.dir) return done(false, "", false);
+    let child = null;
+    try {
+      child = execFile(agentBrowserBin(), args, {
+        env: agentBrowserEnv(session),
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer,
+        windowsHide: true,
+      }, (error, stdout) => {
+        if (!error) return done(true, stdout, false);
+        done(false, "", error.killed === true && error.code !== "ERR_CHILD_PROCESS_STDIO_MAXBUFFER");
+      });
+    } catch (_) {
+      return done(false, "", false);
+    }
+    if (child && typeof child.on === "function") child.on("error", () => { /* reported through the callback */ });
+    if (child && child.stdin) child.stdin.end();
+    if (settled) return;
+    guard = setTimeout(() => {
+      try { if (child && typeof child.kill === "function") child.kill("SIGKILL"); } catch (_) { /* already gone */ }
+      done(false, "", true);
+    }, timeoutMs + SETTLE_GRACE_MS);
+    if (guard.unref) guard.unref();
+  });
+}
+
+module.exports = {
+  DEFAULT_TIMEOUT_MS,
+  agentBrowserBin,
+  agentBrowserEnv,
+  commandArgs,
+  runAgentBrowser,
+};

package/core/auth-flow.js

@@ -109,7 +109,12 @@ function looksLikeOpenAIKey(value) {
 
 function isClaudeAuthErrorText(text) {
   const lower = String(text || "").toLowerCase();
-  return lower.includes("unauthorized") ||
+  // `claude auth status` prints JSON in Claude Code 2.1: signed out it is
+  // {"loggedIn": false, "authMethod": "none"} (exit 1), which no phrase below
+  // matched, so a signed-out Claude read as "unknown" and was still chosen
+  // (9 Oct 2026: the dream of every Codex-only bot ran on Claude).
+  return /"loggedin"\s*:\s*false/.test(lower) ||
+    lower.includes("unauthorized") ||
     lower.includes("not logged in") ||
     lower.includes("login required") ||
     lower.includes("reauthenticate") ||
@@ -145,7 +150,7 @@ function summarizeAuthOutput(output, ok) {
 function summarizeClaudeAuthStatus(output, exitCode, tokenInfo) {
   const text = String(output || "");
   const lower = text.toLowerCase();
-  const loggedOut = /not (logged in|authenticated)|unauthenticated|no auth|login required/.test(lower);
+  const loggedOut = /not (logged in|authenticated)|unauthenticated|no auth|login required|"loggedin"\s*:\s*false/.test(lower);
   const loggedIn = !loggedOut && (exitCode === 0 || /logged in|authenticated|claude\.ai|anthropic/.test(lower));
   const email = (text.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i) || [null])[0];
   const provider = /claude\.ai|claudeai/.test(lower) ? "Claude.ai" : (/anthropic/.test(lower) ? "Anthropic" : "unknown");

package/core/browser-address.js

@@ -0,0 +1,171 @@
+// Where the Browser app's address bar may go (core/browser-control.js navigate): public internet
+// addresses only. The bot's browser runs inside the pod, next to the cluster's services and the
+// cloud's metadata endpoint, so a typed address must not reach what a person outside could not:
+//   - http or https, at most 2048 characters, no user name or password in it;
+//   - no localhost, no single-label name, nothing under .localhost, .local, .internal, .svc,
+//     .cluster.local or .home.arpa;
+//   - no private, loopback, link-local, shared, benchmarking, multicast or reserved IP: typed as
+//     one in any form the URL parser reads as an IP (decimal, octal or hex IPv4, IPv6, IPv4 inside
+//     IPv6), or found in ANY of the name's DNS answers (A and AAAA, 3 s at most).
+//
+// parseAddress(raw)            { url, lookupName } | { error: "bad-url" | "blocked-address" }
+//                              No network: lookupName is the name still to resolve, null for an IP.
+// resolveAddress(name)         { addresses } | { error: "blocked-address" | "unknown-host" }
+// checkAddress(raw)            both: { ok: true, url, addresses } | { ok: false, error }
+//
+// The browser resolves the name again when it loads the page; this check keeps a typed address
+// from reaching the inside, it does not follow redirects.
+
+const dns = require("dns");
+const net = require("net");
+
+const MAX_URL_LENGTH = 2048;
+const DNS_TIMEOUT_MS = 3000;
+
+function v4Bytes(text) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(String(text));
+  if (!m) return null;
+  const bytes = m.slice(1).map(Number);
+  return bytes.every((b) => b <= 255) ? bytes : null;
+}
+
+function v4Number(bytes) {
+  return ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0;
+}
+
+const BLOCKED_V4 = [
+  ["0.0.0.0", 8], // "this network"
+  ["10.0.0.0", 8], // private
+  ["100.64.0.0", 10], // shared address space (carrier-grade NAT)
+  ["127.0.0.0", 8], // loopback
+  ["169.254.0.0", 16], // link-local, the cloud metadata endpoint
+  ["172.16.0.0", 12], // private
+  ["192.0.0.0", 24], // IETF protocol assignments
+  ["192.168.0.0", 16], // private
+  ["198.18.0.0", 15], // benchmarking
+  ["224.0.0.0", 4], // multicast
+  ["240.0.0.0", 4], // reserved
+  ["255.255.255.255", 32], // broadcast
+].map(([base, bits]) => ({ base: v4Number(v4Bytes(base)), mask: (0xffffffff << (32 - bits)) >>> 0 }));
+
+function v4Blocked(bytes) {
+  const n = v4Number(bytes);
+  return BLOCKED_V4.some(({ base, mask }) => ((n & mask) >>> 0) === base);
+}
+
+// The eight 16-bit words of an IPv6 address (brackets and a zone allowed), or null.
+function v6Words(text) {
+  let s = String(text).replace(/^\[(.*)\]$/, "$1").replace(/%.*$/, "");
+  if (!net.isIPv6(s)) return null;
+  const tail = /^(.*:)(\d{1,3}(?:\.\d{1,3}){3})$/.exec(s);
+  if (tail) {
+    const b = v4Bytes(tail[2]);
+    if (!b) return null;
+    s = `${tail[1]}${((b[0] << 8) | b[1]).toString(16)}:${((b[2] << 8) | b[3]).toString(16)}`;
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const rest = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const fill = halves.length === 2 ? 8 - head.length - rest.length : 0;
+  if (fill < 0) return null;
+  const words = [...head, ...Array(fill).fill("0"), ...rest].map((h) => (/^[0-9a-f]{1,4}$/i.test(h) ? parseInt(h, 16) : NaN));
+  return words.length === 8 && words.every(Number.isInteger) ? words : null;
+}
+
+function v6Blocked(words) {
+  const zero = (from, to) => words.slice(from, to).every((w) => w === 0);
+  if (zero(0, 8)) return true; // ::
+  if (zero(0, 7) && words[7] === 1) return true; // ::1
+  if ((words[0] & 0xfe00) === 0xfc00) return true; // fc00::/7, unique local
+  if ((words[0] & 0xffc0) === 0xfe80) return true; // fe80::/10, link-local
+  if ((words[0] & 0xff00) === 0xff00) return true; // ff00::/8, multicast
+  const v4 = [words[6] >> 8, words[6] & 0xff, words[7] >> 8, words[7] & 0xff];
+  if (zero(0, 5) && words[5] === 0xffff) return v4Blocked(v4); // ::ffff:a.b.c.d, IPv4-mapped
+  if (zero(0, 6)) return v4Blocked(v4); // ::a.b.c.d, IPv4-compatible
+  if (words[0] === 0x64 && words[1] === 0xff9b && zero(2, 6)) return v4Blocked(v4); // 64:ff9b::/96, NAT64
+  return false;
+}
+
+// Is this IP (as text) off limits? Anything that is not an IP is.
+function ipBlocked(ip) {
+  const text = String(ip == null ? "" : ip);
+  if (net.isIPv4(text)) return v4Blocked(v4Bytes(text));
+  const words = v6Words(text);
+  return words ? v6Blocked(words) : true;
+}
+
+// A name that never means the public internet (an IP is judged by ipBlocked instead).
+function blockedName(hostname) {
+  const host = String(hostname || "").toLowerCase().replace(/\.+$/, "");
+  if (!host.includes(".")) return true; // localhost, a bare name: a machine or a Service nearby
+  return /(^|\.)(localhost|local|internal|svc|home\.arpa)$/.test(host); // .local covers .cluster.local
+}
+
+function parseAddress(raw) {
+  if (typeof raw !== "string" || !raw.trim() || raw.length > MAX_URL_LENGTH) return { error: "bad-url" };
+  let url;
+  try {
+    url = new URL(raw);
+  } catch (_) {
+    return { error: "bad-url" };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return { error: "bad-url" };
+  if (url.username || url.password || !url.hostname) return { error: "bad-url" };
+  const host = url.hostname; // the URL parser's own reading: IPv4 in dotted decimal, IPv6 in brackets
+  if (host.startsWith("[")) {
+    const words = v6Words(host);
+    if (!words) return { error: "bad-url" };
+    return v6Blocked(words) ? { error: "blocked-address" } : { url, lookupName: null };
+  }
+  if (net.isIPv4(host)) return v4Blocked(v4Bytes(host)) ? { error: "blocked-address" } : { url, lookupName: null };
+  if (blockedName(host)) return { error: "blocked-address" };
+  return { url, lookupName: host };
+}
+
+function defaultLookup(hostname, options) {
+  return dns.promises.lookup(hostname, options);
+}
+
+function withTimeout(promise, ms) {
+  let timer = null;
+  const late = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error("timed out")), ms);
+  });
+  return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+
+// Every A and AAAA answer must be public; none at all (or no answer in time) is unknown.
+async function resolveAddress(hostname, { lookup = defaultLookup, timeoutMs = DNS_TIMEOUT_MS } = {}) {
+  let answers;
+  try {
+    answers = await withTimeout(Promise.resolve().then(() => lookup(hostname, { all: true })), timeoutMs);
+  } catch (_) {
+    return { error: "unknown-host" };
+  }
+  const addresses = (Array.isArray(answers) ? answers : [answers])
+    .filter((a) => a != null)
+    .map((a) => (typeof a === "object" ? a.address : a));
+  if (!addresses.length) return { error: "unknown-host" };
+  if (addresses.some((a) => typeof a !== "string" || ipBlocked(a))) return { error: "blocked-address" };
+  return { addresses };
+}
+
+async function checkAddress(raw, options = {}) {
+  const parsed = parseAddress(raw);
+  if (parsed.error) return { ok: false, error: parsed.error };
+  if (!parsed.lookupName) return { ok: true, url: parsed.url, addresses: [parsed.url.hostname.replace(/^\[(.*)\]$/, "$1")] };
+  const found = await resolveAddress(parsed.lookupName, options);
+  if (found.error) return { ok: false, error: found.error };
+  return { ok: true, url: parsed.url, addresses: found.addresses };
+}
+
+module.exports = {
+  DNS_TIMEOUT_MS,
+  MAX_URL_LENGTH,
+  blockedName,
+  checkAddress,
+  ipBlocked,
+  parseAddress,
+  resolveAddress,
+};

package/core/browser-control.js

@@ -7,7 +7,12 @@
 //     the browser. It lasts 120 s; the page's heartbeat and every accepted input extend it.
 //   - one input WebSocket per agent-browser session (ws://127.0.0.1:<port>/?maxFps=2): events
 //     are checked strictly, field by field, and forwarded in order. The same socket keeps the
-//     latest frame, which Teach me saves as a click's picture.
+//     latest frame, which Teach me saves as a click's (or a navigation's) picture.
+//   - the address bar: go to an address, back, forward, reload. The stream socket only takes
+//     input, so these are agent-browser commands on the same session, run in the session's queue
+//     after the input before them, with the bot's own agent-browser environment and never a
+//     launch flag (core/agent-browser-cli.js: other launch settings would restart the browser).
+//     Only public internet addresses (core/browser-address.js).
 //   - hand back (release, a closed panel, or a lock found expired by the 30 s sweeper): the lock
 //     goes, the socket closes, any recording stops, and the bot is woken in the person's own chat
 //     to carry on (C6). A recording stopped at the same time folds into one wake-up.
@@ -19,6 +24,8 @@ const WebSocket = require("ws");
 const lockFile = require("./browser-lock");
 const view = require("./browser-view");
 const teach = require("./browser-teach");
+const address = require("./browser-address");
+const { runAgentBrowser } = require("./agent-browser-cli");
 
 const LOCK_TTL_MS = lockFile.LOCK_TTL_MS;
 // Inputs extend the lock; the file (fsynced) is rewritten at most this often, so the lock ends
@@ -31,19 +38,29 @@ const MAX_EVENTS = 50;
 const MAX_PENDING_EVENTS = 1000;
 const COORD_MAX = 10000;
 const ID_RE = /^[A-Za-z0-9._:-]{1,100}$/;
+// An address-bar command still running after this is killed, and the person told it failed.
+const NAVIGATE_TIMEOUT_MS = 20 * 1000;
+const NAVIGATIONS = new Set(["open", "back", "forward", "reload"]);
 
 const HAND_BACK_REASONS = {
   closed: " (they closed the Browser)",
   expired: " (their Browser went quiet for 2 minutes, so control came back on its own)",
 };
 
-let deps = {
-  now: () => Date.now(),
-  listSessions: () => view.listSessions(),
-  connect: (url) => new WebSocket(url),
-  scheduler: null, // core/scheduler by default (through core/cards.js wakeOrigin)
-  runFor: null, // the chat's provider, settings and live session; activeRun() by default
-};
+function defaultDeps() {
+  return {
+    now: () => Date.now(),
+    listSessions: () => view.listSessions(),
+    connect: (url) => new WebSocket(url),
+    scheduler: null, // core/scheduler by default (through core/cards.js wakeOrigin)
+    runFor: null, // the chat's provider, settings and live session; activeRun() by default
+    execFile: null, // child_process.execFile by default (core/agent-browser-cli.js)
+    lookupHost: null, // dns.promises.lookup by default (core/browser-address.js)
+    navigateTimeoutMs: NAVIGATE_TIMEOUT_MS,
+  };
+}
+
+let deps = defaultDeps();
 
 function reply(status, body) {
   return { status, body };
@@ -70,6 +87,19 @@ function sameUser(lock, who) {
   return !!lock && !!who && String(lock.userId) === String(who.userId);
 }
 
+// The live lock this person holds on this session, extended (every accepted input or navigation
+// extends it; the file is rewritten at most every LOCK_REWRITE_MS), or null.
+function extendDriverLock(session, who) {
+  const now = deps.now();
+  const lock = lockFile.liveLock(now);
+  if (!lock || lock.session !== session || !sameUser(lock, who)) return null;
+  if (lockFile.lockExpiresAt(lock) - now < LOCK_TTL_MS - LOCK_REWRITE_MS) {
+    lock.expiresAt = iso(now + LOCK_TTL_MS);
+    lockFile.writeLock(lock);
+  }
+  return lock;
+}
+
 // ---------------------------------------------------------------------------
 // C3: input events, checked field by field. Only the listed fields are forwarded.
 
@@ -382,12 +412,14 @@ async function control(body = {}) {
   return reply(400, { error: "bad-action" });
 }
 
+// navigate: true tells the front door this bot has the address bar (POST /api/browser/navigate).
 function status() {
   const lock = lockFile.liveLock(deps.now());
   return reply(200, {
     driving: !!lock,
     driver: lock ? { name: lock.name, userId: lock.userId } : null,
     recording: teach.activeSummary(),
+    navigate: true,
   });
 }
 
@@ -403,14 +435,8 @@ async function input({ session, events, who } = {}) {
     if (!msg) return reply(400, { error: "bad-event", index: i });
     messages.push(msg);
   }
-  const now = deps.now();
-  const lock = lockFile.liveLock(now);
-  if (!lock || lock.session !== session || !sameUser(lock, who)) return reply(409, { error: "not-driving" });
-  // Every accepted input extends the lock; the file is rewritten only every few seconds.
-  if (lockFile.lockExpiresAt(lock) - now < LOCK_TTL_MS - LOCK_REWRITE_MS) {
-    lock.expiresAt = iso(now + LOCK_TTL_MS);
-    lockFile.writeLock(lock);
-  }
+  // Every accepted input extends the lock.
+  if (!extendDriverLock(session, who)) return reply(409, { error: "not-driving" });
   if (!messages.length) return reply(200, { ok: true, accepted: 0 });
   const entry = openInputSocket(session);
   if (!entry) return reply(404, { error: "not-running" });
@@ -436,6 +462,72 @@ async function input({ session, events, who } = {}) {
   return job;
 }
 
+// ---------------------------------------------------------------------------
+// The address bar: open an address, back, forward, reload
+
+// Log words. An address is cut to origin + path: query strings and fragments can carry tokens.
+function navigationWords(action, href) {
+  if (action === "open") {
+    const where = view.safePageAddress(href) || "an address";
+    return { done: `went to ${where}`, failed: `go to ${where}` };
+  }
+  if (action === "reload") return { done: "reloaded the page", failed: "reload the page" };
+  return { done: `went ${action}`, failed: `go ${action}` };
+}
+
+// { session, action: "open" | "back" | "forward" | "reload", url (open), who: { userId } }
+async function navigate({ session, action, url, who } = {}) {
+  if (!validSession(session) || !validWho(who)) return reply(400, { error: "bad-request" });
+  if (!NAVIGATIONS.has(action)) return reply(400, { error: "bad-action" });
+  let target = null;
+  if (action === "open") {
+    target = address.parseAddress(url);
+    if (target.error) return reply(target.error === "bad-url" ? 400 : 403, { error: target.error });
+  }
+  // Like an input, a navigation needs the live lock and extends it.
+  if (!extendDriverLock(session, who)) return reply(409, { error: "not-driving" });
+  if (!openInputSocket(session)) return reply(404, { error: "not-running" });
+  // The name is resolved from now on, while the input queued before this still runs.
+  const resolving = target && target.lookupName
+    ? address.resolveAddress(target.lookupName, { lookup: deps.lookupHost || undefined })
+    : null;
+  const href = target ? target.url.href : null;
+  const job = runQueued(session, 1, async () => {
+    if (resolving) {
+      const found = await resolving;
+      if (found.error) return reply(found.error === "unknown-host" ? 400 : 403, { error: found.error });
+    }
+    // agent-browser starts a new browser for a session it does not know: one that ended while
+    // this waited is not asked.
+    const info = sessionInfo(session);
+    if (!info || !info.dir) return reply(404, { error: "not-running" });
+    const recorder = teach.recorderFor(session, who.userId);
+    if (recorder) {
+      const live = sockets.get(session);
+      try {
+        await recorder.onNavigate({ how: action, to: href }, { session: { name: info.name, dir: info.dir }, frame: live && !live.closed ? live.frame : null });
+      } catch (e) {
+        console.error(`[browser] recording a step failed: ${e.message}`);
+      }
+    }
+    const words = navigationWords(action, href);
+    const run = await runAgentBrowser(info, action === "open" ? ["open", href] : [action], {
+      timeoutMs: deps.navigateTimeoutMs,
+      execFile: deps.execFile || undefined,
+    });
+    if (!run.ok) {
+      // Never the command's own output or error: both can repeat the whole address.
+      const why = run.timedOut ? `agent-browser took longer than ${Math.ceil(deps.navigateTimeoutMs / 1000)} s and was stopped` : "agent-browser failed";
+      console.error(`[browser] ${who.userId} could not ${words.failed}: ${why}`);
+      return reply(503, { error: "browser-unavailable" });
+    }
+    console.log(`[browser] ${who.userId} ${words.done}`);
+    return reply(200, { ok: true });
+  });
+  if (!job) return reply(429, { error: "busy" });
+  return job;
+}
+
 // ---------------------------------------------------------------------------
 // C4: Teach me, start / stop / cancel
 
@@ -501,7 +593,8 @@ function startSweeper({ intervalMs = SWEEP_INTERVAL_MS } = {}) {
   return sweepTimer;
 }
 
-// Tests swap the clock, the session list, the socket factory, the scheduler and the run lookup.
+// Tests swap the clock, the session list, the socket factory, the scheduler, the run lookup, the
+// agent-browser call (execFile), the DNS lookup and the address-bar time limit.
 function _setDeps(overrides = {}) {
   deps = { ...deps, ...overrides };
 }
@@ -509,24 +602,20 @@ function _reset() {
   for (const name of [...sockets.keys()]) closeInputSocket(name);
   queues.clear();
   if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
-  deps = {
-    now: () => Date.now(),
-    listSessions: () => view.listSessions(),
-    connect: (url) => new WebSocket(url),
-    scheduler: null,
-    runFor: null,
-  };
+  deps = defaultDeps();
 }
 
 module.exports = {
   LOCK_TTL_MS,
   MAX_EVENTS,
+  NAVIGATE_TIMEOUT_MS,
   SWEEP_INTERVAL_MS,
   checkEvent,
   chatOrigin,
   control,
   handBackLine,
   input,
+  navigate,
   release,
   renew,
   startSweeper,