witan-code 0.12.1__tar.gz → 0.12.2__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.2}/CHANGELOG.md +27 -0
  2. {witan_code-0.12.1 → witan_code-0.12.2}/PKG-INFO +2 -2
  3. {witan_code-0.12.1 → witan_code-0.12.2}/pyproject.toml +13 -11
  4. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_remote_proxy.py +69 -0
  5. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_remote_store.py +156 -0
  6. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/cli.py +24 -1
  7. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/remote/proxy.py +26 -2
  8. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/remote/store.py +110 -19
  9. {witan_code-0.12.1 → witan_code-0.12.2}/.gitignore +0 -0
  10. {witan_code-0.12.1 → witan_code-0.12.2}/README.md +0 -0
  11. {witan_code-0.12.1 → witan_code-0.12.2}/config/claude.json +0 -0
  12. {witan_code-0.12.1 → witan_code-0.12.2}/config/copilot.json +0 -0
  13. {witan_code-0.12.1 → witan_code-0.12.2}/config/pi.json +0 -0
  14. {witan_code-0.12.1 → witan_code-0.12.2}/docs/BRANCH_INDEXING.md +0 -0
  15. {witan_code-0.12.1 → witan_code-0.12.2}/docs/CLI_REFERENCE.md +0 -0
  16. {witan_code-0.12.1 → witan_code-0.12.2}/docs/EDGE_PRECISION_TIERS.md +0 -0
  17. {witan_code-0.12.1 → witan_code-0.12.2}/docs/PACKAGE_MAP.md +0 -0
  18. {witan_code-0.12.1 → witan_code-0.12.2}/docs/STAGE2_STITCHING.md +0 -0
  19. {witan_code-0.12.1 → witan_code-0.12.2}/docs/SYMBOL_FORMAT.md +0 -0
  20. {witan_code-0.12.1 → witan_code-0.12.2}/docs/SYMBOL_TABLE.md +0 -0
  21. {witan_code-0.12.1 → witan_code-0.12.2}/docs/USER_GUIDE.md +0 -0
  22. {witan_code-0.12.1 → witan_code-0.12.2}/install.sh +0 -0
  23. {witan_code-0.12.1 → witan_code-0.12.2}/tests/__init__.py +0 -0
  24. {witan_code-0.12.1 → witan_code-0.12.2}/tests/conftest.py +0 -0
  25. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_batched_deletes.py +0 -0
  26. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_branches.py +0 -0
  27. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_bridge.py +0 -0
  28. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_chunked_load.py +0 -0
  29. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_cli_dispatch.py +0 -0
  30. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_cli_hooks.py +0 -0
  31. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_cli_output_format.py +0 -0
  32. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_config.py +0 -0
  33. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_config_targets.py +0 -0
  34. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_context.py +0 -0
  35. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_crossrepo.py +0 -0
  36. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_edges.py +0 -0
  37. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_elicit.py +0 -0
  38. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_enrichment.py +0 -0
  39. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_github_app.py +0 -0
  40. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_graph.py +0 -0
  41. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_hooks.py +0 -0
  42. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_identity.py +0 -0
  43. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_indexer.py +0 -0
  44. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_indexer_scope.py +0 -0
  45. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_ingest.py +0 -0
  46. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_languages.py +0 -0
  47. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_maintenance.py +0 -0
  48. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_package_map.py +0 -0
  49. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_reaper.py +0 -0
  50. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_repo.py +0 -0
  51. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_server.py +0 -0
  52. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_setup.py +0 -0
  53. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_stitch.py +0 -0
  54. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_store.py +0 -0
  55. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_symbol_table.py +0 -0
  56. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_tasks.py +0 -0
  57. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_views.py +0 -0
  58. {witan_code-0.12.1 → witan_code-0.12.2}/tests/test_visualize.py +0 -0
  59. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/__init__.py +0 -0
  60. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/__main__.py +0 -0
  61. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/bridge.py +0 -0
  62. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/bridge_extractors.py +0 -0
  63. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/config.py +0 -0
  64. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/context.py +0 -0
  65. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/edges.py +0 -0
  66. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/elicit.py +0 -0
  67. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/extensions/pi/codegraph.ts +0 -0
  68. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/github_app.py +0 -0
  69. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/graph.py +0 -0
  70. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/hooks.py +0 -0
  71. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/identity.py +0 -0
  72. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/indexer.py +0 -0
  73. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/ingest.py +0 -0
  74. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/maintenance.py +0 -0
  75. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/output.py +0 -0
  76. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/package_map.py +0 -0
  77. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries/bridge.gq +0 -0
  78. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries/code_mutations.gq +0 -0
  79. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries/code_read.gq +0 -0
  80. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries/delete.gq +0 -0
  81. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries_ts/bash.scm +0 -0
  82. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries_ts/hcl.scm +0 -0
  83. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries_ts/python.scm +0 -0
  84. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries_ts/sql.scm +0 -0
  85. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries_ts/typescript.scm +0 -0
  86. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/queries_ts/yaml.scm +0 -0
  87. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/reaper.py +0 -0
  88. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/remote/__init__.py +0 -0
  89. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/remote/oidc.py +0 -0
  90. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/repo.py +0 -0
  91. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/schema/bridge-schema.pg +0 -0
  92. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/schema/code-schema.pg +0 -0
  93. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/server.py +0 -0
  94. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/setup.py +0 -0
  95. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/skills/witan-code/SKILL.md +0 -0
  96. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/stitch.py +0 -0
  97. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/store.py +0 -0
  98. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/views.py +0 -0
  99. {witan_code-0.12.1 → witan_code-0.12.2}/witan_code/visualize.py +0 -0
@@ -6,6 +6,33 @@ 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.2] - 2026-08-07
10
+
11
+ ### Fixed
12
+
13
+ - An oversized index batch is refused **once**, as a sentence, instead of being
14
+ retried and then raising a traceback. A direct 413 is an httpx error, so
15
+ `StoreSession.call`'s generic arm read it as a dropped socket and did what it
16
+ does for one: reconnect and send the same multi-MiB body again, to be refused
17
+ identically. Retrying cannot help — the payload is the thing being rejected.
18
+ Both faces of a 413 are now classified: relayed through the vMCP as a
19
+ `ToolError`, and direct as an httpx status error.
20
+ - The refusal message is per-operation rather than one claim for all of them.
21
+ Every store call comes through one helper, but most are not chunked loads:
22
+ reads, `code_store_views`, and single mutations carry no byte budget and apply
23
+ nothing incrementally; `load(mode="overwrite")` is sent whole and cannot be
24
+ chunked at all; `change_many` chunks by statement COUNT, so `chunk_size` is
25
+ its knob and no byte budget bounds it. A chunked `load` reports the budget
26
+ actually in play — `max_bytes` comes from the caller, so a hardcoded "2 MiB"
27
+ was wrong for any non-default — plus which batch was refused and how many
28
+ already landed.
29
+
30
+ ### Changed
31
+
32
+ - `witan-core` floor raised to `>=0.12` for `RemotePayloadTooLarge` /
33
+ `payload_too_large`, imported at module scope in `remote/store.py`. Third time
34
+ this floor has been tripped; the pin comment now says so.
35
+
9
36
  ## [0.12.1] - 2026-08-07
10
37
 
11
38
  ### 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.2
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.12
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.2"
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,18 @@ 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.11 was required for chunking.MCP_LOAD_MAX_BYTES, evaluated as a
26
+ # default argument; >=0.10 for witan_core.chunking + load_batch, both moved
27
+ # up from this package; >=0.9 for observability.middleware; >=0.8 for
28
+ # OmnigraphClient.change_many with chunk_size.)
29
+ "witan-core[cli,remote,observability]>=0.12,<1",
28
30
  "fastmcp>=3.4.2,<5",
29
31
  "cyclopts>=4,<5",
30
32
  # [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,161 @@ 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
+
463
+ log: list = []
464
+ session = StoreSession(
465
+ "http://x/mcp",
466
+ lambda: "jwt",
467
+ lambda _t: _RefusesForSize(log, ToolError("no view named 'payload-413'")),
468
+ )
469
+ with pytest.raises(ToolError):
470
+ RemoteStoreClient(REPO, session).list_branches()
471
+
472
+
317
473
  def test_an_empty_load_costs_nothing():
318
474
  log: list = []
319
475
  session = StoreSession("http://x/mcp", lambda: "jwt", lambda _t: _FakeClient(log))
@@ -1009,7 +1009,30 @@ 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 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
+ except (
1026
+ RemoteAuthError,
1027
+ RemotePayloadTooLarge,
1028
+ RemoteToolUnavailable,
1029
+ RemoteUnreachable,
1030
+ ) as exc:
1031
+ # markup=False — a target block is written `[qa]`, which rich parses as
1032
+ # a style tag and swallows, taking the name of the setting to unset
1033
+ # with it.
1034
+ Console().print(str(exc), style="red", markup=False)
1035
+ raise SystemExit(1) from None
1013
1036
 
1014
1037
 
1015
1038
  if __name__ == "__main__":
@@ -14,9 +14,13 @@ 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
+ RemoteToolUnavailable,
20
+ RemoteUnreachable,
21
+ )
18
22
 
19
- __all__ = ["RemoteServerProxy", "RemoteToolUnavailable"]
23
+ __all__ = ["RemoteServerProxy", "RemoteToolUnavailable", "RemoteUnreachable"]
20
24
 
21
25
  # Tools that only mean anything against a local checkout. `code_reindex` IS
22
26
  # registered on the deployment (it is the same server module), but running it
@@ -31,10 +35,30 @@ class RemoteServerProxy(RemoteMCPProxy):
31
35
 
32
36
  def __init__(self, cfg: RemoteConfig, token_provider: Callable[[], str]) -> None:
33
37
  super().__init__(cfg.url, token_provider)
38
+ self._url_source = cfg.url_source
34
39
 
35
40
  def _is_admin_tool(self, name: str) -> bool:
36
41
  return name in _LOCAL_ONLY
37
42
 
43
+ def _unreachable_hint(self) -> str:
44
+ # Two ways to name the wrong setting here, and this avoids both.
45
+ # `remote_url` is what routes a client to this proxy — NOT
46
+ # `code_transport`, which selects the direct-omnigraph store path that
47
+ # `store._index_locally_hint` speaks to. And *which* `remote_url` is
48
+ # the resolver's answer to give (`url_source`), not something to infer
49
+ # from `target_name`: env overrides a matched target, and a global key
50
+ # supplies the URL with no target at all.
51
+ setting = self._url_source or "the configured remote URL"
52
+ return (
53
+ "witan-code does not fall back to a local store — a hit-free answer "
54
+ "from a stale or absent local index is indistinguishable from a "
55
+ "real one, so a silent fallback would report 'no callers' for code "
56
+ "that has them. Check the endpoint is reachable and that your "
57
+ "session is still valid (`witan-code whoami`, then `witan-code "
58
+ f"login`), or unset {setting} to query a locally-indexed store on "
59
+ "purpose."
60
+ )
61
+
38
62
  def _admin_error(self, name: str) -> str:
39
63
  return (
40
64
  f"`{name}` indexes a git checkout, which the deployed service does "
@@ -33,10 +33,12 @@ 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 RemotePayloadTooLarge, payload_too_large
36
37
 
37
38
  from witan_core import chunking
38
39
 
39
40
  __all__ = [
41
+ "RemotePayloadTooLarge",
40
42
  "RemoteStoreClient",
41
43
  "RemoteStoreUnsupported",
42
44
  "StoreSession",
@@ -52,6 +54,68 @@ class RemoteStoreUnsupported(RuntimeError):
52
54
  """A store operation with no counterpart on the MCP tier."""
53
55
 
54
56
 
57
+ def _refuse_if_too_large(exc: BaseException, tool: str, url: str) -> None:
58
+ """Re-raise a body refused for its size as a sentence. Otherwise no-op.
59
+
60
+ Called on BOTH arms of ``StoreSession.call``'s handler, because a 413
61
+ reaches this transport wearing either face: relayed through ToolHive's vMCP
62
+ it is a ``ToolError``, while a direct connection raises an httpx status
63
+ error that the generic arm would treat as a dropped socket. That second one
64
+ is why this exists at all — the generic arm RECONNECTS AND RETRIES, so an
65
+ oversized index batch would be sent, refused, sent again, refused again,
66
+ and only then surface as a traceback. Retrying cannot help: the payload is
67
+ the thing being rejected.
68
+
69
+ ★ OPERATION-NEUTRAL, for the same reason the witan_core base message is.
70
+ Every store call comes through here — reads, `code_store_views`, single
71
+ mutations, the count-chunked `code_store_mutate_many`, and an `overwrite`
72
+ load that is not chunked at all. An earlier revision asserted here that
73
+ records were batched under 2 MiB and that an index had stopped part-way;
74
+ that was false for all of those, and false for any `load` given a
75
+ non-default ``max_bytes``. The operations that DO know their budget add it
76
+ themselves below.
77
+ """
78
+ oversized = payload_too_large(exc)
79
+ if oversized is None:
80
+ return
81
+ raise RemotePayloadTooLarge(
82
+ f"{url} refused `{tool}`: the request body is over the deployment's "
83
+ f"size cap ({oversized}). Retrying sends the same bytes to the same "
84
+ "answer — the payload itself is what was rejected."
85
+ ) from exc
86
+
87
+
88
+ def _load_refusal(exc: BaseException, *, batch: int, mode: str, max_bytes: int) -> str:
89
+ """Add load-specific context to the neutral refusal above.
90
+
91
+ Splits on ``mode`` because the two are not the same failure. A ``merge``
92
+ load is byte-chunked, so the budget and the count already applied are both
93
+ real and worth stating. An ``overwrite`` load is sent WHOLE — it cannot be
94
+ chunked, since a partial overwrite would delete exactly what the later
95
+ batches were going to restore — so quoting a batch budget at the reader
96
+ would send them looking for a knob that does not apply.
97
+ """
98
+ if mode == "overwrite":
99
+ return (
100
+ f"{exc} An `overwrite` load is sent whole: it cannot be chunked, "
101
+ "because a partial overwrite would delete what the remaining "
102
+ "batches were going to restore. The record set itself has to get "
103
+ "smaller, or the load has to run in-cluster instead."
104
+ )
105
+ size = chunking.describe_budget(max_bytes)
106
+ applied = (
107
+ f"The {batch} batch(es) before this one were applied — the index "
108
+ "stopped part-way, it did not roll back."
109
+ if batch
110
+ else "Nothing was applied: this was the first batch."
111
+ )
112
+ return (
113
+ f"{exc} This was batch {batch + 1} of a chunked load, sized against a "
114
+ f"budget of {size} — so either one record is too large to split, or "
115
+ f"the deployment's cap is below {size}. {applied}"
116
+ )
117
+
118
+
55
119
  # Added to the store tier after the first clients shipped, so its presence is
56
120
  # asked rather than assumed — see `RemoteStoreClient.change_many`.
57
121
  _MUTATE_MANY_TOOL = "code_store_mutate_many"
@@ -113,11 +177,13 @@ class StoreSession:
113
177
  self._connect()
114
178
  try:
115
179
  return self._invoke(tool, arguments)
116
- except ToolError:
180
+ except ToolError as exc:
117
181
  # The server ran the tool and it failed — a refusal, a bad
118
182
  # query, a store error. Reconnecting would only run it again.
183
+ _refuse_if_too_large(exc, tool, self.url)
119
184
  raise
120
- except Exception: # noqa: BLE001 — transport-shaped; retry once
185
+ except Exception as exc: # noqa: BLE001 — transport-shaped; retry once
186
+ _refuse_if_too_large(exc, tool, self.url)
121
187
  # Info: one reconnect is routine (idle session dropped), but a
122
188
  # deployment that reconnects on every call is pathological and
123
189
  # invisible without this.
@@ -321,15 +387,35 @@ class RemoteStoreClient:
321
387
  return
322
388
  size = chunk_size or len(steps)
323
389
  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
- )
390
+ try:
391
+ self._session.call(
392
+ _MUTATE_MANY_TOOL,
393
+ graph=self.graph,
394
+ steps=[
395
+ {"query": query_file, "name": query_name, "params": params}
396
+ for query_file, query_name, params in steps[
397
+ start : start + size
398
+ ]
399
+ ],
400
+ view=self.branch,
401
+ )
402
+ except RemotePayloadTooLarge as exc:
403
+ # ★ THIS CHUNKING IS BY STATEMENT COUNT, NOT BYTES — so unlike
404
+ # `load` there is no byte budget to quote, and pointing the
405
+ # reader at one would send them to a knob that does not exist
406
+ # here. `chunk_size` is the knob, and it is the caller's.
407
+ raise RemotePayloadTooLarge(
408
+ f"{exc} This batch carried {min(size, len(steps) - start)} "
409
+ "statements. `change_many` chunks by statement COUNT, not "
410
+ "by bytes, so there is no byte budget bounding it — pass a "
411
+ f"smaller `chunk_size` (currently {size}). "
412
+ + (
413
+ f"The {start} statement(s) before it were applied — "
414
+ "chunks commit independently, so this stopped part-way."
415
+ if start
416
+ else "Nothing was applied: this was the first chunk."
417
+ )
418
+ ) from exc
333
419
 
334
420
  def load(
335
421
  self,
@@ -364,14 +450,19 @@ class RemoteStoreClient:
364
450
  if mode == "overwrite"
365
451
  else chunking.chunk_records(records, max_bytes)
366
452
  )
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
- )
453
+ for index, batch in enumerate(batches):
454
+ try:
455
+ self._session.call(
456
+ "code_store_load",
457
+ graph=self.graph,
458
+ records=batch,
459
+ mode=mode,
460
+ view=self.branch,
461
+ )
462
+ except RemotePayloadTooLarge as exc:
463
+ raise RemotePayloadTooLarge(
464
+ _load_refusal(exc, batch=index, mode=mode, max_bytes=max_bytes)
465
+ ) from exc
375
466
 
376
467
  def ensure_branch(self) -> None:
377
468
  if self.branch is None:
File without changes
File without changes
File without changes
File without changes