caura-ai/caura

Caura.submit_interview() in clients/python/src/caura_client/client.py has real logic that no test exercises on the success path: it builds the body from tenant_id or self.tenant_id, and only includes fleet_id / command_id when given; it passes its own timeout=120.0 per request instead of the client-wide 30s; it adds an "http_status" key to the returned body so callers can tell a 207 partial from a 200 committed. grep -rn "http_status" clients/python/tests finds nothing; submit_interview appears only in tests/test_transport_errors.py (error mapping). So the one documented behavior callers rely on (the 207 vs 200 distinction, called out in the README) can regress unnoticed. Proposed tests (follow the httpx.MockTransport pattern in tests/test_client.py): A 200 and a 207 response each come back with result["http_status"] set to that status. The request body contains tenant_id (default from the client, and overridden by the argument) and omits fleet_id / command_id when not passed, inclu

Describe the bug Both clients parse Retry-After as a number of seconds only. RFC 9110 also allows an HTTP-date (Retry-After: Wed, 21 Oct 2026 07:28:00 GMT). When a gateway or proxy in front of Caura sends the date form, RateLimitError.retry_after is silently None, so callers that back off on retry_after fall back to their default delay and may retry too early or too late. Python, clients/python/src/caura_client/client.py: float(response.headers["Retry-After"]) → ValueError → retry_after = None. TypeScript, clients/typescript/src/index.ts (~line 346): Number(retryAfter) → NaN → treated as absent. Steps to reproduce (Python) import httpx from caura_client import Caura, RateLimitError t = httpx.MockTransport(lambda r: httpx.Response( 429, headers={"Retry-After": "Wed, 21 Oct 2026 07:28:00 GMT"}, json={})) try: Caura("k", tenant_id="t", transport=t).health() except RateLimitError as e: print(e.retry_after) # None Expected: seconds until that date (clamped at 0), as

.pre-commit-config.yaml says it "mirrors the checks ci.yml runs", but its ruff hooks only match ^(core-api|core-storage-api)/src/. The Python client has its own CI gate (.github/workflows/client-python-ci.yml runs ruff check src tests in clients/python/), and its pyproject.toml has its own [tool.ruff] config — yet a local commit that touches clients/python/ gets no ruff check, so lint failures only show up after pushing. Proposed change Add a third ruff hook entry (or widen files:) so clients/python/(src|tests)/ is linted locally: - id: ruff name: ruff (clients/python) args: [--fix] files: ^clients/python/(src|tests)/ Notes for whoever picks this up: The client has its own ruff config, so pre-commit needs to run from that directory or pass --config clients/python/pyproject.toml (the root hook's config would otherwise apply). Check which one works and keep the CI command (ruff check src tests) as the reference. CI only runs ruff check on the client, not ruff format, so do not a

docs/README.md is the documentation index (added in #1407), but it does not list docs/telemetry.md — the page that explains the anonymous daily heartbeat a self-hosted server sends. It is the one doc an operator most needs to find before deciding whether to opt out, and it is only reachable if you already know the filename. Check: grep -n "telemetry.md" docs/README.md # no match (docs/telemetry-schema-v1.json is its companion.) Proposed change Add a bullet for telemetry.md under Operating a deployment in docs/README.md, in the same one-line style as its neighbours, e.g. "what the anonymous daily heartbeat sends, and how to turn it off". Confirm the one-line description against the first paragraph of docs/telemetry.md. Maintainers' call (optional): docs/atomic-fact-fanout/, docs/fts-title-weighting/, docs/search-path-bisect/ and docs/unembedded-rows/ are also unlisted. They look like internal investigation notes, so leaving them out may be intentional — if so, a one-line comment

Describe the bug The TypeScript client leaks a raw SyntaxError when a 2xx response has a non-JSON body (for example an HTML page from a captive portal or a misconfigured proxy). Callers who catch CauraError miss it. This is the TypeScript counterpart of the Python-client issue #1899. clients/typescript/src/index.ts, readResponseJson: async function readResponseJson(res: Response): Promise<any> { try { return await res.json(); } catch (cause) { if (cause instanceof SyntaxError) throw cause; // <- escapes as a bare SyntaxError throw new TransportError(cause); } } raiseForStatus deliberately relies on that SyntaxError to detect "error body isn't JSON", which is why it is rethrown here — but on the success path (request() → return await readResponseJson(res)) nothing converts it into a Caura error. Steps to reproduce Mock fetch to return new Response("<html>login</html>", { status: 200 }), then call client.health() or client.write("x"). Expected: a CauraAPIError(200