Repository navigation
release: 1.5.0 — conversation runs and could-not-process in the kit - #31
Merged
Merged
Conversation
…ailure report
A message the recipient's AI cannot process (a provider refusal, a crash,
a timeout) failed every run that held it: in single-run mode the whole
tray, for every peer, and that one conversation for good in every mode.
- client.conversations.reportProcessingFailure(conversationId,
{ throughMessageId, outcome, evidence }): POST
/v1/conversations/{id}/processing-failures with an Idempotency-Key;
answers { action: retry | hidden | paused | none, attempts,
hidden_message_ids, paused_until }. An older server's plain 404 reads as
{ action: 'none', attempts: 0 }.
- getMessages / getMessagesPage take afterMessageId and waitMs (the scoped
wait); getMessagesPage returns waitedMs.
- Types: Message.could_not_process, InboxCardPreview.could_not_process,
Texts.conversation_run_template, ErrorCode.COULD_NOT_PROCESS, the
ProcessingFailure* types.
- ReceiveLoop, single-run: conversation runs whenever the texts carry
conversation_run_template (conversationRuns: false keeps the tray run):
one run per owed card for that one conversation, one invite run, slots
as turns, held out of later cycles while running or waiting, D5 pacing
after a completed run at the same anchor, no verdicts recorded. Old texts
behave exactly as before. RunRequest.kind / conversationId,
RunEnd.timedOut, TurnEnd (failed).timedOut.
- ReceiveLoop, both modes: a failed or timed-out conversation run, reply
turn or single-card gate call is reported only with evidence (another
run, turn or gate call completed after it started, or checkRuntime()
passes); without it the failure waits for the next completion (at most
10 minutes), and is dropped when the runtime check fails. A run or turn
that answered or recorded a verdict before it failed is not reported.
The conversation stays held until the server answers. retry / hidden run
it again after the others already queued (a reply turn asked for while a
gate decides starts after that cycle's turns); paused / none stop, and a
waiting run for it does not start; at most 3 re-runs per conversation per
cycle. processing_failure events and status().processingFailures.
- ReceiveLoop, gate-call: a failed chunk of more than one card is re-gated
one card per call in the same cycle before turns start; a card whose
last gate call failed is gated alone after the chunks; the split stops
after two single-card failures in a row (only a decided call resets it).
Four chunk tests that pinned "a failed chunk's cards wait for the next
wake" now expect the split; their chunk-level checks are kept.
In conversation-run mode a card whose only unread messages are system notices (preview null: a member joined or left, a rename) no longer gets a run of its own: a whole model run to look at "X joined" costs the owner for nothing. It waits on the tray, and the next run of that conversation (a real message) reads through it. Notices never wake (contract v1 §4), so nothing loops. A tray of such cards only is nothing_owed, with no readiness probe. One run for the tray (texts without the template) is unchanged.
- Evidence (a): a later completion of the same kind of work (a gate call for a gate call, a turn for a turn, a run for a run) for a different conversation, after the failed one started. A completion on the failing conversation's own card no longer counts, nor does an invite's. - Evidence (b): checkRuntime() passes, only while no other conversation of that kind has failed since that kind last completed (several failing together is the runtime). - Order: the failure waits; the queued work runs first, and the runtime check is asked only once nothing of that kind is queued (for a gate call, the end of the cycle's single-card calls). The window stays 10 minutes. - Conversation runs: a tray that cannot be read starts no run (tray_failed); one run for the tray would undo the walls. One run for the tray (texts without the template) is unchanged. - Split guard: after two single-card failures in a row with nothing decided in the cycle, the split goes on only if checkRuntime() passes; otherwise it stops (split_stopped event, splitStopped in the summary, processingFailures.splitsStopped).
…on an older server - A timed_out failure (RunEnd / TurnEnd timedOut, a gate call past its deadline) is reported only on other_run_completed evidence, never on checkRuntime() alone: a timeout is ambiguous (a brownout, a hung hook) and the runtime check does not exercise those paths. Plain failed keeps both kinds of evidence. - getMessages docs: a server that predates the scoped wait ignores wait_ms and after_message_id and answers the newest page, newest first; callers must detect it. getMessagesPage returns scopedWaitSupported (false when waitMs > 0 and no X-AgentChat-Waited-Ms came back; null for a plain read).
…_count - Message.client_msg_id is optional: the server omits it (a sender-written field) on a message hidden from its recipient. Nothing in the SDK or kit reads it on a received message (dedup keys on id, gap-fill and ordering on seq, the drain validates id / conversation_id / delivery_id); tests now prove a hidden message without it flows through the live path, the gap-fill and the offline drain. - ProcessingFailureAction.hidden_count (optional): the total hidden; hidden_message_ids lists at most 200.
…uld_not_process_note) The published texts.sample.json now carries conversation_run_template and could_not_process_note; texts.sample.json and manifest.sha256 are byte-identical to agentchat.me/contract/v1/conformance/. Texts gains could_not_process_note. The single-run tests that pin one run for the tray now use the texts as an older server served them (no template); a new test starts conversation runs from the published template itself.
sanctrl
enabled auto-merge (squash)
November 19, 2026 23:22
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
A message the recipient's AI cannot process (a provider refusal, a crash, a timeout) used to fail every run that held it. In single-run mode that meant the whole tray, for every peer; in every mode, that one conversation for good. This is the TypeScript SDK half of "could not process" (contract v1, additive). The server half serves the new route and texts. Until it ships, nothing here changes behaviour: without
conversation_run_templatethe loop stays in single-run mode, and the report route answers an older server's plain 404 asnone.Client and types
client.conversations.reportProcessingFailure(conversationId, { throughMessageId, outcome: 'failed' | 'timed_out', evidence: 'other_run_completed' | 'runtime_check' })→{ action: 'retry' | 'hidden' | 'paused' | 'none', attempts, hidden_message_ids, hidden_count?, paused_until }.hidden_message_idslists at most 200;hidden_countis the total.POST /v1/conversations/{id}/processing-failureswith an Idempotency-Key.CONVERSATION_NOT_FOUND/MESSAGE_NOT_FOUND(an older server) reads as{ action: 'none', attempts: 0 }.none.getMessagestakesafterMessageIdandwaitMs(the scoped long-poll). The newgetMessagesPagealso returnswaitedMsandscopedWaitSupported. A server that predates the scoped wait ignoreswait_ms/after_message_idand answers the newest page, newest first.scopedWaitSupportedis thenfalse:waitMs> 0 and noX-AgentChat-Waited-Mscame back. It isnullfor a plain read.Message.could_not_process({ at, original_type }) andInboxCardPreview.could_not_process;Message.client_msg_idbecomes optional: the server omits it on a message hidden from its recipient. Nothing in the SDK or kit reads it on a received message: dedupe keys onid, and gap-fill and ordering useseq;Texts.conversation_run_templateandTexts.could_not_process_note;ErrorCode.COULD_NOT_PROCESS;ProcessingFailure*types.Kit (
integration.ReceiveLoop)conversation_run_template;conversationRuns: falseturns them off.kind: 'conversation',conversationId; prompt fromconversationRunPrompt), plus one invite run (kind: 'invite').preview: null: "X joined", a rename) gets no run of its own; it waits on the tray, and the next run of that conversation reads through it. Notices never wake, so nothing loops. A tray of only such cards isnothing_owed, and the readiness probe is not called.maxConcurrentTurns, default 1). A conversation whose run is running or waiting is held out of later cycles.runs_started.idle()andstop()wait for the runs.tray_failed): one run for the tray would undo the walls.kind: 'tray'), the unreadable-tray run included.checkRuntime()option passes, but only while no other conversation of that kind has failed since that kind last completed. Several failing together is the runtime.timed_outfailure needs (a), never (b) alone: a timeout is ambiguous (a brownout, a hung hook), and the check does not exercise those paths.stop()cut short.retry/hiddenrun it again after the others already queued. A reply turn asked for while a gate is deciding starts after that cycle's own turns. A gate call afterhiddenwaits for the next cycle, so it sees the fresh card.paused/nonestop for that conversation, and a run for it still waiting for a slot does not start.processing_failureevent;status().processingFailurescounts reports, answers and re-runs.checkRuntime()passes. Otherwise it stops: asplit_stoppedevent,splitStoppedin the summary.splitCallsOk/splitCallsFailed, andprocessingFailures.splitsStopped. Split calls'gate_chunkevents carrysplit: true.RunEnd.timedOutandTurnEnd(failed)timedOutare added, so a report can saytimed_out.Conformance fixtures: the published
texts.sample.jsonnow carriesconversation_run_templateandcould_not_process_note. It andmanifest.sha256are copied byte for byte. The single-run tests that pin one run for the tray now use the texts as an older server served them (no template).Docs: the receive-loop header,
docs/integration-kit.md(single-run, gate-call, and a new "Could not process" section), the README API reference, and the CHANGELOG under Unreleased. No version bump.Verification
Tests:
pnpm run type-checkclean.pnpm run test: 889 passed in 30 files (839 before; 50 new). The new tests cover:tray_failed);checkRuntimepasses, elsesplit_stopped;timed_out(run, turn, gate call) is reported only when the same kind of work completes for another conversation, never on the runtime check alone;scopedWaitSupported: false;client_msg_idflows through the live path (deduped by id, acked), the gap-fill and the offline drain;hidden_countcomes through on the report's answer;conversation_run_templatestarts conversation runs;none(end-to-end throughAgentChatClient);conversationRuns: false→ one tray run, unchanged;nothing_owed, no run, no readiness probe; it runs once a real message arrives), and the tray run is unchanged;Four existing chunk tests pinned "a failed chunk's cards wait for the next wake". They now expect the split, and their chunk-level checks are kept.
pnpm run buildOK,pnpm audit --prod --audit-level highclean,scripts/check-contract-fixtures.shmatches the published contract.pnpm run linthas no linter configured.Review: an independent code review (medium) of the diff found 10 issues. All are fixed here, each with a test where it is reachable:
next;waitMs< 1.Live check: n/a until the server half ships (
processing-failures, the scoped wait,conversation_run_template). Then a live-fire with a stand-in runtime that fails one chosen conversation on purpose.Risk and rollback
conversationRuns: falserestores the tray run.Message.client_msg_idbecoming optional is a type change for readers: code that reads it must allowundefined.