@cliptude/cli 0.1.21 → 0.1.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,207 @@
1
+ """MCP tools that make the user's own avatar and voices: create_avatar, design_voice_previews, save_designed_voice,
2
+ clone_voice. The avatar and voice picker widgets call them with `tools/call`; the model can call them too.
3
+
4
+ Files travel as base64 in the tool call (the widget reads the file the user picked, or a recording), never as a
5
+ path on the hosted server: a local path is accepted only by the stdio server, which runs on the user's computer.
6
+ The server-side rules are the website's (videos/creation_api.py): paid plans, the 55-credit avatar goes through a
7
+ 428 price review first, clones need the same consent as the Clone a voice page, every voice and avatar is private.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import base64
13
+ import binascii
14
+ import json
15
+ import mimetypes
16
+ from collections.abc import Callable
17
+ from pathlib import Path
18
+ from typing import Annotated, Any
19
+
20
+ import httpx
21
+ from mcp.types import CallToolResult, TextContent, ToolAnnotations
22
+ from pydantic import Field
23
+
24
+ from cliptude_mcp.client import CliptudeApiError
25
+
26
+ MAX_UPLOAD_BYTES = 10 * 1024 * 1024
27
+ CLONE_CONSENT_TEXT = (
28
+ "I confirm this is my own voice, or I have the voice owner's explicit consent and the rights to clone it. "
29
+ "I will not use cloned voices to impersonate or deceive others, as required by the Terms of Service."
30
+ )
31
+
32
+
33
+ def _file_arg(
34
+ *, data_base64: str | None, file_name: str | None, path: str | None, local: bool, what: str
35
+ ) -> tuple[str, bytes, str] | None:
36
+ """(name, bytes, mime) from base64 or (stdio only) a local path; None when neither was given."""
37
+ if path:
38
+ if not local:
39
+ raise CliptudeApiError(f"This server cannot read files on your computer: send the {what} as base64.")
40
+ p = Path(path).expanduser()
41
+ if not p.is_file():
42
+ raise CliptudeApiError(f"{what.capitalize()} not found: {p}")
43
+ raw = p.read_bytes()
44
+ name = p.name
45
+ elif data_base64:
46
+ text = data_base64.split(",", 1)[1] if data_base64.startswith("data:") else data_base64
47
+ try:
48
+ raw = base64.b64decode(text, validate=False)
49
+ except (binascii.Error, ValueError) as exc:
50
+ raise CliptudeApiError(f"The {what} is not valid base64.") from exc
51
+ name = (file_name or "").strip() or what.replace(" ", "_")
52
+ else:
53
+ return None
54
+ if len(raw) > MAX_UPLOAD_BYTES:
55
+ raise CliptudeApiError(f"The {what} is over {MAX_UPLOAD_BYTES // (1024 * 1024)} MB.")
56
+ if not raw:
57
+ raise CliptudeApiError(f"The {what} is empty.")
58
+ mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
59
+ return name, raw, mime
60
+
61
+
62
+ CLONE_PROVIDERS = frozenset({"elevenlabs", "minimax", "cartesia", "inworld", "voicetory"})
63
+
64
+
65
+ def _path_refused(local: bool, name: str, value: Any) -> dict[str, Any] | None:
66
+ """A hosted server never reads its own disk for a caller (same code as the server's other tools)."""
67
+ if local or value is None or not str(value).strip():
68
+ return None
69
+ from cliptude_mcp.server import LOCAL_FILES_REFUSED
70
+
71
+ return {"error": LOCAL_FILES_REFUSED.format(param=name), "code": "local_path_not_allowed"}
72
+
73
+
74
+ def post_form(client: Any, path: str, data: dict[str, Any], files: dict[str, tuple[str, bytes, str]] | None = None,
75
+ *, _retried: bool = False) -> Any:
76
+ """Multipart/form POST to the Cliptude API with the client's auth (client.request only sends JSON)."""
77
+ try:
78
+ resp = httpx.post(
79
+ f"{client.base_url}{path}",
80
+ headers=client._headers(json_content=False),
81
+ data={k: v for k, v in data.items() if v not in (None, "")},
82
+ files=files or None,
83
+ timeout=max(float(client.timeout or 0), 180.0),
84
+ )
85
+ except httpx.HTTPError as exc:
86
+ raise CliptudeApiError(str(exc)) from exc
87
+ if resp.status_code == 401 and not _retried and client._maybe_refresh():
88
+ return post_form(client, path, data, files, _retried=True)
89
+ try:
90
+ payload = resp.json()
91
+ except ValueError:
92
+ payload = {"error": resp.text}
93
+ if resp.status_code >= 400:
94
+ client._raise_http(resp, payload=payload)
95
+ return payload
96
+
97
+
98
+ def register_creation_tools(
99
+ mcp: Any, client: Callable[[], Any], err: Callable[[Exception], dict[str, Any]], *, local: bool
100
+ ) -> None:
101
+ @mcp.tool(
102
+ title="Create avatar",
103
+ annotations=ToolAnnotations(title="Create avatar", read_only_hint=False, destructive_hint=False,
104
+ open_world_hint=True),
105
+ )
106
+ def create_avatar(
107
+ display_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the new avatar")],
108
+ gender: Annotated[str | None, Field(description='"male" or "female" (needed for a description; a photo is detected)')] = None,
109
+ appearance: Annotated[str | None, Field(description="Describe the presenter, when there is no photo")] = None,
110
+ photo_base64: Annotated[str | None, Field(description="A landscape 16:9 JPG/PNG/WEBP photo, base64 (max 10 MB)")] = None,
111
+ photo_file_name: Annotated[str | None, Field(description="The photo's file name, e.g. me.jpg")] = None,
112
+ photo_path: Annotated[str | None, Field(description="Local photo path (only when Cliptude runs on this computer)")] = None,
113
+ review_token: Annotated[str | None, Field(description="From the 428 review, after the user approved the price")] = None,
114
+ ) -> dict[str, Any]:
115
+ """Create the user's own private photo avatar for Avatar Video, from a 16:9 photo of them (or someone who agreed) or a description. It costs 55 credits: the first call returns a review (status 428, detail.review with the price) and creates nothing; show it to the user and call again with the same arguments and review_token once they approve. HeyGen finishes it in a few minutes; list_avatars(section="mine") shows it then."""
116
+ refused = _path_refused(local, "photo_path", photo_path)
117
+ if refused:
118
+ return refused
119
+ try:
120
+ photo = _file_arg(data_base64=photo_base64, file_name=photo_file_name, path=photo_path, local=local,
121
+ what="photo")
122
+ data = {"display_name": display_name, "gender": gender, "appearance": appearance,
123
+ "review_token": review_token}
124
+ return post_form(client(), "/api/v1/avatars/new", data,
125
+ {"photo_file": photo} if photo else None)
126
+ except Exception as exc:
127
+ return err(exc)
128
+
129
+ @mcp.tool(
130
+ title="Design voice previews",
131
+ annotations=ToolAnnotations(title="Design voice previews", read_only_hint=False, destructive_hint=False,
132
+ open_world_hint=True),
133
+ )
134
+ def design_voice_previews(
135
+ provider: Annotated[str, Field(description="elevenlabs, minimax or inworld")],
136
+ description: Annotated[str, Field(min_length=10, max_length=1000, description="The voice to design: age, gender, accent, tone, pace")],
137
+ language: Annotated[str | None, Field(description="Narration language, e.g. English")] = None,
138
+ ) -> CallToolResult:
139
+ """Design a new narration voice from a description: returns a few previews (preview_id) to listen to. Keep one with save_designed_voice. Paid plans; a user keeps one designed voice per provider. The audio goes to the voice picker widget only; the text result lists the preview ids."""
140
+ try:
141
+ payload = post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}/previews",
142
+ {"description": description, "language": language})
143
+ except Exception as exc:
144
+ failure = err(exc)
145
+ return CallToolResult(content=[TextContent(type="text", text=json.dumps(failure, default=str))],
146
+ structured_content=failure)
147
+ previews = payload.get("previews") or [] if isinstance(payload, dict) else []
148
+ summary = {
149
+ "provider": provider,
150
+ "previews": [{"preview_id": p.get("preview_id")} for p in previews],
151
+ "rounds_left_today": payload.get("rounds_left_today") if isinstance(payload, dict) else None,
152
+ "next": "Let the user listen in the voice picker (or describe the previews), then save_designed_voice "
153
+ "with the preview_id they pick and a voice_name.",
154
+ }
155
+ return CallToolResult(
156
+ content=[TextContent(type="text", text=json.dumps(summary))],
157
+ structured_content={"provider": provider, **(payload if isinstance(payload, dict) else {})},
158
+ )
159
+
160
+ @mcp.tool(
161
+ title="Save designed voice",
162
+ annotations=ToolAnnotations(title="Save designed voice", read_only_hint=False, destructive_hint=False,
163
+ open_world_hint=True),
164
+ )
165
+ def save_designed_voice(
166
+ provider: Annotated[str, Field(description="Same provider as the previews")],
167
+ preview_id: Annotated[str, Field(min_length=1, description="The preview the user picked")],
168
+ voice_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the voice")],
169
+ ) -> dict[str, Any]:
170
+ """Keep one designed preview as the user's own private voice. It then appears in list_voices under my_voices and can be used as voice_id (with voice_provider) in create_template."""
171
+ try:
172
+ return post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}",
173
+ {"preview_id": preview_id, "voice_name": voice_name})
174
+ except Exception as exc:
175
+ return err(exc)
176
+
177
+ @mcp.tool(
178
+ title="Clone voice",
179
+ annotations=ToolAnnotations(title="Clone voice", read_only_hint=False, destructive_hint=False,
180
+ open_world_hint=True),
181
+ )
182
+ def clone_voice(
183
+ provider: Annotated[str, Field(description="elevenlabs, minimax, cartesia, inworld or voicetory")],
184
+ voice_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the clone")],
185
+ consent: Annotated[bool, Field(description="True only after the user confirmed: " + CLONE_CONSENT_TEXT)],
186
+ audio_base64: Annotated[str | None, Field(description="30 s to 3 min of clear speech (MP3, M4A or WAV), base64, max 10 MB")] = None,
187
+ audio_file_name: Annotated[str | None, Field(description="The recording's file name, e.g. me.mp3")] = None,
188
+ audio_path: Annotated[str | None, Field(description="Local recording path (only when Cliptude runs on this computer)")] = None,
189
+ ) -> dict[str, Any]:
190
+ """Clone the user's own voice from a recording, private to their account; it then appears in list_voices under my_voices. Paid plans. Ask the user to confirm the consent statement first and pass consent=true only after they do."""
191
+ refused = _path_refused(local, "audio_path", audio_path)
192
+ if refused:
193
+ return refused
194
+ provider = (provider or "").strip().lower()
195
+ if provider not in CLONE_PROVIDERS:
196
+ return {"error": f"provider must be one of: {', '.join(sorted(CLONE_PROVIDERS))}."}
197
+ if not consent:
198
+ return {"error": "The user must confirm: " + CLONE_CONSENT_TEXT}
199
+ try:
200
+ audio = _file_arg(data_base64=audio_base64, file_name=audio_file_name, path=audio_path, local=local,
201
+ what="recording")
202
+ if audio is None:
203
+ return {"error": "Send the recording as audio_base64."}
204
+ return post_form(client(), f"/api/v1/voice-clones/{provider}",
205
+ {"voice_name": voice_name, "voice_consent": "true"}, {"clone_audio": audio})
206
+ except Exception as exc:
207
+ return err(exc)
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  import json
6
6
  import os
7
+ import secrets
7
8
  from pathlib import Path
8
9
  from typing import Any
9
10
 
@@ -27,13 +28,38 @@ def load_credentials() -> dict[str, Any] | None:
27
28
 
28
29
 
29
30
  def save_credentials(data: dict[str, Any]) -> Path:
31
+ """Write the login atomically, owner-only (0600) from the moment the file exists (folder 0700)."""
30
32
  path = credentials_path()
31
- path.parent.mkdir(parents=True, exist_ok=True)
32
- path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
33
+ folder = path.parent
34
+ if not folder.exists():
35
+ folder.mkdir(mode=0o700, parents=True, exist_ok=True)
36
+ try:
37
+ os.chmod(folder, 0o700) # mkdir's mode is masked by the umask
38
+ except OSError:
39
+ pass
40
+ payload = (json.dumps(data, indent=2) + "\n").encode("utf-8")
41
+ tmp = folder / f".{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp"
42
+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
43
+ fd = os.open(tmp, flags, 0o600)
33
44
  try:
34
- os.chmod(path, 0o600)
35
- except OSError:
36
- pass
45
+ try:
46
+ os.fchmod(fd, 0o600) # in case the umask kept bits back; never wider than 0600
47
+ except (AttributeError, OSError):
48
+ pass
49
+ with os.fdopen(fd, "wb") as fh:
50
+ fd = -1
51
+ fh.write(payload)
52
+ fh.flush()
53
+ os.fsync(fh.fileno())
54
+ os.replace(tmp, path)
55
+ except BaseException:
56
+ if fd >= 0:
57
+ os.close(fd)
58
+ try:
59
+ tmp.unlink()
60
+ except OSError:
61
+ pass
62
+ raise
37
63
  return path
38
64
 
39
65
 
@@ -0,0 +1,226 @@
1
+ """Browser fallback for the widgets, for MCP clients that cannot show MCP Apps.
2
+
3
+ Claude Code and Codex in a terminal, Cursor and other clients without MCP Apps cannot draw the avatar, voice,
4
+ music or review widgets. For them the widget-bound tools add `browser_picker_url` and `pick_id` to their
5
+ result: a cliptude.com/pick/... link (signed, 15 minutes, only for the signed-in owner) that opens the same
6
+ widget in the user's browser. Their pick, or their click on Confirm in a review, is stored on Cliptude;
7
+ `get_pick(pick_id)` reads it. The server builds what the page shows (POST /api/v1/picks with where to read it
8
+ from, never the content), and a review is only approved there: the agent then resends the call with the
9
+ review_token from get_pick. Clients that negotiated MCP Apps get exactly the old results.
10
+
11
+ How support is detected: the client's `initialize` capabilities (or the per-request capabilities on
12
+ 2026-07-28) carry `extensions["io.modelcontextprotocol/ui"]` with the `text/html;profile=mcp-app` MIME type
13
+ (`mcp.server.apps.client_supports_apps`). The SDK parses `initialize` with the latest schema, so a client on
14
+ protocol 2025-11-25 that sends `capabilities.extensions` is seen too, although the server cannot advertise the
15
+ extension back at that version. Hosts that put it under `experimental`, and the hosts known to render widgets
16
+ (claude.ai / Claude Desktop, ChatGPT) by client name, count as supporting it as well.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import functools
22
+ import os
23
+ from collections.abc import Callable
24
+ from typing import Annotated, Any
25
+
26
+ from pydantic import Field
27
+
28
+ EXTENSION_ID = "io.modelcontextprotocol/ui"
29
+ APP_MIME_TYPE = "text/html;profile=mcp-app"
30
+ # Client names (initialize clientInfo.name) of hosts that render MCP Apps widgets even if they do not say so.
31
+ WIDGET_HOST_CLIENTS = frozenset({"claude-ai", "openai-mcp", "chatgpt"})
32
+ CTX_KWARG = "_cliptude_ctx"
33
+
34
+ PICKER_NOTE = (
35
+ "This client shows no widgets, so the choice opens in the user's browser: give the user browser_picker_url "
36
+ "(in a terminal agent, offer to open it), wait until they say they are done, then call get_pick with "
37
+ "pick_id. Only status \"done\" carries their pick; a review counts as approved only when get_pick shows "
38
+ "confirmed: true (or the user says OK in this chat). The link works for 15 minutes, once, for the signed-in "
39
+ "owner only."
40
+ )
41
+
42
+ # Tools whose results get a browser picker, and the pick kind.
43
+ LIST_KINDS: dict[str, str] = {
44
+ "list_avatars": "avatars",
45
+ "list_voices": "voices",
46
+ "list_vector_characters": "characters",
47
+ "show_choices": "choices",
48
+ "list_templates": "templates",
49
+ "get_template": "template",
50
+ "create_template": "template",
51
+ "get_job": "job",
52
+ "get_product_video_status": "job",
53
+ "get_render": "video",
54
+ "show_video": "video",
55
+ "show_publish_kit": "publish_kit",
56
+ }
57
+
58
+
59
+ def enabled() -> bool:
60
+ """CLIPTUDE_BROWSER_PICKER=0 turns the fallback off (an operator switch, and the tests' default)."""
61
+ return (os.environ.get("CLIPTUDE_BROWSER_PICKER") or "1").strip().lower() not in ("0", "false", "no", "off")
62
+
63
+
64
+ def client_renders_apps(ctx: Any) -> bool:
65
+ """Whether the connected client shows MCP Apps widgets. Unknown (no context) counts as yes: no fallback."""
66
+ if ctx is None:
67
+ return True
68
+ try:
69
+ from mcp.server.apps import client_supports_apps
70
+ except ImportError: # pragma: no cover - an SDK without Apps serves no widgets at all
71
+ client_supports_apps = None
72
+ try:
73
+ if client_supports_apps is not None and client_supports_apps(ctx):
74
+ return True
75
+ capabilities = ctx.client_capabilities
76
+ except Exception:
77
+ return True
78
+ experimental = getattr(capabilities, "experimental", None) or {}
79
+ if isinstance(experimental, dict) and EXTENSION_ID in experimental:
80
+ return True
81
+ try:
82
+ params = ctx.request_context.session.client_params
83
+ name = str(getattr(getattr(params, "client_info", None), "name", "") or "").strip().lower()
84
+ except Exception:
85
+ name = ""
86
+ return name in WIDGET_HOST_CLIENTS
87
+
88
+
89
+ def _review_arguments(args: dict[str, Any]) -> dict[str, Any]:
90
+ """The reviewed call's arguments, for the pick to hand back; file contents stay with the agent."""
91
+ out = {}
92
+ for key, value in args.items():
93
+ if key in ("review_token", "acknowledge") or value is None:
94
+ continue
95
+ if key.endswith("_base64"):
96
+ out[key] = "<the same file as before>"
97
+ continue
98
+ out[key] = value
99
+ return out
100
+
101
+
102
+ def _is_script(data: dict[str, Any]) -> bool:
103
+ """views.js isScript: a written script waiting for the user's approval."""
104
+ if not isinstance(data.get("script"), str) or not data["script"].strip():
105
+ return False
106
+ if data.get("stage"):
107
+ return data["stage"] == "script_ready"
108
+ return data.get("output_kind") == "script" and data.get("status") == "completed"
109
+
110
+
111
+ def _is_ready(data: dict[str, Any]) -> bool:
112
+ stage = data.get("stage") or ""
113
+ if stage:
114
+ return stage in ("ready_for_review", "rendered")
115
+ kind = data.get("output_kind") or "video"
116
+ return data.get("status") in ("ready_for_edit", "completed") and kind in ("video", "plan")
117
+
118
+
119
+ def pick_source(name: str, args: dict[str, Any], result: Any) -> tuple[str, dict[str, Any]] | None:
120
+ """(kind, payload_source) of the browser picker for one tool result, or None when there is nothing to pick."""
121
+ from cliptude_mcp.apps import REVIEW_TOOLS
122
+
123
+ if not isinstance(result, dict):
124
+ return None
125
+ if name in REVIEW_TOOLS:
126
+ detail = result.get("detail") if isinstance(result.get("detail"), dict) else {}
127
+ if result.get("status") == 428 and detail.get("review") and detail.get("review_token"):
128
+ return "review", {"tool": name, "arguments": _review_arguments(args),
129
+ "review_token": detail["review_token"]}
130
+ return None
131
+ if result.get("error"):
132
+ return None
133
+ kind = LIST_KINDS.get(name)
134
+ if kind is None:
135
+ return None
136
+ if name == "list_avatars":
137
+ return kind, {k: args.get(k) for k in ("section", "search", "gender", "limit", "offset") if args.get(k) is not None}
138
+ if name == "list_voices":
139
+ return kind, {k: args.get(k) for k in ("provider", "language") if args.get(k)}
140
+ if name == "show_choices":
141
+ return kind, {"format": args.get("format"), "field": args.get("field")}
142
+ if name == "get_template":
143
+ return kind, {"template_id": args.get("template_id")}
144
+ if name == "create_template":
145
+ template_id = result.get("id") or (result.get("template") or {}).get("id")
146
+ return (kind, {"template_id": template_id}) if template_id else None
147
+ if name in ("get_job", "get_product_video_status"):
148
+ source = {"job_id": args.get("job_id"), "product": name == "get_product_video_status"}
149
+ if _is_script(result):
150
+ return "script", source
151
+ return (kind, source) if _is_ready(result) else None # progress alone: nothing to pick
152
+ if name == "get_render":
153
+ render = result.get("render") if isinstance(result.get("render"), dict) else {}
154
+ return (kind, {"render_id": args.get("render_id")}) if render.get("output_url") else None
155
+ if name == "show_video":
156
+ return (kind, {"job_id": args.get("job_id")}) if result.get("url") else None
157
+ if name == "show_publish_kit":
158
+ return kind, {"job_id": args.get("job_id")}
159
+ return kind, {}
160
+
161
+
162
+ def _with_picker(result: dict[str, Any], pick: Any) -> dict[str, Any]:
163
+ if not isinstance(pick, dict) or not pick.get("url") or not pick.get("pick_id"):
164
+ return result
165
+ return {**result, "browser_picker_url": pick["url"], "pick_id": pick["pick_id"],
166
+ "browser_picker": PICKER_NOTE}
167
+
168
+
169
+ def _wrap(tool: Any, name: str, client: Callable[[], Any]) -> None:
170
+ original = tool.fn
171
+ if getattr(original, "_cliptude_picker", False) or getattr(tool, "is_async", False):
172
+ return
173
+ if tool.context_kwarg not in (None, CTX_KWARG):
174
+ return # the tool takes the context itself; leave it alone
175
+
176
+ @functools.wraps(original)
177
+ def with_picker(*args: Any, **kwargs: Any) -> Any:
178
+ ctx = kwargs.pop(CTX_KWARG, None)
179
+ result = original(*args, **kwargs)
180
+ if not enabled() or client_renders_apps(ctx):
181
+ return result
182
+ source = pick_source(name, kwargs, result)
183
+ if source is None:
184
+ return result
185
+ try:
186
+ pick = client().create_pick(source[0], source[1])
187
+ except Exception:
188
+ return result # the tool's own answer matters more than the link
189
+ return _with_picker(result, pick)
190
+
191
+ with_picker._cliptude_picker = True # type: ignore[attr-defined]
192
+ tool.fn = with_picker
193
+ tool.context_kwarg = CTX_KWARG
194
+
195
+
196
+ def add_browser_fallback(mcp: Any, client: Callable[[], Any]) -> list[str]:
197
+ """Give the widget-bound tools a browser picker for clients without MCP Apps; returns the names wrapped."""
198
+ from cliptude_mcp.apps import REVIEW_TOOLS
199
+
200
+ manager = getattr(mcp, "_tool_manager", None)
201
+ wrapped = []
202
+ for name in (*LIST_KINDS, *REVIEW_TOOLS):
203
+ tool = manager.get_tool(name) if manager is not None else None
204
+ if tool is None:
205
+ continue
206
+ _wrap(tool, name, client)
207
+ if getattr(tool.fn, "_cliptude_picker", False):
208
+ wrapped.append(name)
209
+ return wrapped
210
+
211
+
212
+ def register_pick_tools(mcp: Any, client: Callable[[], Any], err: Callable[[Exception], dict[str, Any]]) -> None:
213
+ from mcp.types import ToolAnnotations
214
+
215
+ @mcp.tool(
216
+ title="Get pick",
217
+ annotations=ToolAnnotations(title="Get pick", read_only_hint=True, open_world_hint=False),
218
+ )
219
+ def get_pick(
220
+ pick_id: Annotated[str, Field(min_length=8, description="pick_id from a result's browser picker")],
221
+ ) -> dict[str, Any]:
222
+ """What the user picked or confirmed on a browser picker page (browser_picker_url, for clients that show no widgets). Returns {status: open|done|expired, result}. Only status done carries their pick: result.message and result.choice (the exact ids), or for a review result.confirmed with tool, arguments, review_token and acknowledge to resend that call once. Call it after the user says they are done; while open, ask them to finish on the page."""
223
+ try:
224
+ return client().get_pick(pick_id)
225
+ except Exception as exc:
226
+ return err(exc)