abstract-serve-core 0.1.1__tar.gz

abstract_serve_core-0.1.1/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: abstract-serve-core
+Version: 0.1.1
+Summary: Provider-neutral shared Serve console for Claude, GPT, Hugpy, and local model backends.
+License: Proprietary
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: prompt_toolkit>=3.0
+Provides-Extra: gpt
+Requires-Dist: abstract-gpt>=0.1.9; extra == "gpt"
+
+# abstract-serve
+
+The provider-neutral shared Serve console. It owns the durable conversation
+store, queue/hold contract, session picker, and provider adapters. Claude, GPT,
+Hugpy, and local-model packages may provide adapters without owning the Serve
+runtime.
+
+Run `abstract-serve --no-browser` to start the console.

abstract_serve_core-0.1.1/README.md

@@ -0,0 +1,8 @@
+# abstract-serve
+
+The provider-neutral shared Serve console. It owns the durable conversation
+store, queue/hold contract, session picker, and provider adapters. Claude, GPT,
+Hugpy, and local-model packages may provide adapters without owning the Serve
+runtime.
+
+Run `abstract-serve --no-browser` to start the console.

abstract_serve_core-0.1.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abstract-serve-core"
+version = "0.1.1"
+description = "Provider-neutral shared Serve console for Claude, GPT, Hugpy, and local model backends."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+dependencies = ["prompt_toolkit>=3.0"]
+
+[project.optional-dependencies]
+gpt = ["abstract-gpt>=0.1.9"]
+
+[project.scripts]
+abstract-serve = "abstract_serve.serve_cli:main"
+abstract-serve-mcp = "abstract_serve.mcp:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+abstract_serve = ["templates/*.json", "webui/*", "webui/assets/*"]

abstract_serve_core-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

abstract_serve_core-0.1.1/src/abstract_serve/__init__.py

@@ -0,0 +1,10 @@
+"""abstract-serve — provider-neutral shared Serve console."""
+try:  # the installed distribution's version (pyproject), never a hand-kept string
+    from importlib.metadata import version as _v
+    __version__ = _v("abstract-serve")
+except Exception:  # running from a source checkout without metadata
+    __version__ = "0.0.0+src"
+
+from .toolset import get_toolset  # noqa: E402
+
+__all__ = ["get_toolset"]

abstract_serve_core-0.1.1/src/abstract_serve/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

abstract_serve_core-0.1.1/src/abstract_serve/actions.py

@@ -0,0 +1,594 @@
+"""Core actions: template save/restore/reset, oauth, state, and root init."""
+import os
+import shutil
+
+from . import paths
+from .paths import (CONFIG_PATH, HOME, LIVE_CLAUDE_DIR, LIVE_DOTCLAUDE,
+                    LIVE_SETTINGS, ROOT, SESSIONS_DIR, TEMPLATE_DIR, TPL_DOTCLAUDE,
+                    TPL_SETTINGS)
+from .util import (OAUTH_ENV, _operator_token, has_claude_auth, has_real_login, load_json,
+                   load_oauth_token,
+                   real_claude, run, save_json, store_oauth_token, which_claude_auth)
+
+# Session-settings surfaced by the console (valid keys in current CC schema).
+BOOL_KEYS = [
+    "enableArtifact", "workflowKeywordTriggerEnabled", "promptSuggestionEnabled",
+    "awaySummaryEnabled", "skipDangerousModePermissionPrompt", "autoCompactEnabled",
+    "switchModelsOnFlag", "autoScrollEnabled", "fileCheckpointingEnabled",
+    "terminalProgressBarEnabled", "remoteControlAtStartup", "inputNeededNotifEnabled",
+    "agentPushNotifEnabled",
+]
+EFFORT_VALUES = ["low", "medium", "high", "xhigh"]
+PERM_MODES = ["acceptEdits", "auto", "bypassPermissions", "default", "plan"]
+
+# Minimal flags a fresh ~/.claude.json needs to skip onboarding/trust prompts.
+FLAG_KEYS = ["hasCompletedOnboarding", "bypassPermissionsModeAccepted",
+             "hasSeenAutoModeEntryWarning", "hasSeenTasksHint"]
+
+
+def _pkg_default(name):
+    """Read a shipped default template file from package data."""
+    try:
+        from importlib.resources import files
+        return (files("abstract_claude.templates") / name).read_text()
+    except Exception:
+        return None
+
+
+def init_root():
+    """Materialize AC_ROOT with config.json + template/ from shipped defaults if missing."""
+    os.makedirs(TEMPLATE_DIR, exist_ok=True)
+    created = []
+    if not os.path.exists(CONFIG_PATH):
+        save_json(CONFIG_PATH, dict(paths.DEFAULTS))
+        created.append(CONFIG_PATH)
+    for dst, name in ((TPL_SETTINGS, "settings.json"), (TPL_DOTCLAUDE, "dot-claude.json")):
+        if not os.path.exists(dst):
+            data = _pkg_default(name)
+            if data is not None:
+                with open(dst, "w") as f:
+                    f.write(data)
+                created.append(dst)
+    return created
+
+
+def save_template():
+    """Capture current settings.json + derive minimal flags into the template."""
+    os.makedirs(TEMPLATE_DIR, exist_ok=True)
+    live = load_json(LIVE_SETTINGS, {})
+    save_json(TPL_SETTINGS, live)
+    dot = load_json(LIVE_DOTCLAUDE, {})
+    tpl_existing = load_json(TPL_DOTCLAUDE, {})
+    flags = {k: bool(dot.get(k, True)) for k in FLAG_KEYS}
+    # preserve MCP server registration (from live if present, else keep the template's)
+    mcp = dot.get("mcpServers") or tpl_existing.get("mcpServers")
+    if mcp:
+        flags["mcpServers"] = mcp
+    save_json(TPL_DOTCLAUDE, flags)
+    return {"ok": True, "out": f"saved settings + flags -> {TEMPLATE_DIR}"}
+
+
+def restore():
+    """Create a fresh ~/.claude (settings + flags) if it does not exist."""
+    if os.path.isdir(LIVE_CLAUDE_DIR):
+        return {"ok": True, "out": "~/.claude exists (use reset to force a fresh session)"}
+    os.makedirs(LIVE_CLAUDE_DIR, mode=0o700, exist_ok=True)
+    tpl = load_json(TPL_SETTINGS, {})
+    save_json(LIVE_SETTINGS, tpl)
+    save_json(LIVE_DOTCLAUDE, load_json(TPL_DOTCLAUDE, {}))
+    return {"ok": True, "out": "fresh ~/.claude created; login via CLAUDE_CODE_OAUTH_TOKEN"}
+
+
+def reset(hard=False):
+    """Wipe prior state and reseed the template -> a clean session.
+
+    By default the interactive login (~/.claude/.credentials.json) is PRESERVED,
+    since Claude Code's interactive startup requires it and the env token does not
+    suppress the login menu. Pass hard=True to also remove the login.
+    """
+    creds_path = os.path.join(LIVE_CLAUDE_DIR, ".credentials.json")
+    saved_creds = None
+    if not hard:
+        try:
+            with open(creds_path, "rb") as f:
+                saved_creds = f.read()
+        except OSError:
+            pass
+    shutil.rmtree(LIVE_CLAUDE_DIR, ignore_errors=True)
+    try:
+        os.remove(LIVE_DOTCLAUDE)
+    except FileNotFoundError:
+        pass
+    r = restore()
+    note = "wiped prior state"
+    if saved_creds is not None:
+        os.makedirs(LIVE_CLAUDE_DIR, mode=0o700, exist_ok=True)
+        with open(creds_path, "wb") as f:
+            f.write(saved_creds)
+        os.chmod(creds_path, 0o600)
+        note += " (kept login)"
+    else:
+        note += " (no stored login to keep — interactive will ask once)" if not hard \
+                else " (hard: login removed)"
+    r["out"] = note + "; " + r["out"]
+    return r
+
+
+def ensure_provisioned():
+    """Idempotently ensure ~/.claude carries the template's settings + onboarding/
+    trust flags + MCP servers — so no theme/onboarding/trust prompts and tools are
+    registered. Non-destructive: never wipes transcripts or login, only ADDS missing
+    keys. Safe to call on every launch.
+    """
+    changed = []
+    tpl_s = load_json(TPL_SETTINGS, {})
+    live_s = load_json(LIVE_SETTINGS, {})
+    added = not os.path.exists(LIVE_SETTINGS)
+    for k, v in tpl_s.items():
+        if k not in live_s:
+            live_s[k] = v
+            added = True
+    if added:
+        os.makedirs(LIVE_CLAUDE_DIR, mode=0o700, exist_ok=True)
+        save_json(LIVE_SETTINGS, live_s)
+        changed.append("settings")
+
+    tpl_d = load_json(TPL_DOTCLAUDE, {})
+    live_d = load_json(LIVE_DOTCLAUDE, {})
+    added = not os.path.exists(LIVE_DOTCLAUDE)
+    for k, v in tpl_d.items():
+        if k == "mcpServers":
+            live_mcp = dict(live_d.get("mcpServers") or {})
+            for name, spec in v.items():
+                if name not in live_mcp:
+                    live_mcp[name] = spec
+                    added = True
+            live_d["mcpServers"] = live_mcp
+        elif k not in live_d:
+            live_d[k] = v
+            added = True
+    if added:
+        save_json(LIVE_DOTCLAUDE, live_d)
+        changed.append("flags")
+    return changed
+
+
+def _pid_alive(pid):
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except (ProcessLookupError, ValueError):
+        return False
+    except PermissionError:
+        return True
+
+
+def list_sessions(sessions_dir=None):
+    """Per-launch session dirs, oldest first: [{path, name, pid, alive, started, cwd}]."""
+    base = sessions_dir or SESSIONS_DIR
+    out = []
+    try:
+        names = sorted(os.listdir(base))
+    except FileNotFoundError:
+        return out
+    for n in names:
+        d = os.path.join(base, n)
+        if not os.path.isdir(d):
+            continue
+        meta = load_json(os.path.join(d, "session.json"), {})
+        pid = meta.get("pid") or (n.rsplit("-", 1)[-1] if "-" in n else "")
+        out.append({"path": d, "name": n, "pid": pid, "alive": _pid_alive(pid) if pid else False,
+                    "started": meta.get("started", ""), "cwd": meta.get("cwd", "")})
+    return out
+
+
+def prune_sessions(keep=30, sessions_dir=None):
+    """Remove the oldest finished session dirs beyond `keep` (live pids are never
+    touched). keep=0 disables pruning. Returns the removed paths."""
+    removed = []
+    if not keep or keep < 0:
+        return removed
+    finished = [s for s in list_sessions(sessions_dir) if not s["alive"]]
+    for s in finished[:max(0, len(finished) - keep)]:
+        shutil.rmtree(s["path"], ignore_errors=True)
+        removed.append(s["path"])
+    return removed
+
+
+def _creds_ok(path):
+    d = load_json(path, {})
+    return bool(((d.get("claudeAiOauth") or {}).get("accessToken") or "").strip())
+
+
+def freshest_credentials(sessions_dir=None):
+    """Path of the newest NON-EMPTY .credentials.json among ~/.claude and every
+    per-launch session dir — Claude Code rotates the OAuth refresh token inside
+    whichever config dir it runs in, so the holder copy in ~/.claude goes stale
+    after a session refreshes. The freshest copy is synced back into ~/.claude
+    (the holder) so it stays current. Returns '' when there is no login at all."""
+    base = sessions_dir or SESSIONS_DIR
+    holder = os.path.join(LIVE_CLAUDE_DIR, ".credentials.json")
+    cands = [holder]
+    try:
+        cands += [os.path.join(base, n, ".credentials.json") for n in os.listdir(base)]
+    except FileNotFoundError:
+        pass
+    best, best_m = "", -1.0
+    for c in cands:
+        try:
+            m = os.stat(c).st_mtime
+        except OSError:
+            continue
+        if m > best_m and _creds_ok(c):
+            best, best_m = c, m
+    if best and best != holder:
+        try:
+            os.makedirs(LIVE_CLAUDE_DIR, mode=0o700, exist_ok=True)
+            shutil.copyfile(best, holder)
+            os.chmod(holder, 0o600)
+        except OSError:
+            pass
+    return best
+
+
+def _template_doc(path, shipped_name):
+    """AC_ROOT template file, else the package's shipped default (a seat with no
+    AC_ROOT materialized still gets a sane profile), else {}."""
+    doc = load_json(path, None)
+    if isinstance(doc, dict):
+        return doc
+    import json
+    try:
+        return json.loads(_pkg_default(shipped_name) or "{}")
+    except Exception:
+        return {}
+
+
+def _login_identity():
+    """oauthAccount/userID from the live ~/.claude.json (or ~/.claude/.claude.json)."""
+    holder = load_json(LIVE_DOTCLAUDE, None)
+    if not isinstance(holder, dict):
+        holder = load_json(os.path.join(LIVE_CLAUDE_DIR, ".claude.json"), {}) or {}
+    return {k: holder[k] for k in ("oauthAccount", "userID") if holder.get(k)}
+
+
+def _session_settings(settings=None):
+    """The settings.json a fresh session starts with: the given doc, else
+    $AC_SETTINGS_JSON (an embedder such as hugpy-station), else the template."""
+    import json
+    if settings is None and os.environ.get("AC_SETTINGS_JSON"):
+        try:
+            settings = json.loads(os.environ["AC_SETTINGS_JSON"])
+        except Exception:
+            settings = None
+    if not isinstance(settings, dict):
+        settings = _template_doc(TPL_SETTINGS, "settings.json")
+    return settings
+
+
+def fresh_home(cwd=None, settings=None):
+    """`abstract-claude reset` semantics on every launch (operator ruling
+    2026-09-04: "delete the .claude then run claude — no memory"): the existing
+    reset() clears ~/.claude + ~/.claude.json and keeps only the login; then the
+    session settings (template or $AC_SETTINGS_JSON) and fresh flags carrying the
+    login identity are written so Claude Code starts signed in with no
+    transcripts, history, todos, project trust or caches from earlier sessions.
+    Returns ~/.claude."""
+    cwd = cwd or os.getcwd()
+    freshest_credentials()                      # newest rotated token into the holder first
+    ident = _login_identity()                   # captured BEFORE reset removes ~/.claude.json
+    settings = _session_settings(settings)
+    reset(hard=False)
+    save_json(LIVE_SETTINGS, settings)
+    save_json(LIVE_DOTCLAUDE, session_flags(cwd, identity=ident))
+    return LIVE_CLAUDE_DIR
+
+
+def session_flags(cwd, tpl=None, identity=None):
+    """The .claude.json a fresh session starts with: template flags + MCP
+    servers, the login IDENTITY carried from the holder (~/.claude.json
+    oauthAccount/userID — without it interactive startup shows the login
+    picker even with valid credentials), onboarding/trust flags forced on,
+    folder trust for `cwd` (no trust dialog), and the toolserver MCP bridge
+    given the fleet operator token when one is resolvable. Never carries
+    project history, per-project allow-lists or any other session state."""
+    d = dict(tpl if tpl is not None else _template_doc(TPL_DOTCLAUDE, "dot-claude.json"))
+    holder = identity if isinstance(identity, dict) else load_json(LIVE_DOTCLAUDE, None)
+    if not isinstance(holder, dict):
+        holder = load_json(os.path.join(LIVE_CLAUDE_DIR, ".claude.json"), {}) or {}
+    for k in ("oauthAccount", "userID"):
+        if k not in d and holder.get(k):
+            d[k] = holder[k]
+    for k in FLAG_KEYS:
+        d.setdefault(k, True)
+    if cwd:
+        d.setdefault("projects", {}).setdefault(cwd, {})["hasTrustDialogAccepted"] = True
+    ms = d.setdefault("mcpServers", {})
+    cur = ms.get("toolserver") or {}
+    if not cur or cur.get("command") == "abstract-claude":
+        env = dict(cur.get("env") or {})
+        url = (os.environ.get("TOOLSERVER_URL") or "").strip().rstrip("/")
+        env["TOOLSERVER_URL"] = url or env.get("TOOLSERVER_URL") or "https://toolserver.hugpy.ai"
+        tok = _operator_token()
+        if tok:
+            env["TOOLSERVER_TOKEN"] = tok
+        ms["toolserver"] = {"type": "stdio", "command": "abstract-claude", "args": ["mcp"], "env": env}
+    return d
+
+
+def new_session_dir(keep_login=True, sessions_dir=None, keep=30, pid=None, cwd=None,
+                    settings=None, label=""):
+    """Materialize a BRAND-NEW per-session Claude config dir (for CLAUDE_CONFIG_DIR):
+    settings.json (the `settings` doc, else $AC_SETTINGS_JSON, else the template),
+    .claude.json from session_flags(), and a copy of the freshest login so the
+    login menu never shows. Nothing from earlier sessions (transcripts, history,
+    project trust) is carried over. Returns the new dir path."""
+    import json, re, time
+    base = sessions_dir or SESSIONS_DIR
+    pid = pid or os.getpid()
+    cwd = cwd or os.getcwd()
+    os.makedirs(base, mode=0o700, exist_ok=True)
+    label = re.sub(r"[^A-Za-z0-9_.-]+", "-", label or os.environ.get("AC_SESSION_LABEL", ""))[:32]
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    stem = f"{stamp}-{pid}" + (f"-{label}" if label else "")
+    d = os.path.join(base, stem)
+    n = 0
+    while os.path.exists(d):
+        n += 1
+        d = os.path.join(base, f"{stem}.{n}")
+    os.makedirs(d, mode=0o700)
+    if settings is None and os.environ.get("AC_SETTINGS_JSON"):
+        try:
+            settings = json.loads(os.environ["AC_SETTINGS_JSON"])
+        except Exception:
+            settings = None
+    if not isinstance(settings, dict):
+        settings = _template_doc(TPL_SETTINGS, "settings.json")
+    save_json(os.path.join(d, "settings.json"), settings)
+    save_json(os.path.join(d, ".claude.json"), session_flags(cwd))
+    kept_login = False
+    if keep_login:
+        src = freshest_credentials(base)
+        if src:
+            dst = os.path.join(d, ".credentials.json")
+            shutil.copyfile(src, dst)
+            os.chmod(dst, 0o600)
+            kept_login = True
+    save_json(os.path.join(d, "session.json"), {
+        "pid": pid, "started": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "cwd": cwd, "label": label, "template": TEMPLATE_DIR, "login_copied": kept_login,
+        "settings_source": "env:AC_SETTINGS_JSON" if os.environ.get("AC_SETTINGS_JSON") else "template",
+    })
+    try:
+        prune_sessions(keep, base)
+    except Exception:
+        pass
+    return d
+
+
+def oauth_status():
+    if has_claude_auth():
+        r = run([which_claude_auth(), "status"], timeout=20)
+        return (r["out"] + (("\n" + r["err"]) if r["err"] else "")).strip()
+    tok = load_oauth_token()
+    if tok:
+        return f"stored token: yes ({tok[:12]}…, {len(tok)} chars); source: abstract_claude store"
+    return ("stored token: none — no durable OAuth token for this toolserver. "
+            "Solution: POST /claude/oauth_solve to auto-import a token this host can "
+            "already see, else mint one on a browser/tty host "
+            "(`abstract-claude oauth-mint`) and register it with "
+            "`abstract-claude oauth-set <sk-ant-oat…>`. Full plan: /claude/oauth_solution")
+
+
+def oauth_set(token):
+    token = (token or "").strip()
+    if not token.startswith("sk-ant-"):
+        return {"ok": False, "err": "token must start with sk-ant-"}
+    path = store_oauth_token(token)                 # self-contained store (0600)
+    if has_claude_auth():                           # keep claude-auth's meta in sync too
+        run([which_claude_auth(), "set", token])
+    return {"ok": True, "out": f"stored durable token -> {path}"}
+
+
+def oauth_mint():
+    """Run `claude setup-token` via a pty, capture the printed sk-ant-oat token, store it.
+
+    The one browser approval still happens interactively (URL is teed to your
+    terminal); the token is never shown or copy-pasted — it's parsed and stored 0600.
+    """
+    import pty
+    import re
+    import sys
+
+    if not sys.stdin.isatty():
+        return {"ok": False, "err": "oauth-mint needs a terminal for browser approval; "
+                                    "use `oauth-set <token>` in non-interactive contexts"}
+    buf = bytearray()
+
+    def _read(fd):
+        data = os.read(fd, 1024)
+        buf.extend(data)
+        return data                                 # pty.spawn tees this to your terminal
+
+    try:
+        pty.spawn([real_claude(), "setup-token"], _read)
+    except Exception as e:
+        return {"ok": False, "err": f"setup-token failed: {e}"}
+    clean = re.sub(rb"\x1b\[[0-9;]*[A-Za-z]", b"", bytes(buf))   # strip ANSI
+    matches = re.findall(rb"sk-ant-oat[0-9A-Za-z_\-]+", clean)
+    if not matches:
+        return {"ok": False, "err": "no sk-ant-oat token found in setup-token output"}
+    token = max(matches, key=len).decode().strip()              # the full token
+    if len(token) < 80:
+        return {"ok": False, "err": f"captured token looks truncated ({len(token)} chars)"}
+    path = store_oauth_token(token)
+    if has_claude_auth():
+        run([which_claude_auth(), "set", token])
+    return {"ok": True, "out": f"minted + stored durable token ({token[:12]}…) -> {path}"}
+
+
+def _credentials_token():
+    """Best-effort durable/OAuth token from the live Claude CLI credential store
+    (~/.claude/.credentials.json) — left behind by any claude login in this HOME."""
+    data = load_json(os.path.join(HOME, ".claude", ".credentials.json"), {})
+    oa = (data or {}).get("claudeAiOauth") or {}
+    return oa.get("accessToken") or data.get("CLAUDE_CODE_OAUTH_TOKEN") or None
+
+
+def discover_oauth_sources():
+    """Token candidates this headless host could adopt WITHOUT a browser, best-first.
+    Each: {source, path, token, kind}. `kind` is 'durable' for sk-ant-oat… tokens."""
+    def _kind(t):
+        return "durable" if t.startswith("sk-ant-oat") else "oauth"
+
+    found, seen = [], set()
+    for source, path, tok in (
+        ("env:CLAUDE_CODE_OAUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN",
+         os.environ.get("CLAUDE_CODE_OAUTH_TOKEN")),
+        ("claude-cli-credentials", os.path.join(HOME, ".claude", ".credentials.json"),
+         _credentials_token()),
+    ):
+        if tok and tok not in seen:
+            seen.add(tok)
+            found.append({"source": source, "path": path, "token": tok, "kind": _kind(tok)})
+    return found
+
+
+def oauth_solution():
+    """Offer a concrete way to ATTAIN a durable OAuth token when none is stored.
+
+    Read-only: reports current state, any token this host could auto-import, and the
+    exact ordered steps. `/claude/oauth_solve` performs the auto-import; minting a
+    fresh token needs a browser/tty and therefore happens off-server.
+    """
+    tok = load_oauth_token()
+    if tok:
+        return {"ok": True, "have_token": True, "stored_to": OAUTH_ENV,
+                "message": f"durable token already stored ({tok[:12]}…, {len(tok)} chars)"}
+    sources = discover_oauth_sources()
+    steps = []
+    if sources:
+        steps.append("Auto-import a token this host can already see: "
+                     "POST /claude/oauth_solve (adopts the best source below).")
+    steps.append("Mint a fresh 1-year token on a machine WITH a browser/tty "
+                 "(`abstract-claude oauth-mint`, or `claude setup-token`), then register "
+                 "it here: `abstract-claude oauth-set <sk-ant-oat…>` "
+                 "(POST /claude/oauth_set {\"token\": \"sk-ant-oat…\"}).")
+    return {
+        "ok": False, "have_token": False,
+        "reason": "no durable OAuth token stored for this toolserver",
+        "can_auto_import": bool(sources),
+        "importable_sources": [
+            {"source": s["source"], "path": s["path"], "kind": s["kind"],
+             "preview": s["token"][:12] + "…"} for s in sources
+        ],
+        "steps": steps,
+        "host_note": "this toolserver runs headless (no browser/tty), so a fresh mint "
+                     "must happen elsewhere; oauth_solve/oauth_set register it here",
+    }
+
+
+def oauth_solve(import_from=None):
+    """Attain a durable token automatically when possible: no-op if one is already
+    stored, else adopt the best discovered source (or the one named by `import_from`).
+    When nothing is importable, returns the oauth_solution() plan (with the manual
+    mint steps) rather than failing silently."""
+    tok = load_oauth_token()
+    if tok:
+        return {"ok": True, "attained": False, "already": True, "stored_to": OAUTH_ENV,
+                "message": f"durable token already stored ({tok[:12]}…)"}
+    sources = discover_oauth_sources()
+    if import_from:
+        sources = [s for s in sources if s["source"] == import_from] or sources
+    if not sources:
+        sol = oauth_solution()
+        sol.update({"ok": False, "attained": False,
+                    "message": "nothing to auto-import; follow the mint steps"})
+        return sol
+    chosen = sources[0]
+    path = store_oauth_token(chosen["token"])
+    if has_claude_auth():
+        run([which_claude_auth(), "set", chosen["token"]])
+    return {"ok": True, "attained": True, "source": chosen["source"],
+            "kind": chosen["kind"], "stored_to": path,
+            "message": f"imported durable token from {chosen['source']} "
+                       f"({chosen['token'][:12]}…)"}
+
+
+def oauth_probe():
+    if has_claude_auth():
+        return run([which_claude_auth(), "probe"], timeout=40)
+    tok = load_oauth_token()
+    if tok:
+        return {"ok": True, "out": f"token present ({tok[:12]}…) — "
+                "no claude-auth binary to run a live probe"}
+    return {"ok": False, "out": "no token stored", "solution": oauth_solution()}
+
+
+def set_model(default_model=None, quota_fallback_model=None, fallback_model=None):
+    live = load_json(LIVE_SETTINGS, {})
+    cfg = load_json(CONFIG_PATH, {})
+    if default_model:
+        live["model"] = default_model
+        cfg["default_model"] = default_model
+    if fallback_model is not None:
+        fm = [x for x in fallback_model if x]
+        if fm:
+            live["fallbackModel"] = fm
+        else:
+            live.pop("fallbackModel", None)
+    if quota_fallback_model:
+        cfg["quota_fallback_model"] = quota_fallback_model
+    save_json(LIVE_SETTINGS, live)
+    save_json(CONFIG_PATH, cfg)
+    return {"ok": True}
+
+
+def mcp_tool_catalog(base=None, server="toolserver"):
+    """Group the toolserver's live tools into MCP permission strings, so the console can
+    render a checklist for permissions.allow instead of hand-typing `mcp__<server>__<tool>`.
+    Best-effort: returns an empty catalog (+ error) if the toolserver is unreachable."""
+    import json as _json
+    import urllib.request
+    base = (base or os.environ.get("TOOLSERVER_URL", "http://127.0.0.1:7004")).rstrip("/")
+    out = {"server": server, "perm_all": "mcp__%s" % server, "base": base, "categories": []}
+    try:
+        with urllib.request.urlopen(base + "/endpoints", timeout=8) as r:
+            eps = _json.loads(r.read().decode())
+    except Exception as exc:  # noqa: BLE001 - surface unreachable toolserver to the UI
+        out["error"] = str(exc)
+        return out
+    seen, cats = set(), {}
+    for ep in (eps if isinstance(eps, list) else []):
+        url = (ep or {}).get("url", "")
+        if not url or url.endswith("/"):
+            continue
+        seg = url.strip("/").split("/")
+        if seg[0] in ("endpoints", "prefixes") or any("<" in s for s in seg):
+            continue
+        name = "_".join(seg)                       # tool id = mcp bridge name (cat_route)
+        if name in seen:
+            continue
+        seen.add(name)
+        cats.setdefault(seg[0], []).append({"tool": name, "perm": "mcp__%s__%s" % (server, name)})
+    out["categories"] = [{"name": c, "tools": sorted(cats[c], key=lambda t: t["tool"])}
+                         for c in sorted(cats)]
+    return out
+
+
+def build_state():
+    ver = run(["claude", "--version"], timeout=15)
+    return {
+        "config": paths.load_config(),
+        "live_settings": load_json(LIVE_SETTINGS, {}),
+        "template_settings": load_json(TPL_SETTINGS, {}),
+        "template_dotclaude": load_json(TPL_DOTCLAUDE, {}),
+        "oauth": oauth_status(),
+        "version": ver["out"] or ver["err"],
+        "bool_keys": BOOL_KEYS,
+        "effort_values": EFFORT_VALUES,
+        "perm_modes": PERM_MODES,
+        "mcp_tools": mcp_tool_catalog(),
+        "live_settings_path": LIVE_SETTINGS,
+        "root": ROOT,
+    }