@yahyahammad/venastine 0.2.0 → 0.3.8

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 (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,379 +1,484 @@
1
- """
2
- mcp_client/config.py
3
-
4
- Discovery and merge of `mcp.json`, plus the "seen this user-level server
5
- before" store. ROADMAP_v2 §17.
6
-
7
- Two locations, both resolved at CALL time (not import time) so tests can
8
- redirect them and a moved config dir is picked up without a restart --
9
- the same rule core/config_loader.py and core/workspace_trust.py follow:
10
-
11
- user ~/.config/venastine/mcp.json -- you authored it
12
- project <project>/.venastine/mcp.json -- trust-gated (D17)
13
-
14
- THE PROJECT PATH IS `.venastine/mcp.json`, NOT `<project>/mcp.json`.
15
- §17/D11 put it at the project root to match Claude Code's convention, but
16
- workspace_trust hashes only `.venastine/`, and is_trusted() returns True
17
- outright when that directory is absent. A root-level mcp.json would
18
- therefore have been ungated and its edits would never have re-prompted --
19
- in a file whose whole purpose is naming a local command to execute. Under
20
- `.venastine/` the existing hash, trust prompt and file listing cover it
21
- with no change to workspace_trust.py at all.
22
-
23
- Validation is deliberately by CONNECTION, not by schema (§17 decision G):
24
- unknown keys are ignored so a config pasted from Claude Desktop or Cursor
25
- works, and an entry we cannot make sense of becomes that one server's
26
- named connect failure rather than a startup error for everything else.
27
- """
28
-
29
- import hashlib
30
- import json
31
- import logging
32
- import os
33
- from dataclasses import dataclass, field
34
- from typing import Any, Optional
35
-
36
- from json_store import write_json_atomic
37
-
38
- logger = logging.getLogger(__name__)
39
-
40
- # Keys this harness actually reads. Anything else is ignored, not an
41
- # error -- see the module docstring. Kept as data so the DEBUG log can
42
- # name exactly what it skipped.
43
- _KNOWN_SERVER_KEYS = frozenset({
44
- "command", "args", "env", "cwd", # stdio
45
- "type", "url", "headers", # http
46
- "autoApprove", "auto_approve", # our extension (§17 D)
47
- "disabled",
48
- })
49
-
50
- # Declared `type` values that mean streamable HTTP. `sse` is NOT one of
51
- # them (#62): D4 promises SSE, the SDK v2 ships sse_client for it, and
52
- # aliasing it here is how a server that speaks only SSE got offered a
53
- # streamable handshake it could not answer.
54
- _STREAMABLE_TYPES = frozenset({"http", "https", "streamable-http", "streamablehttp"})
55
- _SSE_TYPES = frozenset({"sse"})
56
-
57
-
58
- @dataclass
59
- class ServerConfig:
60
- """One entry from an mcp.json `mcpServers` object."""
61
- name: str
62
- tier: str # "user" | "project"
63
- path: str # the file it came from
64
- transport: str # "stdio" | "http" | "sse" | "unknown"
65
- command: Optional[str] = None
66
- args: list = field(default_factory=list)
67
- env: dict = field(default_factory=dict)
68
- cwd: Optional[str] = None
69
- url: Optional[str] = None
70
- headers: dict = field(default_factory=dict)
71
- auto_approve: bool = False
72
- disabled: bool = False
73
- raw: dict = field(default_factory=dict)
74
- error: Optional[str] = None # why transport == "unknown"
75
-
76
- def describe(self) -> str:
77
- """One line naming what this server will actually DO -- shown in
78
- the trust prompt and the first-run warning, where 'informed' has
79
- to mean seeing the command, not the server's nickname.
80
-
81
- #60/F1: the fields that change the security posture ride along.
82
- `autoApprove` decides whether any later prompt ever exists, so a
83
- one-`y` acknowledgement that never named it consented blind to
84
- unprompted execution in every future session including all ten
85
- headless research passes. Env is disclosed by KEY NAME only --
86
- printing values would put a credential on the terminal, which is
87
- a different defect. The digest is computed from the raw entry
88
- (entry_digest), never from this text, so improving the disclosure
89
- cannot by itself re-ask an acknowledged server; F3's store bump
90
- is what forces the one re-consent pass.
91
-
92
- VENASTINE_MCP_ACK_FULL=1 (F2) appends the entry verbatim, for
93
- debugging and audits. Read at call time, like every other state
94
- path in this project: it is operator authority, deliberately not
95
- a settings.json key, because settings.json's precedence lets a
96
- project tier style a consent screen this flag renders.
97
- """
98
- if self.transport == "stdio":
99
- argv = " ".join([self.command or ""] + [str(a) for a in self.args])
100
- text = f"{self.name} [{self.tier}] runs: {argv.strip()}"
101
- elif self.transport == "http":
102
- text = f"{self.name} [{self.tier}] connects to: {self.url}"
103
- elif self.transport == "sse":
104
- text = f"{self.name} [{self.tier}] connects via SSE to: {self.url}"
105
- else:
106
- return f"{self.name} [{self.tier}] UNUSABLE: {self.error}"
107
-
108
- notes = []
109
- if self.auto_approve:
110
- notes.append("AUTO-APPROVED: its tools will run without asking")
111
- if self.cwd:
112
- notes.append(f"working directory: {self.cwd}")
113
- if self.disabled:
114
- notes.append("disabled")
115
- if self.env:
116
- notes.append("env keys: " + ", ".join(sorted(self.env)))
117
- if self.headers:
118
- # Same class of surface as env keys, and MORE live since M19
119
- # stopped discarding them: Authorization is where an http/sse
120
- # server's credential actually rides (#60 owner follow-up).
121
- notes.append("header keys: " + ", ".join(sorted(self.headers)))
122
- lines = [text] + [f" {n}" for n in notes]
123
-
124
- if os.environ.get("VENASTINE_MCP_ACK_FULL") == "1":
125
- rendered = json.dumps(self.raw, indent=2, sort_keys=True,
126
- default=str)
127
- lines.append(" full entry:")
128
- lines.extend(f" {l}" for l in rendered.splitlines())
129
- return "\n".join(lines)
130
-
131
-
132
- def user_config_path() -> str:
133
- return os.path.expanduser("~/.config/venastine/mcp.json")
134
-
135
-
136
- def project_config_path(project_path: str) -> str:
137
- return os.path.join(os.path.realpath(project_path), ".venastine", "mcp.json")
138
-
139
-
140
- def _flag(server: str, key: str, value: Any) -> bool:
141
- """A JSON boolean, or False with a warning.
142
-
143
- NOT bool(value): bool("false") is True, so `"autoApprove": "false"`
144
- -- a plausible hand edit, and a shape other MCP hosts tolerate --
145
- would turn the D28 approval gate OFF on a server the user was trying
146
- to keep gated. Failing closed is the only safe direction for both
147
- flags: an unexpectedly-gated server prompts, an unexpectedly-enabled
148
- one runs third-party code unannounced.
149
- """
150
- if isinstance(value, bool):
151
- return value
152
- logger.warning(
153
- "mcp.json server %r: %s must be true or false, got %r; using false.",
154
- server, key, value)
155
- return False
156
-
157
-
158
- def _parse_entry(name: str, entry: Any, tier: str, path: str) -> ServerConfig:
159
- """Turns one raw JSON value into a ServerConfig. Never raises: a bad
160
- entry is returned with transport == 'unknown' and an error string, so
161
- one malformed server cannot stop the others from connecting."""
162
- if not isinstance(entry, dict):
163
- return ServerConfig(name=name, tier=tier, path=path, transport="unknown",
164
- error=f"expected an object, got {type(entry).__name__}")
165
-
166
- unknown = set(entry) - _KNOWN_SERVER_KEYS
167
- if unknown:
168
- # DEBUG, not WARNING: configs shared with other MCP clients carry
169
- # keys we don't implement, and making that noisy on every startup
170
- # trains people to ignore the log.
171
- logger.debug("mcp.json server %r: ignoring unrecognized keys %s",
172
- name, sorted(unknown))
173
-
174
- cfg = ServerConfig(
175
- name=name, tier=tier, path=path, transport="unknown",
176
- env=entry.get("env") or {},
177
- cwd=entry.get("cwd"),
178
- headers=entry.get("headers") or {},
179
- # accept either spelling; ours is camelCase to match the file's
180
- # existing style, but a snake_case one shouldn't silently no-op
181
- auto_approve=_flag(
182
- name, "autoApprove",
183
- entry.get("autoApprove", entry.get("auto_approve", False))),
184
- disabled=_flag(name, "disabled", entry.get("disabled", False)),
185
- raw=entry,
186
- )
187
-
188
- declared = str(entry.get("type") or "").lower()
189
- if entry.get("command"):
190
- raw_args = entry.get("args") or []
191
- if not isinstance(raw_args, list):
192
- # list("--verbose") is ['-', '-', 'v', ...]. A natural hand
193
- # edit therefore became a per-character argv and failed at
194
- # connect with an opaque error naming none of the cause,
195
- # defeating this module's rule that a bad entry becomes that
196
- # one server's NAMED failure.
197
- cfg.error = "'args' must be an array of strings"
198
- return cfg
199
- cfg.transport = "stdio"
200
- cfg.command = str(entry["command"])
201
- cfg.args = list(raw_args)
202
- # SSE only by EXPLICIT declaration (F5): a bare "url" keeps meaning
203
- # streamable HTTP, because that is what every config written before
204
- # this branch existed assumed, and URL sniffing would be magic. The
205
- # aliases below stay streamable; an unsupported declared type still
206
- # refuses rather than falling through to HTTP (#61's M7).
207
- elif entry.get("url") and declared in _SSE_TYPES:
208
- cfg.transport = "sse"
209
- cfg.url = str(entry["url"])
210
- elif entry.get("url") and (not declared or declared in _STREAMABLE_TYPES):
211
- cfg.transport = "http"
212
- cfg.url = str(entry["url"])
213
- elif entry.get("url"):
214
- cfg.error = f"unsupported transport type {declared!r}"
215
- else:
216
- cfg.error = "no 'command' (stdio) and no 'url' (http)"
217
- return cfg
218
-
219
-
220
- def _read_file(path: str, tier: str) -> dict:
221
- """Reads one mcp.json. A missing file is empty, not an error. A
222
- corrupt one is reported and treated as empty -- consistent with G:
223
- it must not take down a session over a file the user may not have
224
- written, and the message names the file."""
225
- if not os.path.exists(path):
226
- return {}
227
- try:
228
- # utf-8-sig: mcp.json is commonly copied between hosts and hand
229
- # edited, so a BOM is realistic and would otherwise be reported as
230
- # invalid JSON at character 0.
231
- with open(path, "r", encoding="utf-8-sig") as f:
232
- data = json.load(f)
233
- except (OSError, ValueError) as e:
234
- logger.warning("Could not read %s-level mcp.json at %s: %s", tier, path, e)
235
- return {}
236
-
237
- servers = data.get("mcpServers") if isinstance(data, dict) else None
238
- if servers is None and isinstance(data, dict):
239
- # Tolerate a bare {"name": {...}} mapping; some tools write it.
240
- servers = {k: v for k, v in data.items() if isinstance(v, dict)}
241
- if not isinstance(servers, dict):
242
- logger.warning("%s-level mcp.json at %s has no 'mcpServers' object; "
243
- "ignoring it.", tier, path)
244
- return {}
245
-
246
- return {name: _parse_entry(name, entry, tier, path)
247
- for name, entry in servers.items()}
248
-
249
-
250
- def load_server_configs(project_path: str, trusted: bool) -> dict:
251
- """All configured servers, keyed by name.
252
-
253
- USER BEATS PROJECT on a name collision (§17 decision H), which is the
254
- OPPOSITE of a plain "more specific wins" rule and deliberately so:
255
- the user tier is what you authored, the project tier is what arrived
256
- with a repo you cloned. A shadowed agent changes a prompt; a shadowed
257
- MCP server changes which local command runs under a name you already
258
- trust. core/config_loader.py's tier order was changed to match, so
259
- agents, skills and MCP servers now all resolve the same way.
260
-
261
- Non-colliding servers from BOTH tiers load -- precedence only ever
262
- breaks same-name ties.
263
-
264
- Project entries are omitted entirely when `trusted` is False. Absent,
265
- not loaded-and-disabled: untrusted content should not be reachable by
266
- a later bug (§14's rule, applied here).
267
- """
268
- merged: dict = {}
269
-
270
- for cfg in _read_file(user_config_path(), "user").values():
271
- merged[cfg.name] = cfg
272
-
273
- if trusted:
274
- for cfg in _read_file(project_config_path(project_path), "project").values():
275
- if cfg.name in merged:
276
- logger.warning(
277
- "project-level MCP server %r at %s is shadowed by the "
278
- "user-level definition at %s, which wins.",
279
- cfg.name, cfg.path, merged[cfg.name].path,
280
- )
281
- continue
282
- merged[cfg.name] = cfg
283
-
284
- return merged
285
-
286
-
287
- # --- first-run acknowledgement for user-level servers (§17 decision I) ----
288
- #
289
- # Project-level servers are covered by D17's trust prompt. User-level ones
290
- # have no gate at all, on the assumption you authored them -- which is
291
- # exactly wrong when an installer or another tool appended to the file.
292
- # Same content-hash keying as workspace_trust, so an edited command
293
- # re-asks rather than inheriting an old acknowledgement.
294
-
295
- def known_servers_path() -> str:
296
- return os.path.expanduser("~/.config/venastine/known_mcp_servers.json")
297
-
298
-
299
- def entry_digest(cfg: ServerConfig) -> str:
300
- """Hash of what the entry will DO. sort_keys so key order in the file
301
- can't produce a different digest for identical configuration."""
302
- return hashlib.sha256(
303
- json.dumps(cfg.raw, sort_keys=True, default=str).encode("utf-8")
304
- ).hexdigest()
305
-
306
-
307
- # v2 (#60/F3): the acknowledgement prompt used to omit autoApprove -- the
308
- # one field that decides whether any future prompt exists -- so consents
309
- # recorded under v1 were given blind. The store carries a version; a
310
- # legacy store's entries are treated as UNKNOWN (one re-ask each, under
311
- # the improved disclosure) and a blind consent never survives the bump.
312
- KNOWN_STORE_VERSION = 2
313
-
314
-
315
- def _read_store() -> tuple:
316
- """(name -> digest mapping, is_legacy). A missing file is empty and
317
- current. An unreadable one fails CLOSED as empty-and-current: every
318
- server then looks new and gets re-confirmed, which is the safe
319
- direction. A readable store in the OLD flat shape is NOT corrupt --
320
- it is valid v1, and comes back marked legacy."""
321
- path = known_servers_path()
322
- if not os.path.exists(path):
323
- return {}, False
324
- try:
325
- with open(path, "r", encoding="utf-8-sig") as f:
326
- data = json.load(f)
327
- except (OSError, ValueError):
328
- logger.warning("Could not read %s; re-confirming every user-level "
329
- "MCP server.", path)
330
- return {}, False
331
- if not isinstance(data, dict):
332
- logger.warning("%s is not an object; re-confirming every "
333
- "user-level MCP server.", path)
334
- return {}, False
335
- if data.get("version") == KNOWN_STORE_VERSION \
336
- and isinstance(data.get("servers"), dict):
337
- return dict(data["servers"]), False
338
- return {k: v for k, v in data.items()
339
- if isinstance(k, str)}, True
340
-
341
-
342
- def is_known(cfg: ServerConfig) -> bool:
343
- """Whether this exact server entry has already been acknowledged.
344
-
345
- Reads the store itself rather than taking one. It used to accept a
346
- pre-read `store=` for callers batching several checks, and no caller
347
- ever passed one -- so the branch was dead while the parameter went on
348
- advertising an optimisation nobody could see was unused.
349
- """
350
- servers, legacy = _read_store()
351
- # F3: a v1 consent was given under a prompt that never named the
352
- # field it most needed to name. It does not count.
353
- if legacy:
354
- return False
355
- return servers.get(cfg.name) == entry_digest(cfg)
356
-
357
-
358
- def remember_server(cfg: ServerConfig) -> None:
359
- path = known_servers_path()
360
- servers, legacy = _read_store()
361
- if legacy:
362
- # Carrying the old digests forward would silently convert blind
363
- # consents into disclosed ones for servers this session never
364
- # re-asked. They start over; answering y here records THIS server
365
- # only, and the others keep asking until they are answered.
366
- servers = {}
367
- servers[cfg.name] = entry_digest(cfg)
368
- # ATOMIC since batch 45, and this was the odd one out. Its three
369
- # sibling stores each wrote through a temp file and os.replace, and
370
- # each spent four to eight docstring lines on why -- a
371
- # truncate-then-write leaves the file empty for the length of the
372
- # write and permanently damaged if the process dies inside it. This
373
- # one used a bare open(path, "w") and said nothing, for a file that
374
- # records CONSENT: the same class of data as the trust store, which
375
- # is the sibling that argues hardest for the guarantee. Sharing the
376
- # write is what stops a convention four comments long from having a
377
- # fourth copy that does not follow it.
378
- write_json_atomic(path, {"version": KNOWN_STORE_VERSION,
379
- "servers": servers})
1
+ """
2
+ mcp_client/config.py
3
+
4
+ Discovery and merge of `mcp.json`, plus the "seen this user-level server
5
+ before" store. ROADMAP_v2 §17.
6
+
7
+ Two locations, both resolved at CALL time (not import time) so tests can
8
+ redirect them and a moved config dir is picked up without a restart --
9
+ the same rule core/config_loader.py and core/workspace_trust.py follow:
10
+
11
+ user ~/.config/venastine/mcp.json -- you authored it
12
+ project <project>/.venastine/mcp.json -- trust-gated (D17)
13
+
14
+ THE USER ONE IS CREATED EMPTY AT STARTUP IF IT IS ABSENT (batch 121,
15
+ owner request). "You authored it" was doing double duty: it is the
16
+ security argument for why that tier needs no trust prompt, and it was
17
+ also the reason nothing ever created the file -- which left the path
18
+ discoverable only from this docstring. Two plausible homes (the harness
19
+ root, and here) and no way to tell from inside a session means an edit
20
+ goes into a file nothing reads. See ensure_user_config.
21
+
22
+ THE PROJECT PATH IS `.venastine/mcp.json`, NOT `<project>/mcp.json`.
23
+ §17/D11 put it at the project root to match Claude Code's convention, but
24
+ workspace_trust hashes only `.venastine/`, and is_trusted() returns True
25
+ outright when that directory is absent. A root-level mcp.json would
26
+ therefore have been ungated and its edits would never have re-prompted --
27
+ in a file whose whole purpose is naming a local command to execute. Under
28
+ `.venastine/` the existing hash, trust prompt and file listing cover it
29
+ with no change to workspace_trust.py at all.
30
+
31
+ Validation is deliberately by CONNECTION, not by schema (§17 decision G):
32
+ unknown keys are ignored so a config pasted from Claude Desktop or Cursor
33
+ works, and an entry we cannot make sense of becomes that one server's
34
+ named connect failure rather than a startup error for everything else.
35
+ """
36
+
37
+ import hashlib
38
+ import json
39
+ import logging
40
+ import os
41
+ from dataclasses import dataclass, field
42
+ from typing import Any, Optional
43
+
44
+ from json_store import read_regular_text, write_json_atomic
45
+
46
+ logger = logging.getLogger(__name__)
47
+
48
+ # Keys this harness actually reads. Anything else is ignored, not an
49
+ # error -- see the module docstring. Kept as data so the DEBUG log can
50
+ # name exactly what it skipped.
51
+ _KNOWN_SERVER_KEYS = frozenset({
52
+ "command", "args", "env", "cwd", # stdio
53
+ "type", "url", "headers", # http
54
+ "autoApprove", "auto_approve", # our extension (§17 D)
55
+ "disabled",
56
+ })
57
+
58
+ # Declared `type` values that mean streamable HTTP. `sse` is NOT one of
59
+ # them (#62): D4 promises SSE, the SDK v2 ships sse_client for it, and
60
+ # aliasing it here is how a server that speaks only SSE got offered a
61
+ # streamable handshake it could not answer.
62
+ _STREAMABLE_TYPES = frozenset({"http", "https", "streamable-http", "streamablehttp"})
63
+ _SSE_TYPES = frozenset({"sse"})
64
+
65
+
66
+ @dataclass
67
+ class ServerConfig:
68
+ """One entry from an mcp.json `mcpServers` object."""
69
+ name: str
70
+ tier: str # "user" | "project"
71
+ path: str # the file it came from
72
+ transport: str # "stdio" | "http" | "sse" | "unknown"
73
+ command: Optional[str] = None
74
+ args: list = field(default_factory=list)
75
+ env: dict = field(default_factory=dict)
76
+ cwd: Optional[str] = None
77
+ url: Optional[str] = None
78
+ headers: dict = field(default_factory=dict)
79
+ auto_approve: bool = False
80
+ disabled: bool = False
81
+ raw: dict = field(default_factory=dict)
82
+ error: Optional[str] = None # why transport == "unknown"
83
+
84
+ def describe(self) -> str:
85
+ """One line naming what this server will actually DO -- shown in
86
+ the trust prompt and the first-run warning, where 'informed' has
87
+ to mean seeing the command, not the server's nickname.
88
+
89
+ #60/F1: the fields that change the security posture ride along.
90
+ `autoApprove` decides whether any later prompt ever exists, so a
91
+ one-`y` acknowledgement that never named it consented blind to
92
+ unprompted execution in every future session including all ten
93
+ headless research passes. Env is disclosed by KEY NAME only --
94
+ printing values would put a credential on the terminal, which is
95
+ a different defect. The digest is computed from the raw entry
96
+ (entry_digest), never from this text, so improving the disclosure
97
+ cannot by itself re-ask an acknowledged server; F3's store bump
98
+ is what forces the one re-consent pass.
99
+
100
+ VENASTINE_MCP_ACK_FULL=1 (F2) appends the entry verbatim, for
101
+ debugging and audits. Read at call time, like every other state
102
+ path in this project: it is operator authority, deliberately not
103
+ a settings.json key, because settings.json's precedence lets a
104
+ project tier style a consent screen this flag renders.
105
+ """
106
+ if self.transport == "stdio":
107
+ argv = " ".join([self.command or ""] + [str(a) for a in self.args])
108
+ text = f"{self.name} [{self.tier}] runs: {argv.strip()}"
109
+ elif self.transport == "http":
110
+ text = f"{self.name} [{self.tier}] connects to: {self.url}"
111
+ elif self.transport == "sse":
112
+ text = f"{self.name} [{self.tier}] connects via SSE to: {self.url}"
113
+ else:
114
+ return f"{self.name} [{self.tier}] UNUSABLE: {self.error}"
115
+
116
+ notes = []
117
+ if self.auto_approve:
118
+ notes.append("AUTO-APPROVED: its tools will run without asking")
119
+ if self.cwd:
120
+ notes.append(f"working directory: {self.cwd}")
121
+ if self.disabled:
122
+ notes.append("disabled")
123
+ if self.env:
124
+ notes.append("env keys: " + ", ".join(sorted(self.env)))
125
+ if self.headers:
126
+ # Same class of surface as env keys, and MORE live since M19
127
+ # stopped discarding them: Authorization is where an http/sse
128
+ # server's credential actually rides (#60 owner follow-up).
129
+ notes.append("header keys: " + ", ".join(sorted(self.headers)))
130
+ lines = [text] + [f" {n}" for n in notes]
131
+
132
+ if os.environ.get("VENASTINE_MCP_ACK_FULL") == "1":
133
+ rendered = json.dumps(self.raw, indent=2, sort_keys=True,
134
+ default=str)
135
+ lines.append(" full entry:")
136
+ lines.extend(f" {line}" for line in rendered.splitlines())
137
+ return "\n".join(lines)
138
+
139
+
140
+ def user_config_path() -> str:
141
+ return os.path.expanduser("~/.config/venastine/mcp.json")
142
+
143
+
144
+ def project_config_path(project_path: str) -> str:
145
+ return os.path.join(os.path.realpath(project_path), ".venastine", "mcp.json")
146
+
147
+
148
+ def ensure_user_config() -> Optional[str]:
149
+ """Create the user-level mcp.json if absent. Returns the path, or None.
150
+
151
+ Batch 121, owner request: "users don't know whether user-level
152
+ mcp.json is at the harness root or ~/.config/venastine". A file that
153
+ exists answers that; a docstring does not.
154
+
155
+ BEHAVIOUR-NEUTRAL BY CONSTRUCTION. `{"mcpServers": {}}` loads as zero
156
+ servers, and it is the one shape _read_file does not warn about -- an
157
+ empty `{}` trips its "no 'mcpServers' object" branch, so the obvious
158
+ seed would have printed a warning about the harness's own file at
159
+ every launch. The skeleton comes from §24's render_mcp() rather than
160
+ being retyped here, so the two tiers cannot drift.
161
+
162
+ NEVER OVERWRITES, and the check is existence rather than content: a
163
+ file someone emptied by hand is still their file.
164
+
165
+ An OSError is a DEBUG line and None. A read-only config directory is
166
+ a reason not to have the convenience, not a reason not to start --
167
+ every other store in that directory fails the same way, except the
168
+ trust store, which raises because a security decision that silently
169
+ did not persist is worse than a crash. This is not one of those.
170
+
171
+ mode=0o600 like its two siblings there: the entries can carry an
172
+ Authorization header, and on the temp file rather than the
173
+ destination because os.replace carries the source's mode across
174
+ (#19). trailing_newline because a human edits this one -- §24's
175
+ scaffold passes it for exactly that reason.
176
+ """
177
+ from project_init.config_files import render_mcp
178
+
179
+ path = user_config_path()
180
+ if os.path.exists(path):
181
+ return None
182
+ try:
183
+ write_json_atomic(path, render_mcp(), mode=0o600,
184
+ trailing_newline=True)
185
+ except OSError as e:
186
+ logger.debug("Could not create %s: %s", path, e)
187
+ return None
188
+ logger.info("Created user-level mcp.json at %s", path)
189
+ return path
190
+
191
+
192
+ def _flag(server: str, key: str, value: Any,
193
+ consequence: str) -> Optional[bool]:
194
+ """A JSON boolean, or None with a warning naming the consequence.
195
+
196
+ NOT bool(value): bool("false") is True, so `"autoApprove": "false"`
197
+ -- a plausible hand edit, and a shape other MCP hosts tolerate --
198
+ would turn the D28 approval gate OFF on a server the user was trying
199
+ to keep gated.
200
+
201
+ WHAT IT DOES NOT DO ANY MORE IS CHOOSE THE ANSWER (batch 150). It
202
+ used to return False for both keys and say that failing closed was
203
+ "the only safe direction for both flags: an unexpectedly-gated server
204
+ prompts, an unexpectedly-enabled one runs third-party code
205
+ unannounced". That is true of `autoApprove` and backwards for
206
+ `disabled`, where False means NOT disabled -- so the sentence's own
207
+ second clause was the outcome it produced: `"disabled": "true"` ran
208
+ the server, and F1's consent line, which reads self.disabled, showed
209
+ it as live.
210
+
211
+ AND NEITHER CONSTANT IS SAFE FOR `disabled`, which is why this
212
+ function no longer picks one. The two plausible misspellings want
213
+ opposite answers -- `"true"` means stop and `"false"` means run --
214
+ and the only thing that distinguishes them is the value, which this
215
+ function exists to refuse to interpret. So the caller decides, and
216
+ for `disabled` the decision is the one this module already makes for
217
+ an entry it cannot make sense of: that one server's NAMED failure
218
+ (decision G). `tests/test_mcp_config.py` pins both directions.
219
+ """
220
+ if isinstance(value, bool):
221
+ return value
222
+ logger.warning(
223
+ "mcp.json server %r: %s must be true or false, got %r; %s.",
224
+ server, key, value, consequence)
225
+ return None
226
+
227
+
228
+ def _parse_entry(name: str, entry: Any, tier: str, path: str) -> ServerConfig:
229
+ """Turns one raw JSON value into a ServerConfig. Never raises: a bad
230
+ entry is returned with transport == 'unknown' and an error string, so
231
+ one malformed server cannot stop the others from connecting."""
232
+ if not isinstance(entry, dict):
233
+ return ServerConfig(name=name, tier=tier, path=path, transport="unknown",
234
+ error=f"expected an object, got {type(entry).__name__}")
235
+
236
+ unknown = set(entry) - _KNOWN_SERVER_KEYS
237
+ if unknown:
238
+ # DEBUG, not WARNING: configs shared with other MCP clients carry
239
+ # keys we don't implement, and making that noisy on every startup
240
+ # trains people to ignore the log.
241
+ logger.debug("mcp.json server %r: ignoring unrecognized keys %s",
242
+ name, sorted(unknown))
243
+
244
+ # accept either spelling; ours is camelCase to match the file's
245
+ # existing style, but a snake_case one shouldn't silently no-op
246
+ auto_approve = _flag(
247
+ name, "autoApprove",
248
+ entry.get("autoApprove", entry.get("auto_approve", False)),
249
+ "gating its tools, which is this flag's safe answer either way")
250
+ disabled = _flag(
251
+ name, "disabled", entry.get("disabled", False),
252
+ "refusing the entry by name, because neither answer is safe for "
253
+ "this flag")
254
+
255
+ cfg = ServerConfig(
256
+ name=name, tier=tier, path=path, transport="unknown",
257
+ env=entry.get("env") or {},
258
+ cwd=entry.get("cwd"),
259
+ headers=entry.get("headers") or {},
260
+ auto_approve=bool(auto_approve),
261
+ disabled=bool(disabled),
262
+ raw=entry,
263
+ )
264
+
265
+ if disabled is None:
266
+ # A NAMED FAILURE, not a chosen answer (batch 150). `False` ran a
267
+ # server the operator had written a key to stop, and `True` would
268
+ # skip one they had written a key to keep -- which was a defect
269
+ # this file's tests had already been written for once, under the
270
+ # name "the mirror defect". Both directions are pinned now by
271
+ # TestAnUnparseableDisabledIsANamedFailure, whose docstring
272
+ # records why the older test was replaced rather than kept green:
273
+ # it asserted `disabled is False`, which is STILL true here and no
274
+ # longer means the server runs.
275
+ # So the entry becomes unusable the same way a bad `args` does:
276
+ # transport stays 'unknown', describe() prints
277
+ # "UNUSABLE: 'disabled' must be true or false" on the
278
+ # acknowledgement screen, _transport_for raises so the server
279
+ # lands in failures by name, and main.py prints it. Nothing runs
280
+ # and nothing is silent, which is the only pair of properties
281
+ # both spellings can have at once. One edit fixes it.
282
+ cfg.error = "'disabled' must be true or false"
283
+ return cfg
284
+
285
+ declared = str(entry.get("type") or "").lower()
286
+ if entry.get("command"):
287
+ raw_args = entry.get("args") or []
288
+ if not isinstance(raw_args, list):
289
+ # list("--verbose") is ['-', '-', 'v', ...]. A natural hand
290
+ # edit therefore became a per-character argv and failed at
291
+ # connect with an opaque error naming none of the cause,
292
+ # defeating this module's rule that a bad entry becomes that
293
+ # one server's NAMED failure.
294
+ cfg.error = "'args' must be an array of strings"
295
+ return cfg
296
+ cfg.transport = "stdio"
297
+ cfg.command = str(entry["command"])
298
+ cfg.args = list(raw_args)
299
+ # SSE only by EXPLICIT declaration (F5): a bare "url" keeps meaning
300
+ # streamable HTTP, because that is what every config written before
301
+ # this branch existed assumed, and URL sniffing would be magic. The
302
+ # aliases below stay streamable; an unsupported declared type still
303
+ # refuses rather than falling through to HTTP (#61's M7).
304
+ elif entry.get("url") and declared in _SSE_TYPES:
305
+ cfg.transport = "sse"
306
+ cfg.url = str(entry["url"])
307
+ elif entry.get("url") and (not declared or declared in _STREAMABLE_TYPES):
308
+ cfg.transport = "http"
309
+ cfg.url = str(entry["url"])
310
+ elif entry.get("url"):
311
+ cfg.error = f"unsupported transport type {declared!r}"
312
+ else:
313
+ cfg.error = "no 'command' (stdio) and no 'url' (http)"
314
+ return cfg
315
+
316
+
317
+ def _read_file(path: str, tier: str) -> dict:
318
+ """Reads one mcp.json. A missing file is empty, not an error. A
319
+ corrupt one is reported and treated as empty -- consistent with G:
320
+ it must not take down a session over a file the user may not have
321
+ written, and the message names the file."""
322
+ if not os.path.exists(path):
323
+ return {}
324
+ try:
325
+ # utf-8-sig: mcp.json is commonly copied between hosts and hand
326
+ # edited, so a BOM is realistic and would otherwise be reported as
327
+ # invalid JSON at character 0. Regular files only (batch 219, #214):
328
+ # the project tier's copy arrives with a clone, and one linked to
329
+ # /dev/zero would be read until memory ran out.
330
+ data = json.loads(read_regular_text(path))
331
+ except (OSError, ValueError) as e:
332
+ logger.warning("Could not read %s-level mcp.json at %s: %s", tier, path, e)
333
+ return {}
334
+
335
+ servers = data.get("mcpServers") if isinstance(data, dict) else None
336
+ if servers is None and isinstance(data, dict):
337
+ # Tolerate a bare {"name": {...}} mapping; some tools write it.
338
+ servers = {k: v for k, v in data.items() if isinstance(v, dict)}
339
+ if not isinstance(servers, dict):
340
+ logger.warning("%s-level mcp.json at %s has no 'mcpServers' object; "
341
+ "ignoring it.", tier, path)
342
+ return {}
343
+
344
+ return {name: _parse_entry(name, entry, tier, path)
345
+ for name, entry in servers.items()}
346
+
347
+
348
+ def load_server_configs(project_path: str, trusted: bool) -> dict:
349
+ """All configured servers, keyed by name.
350
+
351
+ USER BEATS PROJECT on a name collision (§17 decision H), which is the
352
+ OPPOSITE of a plain "more specific wins" rule and deliberately so:
353
+ the user tier is what you authored, the project tier is what arrived
354
+ with a repo you cloned. A shadowed agent changes a prompt; a shadowed
355
+ MCP server changes which local command runs under a name you already
356
+ trust. core/config_loader.py's tier order was changed to match, so
357
+ agents, skills and MCP servers now all resolve the same way.
358
+
359
+ Non-colliding servers from BOTH tiers load -- precedence only ever
360
+ breaks same-name ties.
361
+
362
+ Project entries are omitted entirely when `trusted` is False. Absent,
363
+ not loaded-and-disabled: untrusted content should not be reachable by
364
+ a later bug (§14's rule, applied here).
365
+ """
366
+ merged: dict = {}
367
+
368
+ for cfg in _read_file(user_config_path(), "user").values():
369
+ merged[cfg.name] = cfg
370
+
371
+ if trusted:
372
+ for cfg in _read_file(project_config_path(project_path), "project").values():
373
+ if cfg.name in merged:
374
+ logger.warning(
375
+ "project-level MCP server %r at %s is shadowed by the "
376
+ "user-level definition at %s, which wins.",
377
+ cfg.name, cfg.path, merged[cfg.name].path,
378
+ )
379
+ continue
380
+ merged[cfg.name] = cfg
381
+
382
+ return merged
383
+
384
+
385
+ # --- first-run acknowledgement for user-level servers (§17 decision I) ----
386
+ #
387
+ # Project-level servers are covered by D17's trust prompt. User-level ones
388
+ # have no gate at all, on the assumption you authored them -- which is
389
+ # exactly wrong when an installer or another tool appended to the file.
390
+ # Same content-hash keying as workspace_trust, so an edited command
391
+ # re-asks rather than inheriting an old acknowledgement.
392
+
393
+ def known_servers_path() -> str:
394
+ return os.path.expanduser("~/.config/venastine/known_mcp_servers.json")
395
+
396
+
397
+ def entry_digest(cfg: ServerConfig) -> str:
398
+ """Hash of what the entry will DO. sort_keys so key order in the file
399
+ can't produce a different digest for identical configuration."""
400
+ return hashlib.sha256(
401
+ json.dumps(cfg.raw, sort_keys=True, default=str).encode("utf-8")
402
+ ).hexdigest()
403
+
404
+
405
+ # v2 (#60/F3): the acknowledgement prompt used to omit autoApprove -- the
406
+ # one field that decides whether any future prompt exists -- so consents
407
+ # recorded under v1 were given blind. The store carries a version; a
408
+ # legacy store's entries are treated as UNKNOWN (one re-ask each, under
409
+ # the improved disclosure) and a blind consent never survives the bump.
410
+ KNOWN_STORE_VERSION = 2
411
+
412
+
413
+ def _read_store() -> tuple:
414
+ """(name -> digest mapping, is_legacy). A missing file is empty and
415
+ current. An unreadable one fails CLOSED as empty-and-current: every
416
+ server then looks new and gets re-confirmed, which is the safe
417
+ direction. A readable store in the OLD flat shape is NOT corrupt --
418
+ it is valid v1, and comes back marked legacy."""
419
+ path = known_servers_path()
420
+ if not os.path.exists(path):
421
+ return {}, False
422
+ try:
423
+ with open(path, encoding="utf-8-sig") as f:
424
+ data = json.load(f)
425
+ except (OSError, ValueError):
426
+ logger.warning("Could not read %s; re-confirming every user-level "
427
+ "MCP server.", path)
428
+ return {}, False
429
+ if not isinstance(data, dict):
430
+ logger.warning("%s is not an object; re-confirming every "
431
+ "user-level MCP server.", path)
432
+ return {}, False
433
+ if data.get("version") == KNOWN_STORE_VERSION \
434
+ and isinstance(data.get("servers"), dict):
435
+ return dict(data["servers"]), False
436
+ return {k: v for k, v in data.items()
437
+ if isinstance(k, str)}, True
438
+
439
+
440
+ def is_known(cfg: ServerConfig) -> bool:
441
+ """Whether this exact server entry has already been acknowledged.
442
+
443
+ Reads the store itself rather than taking one. It used to accept a
444
+ pre-read `store=` for callers batching several checks, and no caller
445
+ ever passed one -- so the branch was dead while the parameter went on
446
+ advertising an optimisation nobody could see was unused.
447
+ """
448
+ servers, legacy = _read_store()
449
+ # F3: a v1 consent was given under a prompt that never named the
450
+ # field it most needed to name. It does not count.
451
+ if legacy:
452
+ return False
453
+ return servers.get(cfg.name) == entry_digest(cfg)
454
+
455
+
456
+ def remember_server(cfg: ServerConfig) -> None:
457
+ path = known_servers_path()
458
+ servers, legacy = _read_store()
459
+ if legacy:
460
+ # Carrying the old digests forward would silently convert blind
461
+ # consents into disclosed ones for servers this session never
462
+ # re-asked. They start over; answering y here records THIS server
463
+ # only, and the others keep asking until they are answered.
464
+ servers = {}
465
+ servers[cfg.name] = entry_digest(cfg)
466
+ # ATOMIC since batch 45, and this was the odd one out. Its three
467
+ # sibling stores each wrote through a temp file and os.replace, and
468
+ # each spent four to eight docstring lines on why -- a
469
+ # truncate-then-write leaves the file empty for the length of the
470
+ # write and permanently damaged if the process dies inside it. This
471
+ # one used a bare open(path, "w") and said nothing, for a file that
472
+ # records CONSENT: the same class of data as the trust store, which
473
+ # is the sibling that argues hardest for the guarantee. Sharing the
474
+ # write is what stops a convention four comments long from having a
475
+ # fourth copy that does not follow it.
476
+ #
477
+ # AND ITS MODE, since batch 170: 0o600, as the trust store has. Without
478
+ # one this took open()'s 0o666 less the umask, so under a umask of 002
479
+ # anyone in the user's group could write a consent here and a server
480
+ # would start without asking. Found by triaging CodeQL's alert on
481
+ # json_store's default mode; the default itself is right for the files
482
+ # the agent writes in a workspace.
483
+ write_json_atomic(path, {"version": KNOWN_STORE_VERSION,
484
+ "servers": servers}, mode=0o600)