Skip to content

release: 1.5.0 — conversation runs and could-not-process in the kit - #31

Merged
sanctrl merged 7 commits into
mainfrom
feat/could-not-process
Nov 19, 2026
Merged

sanctrl merged 7 commits into
mainfrom
feat/could-not-process

Conversation

@sanctrl

@sanctrl sanctrl commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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_template the loop stays in single-run mode, and the report route answers an older server's plain 404 as none.

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_ids lists at most 200; hidden_count is the total.
    • Sends POST /v1/conversations/{id}/processing-failures with an Idempotency-Key.
    • A 404 without CONVERSATION_NOT_FOUND / MESSAGE_NOT_FOUND (an older server) reads as { action: 'none', attempts: 0 }.
    • An unknown action reads as none.
  • getMessages takes afterMessageId and waitMs (the scoped long-poll). The new getMessagesPage also returns waitedMs and scopedWaitSupported. A server that predates the scoped wait ignores wait_ms / after_message_id and answers the newest page, newest first. scopedWaitSupported is then false: waitMs > 0 and no X-AgentChat-Waited-Ms came back. It is null for a plain read.
  • New fields:
    • Message.could_not_process ({ at, original_type }) and InboxCardPreview.could_not_process;
    • Message.client_msg_id becomes 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 on id, and gap-fill and ordering use seq;
    • Texts.conversation_run_template and Texts.could_not_process_note;
    • ErrorCode.COULD_NOT_PROCESS;
    • the ProcessingFailure* types.

Kit (integration.ReceiveLoop)

  • Conversation runs (single-run mode). Used when the served texts carry conversation_run_template; conversationRuns: false turns them off.
    • One run per owed card, for that one conversation (kind: 'conversation', conversationId; prompt from conversationRunPrompt), plus one invite run (kind: 'invite').
    • Owed means an unmuted card with a preview. A notices-only card (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 is nothing_owed, and the readiness probe is not called.
    • Runs take slots like turns (maxConcurrentTurns, default 1). A conversation whose run is running or waiting is held out of later cycles.
    • D5 pacing applies after a completed run that left its card at the same anchor.
    • The loop records no verdicts for cards.
    • The cycle outcome is runs_started. idle() and stop() wait for the runs.
    • A tray that cannot be read starts no run (tray_failed): one run for the tray would undo the walls.
    • Old texts behave exactly as before (kind: 'tray'), the unreadable-tray run included.
  • Failure report (both modes). Covers a failed or timed-out conversation run, reply turn, or single-card gate call.
    • Reported only with evidence, under the rule both kits share (the Python kit gets the same change):
      • (a) a later completion of the same kind of work (gate for gate, turn for turn, run for run) for a different conversation, after the failed one started. A completion on the failing conversation's own card never counts, nor does an invite's.
      • (b) the new 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.
      • A timed_out failure needs (a), never (b) alone: a timeout is ambiguous (a brownout, a hung hook), and the check does not exercise those paths.
    • Order: the failure waits; the work already queued runs first, and the runtime check is asked only once nothing of that kind is queued. The wait lasts at most 10 minutes. If the runtime check fails, the failure is dropped.
    • A run or turn that answered, or recorded a verdict, before it failed (read on a fresh tray) is not reported, nor is one stop() cut short.
    • 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 is deciding starts after that cycle's own turns. A gate call after hidden waits for the next cycle, so it sees the fresh card.
    • paused / none stop for that conversation, and a run for it still waiting for a slot does not start.
    • At most 3 re-runs per conversation per cycle.
    • Each report is a processing_failure event; status().processingFailures counts reports, answers and re-runs.
  • Gate-chunk split (gate-call mode).
    • A chunk of more than one card that fails closed is re-gated one card per call in the same cycle, before any turn starts.
    • A card whose last gate call failed is gated alone, after the chunks.
    • 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: a split_stopped event, splitStopped in the summary.
    • New counters: splitCallsOk / splitCallsFailed, and processingFailures.splitsStopped. Split calls' gate_chunk events carry split: true.
  • RunEnd.timedOut and TurnEnd (failed) timedOut are added, so a report can say timed_out.

Conformance fixtures: the published texts.sample.json now carries conversation_run_template and could_not_process_note. It and manifest.sha256 are 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-check clean. pnpm run test: 889 passed in 30 files (839 before; 50 new). The new tests cover:

    • the 3-message span (one report through the card anchor; the server picks the span);
    • retry → hidden → re-run, after the queued runs: the queued run is the evidence first, the runtime check (nothing queued) next;
    • several conversations failing together: a passing check reports none of them;
    • only the same kind counts: an invite run is no evidence for a conversation run, and a gate call on the failing card's own conversation is no evidence for its turn;
    • an unreadable tray in conversation-run mode starts no run (tray_failed);
    • the split guard: it goes on while checkRuntime passes, else split_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;
    • an older server's answer to the scoped wait → scopedWaitSupported: false;
    • a hidden message without client_msg_id flows through the live path (deduped by id, acked), the gap-fill and the offline drain;
    • hidden_count comes through on the report's answer;
    • the published fixture's own conversation_run_template starts conversation runs;
    • paused stops, including a waiting run;
    • no evidence → no report, and the next completion reports what waits;
    • a failed runtime check drops the failure;
    • an older server's plain 404 → none (end-to-end through AgentChatClient);
    • old texts and conversationRuns: false → one tray run, unchanged;
    • a notices-only card is not owed in conversation runs (nothing_owed, no run, no readiness probe; it runs once a real message arrives), and the tray run is unchanged;
    • the chunk split, with retry and hidden re-gates;
    • reply-turn failures;
    • the cap of 3;
    • the 10-minute evidence window;
    • the hold until the server answers.

    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 build OK, pnpm audit --prod --audit-level high clean, scripts/check-contract-fixtures.sh matches the published contract. pnpm run lint has 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:

    • a stale card re-queued mid-gate;
    • a passing runtime check during a provider outage could keep the split going;
    • held failures reported after an outage ended (now a 10-minute window);
    • the tracker released before the server answered;
    • a decided chunk clearing undecided cards;
    • a misleading next;
    • a turn re-run starting mid-gate;
    • a retired word;
    • a runtime check made when nothing could be reported;
    • 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

  • Gate-call hosts see more model calls when a chunk fails: one per card of the failed chunk, stopping after two failures in a row.
  • Single-run hosts change only once the server serves the template. Then one run per conversation replaces one run per tray: more runs, each smaller; notices-only cards get no run. conversationRuns: false restores the tray run.
  • Message.client_msg_id becoming optional is a type change for readers: code that reads it must allow undefined.
  • Rollback: revert this PR. The new fields are optional, and an older client simply never reports.

…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 sanctrl changed the title could not process: conversation runs, the gate-chunk split, and the failure report release: 1.5.0 — conversation runs and could-not-process in the kit Nov 19, 2026
@sanctrl
sanctrl enabled auto-merge (squash) November 19, 2026 23:22
@sanctrl
sanctrl merged commit d6b74a3 into main Nov 19, 2026
4 of 5 checks passed
@sanctrl
sanctrl deleted the feat/could-not-process branch November 19, 2026 23:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant