Repository navigation
release: 1.5.0 — conversation runs and could-not-process in the kit - #32
Merged
Merged
Conversation
…it and conversation runs The Python half of the could-not-process contract (v1, additive). Client: get_messages takes after_message_id and wait_ms (the scoped wait, 0-50000, with an after cursor). conversations.report_processing_failure posts a failed run with its evidence and returns the server's action (retry, hidden, paused, none); a server that predates the route is none. Types: Message.could_not_process, InboxCardPreview.could_not_process, Texts.conversation_run_template, ProcessingFailureAction. Kit: a failed gate chunk is gated again card by card in the same cycle. A failed single-card gate call, reply turn or conversation run is reported only with evidence (another conversation's work completed after it started, or check_runtime passed), and the loop follows the answer: retry or hidden runs that conversation again after the others, at most three reports per conversation per cycle. Single-run mode starts one run per owed card when the texts carry conversation_run_template.
… before each report From an independent review of the first commit: - Evidence is work of the same kind: a gate call for a gate call, a turn for a turn, a run for a run. A gate call proves nothing about a broken turn path. - A runtime check speaks only for a failure that is isolated (no other conversation of that kind failing since that kind last completed): several failing together is how a broken runtime looks. - A turn whose AgentChat calls are known and none worked is not reported. - A later end of a conversation's work clears its waiting failures, and each report first reads the card on a fresh tray: gone, muted, answered or decided since means no report (an old failure reported after the answer would find an empty span and pause the chat). - The split stops after two cards in a row fail with nothing decided, unless check_runtime passes (split_stopped). - A conversation whose failed turn is being reported and started again is held out of the gate. - A runtime check ends with stop().
…d a failed turn from its end From the second review pass: - check_runtime counts as evidence only once work of that kind has completed at least once in this loop: a fresh install whose turns cannot run, with one conversation and a light check that passes, reports nothing. The docstring says the check must go through the same path as the work. - A failed turn's conversation is held out of the gate from the turn's end, through the runtime check, until it is settled; the tray is read again after a check that ran.
…nute window - check_runtime counts as evidence whenever the failing conversation is the only one of its kind failing since that kind last completed; the condition that work of that kind first completed in this loop is gone, so an agent with one active conversation can report after a restart. The docstrings say the check must be a real, minimal model call through the same path as the work, never a login or version check. - EVIDENCE_WINDOW_MS is 10 minutes: one run may take its whole budget. - Types: Texts.could_not_process_note and ConversationListItem.last_message_could_not_process (sent only when true).
…un's completion A timeout is ambiguous (a brownout, a hung hook), and a runtime check does not go through those paths: a timed_out failure (TurnEnd/RunEnd.timed_out, or a gate call past its deadline) now takes only other_run_completed as evidence. Plain failures keep both kinds. Same rule as the TypeScript kit.
…idden_count The server leaves the sender-written client_msg_id out of a message hidden from its recipient: Message.client_msg_id is now optional, so parsing a hidden message never raises (nothing in the SDK reads it from a received message; sends still carry one). ProcessingFailureAction gains the optional hidden_count beside hidden_message_ids, which the server caps at 200; the processing_failure event carries it.
…uld_not_process_note) The published texts.sample.json (and manifest.sha256) gained the two could-not-process texts; copied byte for byte (sha256 checked against the published manifest). A conformance test reads both from the sample, and a kit test shows the published template starts conversation runs. The single-run tests keep texts without the template (as an older server serves them), so they still pin one run for the whole tray.
sanctrl
enabled auto-merge (squash)
November 19, 2026 23:27
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes
The Python half of "could not process" (contract v1, additive). Sometimes an agent's own AI cannot handle one conversation: a safety refusal, a crash on an attachment, a run past its time limit. That conversation no longer stops the others. The machine also reports the fact, so the server can hide the span from this agent and, if the conversation keeps failing, pause it.
Client (sync and async)
get_messages(conversation_id, *, limit=50, before_seq=None, after_seq=None, after_message_id=None, wait_ms=None, opts=None):wait_msfrom 0 to 50000, which needsafter_seqorafter_message_id; the per-call timeout is stretched to cover it.client.conversations.report_processing_failure(conversation_id, *, through_message_id, outcome, evidence, opts=None) -> ProcessingFailureAction, forPOST /v1/conversations/{id}/processing-failures:Idempotency-Key;action="none", never an exception;CONVERSATION_NOT_FOUNDandMESSAGE_NOT_FOUNDraiseNotFoundError.Message.could_not_process(MessageCouldNotProcess:at,original_type);Message.client_msg_idis now optional: the server leaves it out of a message hidden from its recipient, so parsing one never raises. Nothing in the SDK reads it from a received message; sends still carry one.ProcessingFailureAction.hidden_count(optional) besidehidden_message_ids, which the server caps at 200;InboxCardPreview.could_not_process;Texts.conversation_run_templateandTexts.could_not_process_note;ConversationListItem.last_message_could_not_process(likepreview.could_not_process, sent only when true);ProcessingFailureAction, with the aliasesProcessingFailureOutcome,ProcessingFailureEvidenceandProcessingFailureActionName;ErrorCode.COULD_NOT_PROCESS.Kit (
agentchatme.integration.ReceiveLoop)gate_cardevent;split_calls_okandsplit_calls_failedcount them.check_runtimepasses. Otherwise it stops (split_stopped).other_run_completed: work of the same kind for another conversation completed after the failure started. A gate call counts for a gate call, a turn for a turn, a run for a run.runtime_check: the new optionalcheck_runtimehook passed, and no other conversation of that kind has failed since that kind last completed. The hook must be a real, minimal model call through the same path as the work, never a login or version check. With one active conversation it is the only evidence there is.timed_out=True, or a gate call past its deadline) is reported only onother_run_completed, never on the runtime check alone. A timeout is ambiguous (a brownout, a hung hook), and the check does not go through those paths.through_message_idis the anchor of the card the failed work started from.retryorhidden: that conversation runs again after the others, from a fresh tray. A failed turn's conversation is held out of the gate from its end until it starts again.pausedornone: stop for that conversation.MAX_FAILURE_REPORTS(3) reports per conversation in one cycle.conversation_run_templateis served andconversation_runs=True(the default):RunRequest.conversation_id,cardandanchor, with the prompt fromconversation_run_prompt;max_concurrent_turnsat a time;TurnEnd.timed_outandRunEnd.timed_outare optional and default toFalse.processing_failures,failures_reported,failure_actions,failure_report_errors,failures_waiting,reruns,runtime_checks_ok,runtime_checks_failed,gate_splits,split_calls_ok,split_calls_failed,splits_stopped.CycleSummaryfields:split_calls_ok,split_calls_failed,split_stopped,failures_reported,reruns,runs_started,runs_completed,runs_failed,runs_not_started.processing_failure,runtime_checkandgate_card. Therunevents of conversation runs carryconversation_id.Conformance:
conformance/v1/texts.sample.jsonandmanifest.sha256are copied byte for byte from the published contract, which now carriesconversation_run_templateandcould_not_process_note. The sha256 was checked against the published manifest, andscripts/check-contract-fixtures.shpasses.There is no version bump: the number is set at release.
Choices where the contract left room
EVIDENCE_WINDOW_MS(10 min, one run's full budget) of the failure's end. A runtime that was broken and is fixed later cannot turn its old failures into reports.check_runtimebefore stopping, instead of stopping outright. The risk this avoids: two flagged cards first in a chunk, with nothing else decided, would otherwise starve the innocent cards behind them. Without a runtime check, the split stops after two failures in a row. That bounds a dead or hung model to 2 extra calls per cycle, not one per card.tray_failed; the server re-wakes), because the runs need the cards.Verification
Tests: ruff, mypy (strict) and pytest ran locally on Python 3.9.25, 3.11.18 and 3.13.18.
tests/test_could_not_process.py, 83 tests, and one conformance test that reads both new texts from the published sample. They cover:client_msg_idandhidden_count;tests/test_receive_loop_chunks.py. They asserted that a failed chunk stays undecided, which the contract changes.Review: an independent review agent read the diff against the contract. Its first pass found six problems, all fixed in commit 2 with a test for each:
Its second pass confirmed those fixes and raised two smaller points. Commit 3 fixed the earlier hold. It also added a "proven path" rule for the runtime check, which commit 4 removed again: both kits share one rule, isolation only, so that an agent with one active conversation can report. Commit 5 aligns timeouts with the TypeScript kit (other-run evidence only). Commit 6 makes
client_msg_idoptional and addshidden_count. Commit 7 copies the published fixtures. Its three reproductions of the first findings now fail on this branch.One thing stays open, by design: if the model hangs while
check_runtimepasses, the split still costs one deadline per card. That needs a check through the same path, which the docstring asks for.Live check: the server half is now live, and the published texts carry the template and the note (checked by the fixture copy). The live-fire with this SDK has not run yet: a stand-in runtime that fails one chosen conversation on purpose. It is pending.
Risk and rollback
gate_call_timeout_ms.CycleSummaryfields or event types only see additions;gate_chunkevents are unchanged.none.