mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/ai_plans/claude_code.py

@@ -0,0 +1,208 @@
+"""Claude Code as a Mobster task's agent, on the person's Claude plan (Pro or Max), with only the phone's tools."""
+
+import json
+import re
+
+from .cli import AgentEvent, CliAgent, Command, child_env, classify, limit_signal, run_quietly, usage_counts
+
+TOOL = re.compile(r"mcp__([A-Za-z0-9_-]+?)__(.+)")
+
+
+class ClaudeCode(CliAgent):
+    id = "claude_code"
+    name = "Claude Code"
+    binary = "claude"
+    plan = "Claude"
+    vendor = "Anthropic"
+    install_url = "https://code.claude.com/docs/en/setup"
+    install_command = "curl -fsSL https://claude.ai/install.sh | bash"
+    sign_in_command = "claude, then /login"
+    path_env = "MOBSTER_CLAUDE_CODE_PATH"
+    model_env = "MOBSTER_CLAUDE_CODE_MODEL"
+    # An API key bills per token instead of the plan; a parent session's variables make Claude Code think it is nested.
+    drop_env = ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL", "CLAUDE_CODE_USE_BEDROCK",
+                "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY", "CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT",
+                "CLAUDE_CODE_SSE_PORT", "ANTHROPIC_MODEL")
+
+    def read_status(self, path):
+        env = child_env(path, env=self.env, drop=self.drop_env)
+        code, out, err = run_quietly([path, "auth", "status"], env)
+        version = None
+        vcode, vout, _ = run_quietly([path, "--version"], env)
+        if vcode == 0:
+            found = re.search(r"(\d+\.\d+\.\d+)", vout)
+            version = found.group(1) if found else None
+        state = {"version": version}
+        if code is None:
+            return {**state, "signedIn": False, "hint": f"Couldn't run {self.name}: {err[:120]}"}
+        try:
+            data = json.loads(out)
+        except ValueError:
+            data = {}
+        if not isinstance(data, dict) or not data.get("loggedIn"):
+            return {**state, "signedIn": False, "hint": "Sign in to Claude Code"}
+        method = str(data.get("authMethod") or "")
+        tier = str(data.get("subscriptionType") or "").strip()
+        if method in ("claude.ai", "oauth", "subscription") or tier:
+            name = {"max": "Max", "pro": "Pro", "team": "Team", "enterprise": "Enterprise"}.get(tier.lower(), tier)
+            return {**state, "signedIn": True, "billing": "plan",
+                    "account": f"Claude {name}".strip() if name else "Claude"}
+        return {**state, "signedIn": True, "billing": "api_key", "account": "Claude API key"}
+
+    def mcp_config(self, mcp_url, token):
+        """The MCP config file's text (Mobster writes it 0600 in a private folder and removes it after the run)."""
+        # alwaysLoad skips the tool-search hop; the timeout lets an approval wait.
+        return json.dumps({"mcpServers": {"mobster": {"type": "http", "url": mcp_url,
+                                                      "headers": {"Authorization": f"Bearer {token}"},
+                                                      "alwaysLoad": True, "timeout": 900000}}})
+
+    def argv(self, path, prompt, *, mcp_url, token_env, instructions, workdir, resume=None, model=None,
+             config_path=None):
+        argv = [path, "-p", "--output-format", "stream-json", "--verbose",
+                "--tools", "", "--strict-mcp-config", "--mcp-config", str(config_path),
+                "--allowedTools", "mcp__mobster__*", "--permission-mode", "dontAsk",
+                "--setting-sources", "", "--disable-slash-commands", "--max-turns", "120",
+                "--append-system-prompt", instructions]
+        if version_at_least(self.version, (2, 1, 259)):
+            # Anything that would still prompt is refused and Claude is told not to retry it.
+            argv += ["--permission-prompts", "none"]
+        if resume:
+            argv += ["--resume", resume]
+        if model or self.model():
+            argv += ["--model", model or self.model()]
+        # The prompt comes on stdin, so the person's task never shows in a process list.
+        return Command(argv)
+
+    def stdin(self, prompt, instructions=None):
+        return prompt
+
+    def extra_env(self, token_env, token):
+        # Milliseconds: an approval or a question waits for the person.
+        return {"MCP_TOOL_TIMEOUT": "900000", "MCP_TIMEOUT": "30000", "DISABLE_AUTOUPDATER": "1",
+                "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1", "ENABLE_CLAUDEAI_MCP_SERVERS": "false",
+                "CLAUDE_CODE_DISABLE_CLAUDE_MDS": "1", "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"}
+
+    def parse(self, obj):
+        kind = obj.get("type") if isinstance(obj, dict) else None
+        if kind == "system" and obj.get("subtype") == "init":
+            out = [AgentEvent("session", session_id=obj.get("session_id") or None, model=obj.get("model"),
+                              code=str(obj.get("apiKeySource") or "") or None)]
+            servers = obj.get("mcp_servers") if isinstance(obj.get("mcp_servers"), list) else []
+            mobster = next((s for s in servers if isinstance(s, dict) and s.get("name") == "mobster"), None)
+            if mobster is not None:
+                ok = mobster.get("status") in ("connected", "ok", None)
+                out.append(AgentEvent("mcp", ok=ok, text=str(mobster.get("status") or "")))
+            return out
+        if kind == "assistant":
+            message = obj.get("message") if isinstance(obj.get("message"), dict) else {}
+            out = []
+            if isinstance(message.get("usage"), dict) and message.get("id"):
+                out.append(AgentEvent("step_usage", call_id=str(message["id"])[:128],
+                                      model=message.get("model") if isinstance(message.get("model"), str) else None,
+                                      usage=_counts(message["usage"])))
+            for block in message.get("content") or ():
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "text" and str(block.get("text") or "").strip():
+                    out.append(AgentEvent("message", text=block["text"]))
+                elif block.get("type") == "thinking" and str(block.get("thinking") or "").strip():
+                    out.append(AgentEvent("reasoning", text=block["thinking"]))
+                elif block.get("type") == "tool_use":
+                    server, tool = _split(block.get("name"))
+                    out.append(AgentEvent("tool_start", tool=tool, server=server,
+                                          arguments=block.get("input") if isinstance(block.get("input"), dict) else {}))
+            error = obj.get("error")
+            if error:
+                code = {"rate_limit": "usage_limit", "billing_error": "usage_limit",
+                        "authentication_failed": "signed_out"}.get(str(error))
+                said = " ".join(e.text for e in out if e.kind == "message") or str(error)
+                event = self._error(said, fatal=False)
+                event.code = code or event.code
+                out = [e for e in out if e.kind != "message"] + [event]
+            return out
+        if kind == "user":
+            message = obj.get("message") if isinstance(obj.get("message"), dict) else {}
+            out = []
+            for block in message.get("content") or () if isinstance(message.get("content"), list) else ():
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    failed = bool(block.get("is_error"))
+                    out.append(AgentEvent("tool_end", ok=not failed, text=_text(block.get("content")) if failed
+                                          else ""))
+            return out
+        if kind == "rate_limit_event":
+            info = obj.get("rate_limit_info") if isinstance(obj.get("rate_limit_info"), dict) else {}
+            out = []
+            signal = limit_signal(info.get("status"), info.get("unifiedWindows"), kind=info.get("rateLimitType"),
+                                  resets_at=info.get("resetsAt"))
+            if signal is not None:
+                out.append(AgentEvent("limits", limits=signal))
+            if info.get("status") == "rejected":
+                resets = info.get("resetsAt")
+                out.append(AgentEvent("error", text="usage limit reached", code="usage_limit", fatal=False,
+                                      resets_at=float(resets) if isinstance(resets, (int, float)) else None))
+            return out
+        if kind == "result":
+            usage = obj.get("usage") if isinstance(obj.get("usage"), dict) else {}
+            models = {}
+            for name, figures in (obj.get("modelUsage") if isinstance(obj.get("modelUsage"), dict) else {}).items():
+                if isinstance(name, str) and isinstance(figures, dict):
+                    cost = figures.get("costUSD")
+                    models[name[:200]] = {
+                        "usage": usage_counts(figures.get("inputTokens"), figures.get("outputTokens"),
+                                              figures.get("cacheReadInputTokens"),
+                                              figures.get("cacheCreationInputTokens"), input_includes_cache=False),
+                        "cost_usd": float(cost) if isinstance(cost, (int, float)) and not isinstance(cost, bool)
+                        else None}
+            cost, latency = obj.get("total_cost_usd"), obj.get("duration_api_ms")
+            out = [AgentEvent("usage", usage=_counts(usage), models=models or None,
+                              cost_usd=float(cost) if isinstance(cost, (int, float)) and not isinstance(cost, bool)
+                              else None,
+                              latency_ms=int(latency) if isinstance(latency, (int, float))
+                              and not isinstance(latency, bool) and latency >= 0 else None)]
+            text = obj.get("result") if isinstance(obj.get("result"), str) else ""
+            failed = bool(obj.get("is_error")) or str(obj.get("subtype") or "success") != "success"
+            if failed:
+                out.append(self._error(text or str(obj.get("subtype") or "Claude Code stopped on an error."),
+                                       fatal=True))
+            out.append(AgentEvent("done", text=text if not failed else "", ok=not failed,
+                                  session_id=obj.get("session_id") or None))
+            return out
+        return []
+
+    def _error(self, message, fatal):
+        code = classify(message)
+        resets = None
+        found = re.search(r"\|(\d{9,11})\b", message)  # older: "Claude AI usage limit reached|1760000000"
+        if found:
+            resets, code = float(found.group(1)), "usage_limit"
+        clock = re.search(r"resets\s+(?:\w{3}\s+)?(\d{1,2}(?::\d{2})?\s*[ap]m)", message, re.I)
+        if clock and code == "usage_limit":
+            from .codex import parse_reset
+            words = clock.group(1)
+            resets = parse_reset(words if ":" in words else re.sub(r"(\d+)", r"\1:00", words, 1))
+        return AgentEvent("error", text=message[:2000], code=code, fatal=fatal, resets_at=resets)
+
+
+def _counts(usage):
+    return usage_counts(usage.get("input_tokens"), usage.get("output_tokens"), usage.get("cache_read_input_tokens"),
+                        usage.get("cache_creation_input_tokens"), input_includes_cache=False)
+
+
+def version_at_least(version, minimum):
+    try:
+        return tuple(int(part) for part in str(version).split(".")[:3]) >= minimum
+    except ValueError:
+        return False
+
+
+def _split(name):
+    found = TOOL.fullmatch(str(name or ""))
+    return (found.group(1), found.group(2)) if found else (None, str(name or ""))
+
+
+def _text(content):
+    if isinstance(content, str):
+        return content[:500]
+    if isinstance(content, list):
+        return " ".join(str(c.get("text") or "") for c in content if isinstance(c, dict))[:500]
+    return ""

mobile_agent/ai_plans/cli.py

@@ -0,0 +1,400 @@
+"""The person's own coding agent CLI as a Mobster task's agent: it signs its own requests;
+Mobster never reads its credentials."""
+
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+SEARCH_DIRS = ("~/.local/bin", "/opt/homebrew/bin", "/usr/local/bin", "~/.npm-global/bin", "~/.bun/bin",
+               "~/.volta/bin", "~/.yarn/bin", "~/.cargo/bin", "~/bin", "~/.claude/local", "~/.codex/bin",
+               "/Applications/Codex.app/Contents/Resources", "~/Library/pnpm")
+SHELL_PATH_SECONDS = 4.0
+STATUS_SECONDS = 8.0
+STDERR_KEEP = 8000
+STOP_GRACE = 2.5
+_shell_path = {"value": None, "at": 0.0}
+_shell_lock = threading.Lock()
+
+
+def login_shell_path(env=None, refresh=False):
+    """The PATH a new Terminal window gets (the login shell's), cached for 10 minutes; "" when it can't be read."""
+    env = os.environ if env is None else env
+    with _shell_lock:
+        if not refresh and _shell_path["value"] is not None and time.monotonic() - _shell_path["at"] < 600:
+            return _shell_path["value"]
+        shell = env.get("SHELL") or "/bin/zsh"
+        value = ""
+        try:
+            done = subprocess.run([shell, "-l", "-c", 'printf "%s" "$PATH"'], capture_output=True, text=True,
+                                  timeout=SHELL_PATH_SECONDS, stdin=subprocess.DEVNULL,
+                                  env={k: v for k, v in env.items() if k in ("HOME", "USER", "LOGNAME", "SHELL",
+                                                                              "TMPDIR", "LANG")})
+            if done.returncode == 0:
+                value = done.stdout.strip().splitlines()[-1] if done.stdout.strip() else ""
+        except (OSError, subprocess.SubprocessError, IndexError):
+            value = ""
+        _shell_path.update(value=value, at=time.monotonic())
+        return value
+
+
+def _nvm_dirs():
+    root = Path("~/.nvm/versions/node").expanduser()
+    try:
+        return [str(p / "bin") for p in sorted(root.iterdir(), reverse=True) if (p / "bin").is_dir()]
+    except OSError:
+        return []
+
+
+def search_path(env=None):
+    """Every directory Mobster looks in for a CLI, in order, without duplicates."""
+    env = os.environ if env is None else env
+    dirs = []
+    for part in (env.get("PATH") or "").split(os.pathsep):
+        dirs.append(part)
+    dirs += [str(Path(d).expanduser()) for d in SEARCH_DIRS] + _nvm_dirs()
+    seen, out = set(), []
+    for d in dirs:
+        if d and d not in seen:
+            seen.add(d)
+            out.append(d)
+    return out
+
+
+def find_binary(name, env=None, override=None):
+    """The executable ``name`` (an absolute path), or None."""
+    env = os.environ if env is None else env
+    if override:
+        path = Path(override).expanduser()
+        return str(path) if path.is_file() and os.access(path, os.X_OK) else None
+    found = shutil.which(name, path=os.pathsep.join(search_path(env)))
+    if found:
+        return found
+    shell = login_shell_path(env)
+    return shutil.which(name, path=shell) if shell else None
+
+
+# Mobster's secrets no agent CLI gets; each agent also drops what would move it off its plan.
+MOBSTER_SECRETS = ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "TYPESAFE_API_KEY",
+                   "TEXT_MODEL_API_KEY", "OPENROUTER_API_KEY", "MOBSTER_API_TOKEN", "MOBSTER_API_TOKEN_FILE",
+                   "MOBSTER_APP_SESSION", "MOBSTER_MCP_TOKEN", "MOBSTER_LICENSE_KEY")
+
+
+def child_env(binary, extra=None, env=None, drop=()):
+    """The environment a CLI runs with."""
+    env = dict(os.environ if env is None else env)
+    for key in (*MOBSTER_SECRETS, *drop):
+        env.pop(key, None)
+    parts = [str(Path(binary).resolve().parent), str(Path(binary).parent)]
+    shell = login_shell_path(env)
+    parts += shell.split(os.pathsep) if shell else []
+    parts += search_path(env)
+    seen, path = set(), []
+    for part in parts:
+        if part and part not in seen:
+            seen.add(part)
+            path.append(part)
+    env["PATH"] = os.pathsep.join(path)
+    env.setdefault("TERM", "dumb")
+    env["NO_COLOR"] = "1"
+    env.update(extra or {})
+    return env
+
+
+def run_quietly(argv, env, timeout=STATUS_SECONDS):
+    """(exit code, stdout, stderr) of a short command such as ``codex login status``; (None, "", why)
+    when it couldn't run."""
+    try:
+        done = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, env=env,
+                              stdin=subprocess.DEVNULL)
+        return done.returncode, done.stdout, done.stderr
+    except subprocess.TimeoutExpired:
+        return None, "", "timed out"
+    except OSError as error:
+        return None, "", str(error)
+
+
+def count(value):
+    """A token count as a non-negative int; 0 for anything else (a missing or odd figure is no tokens)."""
+    return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0 else 0
+
+
+def usage_counts(input_tokens, output_tokens, cache_read=0, cache_write=0, *, input_includes_cache=True,
+                 reasoning=None):
+    """One call's (or one run's) tokens in Mobster's convention."""
+    read, write = count(cache_read), count(cache_write)
+    prompt = count(input_tokens) + (0 if input_includes_cache else read + write)
+    out = {"input_tokens": prompt, "output_tokens": count(output_tokens), "cache_read_tokens": read,
+           "cache_write_tokens": write}
+    out["total_tokens"] = out["input_tokens"] + out["output_tokens"]
+    if reasoning is not None:
+        out["reasoning_output_tokens"] = count(reasoning)
+    return out
+
+
+LIMIT_STATUSES = ("allowed", "allowed_warning", "rejected")
+
+
+def _number(value):
+    return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+
+def limit_signal(status, windows=None, *, kind=None, resets_at=None):
+    """An agent's plan-limit reading in the shape the ledger keeps."""
+    if status not in LIMIT_STATUSES:
+        return None
+    kept = {}
+    for name, window in (windows.items() if isinstance(windows, dict) else ()):
+        if isinstance(window, dict) and isinstance(name, str) and len(kept) < 8:
+            kept[name[:40]] = {"utilization": _number(window.get("utilization")),
+                               "resetsAt": _number(window.get("resetsAt"))}
+    return {"status": status, "type": kind if isinstance(kind, str) else None, "resetsAt": _number(resets_at),
+            "windows": kept}
+
+
+@dataclass
+class Command:
+    """What an agent runs for one call: the argv, and the model Mobster asked for when the stream won't name it."""
+    argv: list
+    model: str | None = None
+
+
+@dataclass
+class AgentEvent:
+    """One thing a CLI said, in Mobster's terms."""
+    kind: str
+    text: str = ""
+    session_id: str | None = None
+    tool: str | None = None
+    server: str | None = None
+    arguments: dict | None = None
+    ok: bool = True
+    usage: dict = field(default_factory=dict)
+    code: str | None = None
+    fatal: bool = False
+    model: str | None = None
+    resets_at: float | None = None
+    call_id: str | None = None
+    limits: dict | None = None
+    cost_usd: float | None = None
+    models: dict | None = None
+    latency_ms: int | None = None
+
+
+# Limit wording differs by CLI version, so it is matched loosely.
+LIMIT_WORDS = re.compile(r"usage limit|hit your (?:\w+ )*limit|limit reached|rate limit|quota|too many requests|"
+                         r"resource.?exhausted|you(?:'|’)ve reached|out of credits|spend cap|upgrade to plus|"
+                         r"try again (?:in|at|after)", re.I)
+SIGNED_OUT_WORDS = re.compile(r"not logged in|log ?in again|sign ?in again|please (?:log|sign) ?in|"
+                              r"unauthori[sz]ed|401|token (?:has )?expired|invalid.*(?:token|credentials)|/login",
+                              re.I)
+
+
+def classify(text):
+    """usage_limit, signed_out or other, for an error's text."""
+    text = str(text or "")
+    if LIMIT_WORDS.search(text):
+        return "usage_limit"
+    if SIGNED_OUT_WORDS.search(text):
+        return "signed_out"
+    return "other"
+
+
+class AgentProcess:
+    """One CLI run: started in its own process group (so Stop reaches whatever it starts)."""
+
+    def __init__(self, argv, *, env, cwd, parse, stdin_text=None, log=None):
+        self.argv, self.env, self.cwd, self.parse = list(argv), env, cwd, parse
+        self.stdin_text = stdin_text
+        self.log = log or (lambda message: None)
+        self.process = None
+        self.stderr = []
+        self.stopped = threading.Event()
+        self.started_at = None
+        self._stderr_thread = None
+
+    def start(self):
+        self.started_at = time.monotonic()
+        self.process = subprocess.Popen(
+            self.argv, cwd=self.cwd, env=self.env, stdin=subprocess.PIPE if self.stdin_text is not None
+            else subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE, start_new_session=True,
+            bufsize=1, text=True, encoding="utf-8", errors="replace")
+        if self.stdin_text is not None:
+            try:
+                self.process.stdin.write(self.stdin_text)
+                self.process.stdin.close()
+            except OSError:
+                pass
+        self._stderr_thread = threading.Thread(target=self._drain_stderr, daemon=True, name="mobster-agent-stderr")
+        self._stderr_thread.start()
+        return self
+
+    def _drain_stderr(self):
+        size = 0
+        try:
+            for line in self.process.stderr:
+                self.stderr.append(line)
+                size += len(line)
+                while size > STDERR_KEEP and len(self.stderr) > 1:
+                    size -= len(self.stderr.pop(0))
+        except (OSError, ValueError):
+            pass
+        finally:
+            self.process.stderr.close()
+
+    def stderr_text(self):
+        return "".join(self.stderr)[-STDERR_KEEP:]
+
+    def events(self):
+        """AgentEvents as the CLI prints them, until it exits or is stopped. A line that isn't JSON is skipped."""
+        for line in self.process.stdout:
+            line = line.strip()
+            if not line or line[0] not in "{[":
+                continue
+            try:
+                obj = json.loads(line)
+            except ValueError:
+                continue
+            try:
+                parsed = self.parse(obj) or ()
+            except Exception as error:  # noqa: BLE001 -- one odd event never ends the run
+                self.log(f"an event couldn't be read ({type(error).__name__})")
+                continue
+            for event in parsed:
+                yield event
+        self.process.stdout.close()
+        self.wait()
+
+    def wait(self, timeout=None):
+        try:
+            return self.process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            return None
+
+    @property
+    def returncode(self):
+        return None if self.process is None else self.process.poll()
+
+    def stop(self, grace=STOP_GRACE):
+        """End the CLI and everything it started: SIGTERM to its process group, SIGKILL after ``grace``."""
+        self.stopped.set()
+        process = self.process
+        if process is None or process.poll() is not None:
+            return
+        for sig in (signal.SIGTERM, signal.SIGKILL):
+            try:
+                os.killpg(process.pid, sig)
+            except (ProcessLookupError, PermissionError):
+                return
+            try:
+                process.wait(timeout=grace)
+                return
+            except subprocess.TimeoutExpired:
+                continue
+
+
+class CliAgent:
+    """What every agent CLI adapter provides."""
+
+    id = ""                 # the run's engine: codex, claude_code, gemini
+    name = ""               # "Codex"
+    binary = ""             # "codex"
+    plan = ""               # whose plan, in the person's words: "ChatGPT"
+    vendor = ""             # "OpenAI"
+    install_url = ""
+    install_command = ""
+    sign_in_command = ""
+    path_env = ""           # MOBSTER_CODEX_PATH: a path the person chose
+    model_env = ""          # MOBSTER_CODEX_MODEL
+    drop_env = ()           # keys the CLI must not see (an API key would bill per token instead of the plan)
+
+    def __init__(self, env=None):
+        self.env = os.environ if env is None else env
+        self._status = None
+        self._status_at = 0.0
+        self._lock = threading.Lock()
+
+    def locate(self):
+        return find_binary(self.binary, self.env, self.env.get(self.path_env) or None)
+
+    def status(self, max_age=60.0):
+        """{id, name, plan, installed, signedIn, path, version, account, billing, hint, ready}."""
+        with self._lock:
+            if self._status is not None and time.monotonic() - self._status_at < max_age:
+                return dict(self._status)
+        path = self.locate()
+        state = {"id": self.id, "name": self.name, "plan": self.plan, "vendor": self.vendor, "installed": bool(path),
+                 "signedIn": False, "path": path, "version": None, "account": None, "billing": None,
+                 "hint": None, "ready": False, "installUrl": self.install_url,
+                 "installCommand": self.install_command, "signInCommand": self.sign_in_command}
+        if not path:
+            state["hint"] = f"Install {self.name}"
+        else:
+            try:
+                state.update(self.read_status(path))
+            except Exception as error:  # noqa: BLE001
+                state.update(signedIn=False, hint=f"Couldn't check {self.name} ({type(error).__name__})")
+            self.version = state.get("version")
+            if not state["signedIn"] and not state["hint"]:
+                state["hint"] = f"Sign in to {self.name}"
+            state["ready"] = bool(state["signedIn"])
+        with self._lock:
+            self._status, self._status_at = dict(state), time.monotonic()
+        return state
+
+    def forget_status(self):
+        with self._lock:
+            self._status = None
+
+    def read_status(self, path):  # pragma: no cover - each agent's
+        raise NotImplementedError
+
+    def argv(self, path, prompt, *, mcp_url, token_env, instructions, workdir, resume=None, model=None):
+        raise NotImplementedError
+
+    def parse(self, obj):
+        raise NotImplementedError
+
+    version = None
+
+    def extra_env(self, token_env, token):
+        return {token_env: token}
+
+    resumes = True             # a follow-up resumes the agent's own session
+    signed_out_codes = ()      # exit codes that mean "not signed in"
+
+    def stdin(self, prompt, instructions=None):
+        """What to write to the CLI's stdin (the prompt, so it stays out of process lists), or None."""
+        return None
+
+    def parser(self):
+        """The event parser for one run (an agent whose stream needs state across lines makes a fresh one)."""
+        return self.parse
+
+    def prepare(self, workdir, mcp_url, token):
+        """Files a run needs beside its command line (Gemini's project settings); returns a path to remove after."""
+        return None
+
+    def model(self):
+        chosen = (self.env.get(self.model_env) or "").strip()
+        return chosen if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:\-\[\]]{0,99}", chosen) else None
+
+    def limit_sentence(self, resets_at=None):
+        """The usage-limit error in plain words, saying when it resets when the CLI said."""
+        when = ""
+        if resets_at:
+            when = " It resets " + time.strftime("at %-I:%M %p", time.localtime(resets_at)) \
+                if resets_at - time.time() < 20 * 3600 else " It resets " + time.strftime(
+                    "on %A at %-I:%M %p", time.localtime(resets_at))
+            when += "."
+        return f"You've reached your {self.plan} plan's usage limit in {self.name}.{when}"
+
+    def signed_out_sentence(self):
+        return (f"{self.name} isn't signed in. Open Terminal, run {self.sign_in_command}, then try again."
+                if self.sign_in_command else f"Sign in to {self.name}, then try again.")