@yahyahammad/venastine 0.3.8 → 0.3.9

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.
Files changed (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
package/core/connect.py CHANGED
@@ -1,686 +1,686 @@
1
- """`/connect`'s catalogue, its sign-in flows, and the one way a key is stored
2
- (ROADMAP_v3 §79, HD5, HD13).
3
-
4
- Connecting a model used to mean copying `providers.json.example` and editing
5
- JSON by hand -- the one setup step README said nothing could do for you. This
6
- module is everything about it that is not drawing: which providers there are,
7
- the OAuth flows whose providers explicitly invite a third-party app to use
8
- them, and where a key ends up. The TUI owns the asking.
9
-
10
- ONLY FOUR PROVIDERS SIGN IN, AND THAT IS A RULING RATHER THAN A GAP. The
11
- owner asked for OAuth only where the provider's official guidance gives a
12
- third-party app explicit permission:
13
-
14
- * Hugging Face, https://huggingface.co/docs/hub/oauth -- a "Sign in with HF"
15
- flow "in any website or App", the `inference-api` scope ("Make inference
16
- requests to Inference Providers on behalf of the user"), public apps with
17
- no secret, and a device code flow for apps with no browser of their own.
18
- * OpenRouter, https://openrouter.ai/docs/guides/overview/auth/oauth -- "Use
19
- OAuth to let your users bring their own OpenRouter API key to your app",
20
- PKCE, and a mode with no callback URL in which the code is shown to the
21
- user to copy.
22
- * ModelScope, whose app registration (modelscope.ai, Access Control, OAuth
23
- Connected App) says "Users can authorize your application through
24
- ModelScope OAuth to obtain ModelScope-related permissions associated with
25
- the user" and offers the scope `api-inference` ("Invoke API Inference").
26
- modelscope.cn's form says the same in its original Chinese and offers the
27
- same scope (read 2026-10-26); it is a separate site with separate
28
- accounts, so it is a sign-in of its own (batch 176).
29
- * OpenAI's Sign in with ChatGPT, https://developers.openai.com/siwc -- a
30
- Plus or Pro subscriber spends their ChatGPT plan inside open-source and
31
- locally hosted apps, with no client secret (ROADMAP_v3 §83). A remotely
32
- hosted app needs OpenAI's interest form first, so this one is LOCAL
33
- ONLY (CG1), and its credential lives in `core/chatgpt_auth.py`: an
34
- access token that expires hourly and a refresh token, not a key.
35
-
36
- Hugging Face's and OpenRouter's flows need no server of ours to receive a
37
- redirect, which is why both work the same in a local terminal and in a
38
- browser tab. ModelScope's does not work that way: its token endpoint takes
39
- only a confidential client (`client_secret_basic` / `client_secret_post` in
40
- its discovery document, read 2026-10-22, and the same on modelscope.cn), so
41
- only a hosted bridge, which can keep the secret, completes it --
42
- `deploy/hosted/sign_in.py` -- and a local install connects either ModelScope
43
- site with a pasted key. ChatGPT's redirect comes back to a listener on
44
- 127.0.0.1, which only the person's own machine can reach. Everything else
45
- is a pasted key everywhere.
46
-
47
- NO HTTP LIBRARY IS IMPORTED AT MODULE SCOPE. Every network call goes through a
48
- `post` callable the caller may replace, and the default imports `httpx` when
49
- it runs: the suite's root `conftest.py` stubs `httpx` for the whole process,
50
- so the flows are tested against fake transports rather than a fake library.
51
- """
52
-
53
- from __future__ import annotations
54
-
55
- import base64
56
- import hashlib
57
- import re
58
- import secrets
59
- import time
60
- from collections.abc import Callable
61
- from dataclasses import dataclass
62
- from typing import Optional
63
- from urllib.parse import urlencode, urlsplit
64
-
65
- import credentials
66
-
67
- HF_DEVICE_URL = "https://huggingface.co/oauth/device"
68
- HF_TOKEN_URL = "https://huggingface.co/oauth/token"
69
- DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
70
-
71
- OPENROUTER_AUTH_URL = "https://openrouter.ai/auth"
72
- OPENROUTER_KEYS_URL = "https://openrouter.ai/api/v1/auth/keys"
73
- OPENROUTER_KEY_LABEL = "Venastine Research Harness"
74
-
75
- # How long one sign-in request may take before it is reported as unreachable.
76
- # A device-code poll is many short requests, so this bounds each one and the
77
- # code's own `expires_in` bounds the whole wait.
78
- _HTTP_TIMEOUT_S = 30
79
-
80
- Post = Callable[[str, dict], tuple[int, dict]]
81
-
82
-
83
- class ConnectError(Exception):
84
- """A sign-in or a key that did not work, worded for the person at the
85
- keyboard. Never carries a credential: every message here is built from
86
- the provider's error CODE, not from anything the provider echoed."""
87
-
88
-
89
- class ConnectCancelled(ConnectError):
90
- """The wait for a sign-in was stopped from our side (the app is closing)."""
91
-
92
-
93
- @dataclass(frozen=True)
94
- class Preset:
95
- """One provider `/connect` knows how to set up.
96
-
97
- `name` is what is typed; `provider` is the `providers.json` entry it
98
- writes, upper-case because `/model` upper-cases what it is given.
99
- `default_model` is switched to after connecting when it is set, and left
100
- alone when it is not -- a guessed model name is a 404 on the first turn.
101
- `sign_in` names the OAuth flow, or None where only a pasted key works;
102
- the two ModelScope sites' are completed by a hosted bridge, so each is
103
- offered only where the session's bridge says it can (security/hosted.py).
104
- """
105
-
106
- name: str
107
- provider: str
108
- label: str
109
- api_url: str
110
- is_v1_compatible: bool
111
- supports_stream_usage: bool
112
- default_model: Optional[str] = None
113
- sign_in: Optional[str] = None
114
- key_url: str = ""
115
-
116
-
117
- # URLs and both flags match `providers.json.example` wherever the two name the
118
- # same provider, so a key connected here behaves exactly like one typed there.
119
- PRESETS: dict[str, Preset] = {p.name: p for p in (
120
- Preset("huggingface", "HUGGINGFACE", "Hugging Face Inference Providers",
121
- "https://router.huggingface.co/v1", True, False,
122
- default_model="openai/gpt-oss-120b", sign_in="huggingface",
123
- key_url="https://huggingface.co/settings/tokens"),
124
- # The default is free and served by its own maker. Chosen by the owner
125
- # in batch 168 after a survey on 2026-10-22: every free model listed
126
- # had ONE endpoint, and the previous default's (Nvidia's, for
127
- # nemotron-3-super-120b-a12b:free) had answered 404 for a day at 0%
128
- # uptime, while this one answered a plain call and a tool call.
129
- Preset("openrouter", "OPENROUTER", "OpenRouter",
130
- "https://openrouter.ai/api/v1", True, False,
131
- default_model="minimax/minimax-m3.1-flash:free",
132
- sign_in="openrouter", key_url="https://openrouter.ai/keys"),
133
- # Reports streaming usage, measured 2026-10-22 on four models
134
- # (DeepSeek-V4-Pro-0813, Qwen3.5-27B, Qwen3.8-27B, Nex-N2.5-mini): with
135
- # `stream_options` every one sent real counts, the last in a chunk with
136
- # no choices; without it three of the four sent all-zero usage, so the
137
- # meter could never show. modelscope.cn's endpoint was not measured.
138
- Preset("modelscope", "MODELSCOPE", "ModelScope API-Inference (modelscope.ai)",
139
- "https://api-inference.modelscope.ai/v1", True, True,
140
- sign_in="modelscope",
141
- key_url="https://www.modelscope.ai/my/myaccesstoken"),
142
- Preset("modelscope-cn", "MODELSCOPE_CN",
143
- "ModelScope API-Inference (modelscope.cn)",
144
- "https://api-inference.modelscope.cn/v1", True, False,
145
- sign_in="modelscope-cn",
146
- key_url="https://modelscope.cn/my/myaccesstoken"),
147
- # ROADMAP_v3 §83. Not v1-compatible: the plan takes the Responses API
148
- # only (Chat Completions answered 401, slice 0), which `core/client.py`
149
- # routes CHATGPT to by name. Its `providers.json` entry holds no key and
150
- # is written when a sign-in completes (CG20, `store_chatgpt_entry`).
151
- Preset("chatgpt", "CHATGPT", "ChatGPT plan (Sign in with ChatGPT)",
152
- "https://api.openai.com/v1", False, True, sign_in="chatgpt"),
153
- Preset("openai", "OPENAI", "OpenAI", "https://api.openai.com/v1",
154
- True, True, key_url="https://platform.openai.com/api-keys"),
155
- Preset("anthropic", "ANTHROPIC", "Anthropic", "", False, True,
156
- key_url="https://console.anthropic.com/settings/keys"),
157
- Preset("google", "GOOGLE", "Google Gemini", "", False, False,
158
- key_url="https://aistudio.google.com/apikey"),
159
- Preset("deepseek", "DEEPSEEK", "DeepSeek", "https://api.deepseek.com/v1",
160
- True, False),
161
- Preset("groq", "GROQ", "Groq", "https://api.groq.com/openai/v1",
162
- True, False),
163
- Preset("mistral", "MISTRAL", "Mistral", "https://api.mistral.ai/v1",
164
- True, False),
165
- )}
166
-
167
- # The names `core/client.py` routes by NAME rather than by the
168
- # `is_v1_compatible` flag. A custom endpoint under one would be sent to a
169
- # native SDK it is not -- or, for CHATGPT, to the plan's sign-in (§83) --
170
- # so `custom` refuses them.
171
- _NATIVE_PROVIDERS = frozenset({"ANTHROPIC", "GOOGLE", "CHATGPT"})
172
- _PROVIDER_NAME = re.compile(r"^[A-Z0-9][A-Z0-9_.-]{0,39}$")
173
- _LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
174
-
175
-
176
- def custom_preset(name: str, url: str) -> Preset:
177
- """A preset for any OpenAI-compatible endpoint, named by the user.
178
-
179
- https only, except a loopback host, because the key travels in the
180
- Authorization header of every request and a local server is the one
181
- place plain http is ordinary.
182
- """
183
- provider = name.strip().upper()
184
- if not _PROVIDER_NAME.match(provider):
185
- raise ConnectError(
186
- f"{name!r} is not a usable provider name: letters, digits, "
187
- f"'_', '.' and '-', starting with a letter or digit.")
188
- if provider in _NATIVE_PROVIDERS:
189
- raise ConnectError(
190
- f"{provider} is reserved for its own SDK; use /connect "
191
- f"{provider.lower()} instead.")
192
- parts = urlsplit(url.strip())
193
- local = parts.hostname in _LOOPBACK_HOSTS
194
- if not parts.hostname or parts.scheme not in ("https", "http") or (
195
- parts.scheme == "http" and not local):
196
- raise ConnectError(
197
- f"{url!r} is not an https URL (plain http is accepted only for "
198
- f"localhost).")
199
- return Preset(provider.lower(), provider, f"{provider} (custom)",
200
- url.strip(), True, False)
201
-
202
-
203
- def clean_key(raw: str) -> str:
204
- """The pasted key as it will be stored, or ConnectError.
205
-
206
- Surrounding whitespace is what a paste brings with it and is dropped;
207
- whitespace INSIDE is not a key at all, and storing it would turn every
208
- request into a 401 a long way from the paste that caused it.
209
- """
210
- key = (raw or "").strip()
211
- if not key:
212
- raise ConnectError("Nothing was entered.")
213
- if any(ch.isspace() for ch in key):
214
- raise ConnectError("That has spaces or line breaks inside it, so it "
215
- "is not a key. Paste the key on its own.")
216
- return key
217
-
218
-
219
- def entry_for(preset: Preset, key: str) -> dict:
220
- return {
221
- "API_URL": preset.api_url,
222
- "API_KEY": key,
223
- "is_v1_compatible": preset.is_v1_compatible,
224
- "supports_stream_usage": preset.supports_stream_usage,
225
- }
226
-
227
-
228
- def store(preset: Preset, key: str, *, persist: bool) -> None:
229
- """Record `key` for `preset.provider`, then forget the cached client.
230
-
231
- `persist=False` is the shared hosted demo's rule (HD5): the key lives in
232
- this process's memory and nowhere else. `persist=True` writes
233
- `providers.json` through `save_credentials`, which keeps the file 0600
234
- and atomic and leaves any other field on an existing entry --
235
- `echoes_reasoning` included -- exactly as it was.
236
- """
237
- from core.client import forget_client
238
-
239
- if persist:
240
- credentials.save_credentials(
241
- preset.provider, key, preset.api_url,
242
- preset.is_v1_compatible, preset.supports_stream_usage)
243
- else:
244
- credentials.set_session_provider(preset.provider, entry_for(preset, key))
245
- forget_client(preset.provider)
246
-
247
-
248
- def store_chatgpt_entry() -> None:
249
- """CHATGPT's `providers.json` entry, written when a sign-in completes
250
- (ROADMAP_v3 §83, CG20).
251
-
252
- It holds NO KEY -- the plan's tokens live in `chatgpt_auth.json` (CG4)
253
- -- and exists so that `/model`, the launch restore and the per-provider
254
- flags read CHATGPT the way they read every other entry. Written through
255
- `save_credentials`, so a field already on the entry (`accepts_images`,
256
- once a measurement sets it, CG7) stays as it was. Local installs only:
257
- the sign-in that calls this refuses on a hosted deployment (CG1).
258
- """
259
- from core.client import forget_client
260
-
261
- preset = PRESETS["chatgpt"]
262
- credentials.save_credentials(
263
- preset.provider, "", preset.api_url, preset.is_v1_compatible,
264
- preset.supports_stream_usage)
265
- forget_client(preset.provider)
266
-
267
-
268
- def connected_providers() -> set:
269
- """Names that have a non-empty key right now, file and session alike,
270
- and CHATGPT while its sign-in holds a refresh token (§83): the plan has
271
- no key, so its token file is what says it is connected."""
272
- from core import chatgpt_auth
273
-
274
- names = {name for name, entry in credentials.load_provider_data().items()
275
- if entry.get("API_KEY")}
276
- if chatgpt_auth.status().signed_in:
277
- names.add("CHATGPT")
278
- return names
279
-
280
-
281
- # ---------------------------------------------------------------------------
282
- # ---- /model ----------------------------------------------------------------
283
- # ---------------------------------------------------------------------------
284
- # What `/model` may switch to, for either shell (ROADMAP_v3 §89). Moved out
285
- # of the TUI's handler when the CLI got one: which switches REFUSE is the
286
- # part two copies would come to disagree about, and a refusal one shell
287
- # makes and the other skips is a turn that fails a long way from its cause.
288
-
289
- MODEL_USAGE = "Usage: /model <name>, or /model <PROVIDER> <name>."
290
-
291
-
292
- def _chatgpt_signed_out(command: str) -> str:
293
- return ("The ChatGPT plan is not signed in, so it cannot answer. /connect "
294
- f"chatgpt signs in; then /{command} CHATGPT <name>.")
295
-
296
-
297
- CHATGPT_SIGNED_OUT = _chatgpt_signed_out("model")
298
-
299
-
300
- def configured_providers(providers: dict) -> str:
301
- """The providers a switch can reach, for a bare `/model`."""
302
- from core import chatgpt_auth
303
-
304
- named = sorted(p for p, e in providers.items() if e.get("API_KEY"))
305
- # §83: the plan has no key; its sign-in is what connects it.
306
- if chatgpt_auth.status().signed_in:
307
- named.append("CHATGPT (signed in)")
308
- return ", ".join(named) if named else "none (add a key to providers.json)"
309
-
310
-
311
- def model_switch(args: str, current_provider: str,
312
- command: str = "model") -> tuple:
313
- """`(provider, model, providers, error)` for `/model`'s argument.
314
-
315
- `/model <name>` keeps `current_provider`; `/model <PROVIDER> <name>`
316
- switches both. `error` is the sentence a refusal shows, and the other
317
- three are None with it. `providers` is the file as read after any
318
- entry this wrote, for the caller's missing-key warning.
319
-
320
- `command` is `submodel` for `/submodel` (ROADMAP_v3 §57), which takes
321
- the same pairs and refuses the same ones: a subagent's turn is a chat
322
- turn on another pair, so the plan's refusals hold for it exactly. Only
323
- the sentences that name a command change.
324
- """
325
- from core import chatgpt_auth
326
- from security import hosted
327
-
328
- usage = MODEL_USAGE if command == "model" else SUBMODEL_USAGE
329
- parts = args.split()
330
- if len(parts) == 1:
331
- provider, model = current_provider, parts[0]
332
- elif len(parts) == 2:
333
- provider, model = parts[0].upper(), parts[1]
334
- else:
335
- return None, None, None, usage
336
-
337
- # CG1: a hosted deployment never reaches the plan, signed in or not, so
338
- # the switch refuses with the reason -- not with "/connect chatgpt
339
- # signs in", which that deployment refuses in turn (batch 195).
340
- if provider == "CHATGPT" and hosted.is_hosted():
341
- return None, None, None, chatgpt_auth.LOCAL_ONLY
342
- # ROADMAP_v3 §83. CG11's refusal is lifted: the plan answers since slice
343
- # 2b. While it is signed out a switch would fail the next turn rather
344
- # than this command, so this refuses and says how to sign in (CG20).
345
- if provider == "CHATGPT" and not chatgpt_auth.status().signed_in:
346
- return None, None, None, _chatgpt_signed_out(command)
347
- providers = credentials.load_provider_data()
348
- if provider == "CHATGPT" and provider not in providers:
349
- # A sign-in made before slice 2b wrote no entry; it is written now.
350
- try:
351
- store_chatgpt_entry()
352
- except (OSError, ValueError) as exc:
353
- return (None, None, None,
354
- f"Could not record CHATGPT in providers.json: {exc}")
355
- providers = credentials.load_provider_data()
356
-
357
- # Unknown provider REFUSES: api_initialization would raise the same
358
- # ValueError on the next turn, a long way from the typo that caused it.
359
- if provider not in providers:
360
- return (None, None, None,
361
- f"Unknown provider {provider!r}. Configured: "
362
- f"{', '.join(sorted(providers)) or 'none'}.")
363
- return provider, model, providers, None
364
-
365
-
366
- def agent_pin_note(agent, provider: str, model: str) -> Optional[str]:
367
- """The note a switch owes when an active agent pins its own pair.
368
-
369
- An agent may name its own model/provider (§18), and those win for a
370
- chat turn. Without this the switch is a silent no-op for as long as
371
- that agent is active -- the failure shape this project keeps
372
- producing.
373
- """
374
- if agent is None or not agent.pins_model:
375
- return None
376
- return (f"Note: agent {agent.name!r} pins "
377
- f"{agent.provider or provider} | {agent.model or model} for "
378
- f"chat turns, so this applies to /research and to turns after "
379
- f"/agent default.")
380
-
381
-
382
- # ---------------------------------------------------------------------------
383
- # ---- /submodel (ROADMAP_v3 §57) ---------------------------------------------
384
- # ---------------------------------------------------------------------------
385
- # The model a spawned subagent runs on, for either shell (SM11). Everything
386
- # the command SAYS is decided here and both shells only print it, for
387
- # model_switch's reason above: two copies of what a command reports are two
388
- # copies that come to disagree. The pair itself lives in
389
- # core/pipeline_models.py as the `subagent` role, and the spawn reads it in
390
- # agents/subagent_tool.py.
391
-
392
- SUBMODEL_USAGE = ("Usage: /submodel <name>, or /submodel <PROVIDER> <name>, "
393
- "or /submodel off.")
394
-
395
- #: The runs `/submodel` never reaches, whatever it is set to (SM8). Said by
396
- #: every report, because a choice whose reach is invisible is the silent
397
- #: no-op SM3 exists to close.
398
- SUBMODEL_UNREACHED = ("the compactor, the pipeline reviewer and /init's "
399
- "initializer, which run on the session model")
400
-
401
- #: What `off` is spelled as. `/critic off`'s spellings, so the three role
402
- #: commands take the same words.
403
- _OFF = ("off", "clear", "auto", "none")
404
-
405
-
406
- def submodel_pinned_agents() -> list:
407
- """The spawnable agents `/submodel` does not reach: any that pins
408
- either half of its own pair (SM6). Sorted, for a stable sentence."""
409
- from agents.manager import manager
410
-
411
- return sorted(name for name, agent in manager.all().items()
412
- if agent.spawnable is True and agent.pins_model)
413
-
414
-
415
- def _submodel_reach() -> str:
416
- pinned = submodel_pinned_agents()
417
- agents = (f"the agents that pin their own model ({', '.join(pinned)}), "
418
- f"or " if pinned else "")
419
- return f"It does not reach {agents}{SUBMODEL_UNREACHED}."
420
-
421
-
422
- def submodel_label() -> Optional[str]:
423
- """`PROVIDER | model` while a submodel is set, else None. What the TUI's
424
- header and either shell's opening lines show (SM10)."""
425
- from core import pipeline_models
426
-
427
- pair = pipeline_models.resolve("subagent")
428
- if pair is None:
429
- return None
430
- return f"{pair['provider_name']} | {pair['model']}"
431
-
432
-
433
- def submodel_command(args: str, current_provider: str) -> list:
434
- """What `/submodel <args>` does and says: `[(kind, text)]`, where kind
435
- is "system" or "error", in the order to print them.
436
-
437
- THE STORE IS THE SETTING. There is no session copy for a spawn to read
438
- instead, so a write that failed changed nothing, and this says so
439
- rather than announcing a pair the next spawn will not use. The failure
440
- itself WARNED inside `pipeline_models._write`.
441
-
442
- A provider with no key WARNS and is kept (SM9), `/model`'s rule for
443
- `/model`'s reason: a local OpenAI-compatible endpoint takes none and
444
- the ChatGPT plan has none at all.
445
- """
446
- from core import pipeline_models
447
-
448
- text = args.strip()
449
- if not text:
450
- label = submodel_label()
451
- if label:
452
- lines = [("system", f"Subagents: {label} (remembered). A spawned "
453
- f"agent that pins no model of its own runs "
454
- f"on it.")]
455
- else:
456
- lines = [("system", "No submodel set: a spawned subagent runs on "
457
- "the same model as the run that spawns it.")]
458
- return lines + [("system", _submodel_reach()),
459
- ("system", SUBMODEL_USAGE)]
460
-
461
- if text.lower() in _OFF:
462
- outcome = pipeline_models.forget("subagent")
463
- if outcome == "failed":
464
- return [("error", "The remembered submodel could not be "
465
- "cleared, so spawns still use it.")]
466
- if outcome == "absent":
467
- return [("system", "No submodel was set.")]
468
- return [("system", "Submodel cleared: a spawned subagent runs on the "
469
- "same model as the run that spawns it again.")]
470
-
471
- provider, model, providers, error = model_switch(
472
- text, current_provider, command="submodel")
473
- if error:
474
- return [("error", error)]
475
- if not pipeline_models.remember("subagent", provider, model):
476
- return [("error", f"{provider} | {model} could not be saved, so "
477
- f"spawns are unchanged.")]
478
- lines = [("system", f"Subagents will run on {provider} | {model} from "
479
- f"the next spawn, in this launch and later ones, "
480
- f"until /submodel off.")]
481
- missing = credentials.missing_credential_message(
482
- provider, providers[provider])
483
- if missing:
484
- lines.append(("error", missing))
485
- return lines + [("system", _submodel_reach())]
486
-
487
-
488
- # ---------------------------------------------------------------------------
489
- # ---- HTTP -----------------------------------------------------------------
490
- # ---------------------------------------------------------------------------
491
-
492
- def _post(url: str, *, data: dict | None = None,
493
- json_body: dict | None = None) -> tuple[int, dict]:
494
- import httpx
495
-
496
- try:
497
- response = httpx.post(url, data=data, json=json_body,
498
- timeout=_HTTP_TIMEOUT_S)
499
- except httpx.HTTPError as exc:
500
- raise ConnectError(
501
- f"Could not reach {urlsplit(url).hostname}: "
502
- f"{type(exc).__name__}.") from None
503
- try:
504
- body = response.json()
505
- except ValueError:
506
- body = {}
507
- return response.status_code, body if isinstance(body, dict) else {}
508
-
509
-
510
- def post_form(url: str, data: dict) -> tuple[int, dict]:
511
- return _post(url, data=data)
512
-
513
-
514
- def post_json(url: str, payload: dict) -> tuple[int, dict]:
515
- return _post(url, json_body=payload)
516
-
517
-
518
- def get_json(url: str) -> tuple[int, dict]:
519
- """GET `url` and read a JSON object; `_post`'s shape and refusals."""
520
- import httpx
521
-
522
- try:
523
- response = httpx.get(url, timeout=_HTTP_TIMEOUT_S)
524
- except httpx.HTTPError as exc:
525
- raise ConnectError(
526
- f"Could not reach {urlsplit(url).hostname}: "
527
- f"{type(exc).__name__}.") from None
528
- try:
529
- body = response.json()
530
- except ValueError:
531
- body = {}
532
- return response.status_code, body if isinstance(body, dict) else {}
533
-
534
-
535
- # ---------------------------------------------------------------------------
536
- # ---- Hugging Face: the device code flow ------------------------------------
537
- # ---------------------------------------------------------------------------
538
-
539
- @dataclass(frozen=True)
540
- class DeviceCode:
541
- device_code: str
542
- user_code: str
543
- verification_uri: str
544
- verification_uri_complete: Optional[str]
545
- expires_in: int
546
- interval: int
547
-
548
- @property
549
- def open_url(self) -> str:
550
- """The page to send the person to: the one with the code already
551
- filled in when Hugging Face offers it."""
552
- return self.verification_uri_complete or self.verification_uri
553
-
554
-
555
- def hf_device_start(client_id: str, *, post: Post = post_form) -> DeviceCode:
556
- """Ask Hugging Face for a device code.
557
-
558
- Only `client_id` is sent, exactly as Hugging Face's own sample does: the
559
- SCOPES belong to the OAuth app's registration (`openid profile
560
- inference-api`), so they cannot be widened from here.
561
- """
562
- if not client_id:
563
- raise ConnectError(
564
- "Hugging Face sign-in is not set up in this install "
565
- "(hf_oauth_client_id in config.yaml is empty). Paste a token "
566
- "instead: /connect huggingface --key")
567
- status, body = post(HF_DEVICE_URL, {"client_id": client_id})
568
- try:
569
- return DeviceCode(
570
- device_code=str(body["device_code"]),
571
- user_code=str(body["user_code"]),
572
- verification_uri=str(body["verification_uri"]),
573
- verification_uri_complete=(
574
- str(body["verification_uri_complete"])
575
- if body.get("verification_uri_complete") else None),
576
- expires_in=int(body.get("expires_in") or 900),
577
- interval=max(1, int(body.get("interval") or 5)),
578
- )
579
- except (KeyError, TypeError, ValueError):
580
- raise ConnectError(
581
- f"Hugging Face did not start a sign-in "
582
- f"({body.get('error') or f'HTTP {status}'}).") from None
583
-
584
-
585
- def hf_device_poll(client_id: str, code: DeviceCode, *,
586
- post: Post = post_form,
587
- wait: Callable[[float], bool] | None = None,
588
- now: Callable[[], float] = time.monotonic) -> str:
589
- """Wait for the person to approve the code; return the access token.
590
-
591
- `wait(seconds)` sleeps and answers True when the wait was STOPPED --
592
- `threading.Event.wait`'s contract -- which is how a closing app ends a
593
- poll that would otherwise keep the process alive until the code expired.
594
- The RFC 8628 answers are honoured: `authorization_pending` waits again,
595
- `slow_down` waits five seconds longer from then on, and `access_denied` /
596
- `expired_token` end it.
597
- """
598
- if wait is None:
599
- def wait(seconds: float) -> bool:
600
- time.sleep(seconds)
601
- return False
602
-
603
- deadline = now() + code.expires_in
604
- interval = code.interval
605
- while True:
606
- if wait(interval):
607
- raise ConnectCancelled("The sign-in was stopped.")
608
- if now() >= deadline:
609
- raise ConnectError("The code expired before it was approved. "
610
- "Run /connect huggingface again.")
611
- status, body = post(HF_TOKEN_URL, {
612
- "grant_type": DEVICE_GRANT,
613
- "device_code": code.device_code,
614
- "client_id": client_id,
615
- })
616
- token = body.get("access_token")
617
- if status == 200 and isinstance(token, str) and token:
618
- return token
619
- error = body.get("error")
620
- if error == "authorization_pending":
621
- continue
622
- if error == "slow_down":
623
- interval += 5
624
- continue
625
- if error == "access_denied":
626
- raise ConnectError("The sign-in was declined on Hugging Face.")
627
- if error == "expired_token":
628
- raise ConnectError("The code expired before it was approved. "
629
- "Run /connect huggingface again.")
630
- raise ConnectError(f"Hugging Face refused the sign-in "
631
- f"({error or f'HTTP {status}'}).")
632
-
633
-
634
- # ---------------------------------------------------------------------------
635
- # ---- OpenRouter: PKCE with the code shown to copy -------------------------
636
- # ---------------------------------------------------------------------------
637
-
638
- @dataclass(frozen=True)
639
- class PkceStart:
640
- verifier: str
641
- url: str
642
-
643
-
644
- def _challenge(verifier: str) -> str:
645
- digest = hashlib.sha256(verifier.encode("ascii")).digest()
646
- return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
647
-
648
-
649
- def openrouter_start(*, token: Callable[[int], str] = secrets.token_urlsafe
650
- ) -> PkceStart:
651
- """The authorization URL, and the verifier that must accompany its code.
652
-
653
- NO `callback_url`, deliberately: OpenRouter then shows the code on its
654
- own page for the person to copy, which is what lets a terminal -- local
655
- or in a browser tab -- sign in with nothing listening for a redirect. A
656
- code challenge is REQUIRED in that mode, and S256 is the method
657
- OpenRouter recommends. 64 random bytes give an 86-character verifier,
658
- inside RFC 7636's 43-128.
659
- """
660
- verifier = token(64)
661
- query = urlencode({
662
- "code_challenge": _challenge(verifier),
663
- "code_challenge_method": "S256",
664
- "key_label": OPENROUTER_KEY_LABEL,
665
- })
666
- return PkceStart(verifier=verifier, url=f"{OPENROUTER_AUTH_URL}?{query}")
667
-
668
-
669
- def openrouter_exchange(code: str, verifier: str, *,
670
- post: Post = post_json) -> str:
671
- """Trade the copied code for the person's own OpenRouter key."""
672
- code = (code or "").strip()
673
- if not code:
674
- raise ConnectError("Nothing was entered.")
675
- status, body = post(OPENROUTER_KEYS_URL, {
676
- "code": code,
677
- "code_verifier": verifier,
678
- "code_challenge_method": "S256",
679
- })
680
- key = body.get("key")
681
- if status == 200 and isinstance(key, str) and key:
682
- return key
683
- raise ConnectError(
684
- f"OpenRouter did not accept that code (HTTP {status}). Codes are "
685
- f"single-use; run /connect openrouter again for a fresh one.")
686
-
1
+ """`/connect`'s catalogue, its sign-in flows, and the one way a key is stored
2
+ (ROADMAP_v3 §79, HD5, HD13).
3
+
4
+ Connecting a model used to mean copying `providers.json.example` and editing
5
+ JSON by hand -- the one setup step README said nothing could do for you. This
6
+ module is everything about it that is not drawing: which providers there are,
7
+ the OAuth flows whose providers explicitly invite a third-party app to use
8
+ them, and where a key ends up. The TUI owns the asking.
9
+
10
+ ONLY FOUR PROVIDERS SIGN IN, AND THAT IS A RULING RATHER THAN A GAP. The
11
+ owner asked for OAuth only where the provider's official guidance gives a
12
+ third-party app explicit permission:
13
+
14
+ * Hugging Face, https://huggingface.co/docs/hub/oauth -- a "Sign in with HF"
15
+ flow "in any website or App", the `inference-api` scope ("Make inference
16
+ requests to Inference Providers on behalf of the user"), public apps with
17
+ no secret, and a device code flow for apps with no browser of their own.
18
+ * OpenRouter, https://openrouter.ai/docs/guides/overview/auth/oauth -- "Use
19
+ OAuth to let your users bring their own OpenRouter API key to your app",
20
+ PKCE, and a mode with no callback URL in which the code is shown to the
21
+ user to copy.
22
+ * ModelScope, whose app registration (modelscope.ai, Access Control, OAuth
23
+ Connected App) says "Users can authorize your application through
24
+ ModelScope OAuth to obtain ModelScope-related permissions associated with
25
+ the user" and offers the scope `api-inference` ("Invoke API Inference").
26
+ modelscope.cn's form says the same in its original Chinese and offers the
27
+ same scope (read 2026-10-26); it is a separate site with separate
28
+ accounts, so it is a sign-in of its own (batch 176).
29
+ * OpenAI's Sign in with ChatGPT, https://developers.openai.com/siwc -- a
30
+ Plus or Pro subscriber spends their ChatGPT plan inside open-source and
31
+ locally hosted apps, with no client secret (ROADMAP_v3 §83). A remotely
32
+ hosted app needs OpenAI's interest form first, so this one is LOCAL
33
+ ONLY (CG1), and its credential lives in `core/chatgpt_auth.py`: an
34
+ access token that expires hourly and a refresh token, not a key.
35
+
36
+ Hugging Face's and OpenRouter's flows need no server of ours to receive a
37
+ redirect, which is why both work the same in a local terminal and in a
38
+ browser tab. ModelScope's does not work that way: its token endpoint takes
39
+ only a confidential client (`client_secret_basic` / `client_secret_post` in
40
+ its discovery document, read 2026-10-22, and the same on modelscope.cn), so
41
+ only a hosted bridge, which can keep the secret, completes it --
42
+ `deploy/hosted/sign_in.py` -- and a local install connects either ModelScope
43
+ site with a pasted key. ChatGPT's redirect comes back to a listener on
44
+ 127.0.0.1, which only the person's own machine can reach. Everything else
45
+ is a pasted key everywhere.
46
+
47
+ NO HTTP LIBRARY IS IMPORTED AT MODULE SCOPE. Every network call goes through a
48
+ `post` callable the caller may replace, and the default imports `httpx` when
49
+ it runs: the suite's root `conftest.py` stubs `httpx` for the whole process,
50
+ so the flows are tested against fake transports rather than a fake library.
51
+ """
52
+
53
+ from __future__ import annotations
54
+
55
+ import base64
56
+ import hashlib
57
+ import re
58
+ import secrets
59
+ import time
60
+ from collections.abc import Callable
61
+ from dataclasses import dataclass
62
+ from typing import Optional
63
+ from urllib.parse import urlencode, urlsplit
64
+
65
+ import credentials
66
+
67
+ HF_DEVICE_URL = "https://huggingface.co/oauth/device"
68
+ HF_TOKEN_URL = "https://huggingface.co/oauth/token"
69
+ DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
70
+
71
+ OPENROUTER_AUTH_URL = "https://openrouter.ai/auth"
72
+ OPENROUTER_KEYS_URL = "https://openrouter.ai/api/v1/auth/keys"
73
+ OPENROUTER_KEY_LABEL = "Venastine Research Harness"
74
+
75
+ # How long one sign-in request may take before it is reported as unreachable.
76
+ # A device-code poll is many short requests, so this bounds each one and the
77
+ # code's own `expires_in` bounds the whole wait.
78
+ _HTTP_TIMEOUT_S = 30
79
+
80
+ Post = Callable[[str, dict], tuple[int, dict]]
81
+
82
+
83
+ class ConnectError(Exception):
84
+ """A sign-in or a key that did not work, worded for the person at the
85
+ keyboard. Never carries a credential: every message here is built from
86
+ the provider's error CODE, not from anything the provider echoed."""
87
+
88
+
89
+ class ConnectCancelled(ConnectError):
90
+ """The wait for a sign-in was stopped from our side (the app is closing)."""
91
+
92
+
93
+ @dataclass(frozen=True)
94
+ class Preset:
95
+ """One provider `/connect` knows how to set up.
96
+
97
+ `name` is what is typed; `provider` is the `providers.json` entry it
98
+ writes, upper-case because `/model` upper-cases what it is given.
99
+ `default_model` is switched to after connecting when it is set, and left
100
+ alone when it is not -- a guessed model name is a 404 on the first turn.
101
+ `sign_in` names the OAuth flow, or None where only a pasted key works;
102
+ the two ModelScope sites' are completed by a hosted bridge, so each is
103
+ offered only where the session's bridge says it can (security/hosted.py).
104
+ """
105
+
106
+ name: str
107
+ provider: str
108
+ label: str
109
+ api_url: str
110
+ is_v1_compatible: bool
111
+ supports_stream_usage: bool
112
+ default_model: Optional[str] = None
113
+ sign_in: Optional[str] = None
114
+ key_url: str = ""
115
+
116
+
117
+ # URLs and both flags match `providers.json.example` wherever the two name the
118
+ # same provider, so a key connected here behaves exactly like one typed there.
119
+ PRESETS: dict[str, Preset] = {p.name: p for p in (
120
+ Preset("huggingface", "HUGGINGFACE", "Hugging Face Inference Providers",
121
+ "https://router.huggingface.co/v1", True, False,
122
+ default_model="openai/gpt-oss-120b", sign_in="huggingface",
123
+ key_url="https://huggingface.co/settings/tokens"),
124
+ # The default is free and served by its own maker. Chosen by the owner
125
+ # in batch 168 after a survey on 2026-10-22: every free model listed
126
+ # had ONE endpoint, and the previous default's (Nvidia's, for
127
+ # nemotron-3-super-120b-a12b:free) had answered 404 for a day at 0%
128
+ # uptime, while this one answered a plain call and a tool call.
129
+ Preset("openrouter", "OPENROUTER", "OpenRouter",
130
+ "https://openrouter.ai/api/v1", True, False,
131
+ default_model="minimax/minimax-m3.1-flash:free",
132
+ sign_in="openrouter", key_url="https://openrouter.ai/keys"),
133
+ # Reports streaming usage, measured 2026-10-22 on four models
134
+ # (DeepSeek-V4-Pro-0813, Qwen3.5-27B, Qwen3.8-27B, Nex-N2.5-mini): with
135
+ # `stream_options` every one sent real counts, the last in a chunk with
136
+ # no choices; without it three of the four sent all-zero usage, so the
137
+ # meter could never show. modelscope.cn's endpoint was not measured.
138
+ Preset("modelscope", "MODELSCOPE", "ModelScope API-Inference (modelscope.ai)",
139
+ "https://api-inference.modelscope.ai/v1", True, True,
140
+ sign_in="modelscope",
141
+ key_url="https://www.modelscope.ai/my/myaccesstoken"),
142
+ Preset("modelscope-cn", "MODELSCOPE_CN",
143
+ "ModelScope API-Inference (modelscope.cn)",
144
+ "https://api-inference.modelscope.cn/v1", True, False,
145
+ sign_in="modelscope-cn",
146
+ key_url="https://modelscope.cn/my/myaccesstoken"),
147
+ # ROADMAP_v3 §83. Not v1-compatible: the plan takes the Responses API
148
+ # only (Chat Completions answered 401, slice 0), which `core/client.py`
149
+ # routes CHATGPT to by name. Its `providers.json` entry holds no key and
150
+ # is written when a sign-in completes (CG20, `store_chatgpt_entry`).
151
+ Preset("chatgpt", "CHATGPT", "ChatGPT plan (Sign in with ChatGPT)",
152
+ "https://api.openai.com/v1", False, True, sign_in="chatgpt"),
153
+ Preset("openai", "OPENAI", "OpenAI", "https://api.openai.com/v1",
154
+ True, True, key_url="https://platform.openai.com/api-keys"),
155
+ Preset("anthropic", "ANTHROPIC", "Anthropic", "", False, True,
156
+ key_url="https://console.anthropic.com/settings/keys"),
157
+ Preset("google", "GOOGLE", "Google Gemini", "", False, False,
158
+ key_url="https://aistudio.google.com/apikey"),
159
+ Preset("deepseek", "DEEPSEEK", "DeepSeek", "https://api.deepseek.com/v1",
160
+ True, False),
161
+ Preset("groq", "GROQ", "Groq", "https://api.groq.com/openai/v1",
162
+ True, False),
163
+ Preset("mistral", "MISTRAL", "Mistral", "https://api.mistral.ai/v1",
164
+ True, False),
165
+ )}
166
+
167
+ # The names `core/client.py` routes by NAME rather than by the
168
+ # `is_v1_compatible` flag. A custom endpoint under one would be sent to a
169
+ # native SDK it is not -- or, for CHATGPT, to the plan's sign-in (§83) --
170
+ # so `custom` refuses them.
171
+ _NATIVE_PROVIDERS = frozenset({"ANTHROPIC", "GOOGLE", "CHATGPT"})
172
+ _PROVIDER_NAME = re.compile(r"^[A-Z0-9][A-Z0-9_.-]{0,39}$")
173
+ _LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
174
+
175
+
176
+ def custom_preset(name: str, url: str) -> Preset:
177
+ """A preset for any OpenAI-compatible endpoint, named by the user.
178
+
179
+ https only, except a loopback host, because the key travels in the
180
+ Authorization header of every request and a local server is the one
181
+ place plain http is ordinary.
182
+ """
183
+ provider = name.strip().upper()
184
+ if not _PROVIDER_NAME.match(provider):
185
+ raise ConnectError(
186
+ f"{name!r} is not a usable provider name: letters, digits, "
187
+ f"'_', '.' and '-', starting with a letter or digit.")
188
+ if provider in _NATIVE_PROVIDERS:
189
+ raise ConnectError(
190
+ f"{provider} is reserved for its own SDK; use /connect "
191
+ f"{provider.lower()} instead.")
192
+ parts = urlsplit(url.strip())
193
+ local = parts.hostname in _LOOPBACK_HOSTS
194
+ if not parts.hostname or parts.scheme not in ("https", "http") or (
195
+ parts.scheme == "http" and not local):
196
+ raise ConnectError(
197
+ f"{url!r} is not an https URL (plain http is accepted only for "
198
+ f"localhost).")
199
+ return Preset(provider.lower(), provider, f"{provider} (custom)",
200
+ url.strip(), True, False)
201
+
202
+
203
+ def clean_key(raw: str) -> str:
204
+ """The pasted key as it will be stored, or ConnectError.
205
+
206
+ Surrounding whitespace is what a paste brings with it and is dropped;
207
+ whitespace INSIDE is not a key at all, and storing it would turn every
208
+ request into a 401 a long way from the paste that caused it.
209
+ """
210
+ key = (raw or "").strip()
211
+ if not key:
212
+ raise ConnectError("Nothing was entered.")
213
+ if any(ch.isspace() for ch in key):
214
+ raise ConnectError("That has spaces or line breaks inside it, so it "
215
+ "is not a key. Paste the key on its own.")
216
+ return key
217
+
218
+
219
+ def entry_for(preset: Preset, key: str) -> dict:
220
+ return {
221
+ "API_URL": preset.api_url,
222
+ "API_KEY": key,
223
+ "is_v1_compatible": preset.is_v1_compatible,
224
+ "supports_stream_usage": preset.supports_stream_usage,
225
+ }
226
+
227
+
228
+ def store(preset: Preset, key: str, *, persist: bool) -> None:
229
+ """Record `key` for `preset.provider`, then forget the cached client.
230
+
231
+ `persist=False` is the shared hosted demo's rule (HD5): the key lives in
232
+ this process's memory and nowhere else. `persist=True` writes
233
+ `providers.json` through `save_credentials`, which keeps the file 0600
234
+ and atomic and leaves any other field on an existing entry --
235
+ `echoes_reasoning` included -- exactly as it was.
236
+ """
237
+ from core.client import forget_client
238
+
239
+ if persist:
240
+ credentials.save_credentials(
241
+ preset.provider, key, preset.api_url,
242
+ preset.is_v1_compatible, preset.supports_stream_usage)
243
+ else:
244
+ credentials.set_session_provider(preset.provider, entry_for(preset, key))
245
+ forget_client(preset.provider)
246
+
247
+
248
+ def store_chatgpt_entry() -> None:
249
+ """CHATGPT's `providers.json` entry, written when a sign-in completes
250
+ (ROADMAP_v3 §83, CG20).
251
+
252
+ It holds NO KEY -- the plan's tokens live in `chatgpt_auth.json` (CG4)
253
+ -- and exists so that `/model`, the launch restore and the per-provider
254
+ flags read CHATGPT the way they read every other entry. Written through
255
+ `save_credentials`, so a field already on the entry (`accepts_images`,
256
+ once a measurement sets it, CG7) stays as it was. Local installs only:
257
+ the sign-in that calls this refuses on a hosted deployment (CG1).
258
+ """
259
+ from core.client import forget_client
260
+
261
+ preset = PRESETS["chatgpt"]
262
+ credentials.save_credentials(
263
+ preset.provider, "", preset.api_url, preset.is_v1_compatible,
264
+ preset.supports_stream_usage)
265
+ forget_client(preset.provider)
266
+
267
+
268
+ def connected_providers() -> set:
269
+ """Names that have a non-empty key right now, file and session alike,
270
+ and CHATGPT while its sign-in holds a refresh token (§83): the plan has
271
+ no key, so its token file is what says it is connected."""
272
+ from core import chatgpt_auth
273
+
274
+ names = {name for name, entry in credentials.load_provider_data().items()
275
+ if entry.get("API_KEY")}
276
+ if chatgpt_auth.status().signed_in:
277
+ names.add("CHATGPT")
278
+ return names
279
+
280
+
281
+ # ---------------------------------------------------------------------------
282
+ # ---- /model ----------------------------------------------------------------
283
+ # ---------------------------------------------------------------------------
284
+ # What `/model` may switch to, for either shell (ROADMAP_v3 §89). Moved out
285
+ # of the TUI's handler when the CLI got one: which switches REFUSE is the
286
+ # part two copies would come to disagree about, and a refusal one shell
287
+ # makes and the other skips is a turn that fails a long way from its cause.
288
+
289
+ MODEL_USAGE = "Usage: /model <name>, or /model <PROVIDER> <name>."
290
+
291
+
292
+ def _chatgpt_signed_out(command: str) -> str:
293
+ return ("The ChatGPT plan is not signed in, so it cannot answer. /connect "
294
+ f"chatgpt signs in; then /{command} CHATGPT <name>.")
295
+
296
+
297
+ CHATGPT_SIGNED_OUT = _chatgpt_signed_out("model")
298
+
299
+
300
+ def configured_providers(providers: dict) -> str:
301
+ """The providers a switch can reach, for a bare `/model`."""
302
+ from core import chatgpt_auth
303
+
304
+ named = sorted(p for p, e in providers.items() if e.get("API_KEY"))
305
+ # §83: the plan has no key; its sign-in is what connects it.
306
+ if chatgpt_auth.status().signed_in:
307
+ named.append("CHATGPT (signed in)")
308
+ return ", ".join(named) if named else "none (add a key to providers.json)"
309
+
310
+
311
+ def model_switch(args: str, current_provider: str,
312
+ command: str = "model") -> tuple:
313
+ """`(provider, model, providers, error)` for `/model`'s argument.
314
+
315
+ `/model <name>` keeps `current_provider`; `/model <PROVIDER> <name>`
316
+ switches both. `error` is the sentence a refusal shows, and the other
317
+ three are None with it. `providers` is the file as read after any
318
+ entry this wrote, for the caller's missing-key warning.
319
+
320
+ `command` is `submodel` for `/submodel` (ROADMAP_v3 §57), which takes
321
+ the same pairs and refuses the same ones: a subagent's turn is a chat
322
+ turn on another pair, so the plan's refusals hold for it exactly. Only
323
+ the sentences that name a command change.
324
+ """
325
+ from core import chatgpt_auth
326
+ from security import hosted
327
+
328
+ usage = MODEL_USAGE if command == "model" else SUBMODEL_USAGE
329
+ parts = args.split()
330
+ if len(parts) == 1:
331
+ provider, model = current_provider, parts[0]
332
+ elif len(parts) == 2:
333
+ provider, model = parts[0].upper(), parts[1]
334
+ else:
335
+ return None, None, None, usage
336
+
337
+ # CG1: a hosted deployment never reaches the plan, signed in or not, so
338
+ # the switch refuses with the reason -- not with "/connect chatgpt
339
+ # signs in", which that deployment refuses in turn (batch 195).
340
+ if provider == "CHATGPT" and hosted.is_hosted():
341
+ return None, None, None, chatgpt_auth.LOCAL_ONLY
342
+ # ROADMAP_v3 §83. CG11's refusal is lifted: the plan answers since slice
343
+ # 2b. While it is signed out a switch would fail the next turn rather
344
+ # than this command, so this refuses and says how to sign in (CG20).
345
+ if provider == "CHATGPT" and not chatgpt_auth.status().signed_in:
346
+ return None, None, None, _chatgpt_signed_out(command)
347
+ providers = credentials.load_provider_data()
348
+ if provider == "CHATGPT" and provider not in providers:
349
+ # A sign-in made before slice 2b wrote no entry; it is written now.
350
+ try:
351
+ store_chatgpt_entry()
352
+ except (OSError, ValueError) as exc:
353
+ return (None, None, None,
354
+ f"Could not record CHATGPT in providers.json: {exc}")
355
+ providers = credentials.load_provider_data()
356
+
357
+ # Unknown provider REFUSES: api_initialization would raise the same
358
+ # ValueError on the next turn, a long way from the typo that caused it.
359
+ if provider not in providers:
360
+ return (None, None, None,
361
+ f"Unknown provider {provider!r}. Configured: "
362
+ f"{', '.join(sorted(providers)) or 'none'}.")
363
+ return provider, model, providers, None
364
+
365
+
366
+ def agent_pin_note(agent, provider: str, model: str) -> Optional[str]:
367
+ """The note a switch owes when an active agent pins its own pair.
368
+
369
+ An agent may name its own model/provider (§18), and those win for a
370
+ chat turn. Without this the switch is a silent no-op for as long as
371
+ that agent is active -- the failure shape this project keeps
372
+ producing.
373
+ """
374
+ if agent is None or not agent.pins_model:
375
+ return None
376
+ return (f"Note: agent {agent.name!r} pins "
377
+ f"{agent.provider or provider} | {agent.model or model} for "
378
+ f"chat turns, so this applies to /research and to turns after "
379
+ f"/agent default.")
380
+
381
+
382
+ # ---------------------------------------------------------------------------
383
+ # ---- /submodel (ROADMAP_v3 §57) ---------------------------------------------
384
+ # ---------------------------------------------------------------------------
385
+ # The model a spawned subagent runs on, for either shell (SM11). Everything
386
+ # the command SAYS is decided here and both shells only print it, for
387
+ # model_switch's reason above: two copies of what a command reports are two
388
+ # copies that come to disagree. The pair itself lives in
389
+ # core/pipeline_models.py as the `subagent` role, and the spawn reads it in
390
+ # agents/subagent_tool.py.
391
+
392
+ SUBMODEL_USAGE = ("Usage: /submodel <name>, or /submodel <PROVIDER> <name>, "
393
+ "or /submodel off.")
394
+
395
+ #: The runs `/submodel` never reaches, whatever it is set to (SM8). Said by
396
+ #: every report, because a choice whose reach is invisible is the silent
397
+ #: no-op SM3 exists to close.
398
+ SUBMODEL_UNREACHED = ("the compactor, the pipeline reviewer and /init's "
399
+ "initializer, which run on the session model")
400
+
401
+ #: What `off` is spelled as. `/critic off`'s spellings, so the three role
402
+ #: commands take the same words.
403
+ _OFF = ("off", "clear", "auto", "none")
404
+
405
+
406
+ def submodel_pinned_agents() -> list:
407
+ """The spawnable agents `/submodel` does not reach: any that pins
408
+ either half of its own pair (SM6). Sorted, for a stable sentence."""
409
+ from agents.manager import manager
410
+
411
+ return sorted(name for name, agent in manager.all().items()
412
+ if agent.spawnable is True and agent.pins_model)
413
+
414
+
415
+ def _submodel_reach() -> str:
416
+ pinned = submodel_pinned_agents()
417
+ agents = (f"the agents that pin their own model ({', '.join(pinned)}), "
418
+ f"or " if pinned else "")
419
+ return f"It does not reach {agents}{SUBMODEL_UNREACHED}."
420
+
421
+
422
+ def submodel_label() -> Optional[str]:
423
+ """`PROVIDER | model` while a submodel is set, else None. What the TUI's
424
+ header and either shell's opening lines show (SM10)."""
425
+ from core import pipeline_models
426
+
427
+ pair = pipeline_models.resolve("subagent")
428
+ if pair is None:
429
+ return None
430
+ return f"{pair['provider_name']} | {pair['model']}"
431
+
432
+
433
+ def submodel_command(args: str, current_provider: str) -> list:
434
+ """What `/submodel <args>` does and says: `[(kind, text)]`, where kind
435
+ is "system" or "error", in the order to print them.
436
+
437
+ THE STORE IS THE SETTING. There is no session copy for a spawn to read
438
+ instead, so a write that failed changed nothing, and this says so
439
+ rather than announcing a pair the next spawn will not use. The failure
440
+ itself WARNED inside `pipeline_models._write`.
441
+
442
+ A provider with no key WARNS and is kept (SM9), `/model`'s rule for
443
+ `/model`'s reason: a local OpenAI-compatible endpoint takes none and
444
+ the ChatGPT plan has none at all.
445
+ """
446
+ from core import pipeline_models
447
+
448
+ text = args.strip()
449
+ if not text:
450
+ label = submodel_label()
451
+ if label:
452
+ lines = [("system", f"Subagents: {label} (remembered). A spawned "
453
+ f"agent that pins no model of its own runs "
454
+ f"on it.")]
455
+ else:
456
+ lines = [("system", "No submodel set: a spawned subagent runs on "
457
+ "the same model as the run that spawns it.")]
458
+ return lines + [("system", _submodel_reach()),
459
+ ("system", SUBMODEL_USAGE)]
460
+
461
+ if text.lower() in _OFF:
462
+ outcome = pipeline_models.forget("subagent")
463
+ if outcome == "failed":
464
+ return [("error", "The remembered submodel could not be "
465
+ "cleared, so spawns still use it.")]
466
+ if outcome == "absent":
467
+ return [("system", "No submodel was set.")]
468
+ return [("system", "Submodel cleared: a spawned subagent runs on the "
469
+ "same model as the run that spawns it again.")]
470
+
471
+ provider, model, providers, error = model_switch(
472
+ text, current_provider, command="submodel")
473
+ if error:
474
+ return [("error", error)]
475
+ if not pipeline_models.remember("subagent", provider, model):
476
+ return [("error", f"{provider} | {model} could not be saved, so "
477
+ f"spawns are unchanged.")]
478
+ lines = [("system", f"Subagents will run on {provider} | {model} from "
479
+ f"the next spawn, in this launch and later ones, "
480
+ f"until /submodel off.")]
481
+ missing = credentials.missing_credential_message(
482
+ provider, providers[provider])
483
+ if missing:
484
+ lines.append(("error", missing))
485
+ return lines + [("system", _submodel_reach())]
486
+
487
+
488
+ # ---------------------------------------------------------------------------
489
+ # ---- HTTP -----------------------------------------------------------------
490
+ # ---------------------------------------------------------------------------
491
+
492
+ def _post(url: str, *, data: dict | None = None,
493
+ json_body: dict | None = None) -> tuple[int, dict]:
494
+ import httpx
495
+
496
+ try:
497
+ response = httpx.post(url, data=data, json=json_body,
498
+ timeout=_HTTP_TIMEOUT_S)
499
+ except httpx.HTTPError as exc:
500
+ raise ConnectError(
501
+ f"Could not reach {urlsplit(url).hostname}: "
502
+ f"{type(exc).__name__}.") from None
503
+ try:
504
+ body = response.json()
505
+ except ValueError:
506
+ body = {}
507
+ return response.status_code, body if isinstance(body, dict) else {}
508
+
509
+
510
+ def post_form(url: str, data: dict) -> tuple[int, dict]:
511
+ return _post(url, data=data)
512
+
513
+
514
+ def post_json(url: str, payload: dict) -> tuple[int, dict]:
515
+ return _post(url, json_body=payload)
516
+
517
+
518
+ def get_json(url: str) -> tuple[int, dict]:
519
+ """GET `url` and read a JSON object; `_post`'s shape and refusals."""
520
+ import httpx
521
+
522
+ try:
523
+ response = httpx.get(url, timeout=_HTTP_TIMEOUT_S)
524
+ except httpx.HTTPError as exc:
525
+ raise ConnectError(
526
+ f"Could not reach {urlsplit(url).hostname}: "
527
+ f"{type(exc).__name__}.") from None
528
+ try:
529
+ body = response.json()
530
+ except ValueError:
531
+ body = {}
532
+ return response.status_code, body if isinstance(body, dict) else {}
533
+
534
+
535
+ # ---------------------------------------------------------------------------
536
+ # ---- Hugging Face: the device code flow ------------------------------------
537
+ # ---------------------------------------------------------------------------
538
+
539
+ @dataclass(frozen=True)
540
+ class DeviceCode:
541
+ device_code: str
542
+ user_code: str
543
+ verification_uri: str
544
+ verification_uri_complete: Optional[str]
545
+ expires_in: int
546
+ interval: int
547
+
548
+ @property
549
+ def open_url(self) -> str:
550
+ """The page to send the person to: the one with the code already
551
+ filled in when Hugging Face offers it."""
552
+ return self.verification_uri_complete or self.verification_uri
553
+
554
+
555
+ def hf_device_start(client_id: str, *, post: Post = post_form) -> DeviceCode:
556
+ """Ask Hugging Face for a device code.
557
+
558
+ Only `client_id` is sent, exactly as Hugging Face's own sample does: the
559
+ SCOPES belong to the OAuth app's registration (`openid profile
560
+ inference-api`), so they cannot be widened from here.
561
+ """
562
+ if not client_id:
563
+ raise ConnectError(
564
+ "Hugging Face sign-in is not set up in this install "
565
+ "(hf_oauth_client_id in config.yaml is empty). Paste a token "
566
+ "instead: /connect huggingface --key")
567
+ status, body = post(HF_DEVICE_URL, {"client_id": client_id})
568
+ try:
569
+ return DeviceCode(
570
+ device_code=str(body["device_code"]),
571
+ user_code=str(body["user_code"]),
572
+ verification_uri=str(body["verification_uri"]),
573
+ verification_uri_complete=(
574
+ str(body["verification_uri_complete"])
575
+ if body.get("verification_uri_complete") else None),
576
+ expires_in=int(body.get("expires_in") or 900),
577
+ interval=max(1, int(body.get("interval") or 5)),
578
+ )
579
+ except (KeyError, TypeError, ValueError):
580
+ raise ConnectError(
581
+ f"Hugging Face did not start a sign-in "
582
+ f"({body.get('error') or f'HTTP {status}'}).") from None
583
+
584
+
585
+ def hf_device_poll(client_id: str, code: DeviceCode, *,
586
+ post: Post = post_form,
587
+ wait: Callable[[float], bool] | None = None,
588
+ now: Callable[[], float] = time.monotonic) -> str:
589
+ """Wait for the person to approve the code; return the access token.
590
+
591
+ `wait(seconds)` sleeps and answers True when the wait was STOPPED --
592
+ `threading.Event.wait`'s contract -- which is how a closing app ends a
593
+ poll that would otherwise keep the process alive until the code expired.
594
+ The RFC 8628 answers are honoured: `authorization_pending` waits again,
595
+ `slow_down` waits five seconds longer from then on, and `access_denied` /
596
+ `expired_token` end it.
597
+ """
598
+ if wait is None:
599
+ def wait(seconds: float) -> bool:
600
+ time.sleep(seconds)
601
+ return False
602
+
603
+ deadline = now() + code.expires_in
604
+ interval = code.interval
605
+ while True:
606
+ if wait(interval):
607
+ raise ConnectCancelled("The sign-in was stopped.")
608
+ if now() >= deadline:
609
+ raise ConnectError("The code expired before it was approved. "
610
+ "Run /connect huggingface again.")
611
+ status, body = post(HF_TOKEN_URL, {
612
+ "grant_type": DEVICE_GRANT,
613
+ "device_code": code.device_code,
614
+ "client_id": client_id,
615
+ })
616
+ token = body.get("access_token")
617
+ if status == 200 and isinstance(token, str) and token:
618
+ return token
619
+ error = body.get("error")
620
+ if error == "authorization_pending":
621
+ continue
622
+ if error == "slow_down":
623
+ interval += 5
624
+ continue
625
+ if error == "access_denied":
626
+ raise ConnectError("The sign-in was declined on Hugging Face.")
627
+ if error == "expired_token":
628
+ raise ConnectError("The code expired before it was approved. "
629
+ "Run /connect huggingface again.")
630
+ raise ConnectError(f"Hugging Face refused the sign-in "
631
+ f"({error or f'HTTP {status}'}).")
632
+
633
+
634
+ # ---------------------------------------------------------------------------
635
+ # ---- OpenRouter: PKCE with the code shown to copy -------------------------
636
+ # ---------------------------------------------------------------------------
637
+
638
+ @dataclass(frozen=True)
639
+ class PkceStart:
640
+ verifier: str
641
+ url: str
642
+
643
+
644
+ def _challenge(verifier: str) -> str:
645
+ digest = hashlib.sha256(verifier.encode("ascii")).digest()
646
+ return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
647
+
648
+
649
+ def openrouter_start(*, token: Callable[[int], str] = secrets.token_urlsafe
650
+ ) -> PkceStart:
651
+ """The authorization URL, and the verifier that must accompany its code.
652
+
653
+ NO `callback_url`, deliberately: OpenRouter then shows the code on its
654
+ own page for the person to copy, which is what lets a terminal -- local
655
+ or in a browser tab -- sign in with nothing listening for a redirect. A
656
+ code challenge is REQUIRED in that mode, and S256 is the method
657
+ OpenRouter recommends. 64 random bytes give an 86-character verifier,
658
+ inside RFC 7636's 43-128.
659
+ """
660
+ verifier = token(64)
661
+ query = urlencode({
662
+ "code_challenge": _challenge(verifier),
663
+ "code_challenge_method": "S256",
664
+ "key_label": OPENROUTER_KEY_LABEL,
665
+ })
666
+ return PkceStart(verifier=verifier, url=f"{OPENROUTER_AUTH_URL}?{query}")
667
+
668
+
669
+ def openrouter_exchange(code: str, verifier: str, *,
670
+ post: Post = post_json) -> str:
671
+ """Trade the copied code for the person's own OpenRouter key."""
672
+ code = (code or "").strip()
673
+ if not code:
674
+ raise ConnectError("Nothing was entered.")
675
+ status, body = post(OPENROUTER_KEYS_URL, {
676
+ "code": code,
677
+ "code_verifier": verifier,
678
+ "code_challenge_method": "S256",
679
+ })
680
+ key = body.get("key")
681
+ if status == 200 and isinstance(key, str) and key:
682
+ return key
683
+ raise ConnectError(
684
+ f"OpenRouter did not accept that code (HTTP {status}). Codes are "
685
+ f"single-use; run /connect openrouter again for a fresh one.")
686
+