witan-code 0.12.1__tar.gz → 0.12.3__tar.gz

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 (99) hide show
  1. {witan_code-0.12.1 → witan_code-0.12.3}/CHANGELOG.md +52 -0
  2. {witan_code-0.12.1 → witan_code-0.12.3}/PKG-INFO +2 -2
  3. {witan_code-0.12.1 → witan_code-0.12.3}/pyproject.toml +15 -11
  4. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_remote_proxy.py +69 -0
  5. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_remote_store.py +201 -0
  6. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/cli.py +28 -1
  7. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/remote/proxy.py +32 -2
  8. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/remote/store.py +125 -21
  9. {witan_code-0.12.1 → witan_code-0.12.3}/.gitignore +0 -0
  10. {witan_code-0.12.1 → witan_code-0.12.3}/README.md +0 -0
  11. {witan_code-0.12.1 → witan_code-0.12.3}/config/claude.json +0 -0
  12. {witan_code-0.12.1 → witan_code-0.12.3}/config/copilot.json +0 -0
  13. {witan_code-0.12.1 → witan_code-0.12.3}/config/pi.json +0 -0
  14. {witan_code-0.12.1 → witan_code-0.12.3}/docs/BRANCH_INDEXING.md +0 -0
  15. {witan_code-0.12.1 → witan_code-0.12.3}/docs/CLI_REFERENCE.md +0 -0
  16. {witan_code-0.12.1 → witan_code-0.12.3}/docs/EDGE_PRECISION_TIERS.md +0 -0
  17. {witan_code-0.12.1 → witan_code-0.12.3}/docs/PACKAGE_MAP.md +0 -0
  18. {witan_code-0.12.1 → witan_code-0.12.3}/docs/STAGE2_STITCHING.md +0 -0
  19. {witan_code-0.12.1 → witan_code-0.12.3}/docs/SYMBOL_FORMAT.md +0 -0
  20. {witan_code-0.12.1 → witan_code-0.12.3}/docs/SYMBOL_TABLE.md +0 -0
  21. {witan_code-0.12.1 → witan_code-0.12.3}/docs/USER_GUIDE.md +0 -0
  22. {witan_code-0.12.1 → witan_code-0.12.3}/install.sh +0 -0
  23. {witan_code-0.12.1 → witan_code-0.12.3}/tests/__init__.py +0 -0
  24. {witan_code-0.12.1 → witan_code-0.12.3}/tests/conftest.py +0 -0
  25. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_batched_deletes.py +0 -0
  26. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_branches.py +0 -0
  27. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_bridge.py +0 -0
  28. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_chunked_load.py +0 -0
  29. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_cli_dispatch.py +0 -0
  30. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_cli_hooks.py +0 -0
  31. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_cli_output_format.py +0 -0
  32. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_config.py +0 -0
  33. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_config_targets.py +0 -0
  34. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_context.py +0 -0
  35. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_crossrepo.py +0 -0
  36. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_edges.py +0 -0
  37. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_elicit.py +0 -0
  38. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_enrichment.py +0 -0
  39. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_github_app.py +0 -0
  40. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_graph.py +0 -0
  41. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_hooks.py +0 -0
  42. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_identity.py +0 -0
  43. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_indexer.py +0 -0
  44. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_indexer_scope.py +0 -0
  45. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_ingest.py +0 -0
  46. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_languages.py +0 -0
  47. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_maintenance.py +0 -0
  48. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_package_map.py +0 -0
  49. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_reaper.py +0 -0
  50. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_repo.py +0 -0
  51. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_server.py +0 -0
  52. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_setup.py +0 -0
  53. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_stitch.py +0 -0
  54. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_store.py +0 -0
  55. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_symbol_table.py +0 -0
  56. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_tasks.py +0 -0
  57. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_views.py +0 -0
  58. {witan_code-0.12.1 → witan_code-0.12.3}/tests/test_visualize.py +0 -0
  59. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/__init__.py +0 -0
  60. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/__main__.py +0 -0
  61. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/bridge.py +0 -0
  62. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/bridge_extractors.py +0 -0
  63. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/config.py +0 -0
  64. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/context.py +0 -0
  65. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/edges.py +0 -0
  66. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/elicit.py +0 -0
  67. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/extensions/pi/codegraph.ts +0 -0
  68. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/github_app.py +0 -0
  69. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/graph.py +0 -0
  70. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/hooks.py +0 -0
  71. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/identity.py +0 -0
  72. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/indexer.py +0 -0
  73. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/ingest.py +0 -0
  74. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/maintenance.py +0 -0
  75. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/output.py +0 -0
  76. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/package_map.py +0 -0
  77. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries/bridge.gq +0 -0
  78. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries/code_mutations.gq +0 -0
  79. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries/code_read.gq +0 -0
  80. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries/delete.gq +0 -0
  81. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries_ts/bash.scm +0 -0
  82. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries_ts/hcl.scm +0 -0
  83. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries_ts/python.scm +0 -0
  84. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries_ts/sql.scm +0 -0
  85. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries_ts/typescript.scm +0 -0
  86. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/queries_ts/yaml.scm +0 -0
  87. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/reaper.py +0 -0
  88. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/remote/__init__.py +0 -0
  89. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/remote/oidc.py +0 -0
  90. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/repo.py +0 -0
  91. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/schema/bridge-schema.pg +0 -0
  92. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/schema/code-schema.pg +0 -0
  93. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/server.py +0 -0
  94. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/setup.py +0 -0
  95. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/skills/witan-code/SKILL.md +0 -0
  96. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/stitch.py +0 -0
  97. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/store.py +0 -0
  98. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/views.py +0 -0
  99. {witan_code-0.12.1 → witan_code-0.12.3}/witan_code/visualize.py +0 -0
@@ -6,6 +6,58 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
7
7
  a MINOR bump may include breaking changes).
8
8
 
9
+ ## [0.12.3] - 2026-08-07
10
+
11
+ ### Fixed
12
+
13
+ - A server-side tool error against the deployed cluster reads as a sentence
14
+ rather than a traceback. `witan-code`'s entrypoint already classified the
15
+ four remote failures the `witan` CLI does, but a tool that ran and *refused* —
16
+ a Cedar denial on a code graph the caller may not read, a branch the cluster
17
+ does not have — came back as `fastmcp.exceptions.ToolError`, which is not a
18
+ `RuntimeError` and so escaped as a traceback out of `witan-code symbols`.
19
+ - ★ Fixed on **both** of this package's transports, not just the proxy.
20
+ Index and write commands reach the deployment through `StoreRef.client()` and
21
+ `StoreSession`, which holds its own connection and does its own
22
+ classification — so classifying in `RemoteMCPProxy` alone would have left
23
+ every refusal on the store path escaping exactly as before. `StoreSession.call`
24
+ now raises `RemoteToolFailed` on both of its arms: the first attempt, and the
25
+ re-invoke after a reconnect, so a refusal that happens to follow a dropped
26
+ socket is not left as the one uncovered case.
27
+
28
+ ### Changed
29
+
30
+ - Floor bumped to `witan-core>=0.14` for `remote.proxy.RemoteToolFailed`, which
31
+ `witan_code/remote/proxy.py` re-exports at module scope. Bumped in the same
32
+ change that adds the caller, per the pin comment.
33
+
34
+ ## [0.12.2] - 2026-08-07
35
+
36
+ ### Fixed
37
+
38
+ - An oversized index batch is refused **once**, as a sentence, instead of being
39
+ retried and then raising a traceback. A direct 413 is an httpx error, so
40
+ `StoreSession.call`'s generic arm read it as a dropped socket and did what it
41
+ does for one: reconnect and send the same multi-MiB body again, to be refused
42
+ identically. Retrying cannot help — the payload is the thing being rejected.
43
+ Both faces of a 413 are now classified: relayed through the vMCP as a
44
+ `ToolError`, and direct as an httpx status error.
45
+ - The refusal message is per-operation rather than one claim for all of them.
46
+ Every store call comes through one helper, but most are not chunked loads:
47
+ reads, `code_store_views`, and single mutations carry no byte budget and apply
48
+ nothing incrementally; `load(mode="overwrite")` is sent whole and cannot be
49
+ chunked at all; `change_many` chunks by statement COUNT, so `chunk_size` is
50
+ its knob and no byte budget bounds it. A chunked `load` reports the budget
51
+ actually in play — `max_bytes` comes from the caller, so a hardcoded "2 MiB"
52
+ was wrong for any non-default — plus which batch was refused and how many
53
+ already landed.
54
+
55
+ ### Changed
56
+
57
+ - `witan-core` floor raised to `>=0.12` for `RemotePayloadTooLarge` /
58
+ `payload_too_large`, imported at module scope in `remote/store.py`. Third time
59
+ this floor has been tripped; the pin comment now says so.
60
+
9
61
  ## [0.12.1] - 2026-08-07
10
62
 
11
63
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: witan-code
3
- Version: 0.12.1
3
+ Version: 0.12.3
4
4
  Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
5
  Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
6
  Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -26,7 +26,7 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
26
26
  Requires-Dist: tree-sitter-typescript<0.24,>=0.23
27
27
  Requires-Dist: tree-sitter-yaml<0.8,>=0.7
28
28
  Requires-Dist: tree-sitter<0.26,>=0.25
29
- Requires-Dist: witan-core[cli,observability,remote]<1,>=0.11
29
+ Requires-Dist: witan-core[cli,observability,remote]<1,>=0.14
30
30
  Provides-Extra: tasks
31
31
  Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
32
32
  Description-Content-Type: text/markdown
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "witan-code"
3
- version = "0.12.1"
3
+ version = "0.12.3"
4
4
  description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
5
5
  readme = "README.md"
6
6
  license = "BSD-3-Clause"
@@ -15,16 +15,20 @@ dependencies = [
15
15
  # proxy) behind `witan-code login` and the read commands' remote mode.
16
16
  # Costs nothing extra in practice — fastmcp is already required here and
17
17
  # itself depends on httpx2, the extra's only other dependency.
18
- # >=0.11: remote/store.py evaluates witan_core.chunking.MCP_LOAD_MAX_BYTES
19
- # as a default argument — so it resolves at import time, and 0.10 does not
20
- # export it. A looser floor lets an external install resolve a witan-core
21
- # the server cannot even import; that is what this pin is for, and it has
22
- # now been tripped twice.
23
- # (>=0.10 was already required for witan_core.chunking + load_batch, both
24
- # moved up from this package; >=0.9 for observability.middleware; >=0.8 for
25
- # OmnigraphClient.change_many with chunk_size on the batched reindex
26
- # deletes.)
27
- "witan-core[cli,remote,observability]>=0.11,<1",
18
+ # >=0.12: remote/store.py imports RemotePayloadTooLarge and
19
+ # payload_too_large from witan_core.remote.proxy at module scope, and 0.11
20
+ # exports neither. A looser floor lets an external install resolve a
21
+ # witan-core the server cannot even import; that is what this pin is for,
22
+ # and it has now been tripped THREE times. If you add a witan_core symbol in
23
+ # the same change as its caller, bump this line in that change: the
24
+ # workspace resolves witan-core by path, so nothing here can catch it.
25
+ # (>=0.14 was required for remote.proxy.RemoteToolFailed, re-exported at
26
+ # module scope by witan_code/remote/proxy.py and named by cli.py's cli();
27
+ # >=0.11 for chunking.MCP_LOAD_MAX_BYTES, evaluated as a default argument;
28
+ # >=0.10 for witan_core.chunking + load_batch, both moved up from this
29
+ # package; >=0.9 for observability.middleware; >=0.8 for
30
+ # OmnigraphClient.change_many with chunk_size.)
31
+ "witan-core[cli,remote,observability]>=0.14,<1",
28
32
  "fastmcp>=3.4.2,<5",
29
33
  "cyclopts>=4,<5",
30
34
  # [targets.<name>] override models (config.py) — also transitively pulled
@@ -173,3 +173,72 @@ def test_srv_is_the_server_module_by_default(monkeypatch, tmp_path):
173
173
  assert cli_module._srv() is server_module
174
174
  assert cli_module._is_remote() is False
175
175
  cli_module._server = None
176
+
177
+
178
+ # ── an unreachable deployment ─────────────────────────────────────────────
179
+ # The classification itself is pinned in witan-core; what witan-code owns is
180
+ # the wording, and the fact that `cli()` guards at all — it had no try/except,
181
+ # so a deployment that was down printed a traceback out of `witan-code symbols`.
182
+
183
+
184
+ def _dead(**cfg_kwargs) -> str:
185
+ cfg = RemoteConfig(
186
+ url="https://witan.example.org/mcp",
187
+ oidc_issuer="https://sso/realms/ol",
188
+ **cfg_kwargs,
189
+ )
190
+ proxy = RemoteServerProxy(cfg, lambda: "tok")
191
+ return proxy._unreachable_error(RuntimeError("All connection attempts failed"))
192
+
193
+
194
+ def test_unreachable_message_names_the_endpoint_and_the_cause():
195
+ message = _dead()
196
+ assert "https://witan.example.org/mcp" in message
197
+ assert "All connection attempts failed" in message
198
+
199
+
200
+ def test_unreachable_message_states_that_there_is_no_fallback():
201
+ # Silently answering from a local index is worse here than failing: an
202
+ # index that is stale or absent returns no hits, which reads exactly like a
203
+ # true "nothing calls this".
204
+ assert "does not fall back" in _dead()
205
+
206
+
207
+ def test_unreachable_message_names_remote_url_not_code_transport():
208
+ # `remote_url` is what routes a caller to this proxy. `code_transport`
209
+ # selects the direct-omnigraph store path, and naming it here would send
210
+ # the reader to unset a setting that is not in play.
211
+ message = _dead(url_source="`WITAN_REMOTE_URL`")
212
+ assert "`WITAN_REMOTE_URL`" in message
213
+ assert "code_transport" not in message
214
+
215
+
216
+ def test_unreachable_message_names_the_setting_that_supplied_the_url():
217
+ assert "`remote_url` on target [qa]" in _dead(
218
+ target_name="qa", url_source="`remote_url` on target [qa]"
219
+ )
220
+
221
+
222
+ def test_unreachable_message_does_not_infer_the_setting_from_the_target():
223
+ # A matched target does not mean the target supplied the URL — env
224
+ # overrides it while leaving `target_name` set. Inferring would name a
225
+ # key that is overridden, and the caller would still be routed remotely.
226
+ message = _dead(target_name="qa", url_source="`WITAN_REMOTE_URL`")
227
+ assert "`WITAN_REMOTE_URL`" in message
228
+ assert "target [qa]" not in message
229
+
230
+
231
+ def test_cli_prints_an_unreachable_remote_instead_of_a_traceback(monkeypatch, capsys):
232
+ from types import SimpleNamespace
233
+
234
+ from witan_code import cli as cli_module
235
+ from witan_code.remote.proxy import RemoteUnreachable
236
+
237
+ def _down():
238
+ raise RemoteUnreachable("witan-code is down at X")
239
+
240
+ monkeypatch.setattr(cli_module, "app", SimpleNamespace(meta=_down))
241
+ with pytest.raises(SystemExit) as exit_code:
242
+ cli_module.cli()
243
+ assert exit_code.value.code == 1
244
+ assert "witan-code is down at X" in capsys.readouterr().out
@@ -22,6 +22,7 @@ from fastmcp import Client
22
22
  from witan_code import config as cfg_module
23
23
  from witan_code import store as store_module
24
24
  from witan_code.remote.store import (
25
+ RemotePayloadTooLarge,
25
26
  RemoteStoreClient,
26
27
  RemoteStoreUnsupported,
27
28
  StoreSession,
@@ -314,6 +315,206 @@ def test_a_dropped_connection_is_reconnected_once():
314
315
  session.close()
315
316
 
316
317
 
318
+ class _RefusesForSize(_FakeClient):
319
+ """A deployment that answers every call with a size refusal.
320
+
321
+ ``exc`` is the shape under test: the two faces a 413 wears on this path.
322
+ """
323
+
324
+ def __init__(self, log, exc):
325
+ super().__init__(log)
326
+ self._exc = exc
327
+
328
+ async def call_tool(self, name, arguments):
329
+ self._log.append(("attempt", name))
330
+ raise self._exc
331
+
332
+
333
+ def _http_413():
334
+ import httpx2
335
+
336
+ request = httpx2.Request("POST", "http://x/mcp")
337
+ response = httpx2.Response(413, request=request, text="Request body too large")
338
+ return httpx2.HTTPStatusError("413", request=request, response=response)
339
+
340
+
341
+ def _relayed_413():
342
+ from fastmcp.exceptions import ToolError
343
+
344
+ return ToolError(
345
+ 'backend unavailable: tool call failed on backend witan: calling "tools/call": '
346
+ "Request Entity Too Large: request failed with status 413: Request body too large"
347
+ )
348
+
349
+
350
+ @pytest.mark.parametrize(
351
+ "exc", [_http_413(), _relayed_413()], ids=["direct", "relayed"]
352
+ )
353
+ def test_an_oversized_batch_is_refused_once_and_never_retried(exc):
354
+ """★ The retry is the bug, not just the traceback.
355
+
356
+ A direct 413 is an httpx error, so the generic arm treats it as a dropped
357
+ socket: reconnect and send the same multi-MiB body again, to be refused
358
+ identically. That is one wasted round trip per batch of a repo-scale index
359
+ before the run dies — and it died as a traceback either way.
360
+ """
361
+ log: list = []
362
+ clients = iter([_RefusesForSize(log, exc), _RefusesForSize(log, exc)])
363
+ session = StoreSession("http://x/mcp", lambda: "jwt", lambda _t: next(clients))
364
+ with pytest.raises(RemotePayloadTooLarge) as caught:
365
+ RemoteStoreClient(REPO, session).load([{"id": "n1", "type": "Symbol"}])
366
+ # Exactly one attempt: no reconnect, no second send of the same payload.
367
+ assert [entry[0] for entry in log] == ["connect", "attempt"]
368
+ message = str(caught.value)
369
+ assert "`code_store_load`" in message
370
+ assert "http://x/mcp" in message
371
+ # Chunked-merge context, added by `_load_refusal` where it is actually true.
372
+ assert "budget of 2 MiB" in message
373
+ assert "first batch" in message # nothing applied — this WAS batch 1
374
+
375
+
376
+ def test_a_read_refusal_claims_nothing_about_batching_or_partial_indexes():
377
+ """★ Every store call comes through one helper — most are not chunked loads.
378
+
379
+ Reads, `code_store_views`, and single mutations carry no byte budget and
380
+ apply nothing incrementally. An earlier revision told all of them that
381
+ "records are already batched under 2 MiB" and that "the index stopped
382
+ part-way", which was false for each.
383
+ """
384
+ log: list = []
385
+ session = StoreSession(
386
+ "http://x/mcp", lambda: "jwt", lambda _t: _RefusesForSize(log, _relayed_413())
387
+ )
388
+ with pytest.raises(RemotePayloadTooLarge) as caught:
389
+ RemoteStoreClient(REPO, session).list_branches()
390
+ message = str(caught.value).lower()
391
+ for forbidden in ("batch", "part-way", "mib", "budget", "applied"):
392
+ assert forbidden not in message, (
393
+ f"a read refusal must not mention {forbidden!r}"
394
+ )
395
+
396
+
397
+ def test_an_overwrite_load_is_not_told_to_shrink_a_budget_it_does_not_have():
398
+ """`overwrite` is sent WHOLE — it cannot be chunked, so quoting a batch
399
+ budget would point at a knob that does not apply to it."""
400
+ log: list = []
401
+ session = StoreSession(
402
+ "http://x/mcp", lambda: "jwt", lambda _t: _RefusesForSize(log, _relayed_413())
403
+ )
404
+ with pytest.raises(RemotePayloadTooLarge) as caught:
405
+ RemoteStoreClient(REPO, session).load(
406
+ [{"id": "n1", "type": "Symbol"}], mode="overwrite"
407
+ )
408
+ message = str(caught.value)
409
+ assert "sent whole" in message
410
+ assert "cannot be chunked" in message
411
+ assert "MiB" not in message # no budget to quote
412
+ assert "batch " not in message.lower()
413
+
414
+
415
+ def test_a_custom_max_bytes_is_reported_instead_of_the_default():
416
+ """`load` takes `max_bytes` from its caller, so a hardcoded "2 MiB" would
417
+ send the reader looking for a limit that is not the one that refused them."""
418
+ log: list = []
419
+ session = StoreSession(
420
+ "http://x/mcp", lambda: "jwt", lambda _t: _RefusesForSize(log, _relayed_413())
421
+ )
422
+ with pytest.raises(RemotePayloadTooLarge) as caught:
423
+ RemoteStoreClient(REPO, session).load(
424
+ [{"id": "n1", "type": "Symbol"}], max_bytes=1_500_000
425
+ )
426
+ message = str(caught.value)
427
+ assert "budget of 1,500,000 bytes" in message
428
+ assert "2 MiB" not in message
429
+
430
+
431
+ def test_a_change_many_refusal_points_at_chunk_size_not_a_byte_budget():
432
+ """`change_many` chunks by statement COUNT. There is no byte budget bounding
433
+ it, so naming one would point at a knob that does not exist here."""
434
+ log: list = []
435
+ session = StoreSession(
436
+ "http://x/mcp", lambda: "jwt", lambda _t: _RefusesForSize(log, _relayed_413())
437
+ )
438
+ steps = [("q.gq", "delete_file", {"id": str(n)}) for n in range(10)]
439
+ with pytest.raises(RemotePayloadTooLarge) as caught:
440
+ RemoteStoreClient(REPO, session).change_many(steps, chunk_size=4)
441
+ message = str(caught.value)
442
+ assert "4 statements" in message
443
+ assert "`chunk_size`" in message
444
+ assert "statement COUNT" in message
445
+ assert "MiB" not in message # no byte budget bounds this path
446
+ assert "first chunk" in message # nothing applied yet
447
+
448
+
449
+ def test_a_dropped_socket_is_still_retried_after_the_size_guard():
450
+ """The guard sits ahead of the reconnect; it must not disable it."""
451
+ log: list = []
452
+ clients = iter([_FakeClient(log, fail_first=True), _FakeClient(log)])
453
+ session = StoreSession("http://x/mcp", lambda: "jwt", lambda _t: next(clients))
454
+ assert RemoteStoreClient(REPO, session).list_branches() == ["main"]
455
+ assert [entry[0] for entry in log].count("connect") == 2
456
+ session.close()
457
+
458
+
459
+ def test_an_ordinary_tool_failure_is_not_read_as_a_size_refusal():
460
+ """A tool error relays the server's text, which can quote the caller's data."""
461
+ from fastmcp.exceptions import ToolError
462
+ from witan_code.remote.store import RemoteToolFailed
463
+
464
+ log: list = []
465
+ session = StoreSession(
466
+ "http://x/mcp",
467
+ lambda: "jwt",
468
+ lambda _t: _RefusesForSize(log, ToolError("no view named 'payload-413'")),
469
+ )
470
+ with pytest.raises(RemoteToolFailed) as caught:
471
+ RemoteStoreClient(REPO, session).list_branches()
472
+ assert not isinstance(caught.value, RemotePayloadTooLarge)
473
+
474
+
475
+ def test_a_refused_store_call_reads_as_a_sentence_not_a_traceback():
476
+ """This session is witan-code's OTHER transport, and it needs the same fix.
477
+
478
+ Index and write commands reach the deployment through `StoreRef.client()`
479
+ and this session, not through `RemoteMCPProxy` — so classifying refusals in
480
+ the proxy alone left every one of them escaping as a raw `ToolError`, which
481
+ is not a `RuntimeError` and so slips past `cli()`'s guard tuple.
482
+ """
483
+ from fastmcp.exceptions import ToolError
484
+ from witan_code.remote.store import RemoteToolFailed
485
+
486
+ refusal = ToolError("cedar: read denied on graph 'code'")
487
+ session = StoreSession(
488
+ "http://x/mcp", lambda: "jwt", lambda _t: _RefusesForSize([], refusal)
489
+ )
490
+ with pytest.raises(RemoteToolFailed, match="cedar: read denied") as caught:
491
+ RemoteStoreClient(REPO, session).list_branches()
492
+ assert isinstance(caught.value, RuntimeError)
493
+ assert caught.value.__cause__ is refusal
494
+
495
+
496
+ def test_a_refusal_on_the_post_reconnect_retry_is_classified_too():
497
+ """A refusal that happens to follow a dropped socket takes the other arm.
498
+
499
+ The generic arm reconnects and re-invokes; classifying only the first
500
+ attempt would let exactly the same refusal escape as a traceback whenever
501
+ it landed after a dead connection rather than before one.
502
+ """
503
+ from fastmcp.exceptions import ToolError
504
+ from witan_code.remote.store import RemoteToolFailed
505
+
506
+ log: list = []
507
+ clients = iter(
508
+ [
509
+ _FakeClient(log, fail_first=True),
510
+ _RefusesForSize(log, ToolError("no view named 'branches'")),
511
+ ]
512
+ )
513
+ session = StoreSession("http://x/mcp", lambda: "jwt", lambda _t: next(clients))
514
+ with pytest.raises(RemoteToolFailed, match="no view named 'branches'"):
515
+ RemoteStoreClient(REPO, session).list_branches()
516
+
517
+
317
518
  def test_an_empty_load_costs_nothing():
318
519
  log: list = []
319
520
  session = StoreSession("http://x/mcp", lambda: "jwt", lambda _t: _FakeClient(log))
@@ -1009,7 +1009,34 @@ def _launcher(
1009
1009
 
1010
1010
 
1011
1011
  def cli() -> None:
1012
- app.meta()
1012
+ from rich.console import Console
1013
+
1014
+ from .remote.oidc import RemoteAuthError
1015
+ from .remote.proxy import RemoteToolFailed, RemoteToolUnavailable, RemoteUnreachable
1016
+ from .remote.store import RemotePayloadTooLarge
1017
+
1018
+ try:
1019
+ app.meta()
1020
+ # Same remote failures the `witan` entrypoint classifies. This CLI had no
1021
+ # guard at all, so a deployment that was down, or a token the server
1022
+ # rejected, printed a traceback out of `witan-code symbols`.
1023
+ # RemotePayloadTooLarge comes from the store session rather than the proxy:
1024
+ # this CLI's oversized bodies are index batches, not tool arguments.
1025
+ # RemoteToolFailed covers the tool running and refusing — a Cedar denial on
1026
+ # a code graph the caller may not read, or a branch the cluster does not
1027
+ # have.
1028
+ except (
1029
+ RemoteAuthError,
1030
+ RemotePayloadTooLarge,
1031
+ RemoteToolFailed,
1032
+ RemoteToolUnavailable,
1033
+ RemoteUnreachable,
1034
+ ) as exc:
1035
+ # markup=False — a target block is written `[qa]`, which rich parses as
1036
+ # a style tag and swallows, taking the name of the setting to unset
1037
+ # with it.
1038
+ Console().print(str(exc), style="red", markup=False)
1039
+ raise SystemExit(1) from None
1013
1040
 
1014
1041
 
1015
1042
  if __name__ == "__main__":
@@ -14,9 +14,19 @@ from __future__ import annotations
14
14
  from typing import Callable
15
15
 
16
16
  from witan_core.remote.config import RemoteConfig
17
- from witan_core.remote.proxy import RemoteMCPProxy, RemoteToolUnavailable
17
+ from witan_core.remote.proxy import (
18
+ RemoteMCPProxy,
19
+ RemoteToolFailed,
20
+ RemoteToolUnavailable,
21
+ RemoteUnreachable,
22
+ )
18
23
 
19
- __all__ = ["RemoteServerProxy", "RemoteToolUnavailable"]
24
+ __all__ = [
25
+ "RemoteServerProxy",
26
+ "RemoteToolFailed",
27
+ "RemoteToolUnavailable",
28
+ "RemoteUnreachable",
29
+ ]
20
30
 
21
31
  # Tools that only mean anything against a local checkout. `code_reindex` IS
22
32
  # registered on the deployment (it is the same server module), but running it
@@ -31,10 +41,30 @@ class RemoteServerProxy(RemoteMCPProxy):
31
41
 
32
42
  def __init__(self, cfg: RemoteConfig, token_provider: Callable[[], str]) -> None:
33
43
  super().__init__(cfg.url, token_provider)
44
+ self._url_source = cfg.url_source
34
45
 
35
46
  def _is_admin_tool(self, name: str) -> bool:
36
47
  return name in _LOCAL_ONLY
37
48
 
49
+ def _unreachable_hint(self) -> str:
50
+ # Two ways to name the wrong setting here, and this avoids both.
51
+ # `remote_url` is what routes a client to this proxy — NOT
52
+ # `code_transport`, which selects the direct-omnigraph store path that
53
+ # `store._index_locally_hint` speaks to. And *which* `remote_url` is
54
+ # the resolver's answer to give (`url_source`), not something to infer
55
+ # from `target_name`: env overrides a matched target, and a global key
56
+ # supplies the URL with no target at all.
57
+ setting = self._url_source or "the configured remote URL"
58
+ return (
59
+ "witan-code does not fall back to a local store — a hit-free answer "
60
+ "from a stale or absent local index is indistinguishable from a "
61
+ "real one, so a silent fallback would report 'no callers' for code "
62
+ "that has them. Check the endpoint is reachable and that your "
63
+ "session is still valid (`witan-code whoami`, then `witan-code "
64
+ f"login`), or unset {setting} to query a locally-indexed store on "
65
+ "purpose."
66
+ )
67
+
38
68
  def _admin_error(self, name: str) -> str:
39
69
  return (
40
70
  f"`{name}` indexes a git checkout, which the deployed service does "
@@ -33,12 +33,19 @@ from fastmcp.client.auth import BearerAuth
33
33
  from fastmcp.client.transports import StreamableHttpTransport
34
34
  from fastmcp.exceptions import ToolError
35
35
  from witan_core.observability import get_logger
36
+ from witan_core.remote.proxy import (
37
+ RemotePayloadTooLarge,
38
+ RemoteToolFailed,
39
+ payload_too_large,
40
+ )
36
41
 
37
42
  from witan_core import chunking
38
43
 
39
44
  __all__ = [
45
+ "RemotePayloadTooLarge",
40
46
  "RemoteStoreClient",
41
47
  "RemoteStoreUnsupported",
48
+ "RemoteToolFailed",
42
49
  "StoreSession",
43
50
  "close_sessions",
44
51
  "session_for",
@@ -52,6 +59,68 @@ class RemoteStoreUnsupported(RuntimeError):
52
59
  """A store operation with no counterpart on the MCP tier."""
53
60
 
54
61
 
62
+ def _refuse_if_too_large(exc: BaseException, tool: str, url: str) -> None:
63
+ """Re-raise a body refused for its size as a sentence. Otherwise no-op.
64
+
65
+ Called on BOTH arms of ``StoreSession.call``'s handler, because a 413
66
+ reaches this transport wearing either face: relayed through ToolHive's vMCP
67
+ it is a ``ToolError``, while a direct connection raises an httpx status
68
+ error that the generic arm would treat as a dropped socket. That second one
69
+ is why this exists at all — the generic arm RECONNECTS AND RETRIES, so an
70
+ oversized index batch would be sent, refused, sent again, refused again,
71
+ and only then surface as a traceback. Retrying cannot help: the payload is
72
+ the thing being rejected.
73
+
74
+ ★ OPERATION-NEUTRAL, for the same reason the witan_core base message is.
75
+ Every store call comes through here — reads, `code_store_views`, single
76
+ mutations, the count-chunked `code_store_mutate_many`, and an `overwrite`
77
+ load that is not chunked at all. An earlier revision asserted here that
78
+ records were batched under 2 MiB and that an index had stopped part-way;
79
+ that was false for all of those, and false for any `load` given a
80
+ non-default ``max_bytes``. The operations that DO know their budget add it
81
+ themselves below.
82
+ """
83
+ oversized = payload_too_large(exc)
84
+ if oversized is None:
85
+ return
86
+ raise RemotePayloadTooLarge(
87
+ f"{url} refused `{tool}`: the request body is over the deployment's "
88
+ f"size cap ({oversized}). Retrying sends the same bytes to the same "
89
+ "answer — the payload itself is what was rejected."
90
+ ) from exc
91
+
92
+
93
+ def _load_refusal(exc: BaseException, *, batch: int, mode: str, max_bytes: int) -> str:
94
+ """Add load-specific context to the neutral refusal above.
95
+
96
+ Splits on ``mode`` because the two are not the same failure. A ``merge``
97
+ load is byte-chunked, so the budget and the count already applied are both
98
+ real and worth stating. An ``overwrite`` load is sent WHOLE — it cannot be
99
+ chunked, since a partial overwrite would delete exactly what the later
100
+ batches were going to restore — so quoting a batch budget at the reader
101
+ would send them looking for a knob that does not apply.
102
+ """
103
+ if mode == "overwrite":
104
+ return (
105
+ f"{exc} An `overwrite` load is sent whole: it cannot be chunked, "
106
+ "because a partial overwrite would delete what the remaining "
107
+ "batches were going to restore. The record set itself has to get "
108
+ "smaller, or the load has to run in-cluster instead."
109
+ )
110
+ size = chunking.describe_budget(max_bytes)
111
+ applied = (
112
+ f"The {batch} batch(es) before this one were applied — the index "
113
+ "stopped part-way, it did not roll back."
114
+ if batch
115
+ else "Nothing was applied: this was the first batch."
116
+ )
117
+ return (
118
+ f"{exc} This was batch {batch + 1} of a chunked load, sized against a "
119
+ f"budget of {size} — so either one record is too large to split, or "
120
+ f"the deployment's cap is below {size}. {applied}"
121
+ )
122
+
123
+
55
124
  # Added to the store tier after the first clients shipped, so its presence is
56
125
  # asked rather than assumed — see `RemoteStoreClient.change_many`.
57
126
  _MUTATE_MANY_TOOL = "code_store_mutate_many"
@@ -113,18 +182,28 @@ class StoreSession:
113
182
  self._connect()
114
183
  try:
115
184
  return self._invoke(tool, arguments)
116
- except ToolError:
185
+ except ToolError as exc:
117
186
  # The server ran the tool and it failed — a refusal, a bad
118
187
  # query, a store error. Reconnecting would only run it again.
119
- raise
120
- except Exception: # noqa: BLE001 — transport-shaped; retry once
188
+ _refuse_if_too_large(exc, tool, self.url)
189
+ raise RemoteToolFailed(str(exc)) from exc
190
+ except Exception as exc: # noqa: BLE001 — transport-shaped; retry once
191
+ _refuse_if_too_large(exc, tool, self.url)
121
192
  # Info: one reconnect is routine (idle session dropped), but a
122
193
  # deployment that reconnects on every call is pathological and
123
194
  # invisible without this.
124
195
  logger.info("witan.code.remote.reconnecting", tool=tool, exc_info=True)
125
196
  self._disconnect()
126
197
  self._connect()
127
- return self._invoke(tool, arguments)
198
+ try:
199
+ return self._invoke(tool, arguments)
200
+ except ToolError as refused:
201
+ # The reconnect succeeded and the server refused the retry.
202
+ # Classified here too, or a refusal that happened to follow
203
+ # a dropped socket escapes as the raw traceback the first
204
+ # arm exists to prevent.
205
+ _refuse_if_too_large(refused, tool, self.url)
206
+ raise RemoteToolFailed(str(refused)) from refused
128
207
 
129
208
  def has_tool(self, tool: str) -> bool:
130
209
  """Whether the deployment serves ``tool``.
@@ -321,15 +400,35 @@ class RemoteStoreClient:
321
400
  return
322
401
  size = chunk_size or len(steps)
323
402
  for start in range(0, len(steps), size):
324
- self._session.call(
325
- _MUTATE_MANY_TOOL,
326
- graph=self.graph,
327
- steps=[
328
- {"query": query_file, "name": query_name, "params": params}
329
- for query_file, query_name, params in steps[start : start + size]
330
- ],
331
- view=self.branch,
332
- )
403
+ try:
404
+ self._session.call(
405
+ _MUTATE_MANY_TOOL,
406
+ graph=self.graph,
407
+ steps=[
408
+ {"query": query_file, "name": query_name, "params": params}
409
+ for query_file, query_name, params in steps[
410
+ start : start + size
411
+ ]
412
+ ],
413
+ view=self.branch,
414
+ )
415
+ except RemotePayloadTooLarge as exc:
416
+ # ★ THIS CHUNKING IS BY STATEMENT COUNT, NOT BYTES — so unlike
417
+ # `load` there is no byte budget to quote, and pointing the
418
+ # reader at one would send them to a knob that does not exist
419
+ # here. `chunk_size` is the knob, and it is the caller's.
420
+ raise RemotePayloadTooLarge(
421
+ f"{exc} This batch carried {min(size, len(steps) - start)} "
422
+ "statements. `change_many` chunks by statement COUNT, not "
423
+ "by bytes, so there is no byte budget bounding it — pass a "
424
+ f"smaller `chunk_size` (currently {size}). "
425
+ + (
426
+ f"The {start} statement(s) before it were applied — "
427
+ "chunks commit independently, so this stopped part-way."
428
+ if start
429
+ else "Nothing was applied: this was the first chunk."
430
+ )
431
+ ) from exc
333
432
 
334
433
  def load(
335
434
  self,
@@ -364,14 +463,19 @@ class RemoteStoreClient:
364
463
  if mode == "overwrite"
365
464
  else chunking.chunk_records(records, max_bytes)
366
465
  )
367
- for batch in batches:
368
- self._session.call(
369
- "code_store_load",
370
- graph=self.graph,
371
- records=batch,
372
- mode=mode,
373
- view=self.branch,
374
- )
466
+ for index, batch in enumerate(batches):
467
+ try:
468
+ self._session.call(
469
+ "code_store_load",
470
+ graph=self.graph,
471
+ records=batch,
472
+ mode=mode,
473
+ view=self.branch,
474
+ )
475
+ except RemotePayloadTooLarge as exc:
476
+ raise RemotePayloadTooLarge(
477
+ _load_refusal(exc, batch=index, mode=mode, max_bytes=max_bytes)
478
+ ) from exc
375
479
 
376
480
  def ensure_branch(self) -> None:
377
481
  if self.branch is None:
File without changes
File without changes
File without changes
File without changes