Repository navigation
sdk: handle gateway contract v2 (committed slow answers, new receipt headers, non-success finishes) - #12
Conversation
…headers, non-success finishes)
|
| const committed = isCommitted(response.headers); | ||
| let cut: unknown; | ||
| data = await parseJson(response).catch((cause: unknown) => { |
There was a problem hiding this comment.
If the gateway or a proxy sends committed response headers but leaves the body open without sending more data, the TypeScript client can wait indefinitely. The request timer ends at the headers, and the body read has no idle limit. Bound that read before merging so the caller can receive an error or retry.
Knowledge Base Used: SDK client and transport
Artifacts
Local HTTP committed-response reproduction script
- The authored script runs Transport against a local server in completed-body and open-body modes, providing the executed source.
Completed committed response output
- The completed-body command resolved with the expected answer and exit code 0, establishing the comparison case.
Open committed response output
- The open-body command remained pending beyond both configured timeouts and rejected only after caller abort, confirming the hang.
Ran code and verified through T-Rex
Prompt To Fix With AI
This is a comment left during a code review.
Path: src/transport.ts
Line: 182-184
Comment:
**Slow answer can hang forever**
If the gateway or a proxy sends committed response headers but leaves the body open without sending more data, the TypeScript client can wait indefinitely. The request timer ends at the headers, and the body read has no idle limit. Bound that read before merging so the caller can receive an error or retry.
**Knowledge Base Used:** [SDK client and transport](https://app.greptile.com/conifer/-/custom-context/knowledge-base/coniferkit/use-conifer/-/docs/sdk-client-transport.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| const { status, headers: carried } = member as { status?: unknown; headers?: unknown }; | ||
| if (typeof status !== "number" || !Number.isInteger(status)) return undefined; | ||
| const named = new Map<string, string>(); | ||
| if (typeof carried === "object" && carried !== null) { |
There was a problem hiding this comment.
If a committed answer contains conifer_receipt: {"status": 200} but omits headers, both clients accept it and return the answer without settled cost or routing details. Require the carried headers object before treating the answer as complete; this is a non-blocking concern with incomplete gateway envelopes.
Knowledge Base Used:
Artifacts
Before-and-after verification command
- Runs both focused client mocks against temporary guarded copies and the checked-out source, showing how the comparison was executed.
- Calls the TypeScript chat client with a mocked committed HTTP 200 OK response that omits receipt headers.
- Calls the Python chat client with the same mocked committed HTTP 200 OK envelope.
Guarded-copy responses reject the missing-header envelope
- Both executed clients reject the mocked HTTP 200 OK envelope under a temporary header-shape guard, rather than return an answer without a receipt.
Checked-out clients return answers without settled receipts
- Both executed clients accept the mocked HTTP 200 OK envelope and return the answer with null cost and effective model, confirming the defect.
Ran code and verified through T-Rex
Prompt To Fix With AI
This is a comment left during a code review.
Path: src/keepalive.ts
Line: 31-34
Comment:
**Answer can lose its receipt**
If a committed answer contains `conifer_receipt: {"status": 200}` but omits `headers`, both clients accept it and return the answer without settled cost or routing details. Require the carried headers object before treating the answer as complete; this is a non-blocking concern with incomplete gateway envelopes.
**Knowledge Base Used:**
- [SDK receipts and errors](https://app.greptile.com/conifer/-/custom-context/knowledge-base/coniferkit/use-conifer/-/docs/sdk-receipts-and-errors.md)
- [Python client and receipts](https://app.greptile.com/conifer/-/custom-context/knowledge-base/coniferkit/use-conifer/-/docs/python-client-and-receipts.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| try: | ||
| text = response.read().decode("utf-8") | ||
| except (http.client.IncompleteRead, ConnectionError) as cause: |
There was a problem hiding this comment.
If an EOF-delimited committed answer ends midway through a UTF-8 character, Python raises UnicodeDecodeError outside the connection-error retry path. The caller sees a decoding exception after one request instead of a retry under the same key. This is a non-blocking failure for cut responses; treat the decoding error as a cut committed response.
Knowledge Base Used: Python client and receipts
Artifacts
Local HTTP reproduction script
- The authored script sends a committed response cut mid-character, then a valid response; its optional in-memory exception-tuple change tests the proposed fix without modifying tracked code.
Unmodified client run with a cut UTF-8 response
- The executed request raised UnicodeDecodeError after one POST, showing that the retry was bypassed.
Client run with an in-memory exception catch
- The same request completed after two POSTs bearing the same idempotency key, showing that the catch enables the existing retry path.
Ran code and verified through T-Rex
Prompt To Fix With AI
This is a comment left during a code review.
Path: python/conifer_sdk/transport.py
Line: 50-52
Comment:
**Cut answer skips retry**
If an EOF-delimited committed answer ends midway through a UTF-8 character, Python raises `UnicodeDecodeError` outside the connection-error retry path. The caller sees a decoding exception after one request instead of a retry under the same key. This is a non-blocking failure for cut responses; treat the decoding error as a cut committed response.
**Knowledge Base Used:** [Python client and receipts](https://app.greptile.com/conifer/-/custom-context/knowledge-base/coniferkit/use-conifer/-/docs/python-client-and-receipts.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
This catches both clients (TypeScript and Python, kept in parity) up to what the live gateway ships. The live build is typhoon
e5e9eca, perapi.conifer.build/healthz.Committed slow answers (the correctness fix)
Since 2026-09-30, a non-streaming call still running at 285 s is answered with a provisional
200markedx-conifer-keepalive: committed. Whitespace heartbeats follow, then the real body withconifer_receipt: {status, headers}appended. Before this PR, both clients returned such an answer with an empty receipt, and a committed error came back as a successful completion with no choices. Newsrc/keepalive.ts/python/conifer_sdk/keepalive.pyfix this:conifer_receipt, and that member is stripped from the returned data.conifer_receipt, raises a retryableConiferConnectionErrorand is retried under the same idempotency key. That cut is how the gateway ends an uncharged failure.Transport.request()now also returnsheaders, which chat, embeddings and jobs read the receipt from.Charged errors are never retried
ConiferError.receiptholds the receipt of an error that carries one, andretryableis false whenever it is set. This uses the gateway's own classifier: response-keepalive'scarries_execution_receipttreats any receipt header as "money may have moved". A charged 502 or "retry shortly" 409 would otherwise have been re-sent and paid twice. Stream error frames are excluded, because a stream's head carries identity headers even when nothing was charged. The private beta cost headers aren't in the SDK's list, so a charged beta-router error is not covered. In TypeScript,retryableonConiferRateLimitErrorandConiferUnavailableErrorwidens fromtruetoboolean.Receipt fields
pricingIdentity(x-conifer-pricing-identity) andpinFallback(x-conifer-receipt-pin-fallback), in snake_case in Python.Non-success finishes
Completions expose
finishReason,providerStopReasonandproviderStopDetails. A newincompleteReason(completion)(completion.incomplete_reason) flags anything other thanstoportool_calls: that coverslength,content_filter,pause_turn,incomplete, a missing value and any unknown value. These turns are flagged, not thrown, like empty andlengthanswers already are. The turn was charged, and apause_turnis continued by sending its output back. They are never retried and never advance a client-side fallback chain. The MCP tools returnincomplete_reasontoo.Contract and streams
contracts/gateway-contract.jsonmoves to v2, withoutmodel_managementand the privatebeta_*fields.STREAM_IDLE_MSchanges from 120 000 to 280 000, matching the gateway's new stream idle bound.: keep-alivecomments are skipped and restart the idle clock, and that a late in-band error on a committed stream throws the typed error.Everything goes under
## [Unreleased]in the CHANGELOG. There is no version bump and nothing is published; releasing is a human step (RELEASING.md).Verification (no CI evidence yet; live QA not run because it spends money)
npm run build && npm test: 246/246 pass (223 before).CONIFER_TEST_COMPILE=1 npm test: 246/246.npm run typecheck: clean.python3 -m pytest -q: 159 passed and 14 subtests passed (138 before).unittest discover: 159 OK.check-changelog: ok.Known gaps
ReceiptCollector/SpendBudgetread headers only, so they still record nothing for a committed response. Fixing that means reading a cloned body.conifer-workspace/sdk/, which hasn't absorbed Refuse inexact Helicone quotas and cost ceilings in both clients #11 either. The workspace copy needs this change ported before the nextpublic-split.shrun, or the split will revert it.