hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/anthropic_params.py

@@ -0,0 +1,225 @@
+"""Thinking / effort / max_tokens parameters for Anthropic Messages requests.
+
+One place decides how HyperClaw asks a Claude model to think. Call sites
+never write ``thinking=`` or ``budget_tokens`` themselves; they call
+:func:`thinking_params` with the model id and splat the result into
+``client.messages.create`` / ``client.messages.stream``.
+
+Why: models differ, and sending the wrong shape is a hard 400. The 5.x
+generation (Claude Opus 5.5, Claude Sonnet 5.5, Fable 5/5.1, Opus 5,
+Sonnet 5, Opus 4.7/4.8) rejects ``thinking: {type: "enabled",
+budget_tokens: N}``; they take ``thinking: {type: "adaptive"}`` with depth
+set by ``output_config.effort``. Older models (Haiku 4.5, Sonnet/Opus 4.5
+and earlier) only think with ``enabled`` + ``budget_tokens`` (budget >=
+1024 and < ``max_tokens``). Models without thinking get no thinking param.
+
+The capability table below is data. Per-model overrides live in
+``models.yaml`` under ``models.<model id>``::
+
+    models:
+      claude-sonnet-5-5:
+        thinking: adaptive        # adaptive | enabled | none
+        effort: high              # low | medium | high | xhigh | max
+        thinking_budget: 8000     # only used with thinking: enabled
+
+An override can never ask a model for a mode it rejects: ``enabled`` on a
+model without ``budget_tokens`` support falls back to ``adaptive``, and an
+effort level the model does not list is ignored (both logged).
+
+Unknown models (not in the table, no override): thinking and effort are
+OMITTED. Omitting ``thinking`` is accepted by every Claude model — current
+models then think adaptively by default, older ones answer without
+thinking — so an unknown id can never 400 on these parameters.
+
+Model ids are normalised before lookup, so Bedrock (``anthropic.…``,
+``us.anthropic.…``, ``-v1:0``), Vertex (``@2025…``), dated snapshots
+(``-20251001``) and ``[1m]`` suffixes all resolve to the same entry.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+log = logging.getLogger("hyperclaw.anthropic_params")
+
+THINKING_MODES = ("adaptive", "enabled", "none")
+ALL_EFFORTS = ("low", "medium", "high", "xhigh", "max")
+_E5 = ALL_EFFORTS
+_E46 = ("low", "medium", "high", "max")
+
+DEFAULT_THINKING_BUDGET = 10000
+MIN_THINKING_BUDGET = 1024          # API minimum for budget_tokens
+
+
+@dataclass(frozen=True)
+class ModelThinking:
+    mode: str                         # adaptive | enabled | none
+    effort: Optional[str] = None      # default output_config.effort (None = omit)
+    efforts: tuple = ()               # effort levels the model accepts
+    budget_tokens: bool = False       # accepts thinking.type "enabled" + budget
+    display: Optional[str] = None     # thinking.display to request (adaptive only)
+
+
+def _adaptive(effort=None, efforts=_E5, display="summarized"):
+    return ModelThinking("adaptive", effort, efforts, False, display)
+
+
+_LEGACY = ModelThinking("enabled", None, (), True, None)
+_NONE = ModelThinking("none", None, (), False, None)
+
+# Capability table. Keys are normalised ids (see normalize_model_id).
+# display="summarized" is requested where the API default is "omitted"
+# (empty thinking text), so the TUI's visible-thinking stream has content.
+CAPABILITIES: dict = {
+    # 5.5 generation: adaptive + explicit effort. Opus 5.5's API default is
+    # "medium" (one below Opus 5), so it is set explicitly; Sonnet 5.5 levels
+    # are recalibrated and "medium" is the documented starting point for
+    # agentic, multistep tool use.
+    "claude-opus-5-5": _adaptive(effort="high"),
+    "claude-sonnet-5-5": _adaptive(effort="medium"),
+    # Thinking always on; enabled/disabled are 400s.
+    "claude-fable-5-1": _adaptive(),
+    "claude-mythos-5-1": _adaptive(),
+    "claude-fable-5": _adaptive(),
+    "claude-mythos-5": _adaptive(),
+    # Adaptive only; budget_tokens is a 400.
+    "claude-opus-5": _adaptive(),
+    "claude-sonnet-5": _adaptive(),
+    "claude-opus-4-8": _adaptive(),
+    "claude-opus-4-7": _adaptive(),
+    # 4.6: adaptive recommended (budget_tokens deprecated); no xhigh; the
+    # API already returns summarized thinking, so no display override.
+    "claude-opus-4-6": _adaptive(efforts=_E46, display=None),
+    "claude-sonnet-4-6": _adaptive(efforts=_E46, display=None),
+    # Legacy extended thinking: enabled + budget_tokens only.
+    "claude-haiku-4-5": _LEGACY,
+    "claude-sonnet-4-5": _LEGACY,
+    "claude-opus-4-5": _LEGACY,
+    "claude-opus-4-1": _LEGACY,
+    "claude-opus-4": _LEGACY,
+    "claude-sonnet-4": _LEGACY,
+    "claude-3-7-sonnet": _LEGACY,
+    # No extended thinking.
+    "claude-3-5-haiku": _NONE,
+    "claude-3-5-sonnet": _NONE,
+    "claude-3-haiku": _NONE,
+    "claude-3-opus": _NONE,
+}
+
+UNKNOWN = _NONE   # see module docstring: omit thinking for unknown ids
+
+_PREFIX = re.compile(r"^(?:[a-z]+\.)?anthropic\.")       # Bedrock (+ geo)
+_SUFFIXES = (
+    re.compile(r"\[[^\]]*\]$"),        # [1m]
+    re.compile(r"@.*$"),               # Vertex @20251001
+    re.compile(r"-v\d+(?::\d+)?$"),    # Bedrock -v1:0
+    re.compile(r"-\d{8}$"),            # dated snapshot
+    re.compile(r"-latest$"),
+)
+
+
+def normalize_model_id(model: str) -> str:
+    m = (model or "").strip().lower()
+    m = m.rsplit("/", 1)[-1]            # ARNs / inference-profile paths
+    m = _PREFIX.sub("", m)
+    for _ in range(2):
+        for rx in _SUFFIXES:
+            m = rx.sub("", m)
+    return m
+
+
+def capability_for(model: str) -> ModelThinking:
+    return CAPABILITIES.get(normalize_model_id(model), UNKNOWN)
+
+
+def load_model_overrides(model: str) -> dict:
+    """``models.<id>`` thinking/effort/thinking_budget from models.yaml
+    (user copy, else packaged). Matches the raw id first, then the
+    normalised one. Never raises."""
+    try:
+        import yaml
+        from hyperclaw.api_utils import find_config
+        p = find_config("models.yaml")
+        data = yaml.safe_load(p.read_text()) if p.exists() else {}
+        models = (data or {}).get("models") or {}
+        entry = models.get(model)
+        if entry is None:
+            norm = normalize_model_id(model)
+            entry = next((v for k, v in models.items()
+                          if normalize_model_id(str(k)) == norm), None)
+        entry = entry or {}
+        return {k: entry[k] for k in ("thinking", "effort", "thinking_budget")
+                if k in entry and entry[k] is not None}
+    except Exception as e:   # config problems must not break a chat turn
+        log.warning(f"models.yaml thinking overrides unreadable ({e})")
+        return {}
+
+
+def thinking_params(model: str, max_tokens: int = 16000,
+                    overrides: Optional[dict] = None,
+                    use_config: bool = True) -> dict:
+    """Request kwargs for ``model``: always ``max_tokens``; ``thinking`` and
+    ``output_config`` only when the model takes them.
+
+    ``overrides`` (thinking/effort/thinking_budget) wins over models.yaml,
+    which wins over the capability table."""
+    cap = capability_for(model)
+    ov = {}
+    if use_config:
+        ov.update(load_model_overrides(model))
+    ov.update(overrides or {})
+
+    mode = str(ov.get("thinking", cap.mode)).lower()
+    if mode in ("false", "off", "disabled"):
+        mode = "none"
+    if mode not in THINKING_MODES:
+        log.warning(f"thinking={mode!r} for {model} is not one of {THINKING_MODES}; "
+                    f"using {cap.mode}")
+        mode = cap.mode
+    if mode == "enabled" and not cap.budget_tokens:
+        log.warning(f"{model} does not accept thinking.type 'enabled'; using adaptive")
+        mode = "adaptive"
+    if mode == "adaptive" and cap is UNKNOWN and "thinking" not in ov:
+        mode = "none"
+
+    out: dict = {"max_tokens": int(max_tokens)}
+    if mode == "adaptive":
+        thinking = {"type": "adaptive"}
+        if cap.display:
+            thinking["display"] = cap.display
+        out["thinking"] = thinking
+        effort = ov.get("effort", cap.effort)
+        if effort is not None:
+            effort = str(effort).lower()
+            allowed = cap.efforts or ALL_EFFORTS
+            if effort in allowed:
+                out["output_config"] = {"effort": effort}
+            else:
+                log.warning(f"effort={effort!r} not supported by {model}; omitted")
+    elif mode == "enabled":
+        budget = int(ov.get("thinking_budget", DEFAULT_THINKING_BUDGET))
+        budget = min(budget, int(max_tokens) - MIN_THINKING_BUDGET)  # leave room to answer
+        if budget >= MIN_THINKING_BUDGET:
+            out["thinking"] = {"type": "enabled", "budget_tokens": budget}
+    return out
+
+
+def as_sdk_kwargs(params: dict, method) -> dict:
+    """Adapt :func:`thinking_params` output to the installed SDK: an SDK too
+    old to know ``output_config`` (pyproject allows anthropic>=0.28) gets it
+    via ``extra_body`` so the wire request is identical."""
+    out = dict(params)
+    if "output_config" in out:
+        try:
+            import inspect
+            known = "output_config" in inspect.signature(method).parameters
+        except (TypeError, ValueError):
+            known = True
+        if not known:
+            extra = dict(out.pop("extra_body", None) or {})
+            extra["output_config"] = out.pop("output_config")
+            out["extra_body"] = extra
+    return out

hyperclaw/api_utils.py

@@ -0,0 +1,85 @@
+"""Helpers for reading Claude API responses and locating config files.
+
+Adaptive-thinking models (the Claude 5 family, Opus/Sonnet 4.6 and later)
+may return thinking blocks before — or instead of — text blocks, so
+``response.content[0]`` is not guaranteed to be a TextBlock. Reading
+``.content[0].text`` raises AttributeError on those responses. Always go
+through :func:`extract_text` / :func:`extract_json` instead.
+"""
+
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+
+
+def extract_text(response, default: str = "") -> str:
+    """Join all text blocks of a Messages API response, skipping thinking
+    and tool_use blocks. Returns ``default`` when no text block exists."""
+    blocks = getattr(response, "content", None) or []
+    parts = [b.text for b in blocks if getattr(b, "type", "") == "text" and getattr(b, "text", "")]
+    return "\n".join(parts).strip() or default
+
+
+def extract_json(response):
+    """extract_text + json.loads, tolerating ```json fences around the body."""
+    text = extract_text(response)
+    m = re.search(r"```(?:json)?\s*(.*?)```", text, re.S)
+    if m:
+        text = m.group(1)
+    return json.loads(text)
+
+
+def gmail_token_path() -> Path:
+    """The Gmail OAuth token file the Gmail tools read.
+
+    Checks ``workspace/secrets/`` (the historical location) then ``secrets/``
+    (the directory onboarding creates), under ``$HYPERCLAW_ROOT`` and
+    ``~/.hyperclaw``. Returns the first that exists, else the historical path.
+    """
+    roots = [Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw")),
+             Path.home() / ".hyperclaw"]
+    candidates = []
+    for root in roots:
+        for sub in ("workspace/secrets", "secrets"):
+            c = root / sub / "gmail_token.json"
+            if c not in candidates:
+                candidates.append(c)
+    for c in candidates:
+        if c.exists():
+            return Path(os.path.realpath(c))
+    return candidates[0]
+
+
+def gmail_configured() -> bool:
+    """True when the Gmail tools have credentials: a token file, or the
+    GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET / GMAIL_REFRESH_TOKEN env fallback."""
+    env = os.environ
+    return (gmail_token_path().exists() or bool(env.get("GMAIL_TOKEN"))
+            or all(env.get(k) for k in ("GMAIL_CLIENT_ID", "GMAIL_CLIENT_SECRET",
+                                        "GMAIL_REFRESH_TOKEN")))
+
+
+def find_config(name: str) -> Path:
+    """Locate a HyperClaw config file (e.g. ``agents.yaml``).
+
+    Order: the user's ``$HYPERCLAW_ROOT/config`` (seeded on first access),
+    then a development checkout's ``config/`` directory, then the copy
+    shipped inside the package. Always returns the user path so edits land
+    in one place; callers should still check ``.exists()``.
+    """
+    root = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw"))
+    user = root / "config" / name
+    if user.exists():
+        return user
+    here = Path(__file__).resolve().parent
+    for src in (here.parent / "config" / name, here / "default_config" / name):
+        if src.exists():
+            try:
+                user.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy(src, user)
+                return user
+            except OSError:
+                return src
+    return user

hyperclaw/approval_telegram.py

@@ -0,0 +1,209 @@
+"""
+Send / Edit / Cancel in Telegram (inline buttons).
+
+Every item in the durable approval queue (tools/approval.py) is shown to the
+owner chat with its exact content and three buttons. Only the owner can press
+them: a button press from any other chat or user is refused and logged.
+
+- Send   -> the stored payload runs once, only if the hash on the button still
+            matches the stored payload.
+- Edit   -> the bot asks for the new content; the owner's next message in that
+            chat replaces it, and the new version is shown again with new
+            buttons (the old buttons stop working).
+- Cancel -> nothing runs.
+
+Cards go out with link previews off. Terminal-only actions (shell, desktop
+control) cannot be approved from here.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Dict, List, Optional, Tuple
+
+from hyperclaw.chat_scope import OWNER, owner_ids, scope_for
+from hyperclaw.tools import approval as ap
+
+log = logging.getLogger("hyperclaw.telegram.approval")
+
+CB_PREFIX = "ap"
+CHUNK = 3900
+OPS = {"s": "send", "e": "edit", "c": "cancel"}
+
+
+def callback_data(op: str, item: ap.PendingAction) -> str:
+    return f"{CB_PREFIX}:{op}:{item.id}:{item.short_hash}"   # < 64 bytes
+
+
+def parse_callback(data: str) -> Optional[Tuple[str, str, str]]:
+    parts = str(data or "").split(":")
+    if len(parts) != 4 or parts[0] != CB_PREFIX or parts[1] not in OPS:
+        return None
+    return parts[1], parts[2], parts[3]
+
+
+def keyboard(item: ap.PendingAction):
+    from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+    return InlineKeyboardMarkup([[
+        InlineKeyboardButton("Send", callback_data=callback_data("s", item)),
+        InlineKeyboardButton("Edit", callback_data=callback_data("e", item)),
+        InlineKeyboardButton("Cancel", callback_data=callback_data("c", item)),
+    ]])
+
+
+def card_chunks(item: ap.PendingAction) -> List[str]:
+    """The full card split into Telegram-sized parts (the exact content is
+    never cut; the last part carries the buttons)."""
+    text = ap.render(item)
+    if item.tool in ap._terminal_only():
+        text += "\n(This can only be approved in the HyperAgents terminal: /approvals.)"
+    return [text[i:i + CHUNK] for i in range(0, len(text), CHUNK)] or [text]
+
+
+def actor_for(chat_id, user_id) -> ap.Actor:
+    """Owner only when the chat is the owner chat AND the person pressing is
+    the owner (in a private chat the user id is the chat id)."""
+    chat_ok = scope_for("telegram", chat_id) == OWNER
+    user_ok = user_id is not None and (str(user_id) == str(chat_id)
+                                       or str(user_id) in owner_ids("telegram"))
+    role = "owner" if (chat_ok and user_ok) else "guest"
+    return ap.Actor(role, str(user_id), "telegram")
+
+
+async def push_pending(bot, queue: Optional[ap.ApprovalQueue] = None) -> int:
+    """Show every not-yet-shown pending item to the owner chat(s)."""
+    q = queue or ap.get_queue()
+    owners = sorted(owner_ids("telegram"))
+    if not owners:
+        return 0
+    sent = 0
+    for item in q.pending(unnotified_only=True):
+        notes = []
+        for chat in owners:
+            try:
+                await show(bot, chat, item)
+                notes.append(f"telegram:{chat}")
+            except Exception as e:
+                log.warning("could not show approval %s to the owner chat: %s", item.id,
+                            type(e).__name__)
+        if notes:
+            q.mark_notified(item.id, ",".join(notes))
+            sent += 1
+    return sent
+
+
+async def show(bot, chat_id, item: ap.PendingAction) -> None:
+    from hyperclaw.tools.egress import TELEGRAM_NO_PREVIEW
+    from telegram import LinkPreviewOptions
+    no_preview = LinkPreviewOptions(is_disabled=TELEGRAM_NO_PREVIEW["link_preview_options"]
+                                    ["is_disabled"])
+    chunks = card_chunks(item)
+    for i, part in enumerate(chunks):
+        last = i == len(chunks) - 1
+        await bot.send_message(chat_id=int(chat_id), text=part,
+                               link_preview_options=no_preview,
+                               reply_markup=keyboard(item) if last else None)
+
+
+class TelegramApprovals:
+    """Button presses and the Edit conversation for one bot process."""
+
+    def __init__(self, registry=None, queue: Optional[ap.ApprovalQueue] = None):
+        self.registry = registry
+        self.queue = queue
+        self.awaiting_edit: Dict[int, str] = {}   # chat_id -> action id
+
+    @property
+    def q(self) -> ap.ApprovalQueue:
+        return self.queue or ap.get_queue()
+
+    async def on_callback(self, update, context) -> None:
+        query = update.callback_query
+        parsed = parse_callback(getattr(query, "data", ""))
+        if parsed is None:
+            return
+        op, aid, h = parsed
+        chat_id = query.message.chat.id if query.message else None
+        user_id = query.from_user.id if query.from_user else None
+        actor = actor_for(chat_id, user_id)
+        if not actor.is_owner:
+            log.warning("approval button pressed by a non-owner (chat %s); refused", chat_id)
+            # Records the refusal in the append-only events (raises ApprovalError).
+            try:
+                self.q.cancel(aid, actor)
+            except ap.ApprovalError:
+                pass
+            await query.answer("Only the owner can approve this.", show_alert=True)
+            return
+        if op == "s":
+            await query.answer("Sending…")
+            loop = asyncio.get_running_loop()
+            env = await loop.run_in_executor(
+                None, lambda: ap.send(aid, h, actor, registry=self.registry, queue=self.q))
+            await self._close_card(query)
+            await query.message.reply_text(_outcome("Sent" if env.ok else "Not sent", env))
+        elif op == "c":
+            env = ap.cancel(aid, actor, queue=self.q)
+            await query.answer("Cancelled" if "Cancelled" in env.message else "Not cancelled")
+            await self._close_card(query)
+            await query.message.reply_text(env.message)
+        else:
+            item = self.q.get(aid)
+            if item is None or item.status != ap.PENDING or not item.payload_hash.startswith(h):
+                await query.answer("This is no longer pending.", show_alert=True)
+                return
+            if item.tool in ap._terminal_only():
+                await query.answer("Edit this in the HyperAgents terminal.", show_alert=True)
+                return
+            self.awaiting_edit[int(chat_id)] = aid
+            fld = ap.EDIT_FIELD.get(item.tool)
+            await query.answer()
+            await query.message.reply_text(
+                f"Send me the new {fld} for [{aid}] (or a JSON object with all the arguments). "
+                f"I'll show it again before anything is sent." if fld else
+                f"Send me the new arguments for [{aid}] as a JSON object. I'll show it again "
+                f"before anything is sent.")
+
+    async def on_owner_text(self, update, context) -> bool:
+        """The owner's reply after Edit. True when the message was consumed."""
+        chat_id = update.effective_chat.id
+        aid = self.awaiting_edit.get(int(chat_id))
+        if not aid:
+            return False
+        user_id = update.effective_user.id if update.effective_user else None
+        actor = actor_for(chat_id, user_id)
+        if not actor.is_owner:
+            return False
+        self.awaiting_edit.pop(int(chat_id), None)
+        try:
+            new_item = ap.edit(aid, update.message.text, actor, registry=self.registry,
+                               queue=self.q)
+        except ap.ApprovalError as e:
+            await update.message.reply_text(f"Edit not applied: {e}")
+            return True
+        await show(context.bot, chat_id, new_item)
+        self.q.mark_notified(new_item.id, f"telegram:{chat_id}")
+        return True
+
+    @staticmethod
+    async def _close_card(query) -> None:
+        try:
+            await query.edit_message_reply_markup(reply_markup=None)
+        except Exception:
+            pass
+
+
+def _outcome(prefix: str, env) -> str:
+    rid = f" (receipt {env.receipt_id})" if getattr(env, "receipt_id", None) else ""
+    return f"{prefix}: {env.status}. {env.message[:3000]}{rid}"
+
+
+async def pending_loop(bot, interval: float = 5.0) -> None:
+    """Background: deliver cards queued by any surface (bridge, sub-agents,
+    dashboard) to the owner chat."""
+    while True:
+        try:
+            await push_pending(bot)
+        except Exception:
+            log.warning("approval push failed", exc_info=True)
+        await asyncio.sleep(interval)

hyperclaw/approval_terminal.py

@@ -0,0 +1,80 @@
+"""
+Send / Edit / Cancel in the HyperAgents terminal.
+
+When a tool call in the terminal is queued for approval, the owner sees the
+exact content right away and answers s (send), e (edit) or c (cancel). Edit
+asks for the new content and shows it again. The terminal is the owner's own
+surface, so its answers are owner decisions; nothing here runs without one.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Callable, Optional
+
+from hyperclaw.tools import approval as ap
+from hyperclaw.tools.envelope import Status, make
+
+
+def interactive() -> bool:
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def prompt(item: ap.PendingAction, *, input_fn: Optional[Callable[[str], str]] = None,
+           print_fn: Optional[Callable[[str], None]] = None, registry=None,
+           queue: Optional[ap.ApprovalQueue] = None, ledger=None):
+    """Ask the owner about one queued item. Returns the envelope the model
+    sees: the tool's real result after Send, or a 'nothing was done' result."""
+    import builtins
+    input_fn = input_fn or builtins.input
+    print_fn = print_fn or builtins.print
+    q = queue or ap.get_queue()
+    while True:
+        try:
+            q.mark_notified(item.id, "tui")   # shown here; no second card elsewhere
+        except Exception:
+            pass
+        print_fn("\n" + ap.render(item))
+        try:
+            ans = input_fn("Send, edit or cancel? [s/e/c] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            ans = "c"
+        if ans in ("s", "send"):
+            return ap.send(item.id, item.payload_hash, ap.TERMINAL_OWNER, registry=registry,
+                           queue=q, ledger=ledger)
+        if ans in ("c", "cancel", "n", "no"):
+            return ap.cancel(item.id, ap.TERMINAL_OWNER, queue=q)
+        if ans in ("e", "edit"):
+            fld = ap.EDIT_FIELD.get(item.tool)
+            hint = (f"New {fld} (or a JSON object of all arguments)" if fld
+                    else "New arguments as a JSON object")
+            try:
+                new = input_fn(f"{hint}: ")
+            except (EOFError, KeyboardInterrupt):
+                continue
+            try:
+                item = ap.edit(item.id, new, ap.TERMINAL_OWNER, registry=registry, queue=q)
+            except ap.ApprovalError as e:
+                print_fn(f"Edit not applied: {e}")
+                fresh = q.get(item.id)
+                if fresh is None or fresh.status != ap.PENDING:
+                    return make(Status.PERMISSION_DENIED, f"Not sent: {e}")
+            continue
+        print_fn("Please answer s, e or c.")
+
+
+def review_pending(*, input_fn=None, print_fn=None, registry=None) -> int:
+    """/approvals: walk every pending item (from any surface) with the prompt.
+    Terminal-only tools queued elsewhere can only be approved here."""
+    import builtins
+    print_fn = print_fn or builtins.print
+    items = ap.get_queue().pending()
+    if not items:
+        print_fn("Nothing is waiting for approval.")
+        return 0
+    for item in items:
+        env = prompt(item, input_fn=input_fn, print_fn=print_fn, registry=registry)
+        print_fn(f"[{item.id}] {env.status}: {env.message[:300]}")
+    return len(items)