hunch-sdk 0.3.0__py3-none-any.whl

hunch/__init__.py

@@ -0,0 +1,32 @@
+"""Hunch — drive your Mac focus-free over MCP.
+
+This module is intentionally dependency-free: the CLI (config, creds, connect,
+doctor) must work even when pyobjc or the MCP SDK are missing, so nothing here
+may import them. The server loads lazily via `hunch serve`.
+"""
+
+__version__ = "0.3.0"
+
+# Public SDK surface, loaded lazily (PEP 562) so bare `import hunch` stays dependency-free:
+# touching any of these names pulls in pyobjc via the real modules.
+_LAZY = {
+    "Hunch": ".sdk",
+    "Agent": ".agent",
+    "AgentResult": ".agent",
+    "HunchError": ".gate",
+    "ApprovalDenied": ".gate",
+    "AccessibilityNotGranted": ".gate",
+    "WebNotOpen": ".gate",
+    "StaleRef": ".local_mac",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY:
+        from importlib import import_module
+        return getattr(import_module(_LAZY[name], __name__), name)
+    raise AttributeError(f"module 'hunch' has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted([*globals(), *_LAZY])

hunch/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

hunch/agent.py

@@ -0,0 +1,445 @@
+"""agent.py — the Hunch agent loop: an LLM drives this Mac through the Hunch
+primitives, on the user's own machine and logged-in apps.
+
+    from hunch import Hunch
+    mac = Hunch()
+    result = mac.agent.run("reply to Sarah's latest email, but don't send it")
+    print(result.text)
+
+Anthropic-only in v1: Claude reads the Hunch playbook as its system prompt and drives
+the Mac through the same tools the MCP server exposes. Other models can use the instance
+SDK primitives directly in their own harness. `anthropic` is an OPTIONAL dependency
+(pip install 'hunch-sdk[agent]'), imported lazily so plain `import hunch` stays clean.
+
+Provider seam: request construction and response parsing are isolated in _request /
+_parse_response so a future backend adapter has a clean boundary — no abstraction layer
+is built now.
+"""
+import base64
+from dataclasses import dataclass, field
+
+from .playbook import HUNCH_PLAYBOOK
+from .gate import HunchError, ApprovalDenied, AccessibilityNotGranted, WebNotOpen
+
+__all__ = ["Agent", "AgentResult"]
+
+DEFAULT_MODEL = "claude-opus-4-8"
+
+# ── tool schemas ──────────────────────────────────────────────────────────────
+# The full-input action item (native AX layer). Shared by the `act` tool.
+_ACTION_ITEM = {
+    "type": "object",
+    "properties": {
+        "action": {"type": "string",
+                   "enum": ["click", "right_click", "select", "type", "menu", "key", "click_xy"]},
+        "ref": {"type": "string"}, "text": {"type": "string"},
+        "path": {"type": "array", "items": {"type": "string"}},
+        "key": {"type": "string"}, "modifiers": {"type": "array", "items": {"type": "string"}},
+        "x": {"type": "integer"}, "y": {"type": "integer"}},
+    "required": ["action"]}
+
+# The web/CDP action item — a smaller verb set (no menu/pixel; navigate instead).
+_WEB_ACTION_ITEM = {
+    "type": "object",
+    "properties": {
+        "action": {"type": "string", "enum": ["click", "type", "key", "navigate"]},
+        "ref": {"type": "string"}, "text": {"type": "string"},
+        "key": {"type": "string"}, "modifiers": {"type": "array", "items": {"type": "string"}},
+        "url": {"type": "string"}},
+    "required": ["action"]}
+
+
+def _obj(props=None, required=None):
+    return {"type": "object", "properties": props or {}, **({"required": required} if required else {})}
+
+
+# Names identical to the MCP tools so every HUNCH_PLAYBOOK reference resolves. Descriptions
+# are condensed (the deep procedural guidance lives in the playbook system prompt); each keeps
+# the prescriptive when-to-call sentence, which measurably lifts should-call rate on Opus.
+AGENT_TOOLS = [
+    {"name": "snapshot",
+     "description": ("See an app as an accessibility tree ([ref] per element) — your primary way "
+                     "to read UI focus-free. Pass an app name or leave blank for the frontmost. "
+                     "ref='e42' re-walks just that element's subtree; truncated trees end in `…` "
+                     "markers naming what was dropped."),
+     "input_schema": _obj({"app": {"type": "string"}, "ref": {"type": "string"},
+                           "max_depth": {"type": "integer"}, "max_nodes": {"type": "integer"}})},
+    {"name": "find",
+     "description": ("Search an app's WHOLE tree for matching elements without reading a full "
+                     "snapshot — the cheap way to locate one control in a big window. Filter by "
+                     "role (e.g. 'button', case-insensitive) and/or name_contains (substring of "
+                     "title/description/value). Returns actable [ref]s."),
+     "input_schema": _obj({"role": {"type": "string"}, "name_contains": {"type": "string"},
+                           "app": {"type": "string"}, "max_results": {"type": "integer"}})},
+    {"name": "act",
+     "description": ("Run UI actions in order by ref, then get the updated tree. Verbs: click "
+                     "(activate), right_click (context menu), select (highlight a row), type (set "
+                     "a field by ref = focus-free; no ref types at focus = STEALS FOCUS), menu "
+                     "(invoke a menu-bar path, e.g. ['File','Move to Trash'] — the focus-free "
+                     "stand-in for ⌘-shortcuts), key/click_xy (STEAL FOCUS, last resort). Prefer "
+                     "the focus-free verbs. Pass `reason` when any action steals focus."),
+     "input_schema": _obj({"actions": {"type": "array", "items": _ACTION_ITEM},
+                           "reason": {"type": "string"}}, ["actions"])},
+    {"name": "screenshot",
+     "description": ("See the frontmost app as a PNG — only for genuinely visual content the tree "
+                     "can't convey (an image, a chart). To read UI text or check an action, "
+                     "re-snapshot instead."),
+     "input_schema": _obj()},
+    {"name": "list_apps", "description": "List the running GUI apps you can target with snapshot.",
+     "input_schema": _obj()},
+    {"name": "launch_app",
+     "description": ("Launch or focus an app (reliable OS call — beats clicking the Dock). Set "
+                     "force_accessibility=true for an Electron/Chromium app whose tree reads empty. "
+                     "In simultaneous mode it launches in the background."),
+     "input_schema": _obj({"name": {"type": "string"},
+                           "force_accessibility": {"type": "boolean"},
+                           "reason": {"type": "string"}}, ["name"])},
+    {"name": "simultaneous_mode",
+     "description": ("Toggle simultaneous mode. ON = never steal the user's cursor/keyboard/view "
+                     "(background reads, focus-free actions only, shared-input actions refused). "
+                     "OFF = may bring apps forward and use the full input set."),
+     "input_schema": _obj({"on": {"type": "boolean"}})},
+    {"name": "quit_app", "description": "Quit an app via the OS (reliable regardless of focus).",
+     "input_schema": _obj({"name": {"type": "string"}}, ["name"])},
+    {"name": "focus_app",
+     "description": ("Bring an app to the front and target it. This switches the user's view — "
+                     "always pass `reason` (one short sentence for why)."),
+     "input_schema": _obj({"name": {"type": "string"}, "reason": {"type": "string"}}, ["name"])},
+    {"name": "web_open",
+     "description": ("Open a Chromium browser or Electron app for FOCUS-FREE control over CDP — "
+                     "the way to drive web/Electron apps in the background. `app` is the browser "
+                     "(default 'Google Chrome'); put a website in `url`. Uses the persistent Hunch "
+                     "profile; call web_login once if it isn't signed in."),
+     "input_schema": _obj({"app": {"type": "string"}, "url": {"type": "string"},
+                           "isolated": {"type": "boolean"}})},
+    {"name": "web_login",
+     "description": ("Open a background, banner-tagged window for the HUMAN to sign in once (Hunch "
+                     "never sees the password); the login then persists. Fires a desktop notification."),
+     "input_schema": _obj({"app": {"type": "string"}, "url": {"type": "string"}})},
+    {"name": "web_snapshot",
+     "description": "Read the CDP-controlled page as an accessibility tree. Call web_open first.",
+     "input_schema": _obj()},
+    {"name": "web_screenshot",
+     "description": ("PNG of the CDP page itself (focus-free) — for visual web content the tree "
+                     "can't convey. Use this, never the OS screenshot, for the background browser."),
+     "input_schema": _obj()},
+    {"name": "web_act",
+     "description": ("Run focus-free page actions, then get the updated tree. Verbs: click (by ref), "
+                     "type (REPLACES a field; picks <select> options by visible text), key, navigate "
+                     "(only to a URL you were given or read from the page — click links, don't guess)."),
+     "input_schema": _obj({"actions": {"type": "array", "items": _WEB_ACTION_ITEM}}, ["actions"])},
+    {"name": "web_restart",
+     "description": ("Recover a BROKEN CDP browser by quitting and reopening it fresh (login kept). "
+                     "Last resort — don't restart a merely-slow page; wait and re-snapshot first."),
+     "input_schema": _obj({"app": {"type": "string"}, "url": {"type": "string"}})},
+    {"name": "web_tabs",
+     "description": "List the open CDP tabs (index, title, URL, which is current).",
+     "input_schema": _obj()},
+    {"name": "web_switch_tab",
+     "description": "Switch the CDP session to a tab by index (see web_tabs), then web_snapshot.",
+     "input_schema": _obj({"index": {"type": "integer"}}, ["index"])},
+    {"name": "list_credentials",
+     "description": ("List the service NAMES the user saved credentials for (names + kind only, "
+                     "never values). Fill them with web_fill_login / web_fill_secret."),
+     "input_schema": _obj()},
+    {"name": "web_fill_login",
+     "description": ("Fill the current CDP page's login form from the user's saved credential for "
+                     "`service`, WITHOUT the values entering your context — you only learn which "
+                     "fields were filled. Then submit via web_act. web_open first."),
+     "input_schema": _obj({"service": {"type": "string"}}, ["service"])},
+    {"name": "web_fill_secret",
+     "description": ("Type the user's saved protected value (API key/token) for `service` into a "
+                     "field on the current CDP page, WITHOUT the value entering your context. "
+                     "web_snapshot first and pass the field's ref."),
+     "input_schema": _obj({"service": {"type": "string"}, "ref": {"type": "string"}}, ["service"])},
+    {"name": "notify_user",
+     "description": ("Alert the user when you need them SHORTLY — to finish a login, approve a 2FA "
+                     "prompt, solve a captcha, or make a decision only they can. Call this the moment "
+                     "you hit a step only the human can do."),
+     "input_schema": _obj({"message": {"type": "string"}}, ["message"])},
+    {"name": "request_focus",
+     "description": ("Ask the user's permission BEFORE a focus-stealing step you'll do via other "
+                     "tools. Pops a one-click Go ahead / Cancel dialog and returns their choice."),
+     "input_schema": _obj({"reason": {"type": "string"}}, ["reason"])},
+    {"name": "trash",
+     "description": ("Move file(s)/folder(s) to the Trash by path — focus-free and reversible. Use "
+                     "this to delete files instead of driving Finder."),
+     "input_schema": _obj({"paths": {"type": "array", "items": {"type": "string"}}}, ["paths"])},
+    {"name": "file_op",
+     "description": ("Focus-free filesystem op by path: op='move'|'copy' (src -> dst) or op='mkdir' "
+                     "(create a folder at src). To delete, use trash."),
+     "input_schema": _obj({"op": {"type": "string", "enum": ["move", "copy", "mkdir"]},
+                           "src": {"type": "string"}, "dst": {"type": "string"}}, ["op", "src"])},
+    {"name": "open_file",
+     "description": ("Open a file/folder/URL/app-deep-link with its default (or a named) app — "
+                     "focus-free launch (also 'mailto:', 'spotify:track:...')."),
+     "input_schema": _obj({"path": {"type": "string"}, "app": {"type": "string"}}, ["path"])},
+    {"name": "reveal_in_finder",
+     "description": "Reveal/select item(s) in a Finder window by path (this does front Finder).",
+     "input_schema": _obj({"paths": {"type": "array", "items": {"type": "string"}}}, ["paths"])},
+    {"name": "clipboard_get", "description": "Read the clipboard's text — focus-free (no ⌘C).",
+     "input_schema": _obj()},
+    {"name": "clipboard_set", "description": "Put text on the clipboard — focus-free (no ⌘V).",
+     "input_schema": _obj({"text": {"type": "string"}}, ["text"])},
+    {"name": "applescript",
+     "description": ("Run AppleScript to control scriptable native apps FOCUS-FREE via Apple Events "
+                     "— Mail, Messages, Notes, Reminders, Calendar, Music, Finder, Safari. Prefer "
+                     "this over UI-driving those apps. Risky scripts prompt the user."),
+     "input_schema": _obj({"script": {"type": "string"}}, ["script"])},
+]
+
+AGENT_ADDENDUM = """\
+
+── You are an autonomous agent driving THIS Mac ──
+You are driving the user's real Mac on their behalf through the tools above. The playbook
+above is your operating manual — follow its NATIVE-FIRST routing and layer order.
+
+TERMINATION: when the task is complete — or you are blocked on something only the human can
+do (a login, a 2FA prompt, a decision) AFTER calling notify_user — end your turn with a
+plain final message summarizing the outcome. There is no "done" tool; your final message is
+the deliverable. Do not end mid-task with only a statement of intent ("I'll now…") — do the
+action, then report.
+
+REFUSALS: a tool result starting with "REFUSED" or "User did NOT approve" is a hard human
+decision, not a transient error. Do NOT retry the identical call — adapt (a focus-free
+alternative) or call notify_user and stop.
+
+CAUTION: before an irreversible or outward action (sending a message/email, deleting beyond
+the Trash, a purchase), confirm intent with the user via notify_user unless they already
+asked for exactly that. Report outcomes faithfully — if something failed, say so."""
+
+
+# ── exception → tool_result content mapping ─────────────────────────────────────
+def _img(png_bytes):
+    return [{"type": "image", "source": {"type": "base64", "media_type": "image/png",
+                                         "data": base64.b64encode(png_bytes).decode()}}]
+
+
+# Dispatcher: tool name -> callable(mac, args) -> content (str or image-block list).
+_DISPATCH = {
+    "snapshot": lambda m, a: m.snapshot(a.get("app", ""), ref=a.get("ref") or None,
+                                        max_depth=a.get("max_depth"), max_nodes=a.get("max_nodes")),
+    "find": lambda m, a: m.find(role=a.get("role") or None, name_contains=a.get("name_contains") or None,
+                                app=a.get("app", ""), max_results=a.get("max_results", 20)),
+    "act": lambda m, a: m.act(a.get("actions", []), reason=a.get("reason", "")),
+    "screenshot": lambda m, a: _img(m.screenshot()),
+    "list_apps": lambda m, a: m.list_apps(),
+    "launch_app": lambda m, a: m.launch_app(a["name"], force_accessibility=a.get("force_accessibility", False),
+                                            reason=a.get("reason", "")),
+    "simultaneous_mode": lambda m, a: _set_simultaneous(m, a.get("on", True)),
+    "quit_app": lambda m, a: m.quit_app(a["name"]),
+    "focus_app": lambda m, a: m.focus_app(a["name"], reason=a.get("reason", "")),
+    "web_open": lambda m, a: m.web.open(url=a.get("url", ""), app=a.get("app", "Google Chrome"),
+                                        isolated=a.get("isolated", False)),
+    "web_login": lambda m, a: m.web.login(url=a.get("url", ""), app=a.get("app", "Google Chrome")),
+    "web_snapshot": lambda m, a: m.web.snapshot(),
+    "web_screenshot": lambda m, a: _img(m.web.screenshot()),
+    "web_act": lambda m, a: m.web.act(a.get("actions", [])),
+    "web_restart": lambda m, a: m.web.restart(url=a.get("url", ""), app=a.get("app", "Google Chrome")),
+    "web_tabs": lambda m, a: m.web.tabs(),
+    "web_switch_tab": lambda m, a: m.web.switch_tab(a["index"]),
+    "list_credentials": lambda m, a: m.list_credentials(),
+    "web_fill_login": lambda m, a: m.web.fill_login(a["service"]),
+    "web_fill_secret": lambda m, a: m.web.fill_secret(a["service"], ref=a.get("ref", "")),
+    "notify_user": lambda m, a: _notify(m, a["message"]),
+    "request_focus": lambda m, a: _request_focus(m, a["reason"]),
+    "trash": lambda m, a: m.files.trash(a.get("paths", [])),
+    "file_op": lambda m, a: _file_op(m, a),
+    "open_file": lambda m, a: m.files.open(a["path"], app=a.get("app") or None),
+    "reveal_in_finder": lambda m, a: m.files.reveal(a.get("paths", [])),
+    "clipboard_get": lambda m, a: m.clipboard.get(),
+    "clipboard_set": lambda m, a: m.clipboard.set(a["text"]),
+    "applescript": lambda m, a: m.applescript(a["script"]),
+}
+
+
+def _set_simultaneous(mac, on):
+    mac.simultaneous = bool(on)
+    return ("simultaneous mode ON — Hunch will not touch your foreground, cursor, or keyboard"
+            if on else "simultaneous mode OFF — Hunch may bring apps forward and use the cursor/keyboard")
+
+
+def _notify(mac, message):
+    mac.notify(message, "Hunch needs you")
+    return f"notified the user: {message}"
+
+
+def _request_focus(mac, reason):
+    ok = mac._gate.confirm_dialog(f"Hunch wants to {reason}. Allow it to take over your screen?")
+    return ("user clicked Go ahead — proceed, then restore their previous app afterwards"
+            if ok else "user did not approve — do NOT proceed with the focus-stealing action")
+
+
+def _file_op(mac, a):
+    op, src, dst = a.get("op"), a.get("src", ""), a.get("dst", "")
+    if op == "move":
+        return mac.files.move(src, dst)
+    if op == "copy":
+        return mac.files.copy(src, dst)
+    if op == "mkdir":
+        return mac.files.mkdir(src)
+    return f"unknown op {op!r} — use 'move', 'copy', or 'mkdir' (or the trash tool to delete)"
+
+
+def _run_tool(mac, tool_use):
+    """Dispatch one tool_use block -> a tool_result dict. Expected Hunch exceptions become
+    plain content strings so the model can adapt; only genuinely unexpected exceptions set
+    is_error (mirrors the MCP server's return-the-message behavior)."""
+    from .local_mac import StaleRef
+    name = tool_use.name
+    tid = tool_use.id
+    args = tool_use.input or {}
+    fn = _DISPATCH.get(name)
+    if fn is None:
+        return {"type": "tool_result", "tool_use_id": tid, "content": f"unknown tool {name}",
+                "is_error": True}
+    try:
+        content = fn(mac, args)
+    except ApprovalDenied as e:
+        content = (f"REFUSED: {e} — the user declined; do not retry the identical action, "
+                   "adapt or call notify_user")
+    except StaleRef:
+        content = "ref is stale — re-snapshot the app and use fresh refs"
+    except (WebNotOpen, AccessibilityNotGranted, HunchError) as e:
+        content = str(e)
+    except Exception as e:  # noqa: BLE001 — genuinely unexpected: flag it
+        return {"type": "tool_result", "tool_use_id": tid, "content": f"error: {e}", "is_error": True}
+    return {"type": "tool_result", "tool_use_id": tid, "content": content}
+
+
+def _preview(content):
+    if isinstance(content, list):
+        return "[image]"
+    s = str(content)
+    return s if len(s) <= 200 else s[:200] + "…"
+
+
+# ── caching: rolling breakpoint on the last user-message block ──────────────────
+def _mark_cache(messages):
+    """Put a cache_control breakpoint on the last block of the most recent user message and
+    clear it from earlier ones. Only touches dict blocks (our tool_result / text dicts) — it
+    NEVER mutates the pydantic assistant/thinking blocks we replay verbatim."""
+    last = None
+    for msg in messages:
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, dict):
+                block.pop("cache_control", None)
+                if msg.get("role") == "user":
+                    last = block
+    if last is not None:
+        last["cache_control"] = {"type": "ephemeral"}
+
+
+@dataclass
+class AgentResult:
+    text: str
+    turns: int
+    stop_reason: str
+    usage: dict = field(default_factory=dict)
+    aborted: bool = False
+
+
+class Agent:
+    """The agent loop. Created lazily as `Hunch.agent`. Holds conversation state across
+    act() calls (continuation); call reset() to start a fresh task."""
+
+    def __init__(self, hunch, client=None):
+        self._h = hunch
+        self._client = client          # test seam; None -> lazily anthropic.Anthropic()
+        self.messages = []
+
+    def reset(self):
+        """Clear the conversation for an unrelated task (same Hunch instance and gates)."""
+        self.messages = []
+
+    def _ensure_client(self):
+        if self._client is None:
+            try:
+                import anthropic
+            except ImportError as e:
+                raise HunchError("the agent loop needs the optional 'anthropic' package — "
+                                 "install it with: pip install 'hunch-sdk[agent]'") from e
+            self._client = anthropic.Anthropic()   # env key / auth token / ant profile
+        return self._client
+
+    def _system(self, system_suffix):
+        blocks = [{"type": "text", "text": HUNCH_PLAYBOOK + "\n" + AGENT_ADDENDUM,
+                   "cache_control": {"type": "ephemeral"}}]
+        if system_suffix:
+            blocks.append({"type": "text", "text": system_suffix})
+        return blocks
+
+    def _request(self, client, model, max_tokens, system, effort):
+        """Provider seam: build kwargs + run one streamed turn, return the final Message."""
+        kwargs = dict(model=model, max_tokens=max_tokens, system=system,
+                      tools=AGENT_TOOLS, messages=self.messages,
+                      thinking={"type": "adaptive"})
+        if effort:
+            kwargs["output_config"] = {"effort": effort}
+        with client.messages.stream(**kwargs) as stream:
+            return stream.get_final_message()
+
+    @staticmethod
+    def _accumulate(usage, resp_usage):
+        for k in ("input_tokens", "output_tokens",
+                  "cache_creation_input_tokens", "cache_read_input_tokens"):
+            usage[k] = usage.get(k, 0) + (getattr(resp_usage, k, 0) or 0)
+
+    def run(self, task, model=DEFAULT_MODEL, max_turns=40, on_event=None,
+            system_suffix="", effort=None, max_tokens=16000):
+        """Run the agent loop until Claude finishes the task (end_turn), is blocked, or hits
+        max_turns. Returns an AgentResult. on_event(kind, data) receives 'text' | 'tool' |
+        'tool_result' | 'done' | 'error' as work streams."""
+        client = self._ensure_client()   # friendly HunchError if 'anthropic' isn't installed
+        try:
+            import anthropic
+            _AuthError = anthropic.AuthenticationError
+        except Exception:                # injected fake client without anthropic present
+            _AuthError = ()
+        emit = on_event or (lambda kind, data: None)
+        self.messages.append({"role": "user", "content": task})
+        usage = {}
+        stop_reason, final_text, aborted, turn = "max_turns", "", True, 0
+
+        for turn in range(1, max_turns + 1):
+            _mark_cache(self.messages)
+            try:
+                resp = self._request(client, model, max_tokens, self._system(system_suffix), effort)
+            except _AuthError as e:
+                raise HunchError("no valid Anthropic credentials — set ANTHROPIC_API_KEY or "
+                                 "run `ant auth login` (then retry)") from e
+            self._accumulate(usage, resp.usage)
+            for b in resp.content:
+                if getattr(b, "type", None) == "text" and b.text.strip():
+                    emit("text", b.text.strip())
+            self.messages.append({"role": "assistant", "content": resp.content})  # verbatim replay
+
+            if resp.stop_reason == "tool_use":
+                results = []
+                for tu in [b for b in resp.content if getattr(b, "type", None) == "tool_use"]:
+                    emit("tool", {"name": tu.name, "input": tu.input})
+                    r = _run_tool(self._h, tu)
+                    emit("tool_result", _preview(r["content"]))
+                    results.append(r)
+                self.messages.append({"role": "user", "content": results})   # ALL results, ONE message
+                continue
+            if resp.stop_reason == "pause_turn":   # defensive; no server tools in v1
+                continue
+
+            stop_reason = resp.stop_reason
+            if stop_reason == "end_turn":
+                final_text = "\n".join(b.text for b in resp.content
+                                       if getattr(b, "type", None) == "text").strip()
+                aborted = False
+                emit("done", final_text)
+            else:                                   # max_tokens | refusal | other
+                emit("error", f"stopped: {stop_reason}")
+            break
+        else:
+            emit("error", f"aborted after max_turns={max_turns}")
+
+        return AgentResult(text=final_text, turns=turn, stop_reason=stop_reason,
+                         usage=usage, aborted=aborted)