octo-agent 0.11.2

data/lib/octo/web/ws-dispatcher.js

@@ -0,0 +1,357 @@
+// ── WS event dispatcher ───────────────────────────────────────────────────
+//
+// Consumes events emitted by WS (ws.js) and dispatches them to the right
+// business module (Sessions, Tasks, Skills, Channels, Settings, Brand, ...).
+//
+// Kept as a separate file from ws.js on purpose:
+//   - ws.js is a pure transport layer (connect / send / subscribe / reconnect)
+//   - this file is the application-level router that knows about every
+//     business module. Mixing the two would force ws.js to depend on every
+//     other module, breaking layering.
+//
+// Depends on: WS (ws.js), Sessions, Tasks, Skills, Channels, Settings, Brand,
+//             Router, I18n, global $ / escapeHtml / showConfirmModal helpers.
+// ─────────────────────────────────────────────────────────────────────────
+(function() {
+  // Guard: restore hash routing only once after initial session_list arrives.
+  let _initialRestoreDone = false;
+
+
+WS.onEvent(ev => {
+  console.log("[DEBUG] WS event received:", ev.type, ev);
+  switch (ev.type) {
+
+    // ── Internal WS lifecycle ──────────────────────────────────────────
+    case "_ws_connected": {
+      const banner = document.getElementById("offline-banner");
+      if (banner) banner.style.display = "none";
+      const hint = $("ws-disconnect-hint");
+      if (hint) hint.style.display = "none";
+      break;
+    }
+
+    case "_ws_disconnected": {
+      const banner = document.getElementById("offline-banner");
+      if (banner) {
+        banner.textContent = I18n.t("offline.banner");
+        banner.style.display = "block";
+      }
+      // Do NOT force status bar to "idle" here — on a brief WS hiccup the
+      // agent may still be running, and reconnect will deliver a fresh
+      // session snapshot that patches the real status. Forcing idle here
+      // caused stuck UI after reconnect when the snapshot logic wasn't
+      // re-asserting status on every reconnect.
+      Sessions.clearAllProgress();
+      break;
+    }
+
+    // ── Session list ───────────────────────────────────────────────────
+    case "session_list": {
+      Sessions.setAll(ev.sessions || [], !!ev.has_more, ev.cron_count || 0);
+      Sessions.renderList();
+
+      // Restore URL hash once on initial connect; ignore subsequent session_list events.
+      // Skip if we are already on a session view (e.g. onboard flow navigated there
+      // before WS connected) — restoreFromHash would wrongly redirect to "welcome"
+      // because there is no hash set during onboarding.
+      if (!_initialRestoreDone) {
+        _initialRestoreDone = true;
+        if (Router.current !== "session") {
+          Router.restoreFromHash();
+        }
+      } else {
+        // If active session was deleted, go to welcome
+        if (Sessions.activeId && !Sessions.find(Sessions.activeId)) {
+          Router.navigate("welcome");
+        }
+      }
+      break;
+    }
+
+    // ── Session lifecycle ──────────────────────────────────────────────
+    case "subscribed": {
+      // Re-enable send button now that the server has confirmed the subscription.
+      $("btn-send").disabled = false;
+      $("user-input").focus();
+      // If this session was created by Tasks.run(), fire the agent now that
+      // we're guaranteed to receive its broadcasts.
+      const pendingId = Sessions.takePendingRunTask();
+      if (pendingId && pendingId === ev.session_id) {
+        WS.send({ type: "run_task", session_id: pendingId });
+      }
+      // If a slash-command was queued (e.g. /onboard from first-boot flow),
+      // send it now — after restoreFromHash has settled — so appendMsg won't be wiped.
+      const pendingMsg = Sessions.takePendingMessage();
+      if (pendingMsg && pendingMsg.session_id === ev.session_id) {
+        Sessions.appendMsg("user", escapeHtml(pendingMsg.content), { time: new Date() });
+        WS.send({ type: "message", session_id: pendingMsg.session_id, content: pendingMsg.content });
+      }
+      break;
+    }
+
+    case "session_update": {
+      // Two shapes arrive under this type:
+      //   (1) Full session object from http_server broadcast_session_update:
+      //       { type, session: { id, name, status, total_tasks, ... } }
+      //   (2) Partial real-time update from web_ui_controller (tasks/status):
+      //       { type, session_id, tasks?, status? }
+      let sid, patch;
+      if (ev.session) {
+        // Shape (1): full session — use as-is
+        sid   = ev.session.id;
+        patch = ev.session;
+      } else {
+        // Shape (2): partial update — build patch from top-level fields
+        sid   = ev.session_id;
+        patch = {};
+        if (ev.tasks   !== undefined) patch.total_tasks    = ev.tasks;
+        if (ev.status  !== undefined) patch.status         = ev.status;
+        // Latency pushed by Agent after each LLM call (see update_sessionbar).
+        // Stored under latest_latency — same field name the HTTP /api/sessions
+        // list returns, so updateInfoBar doesn't need to branch on the source.
+        if (ev.latency !== undefined) patch.latest_latency = ev.latency;
+      }
+      if (!sid) break;
+      Sessions.patch(sid, patch);
+      Sessions.renderList();
+      if (sid === Sessions.activeId) {
+        const current = Sessions.find(sid);
+        if (patch.status !== undefined) Sessions.updateStatusBar(patch.status);
+        Sessions.updateInfoBar(current);
+        // Update chat title/subtitle in case session was renamed or working_dir changed
+        Sessions.updateChatHeader(current);
+      }
+      // When a session finishes, refresh tasks and skills, and clear any progress state
+      if (patch.status === "idle") {
+        Tasks.load();
+        Skills.load();
+        // Clear progress state for this session (even if not currently active)
+        Sessions.clearProgress(sid);
+      }
+      break;
+    }
+
+    case "session_renamed": {
+      Sessions.patch(ev.session_id, { name: ev.name });
+      Sessions.renderList();
+      // Title is now shown only in the sidebar; chat-header element was removed.
+      break;
+    }
+
+    case "session_deleted":
+      Sessions.remove(ev.session_id);
+      if (ev.session_id === Sessions.activeId) Router.navigate("welcome");
+      Sessions.renderList();
+      break;
+
+    // ── Chat messages ──────────────────────────────────────────────────
+    case "history_user_message":
+      // During history replay, HistoryCollector sends events via HTTP — they
+      // never hit the WS dispatcher. Events arriving here are always live
+      // (agent just drained a queued message from the inbox). Remove the
+      // ghost bubble and render the real user message.
+      // Only remove the first pending ghost — subsequent ghosts belong
+      // to other queued messages that haven't been drained yet.
+      if (ev.session_id !== Sessions.activeId) break;
+      const firstGhost = document.querySelector(".msg-pending");
+      if (firstGhost) firstGhost.remove();
+      let userHtml = "";
+      if (Array.isArray(ev.images) && ev.images.length > 0) {
+        userHtml += ev.images.map(src => {
+          if (typeof src !== "string" || !src) return "";
+          if (src.startsWith("pdf:")) {
+            const fname = src.slice(4);
+            const lower = fname.toLowerCase();
+            const ext = (fname.split(".").pop() || "file").toUpperCase();
+            const displayExt = lower.endsWith(".tar.gz") ? "TAR.GZ" : ext;
+            const icon = ext === "PDF" ? "📄" :
+              (ext === "ZIP" || ext === "GZ" || ext === "TGZ" || ext === "TAR" ||
+               ext === "RAR" || ext === "7Z" || lower.endsWith(".tar.gz")) ? "🗜️" :
+              (ext === "DOC" || ext === "DOCX") ? "📝" :
+              (ext === "XLS" || ext === "XLSX" || ext === "CSV") ? "📊" :
+              (ext === "PPT" || ext === "PPTX") ? "📋" :
+              (ext === "MD" || ext === "MARKDOWN") ? "📝" :
+              (ext === "TXT" || ext === "LOG") ? "📄" : "📎";
+            return `<span class="msg-pdf-badge">` +
+              `<span class="msg-pdf-badge-icon">${icon}</span>` +
+              `<span class="msg-pdf-badge-info">` +
+                `<span class="msg-pdf-badge-name">${escapeHtml(fname)}</span>` +
+                `<span class="msg-pdf-badge-type">${escapeHtml(displayExt)}</span>` +
+              `</span>` +
+            `</span>`;
+          }
+          if (src.startsWith("expired:")) {
+            const fname = src.slice(8);
+            return `<span class="msg-pdf-badge msg-image-expired">` +
+              `<span class="msg-pdf-badge-icon">🖼️</span>` +
+              `<span class="msg-pdf-badge-info">` +
+                `<span class="msg-pdf-badge-name">${escapeHtml(fname || "image")}</span>` +
+                `<span class="msg-pdf-badge-type">${I18n.t("chat.image_expired") || "Expired"}</span>` +
+              `</span>` +
+            `</span>`;
+          }
+          return `<img src="${escapeHtml(src)}" alt="image" class="msg-image-thumb">`;
+        }).join("");
+        if (ev.content) userHtml += "<br>";
+      }
+      userHtml += escapeHtml(ev.content || "");
+      Sessions.appendMsg("user", userHtml, { time: ev.created_at });
+      break;
+
+    case "pending_user_messages":
+      // Replayed on WebSocket (re)subscribe — messages still in the
+      // inbox queue. Render them as pending ghost bubbles that the
+      // regular history_user_message handler will replace when the
+      // agent drains each one.
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.renderPendingMessages(ev.messages || []);
+      break;
+
+    case "assistant_message":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.clearProgress();
+      Sessions.appendMsg("assistant", ev.content);
+      break;
+
+    case "tool_call":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.clearProgress();
+      Sessions.appendToolCall(ev.name, ev.args, ev.summary);
+      break;
+
+    case "tool_result":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.appendToolResult(ev.result, ev.ui_payload);
+      break;
+
+    case "tool_stdout":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.appendToolStdout(ev.lines);
+      break;
+
+    case "diff":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.appendDiff(ev.diff, ev.truncated);
+      break;
+
+    case "tool_error":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.appendMsg("info", `⚠ Tool error: ${escapeHtml(ev.error)}`);
+      break;
+
+    case "token_usage":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.appendTokenUsage(ev);
+      break;
+
+    case "progress":
+      if (ev.session_id !== Sessions.activeId) break;
+      if (ev.phase === "active" || ev.status === "start") {
+        const progress_type = ev.progress_type || "thinking";
+        const metadata = ev.metadata || {};
+        Sessions.showProgress(ev.message, progress_type, metadata, ev.started_at || null);
+        // A new turn started — any cached suggestion from the previous turn
+        // is stale.
+        Sessions.clearInputSuggestion();
+      } else {
+        Sessions.clearProgress(ev.message);
+      }
+      break;
+
+    case "complete":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.clearProgress();
+      Sessions.collapseToolGroup();
+      {
+        let mainLine = I18n.t("chat.done", { n: ev.iterations });
+        if (typeof ev.duration === "number" && ev.duration > 0) {
+          mainLine += I18n.t("chat.done.duration", { duration: ev.duration.toFixed(1) });
+        }
+        let cacheLine = null;
+        const cs = ev.cache_stats;
+        const total = cs && (cs.total_requests || cs["total_requests"]);
+        const hits = cs && (cs.cache_hit_requests || cs["cache_hit_requests"]);
+        const cachedTokens = cs && (cs.cache_read_input_tokens || cs["cache_read_input_tokens"]);
+        if (total && total > 0 && cachedTokens && cachedTokens > 0) {
+          const rate = ((hits / total) * 100).toFixed(1);
+          const tokensFmt = cachedTokens >= 1000
+            ? `${(cachedTokens / 1000).toFixed(1)}k`
+            : `${cachedTokens}`;
+          cacheLine = I18n.t("chat.done.cache", {
+            rate, hits, total: total, tokens: tokensFmt
+          });
+        }
+        Sessions.appendInfo(`✓ ${mainLine}`, cacheLine);
+      }
+      break;
+
+    case "next_message_suggestion":
+      // Backend predicted the user's next message — render as ghost text
+      // in the composer. Only apply when the suggestion is for the session
+      // the user is currently looking at; suggestions for background
+      // sessions are dropped (they'd be stale by the time the user switches).
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.setInputSuggestion(ev.text);
+      break;
+
+    case "request_feedback":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.showFeedbackRequest(ev.question, ev.context, ev.options);
+      break;
+
+    case "request_confirmation":
+      if (ev.session_id !== Sessions.activeId) break;
+      showConfirmModal(ev.id, ev.message);
+      break;
+
+    case "interrupted":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.clearProgress();
+      Sessions.collapseToolGroup();
+      Sessions.appendInfo(I18n.t("chat.interrupted"));
+      break;
+
+    // ── Info / errors ──────────────────────────────────────────────────
+    case "info":
+      Sessions.appendInfo(ev.message);
+      break;
+
+    case "background_tasks_update":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.updateBgTasksBadge(ev.running || 0, ev.tasks || []);
+      break;
+
+    case "background_task_notice":
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.appendBgTaskNotice(ev.command, ev.handle_id, ev.status);
+      break;
+
+    case "user_message_queue_status":
+      // Agent broadcast: N user messages are sitting in the inbox waiting
+      // to be drained at the next iteration boundary. Show/hide the
+      // "{{n}} messages waiting" hint above the input bar.
+      if (ev.session_id !== Sessions.activeId) break;
+      Sessions.setInputQueueHint(ev.pending || 0);
+      break;
+
+    case "warning":
+      // Optimize retry messages for better UX
+      const friendlyWarning = _transformRetryWarning(ev.message);
+      if (friendlyWarning) {
+        Sessions.appendInfo(friendlyWarning);
+      }
+      break;
+
+    case "success":
+      Sessions.appendMsg("success", "✓ " + escapeHtml(ev.message));
+      break;
+
+    case "error":
+      if (!ev.session_id || ev.session_id === Sessions.activeId)
+        Sessions.appendMsg("error", escapeHtml(ev.message));
+      break;
+  }
+});
+
+
+})();

data/lib/octo/web/ws.js

@@ -0,0 +1,128 @@
+// ── WS — WebSocket connection manager ─────────────────────────────────────
+//
+// Responsibilities:
+//   - Connect / reconnect with exponential backoff
+//   - Queue outbound messages while disconnected, flush on reconnect
+//   - Track active session subscription; restore it after reconnect
+//   - Dispatch inbound server events to registered handlers
+//
+// Usage:
+//   WS.onEvent(handler)        // register an event handler
+//   WS.send({ type: "..." })   // send (queued if not yet connected)
+//   WS.connect()               // start connection
+// ─────────────────────────────────────────────────────────────────────────
+
+const WS = (() => {
+  // ── Private state ──────────────────────────────────────────────────────
+  let _socket       = null;
+  let _ready        = false;
+  let _retryDelay   = 1000;        // ms; doubles on each failure, cap 30s
+  let _retryTimer   = null;
+  let _queue        = [];          // messages queued while disconnected
+  let _handlers     = [];          // event handler callbacks
+  let _subscribedId = null;        // currently subscribed session id
+
+  const MAX_DELAY = 30_000;
+
+  // ── Private helpers ────────────────────────────────────────────────────
+  function _dispatch(event) {
+    _handlers.forEach(fn => {
+      try { fn(event); } catch (e) { console.error("[WS] handler error", e); }
+    });
+  }
+
+  function _flushQueue() {
+    const pending = _queue.splice(0);
+    pending.forEach(msg => {
+      try { _socket.send(JSON.stringify(msg)); }
+      catch (e) { _queue.unshift(msg); } // re-queue on send error
+    });
+  }
+
+  function _onOpen() {
+    _ready      = true;
+    _retryDelay = 1000;           // reset backoff on successful connect
+
+    // Always request fresh session list on (re)connect
+    _socket.send(JSON.stringify({ type: "list_sessions" }));
+
+    // Restore subscription if we had one before disconnect
+    if (_subscribedId) {
+      _socket.send(JSON.stringify({ type: "subscribe", session_id: _subscribedId }));
+    }
+
+    _flushQueue();
+    _dispatch({ type: "_ws_connected" });
+  }
+
+  function _onMessage(e) {
+    let event;
+    try { event = JSON.parse(e.data); }
+    catch (ex) { console.error("[WS] parse error", ex); return; }
+    _dispatch(event);
+  }
+
+  function _onClose(e) {
+    // 1006 = abnormal closure (server rejected handshake, likely 401)
+    if (e.code === 1006 && !Auth.passed) {
+      Auth.reset();
+      Auth.check();
+      return;
+    }
+    _ready  = false;
+    _socket = null;
+    console.warn(`[WS] closed — retry in ${_retryDelay}ms`);
+    _dispatch({ type: "_ws_disconnected" });
+
+    _retryTimer = setTimeout(() => {
+      _retryDelay = Math.min(_retryDelay * 2, MAX_DELAY);
+      _connect();
+    }, _retryDelay);
+  }
+
+  function _onError(err) {
+    console.error("[WS] error", err);
+    // onclose will fire automatically after onerror
+  }
+
+  function _connect() {
+    if (_retryTimer) { clearTimeout(_retryTimer); _retryTimer = null; }
+    if (_socket && (_socket.readyState === WebSocket.OPEN ||
+                    _socket.readyState === WebSocket.CONNECTING)) return;
+
+    const accessKey = Auth.getKey();
+    const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+    const url = accessKey
+      ? `${protocol}//${location.host}/ws?access_key=${encodeURIComponent(accessKey)}`
+      : `${protocol}//${location.host}/ws`;
+    _socket = new WebSocket(url);
+    _socket.onopen    = _onOpen;
+    _socket.onmessage = _onMessage;
+    _socket.onclose   = _onClose;
+    _socket.onerror   = _onError;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────
+  return {
+    /** Register a handler for all server events. */
+    onEvent(fn) { _handlers.push(fn); },
+
+    /** Send a message. If not connected, queue it for later. */
+    send(obj) {
+      if (_ready && _socket) {
+        try { _socket.send(JSON.stringify(obj)); return; }
+        catch (e) { /* fall through to queue */ }
+      }
+      _queue.push(obj);
+    },
+
+    /** Track which session is currently subscribed (used for reconnect). */
+    setSubscribedSession(id) { _subscribedId = id; },
+
+    /** Start the connection. Call once on boot. */
+    connect: _connect,
+
+    /** True when the socket is open and ready. */
+    get ready() { return _ready; },
+  };
+})();

data/lib/octo.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# ── Global encoding defaults ──────────────────────────────────────────────────
+# Force UTF-8 as the default external/internal encoding for all IO operations
+# (File.read, Open3.capture3, HTTP bodies, etc.) so that binary-encoded strings
+# from external processes or network I/O never cause "invalid byte sequence in
+# UTF-8" errors on Ruby 2.6+.
+# Binary-specific operations (File.binread, IO#read with "b" mode, .b) are
+# unaffected — they always bypass this setting.
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+# ── Ruby < 2.7 polyfills ──────────────────────────────────────────────────────
+
+# Enumerable#filter_map was added in Ruby 2.7.
+if RUBY_VERSION < "2.7"
+  module Enumerable
+    def filter_map(&block)
+      return to_enum(:filter_map) unless block
+
+      each_with_object([]) do |item, result|
+        mapped = block.call(item)
+        result << mapped if mapped
+      end
+    end
+  end
+end
+
+# File.absolute_path? was added in Ruby 2.7.
+# Polyfill: a path is absolute if it starts with "/" (Unix) or a drive letter (Windows).
+unless File.respond_to?(:absolute_path?)
+  def File.absolute_path?(path)
+    File.expand_path(path) == path.to_s
+  end
+end
+
+# URI.encode_uri_component was added in Ruby 3.2.
+# CGI.escape encodes spaces as '+'; replace with '%20' to match URI encoding.
+require "uri"
+require "cgi"
+unless URI.respond_to?(:encode_uri_component)
+  def URI.encode_uri_component(str)
+    CGI.escape(str.to_s).gsub("+", "%20")
+  end
+end
+
+# YAML.safe_load with permitted_classes: keyword was added in Psych 4 (Ruby 3.1).
+# On older Ruby, the second positional argument serves the same purpose.
+# This helper provides a unified interface across Ruby versions.
+module YAMLCompat
+  def self.safe_load(yaml_string, permitted_classes: [])
+    if Psych::VERSION >= "4.0"
+      YAML.safe_load(yaml_string, permitted_classes: permitted_classes)
+    else
+      YAML.safe_load(yaml_string, permitted_classes)
+    end
+  end
+
+  def self.load_file(path, permitted_classes: [])
+    safe_load(File.read(path), permitted_classes: permitted_classes)
+  end
+end
+
+require_relative "octo/version"
+require_relative "octo/message_format/anthropic"
+require_relative "octo/message_format/open_ai"
+require_relative "octo/message_format/bedrock"
+require_relative "octo/bedrock_stream_aggregator"
+require_relative "octo/openai_stream_aggregator"
+require_relative "octo/anthropic_stream_aggregator"
+require_relative "octo/client"
+require_relative "octo/skill"
+require_relative "octo/skill_loader"
+
+# Agent system
+require_relative "octo/message_history"
+require_relative "octo/agent_config"
+require_relative "octo/agent_profile"
+require_relative "octo/providers"
+require_relative "octo/session_manager"
+require_relative "octo/idle_compression_timer"
+
+# Agent modules
+require_relative "octo/agent/message_compressor"
+require_relative "octo/agent/hook_manager"
+require_relative "octo/agent/tool_registry"
+
+# UI modules
+require_relative "octo/ui2/thinking_verbs"
+require_relative "octo/ui2/progress_indicator"
+
+# Utils
+require_relative "octo/utils/logger"
+require_relative "octo/utils/encoding"
+require_relative "octo/utils/environment_detector"
+require_relative "octo/utils/browser_detector"
+require_relative "octo/utils/scripts_manager"
+require_relative "octo/utils/model_pricing"
+require_relative "octo/utils/gitignore_parser"
+require_relative "octo/utils/limit_stack"
+require_relative "octo/utils/path_helper"
+require_relative "octo/utils/file_ignore_helper"
+require_relative "octo/utils/string_matcher"
+require_relative "octo/utils/login_shell"
+require_relative "octo/tools/base"
+require_relative "octo/utils/file_processor"
+
+require_relative "octo/tools/security"
+require_relative "octo/tools/file_reader"
+require_relative "octo/tools/write"
+require_relative "octo/tools/edit"
+require_relative "octo/tools/glob"
+require_relative "octo/tools/grep"
+require_relative "octo/tools/web_search"
+require_relative "octo/tools/web_fetch"
+require_relative "octo/tools/todo_manager"
+require_relative "octo/tools/trash_manager"
+require_relative "octo/tools/request_user_feedback"
+require_relative "octo/tools/invoke_skill"
+require_relative "octo/tools/undo_task"
+require_relative "octo/tools/redo_task"
+require_relative "octo/tools/list_tasks"
+require_relative "octo/tools/browser"
+require_relative "octo/tools/terminal"
+require_relative "octo/agent"
+
+require_relative "octo/server/session_registry"
+require_relative "octo/server/web_ui_controller"
+require_relative "octo/server/browser_manager"
+require_relative "octo/cli"
+
+module Octo
+  class AgentInterrupted < Exception; end  # Inherit from Exception to bypass rescue StandardError
+  class AgentError < StandardError; end
+  class BadRequestError < AgentError; end  # 400 errors — our request was malformed, history should be rolled back
+  class RetryableError < StandardError; end  # Transient errors that should be retried (5xx, HTML response, rate limit)
+  # Upstream (model/router like OpenRouter/Bedrock) returned finish_reason="stop" together with
+  # one or more tool_calls whose `arguments` JSON was truncated (empty, "{}" placeholder, or
+  # otherwise unparseable). Subclass of RetryableError so it flows through the existing
+  # retry/fallback pipeline in LlmCaller#call_llm.
+  class UpstreamTruncatedError < RetryableError; end
+  class ToolCallError < AgentError; end  # Raised when tool call fails due to invalid parameters
+  class BrowserNotReachableError < AgentError; end  # Chrome/Edge not running or remote debugging disabled
+  # BrowserManager singleton: Octo::BrowserManager.instance
+end