Skip to content

Integration kit + contract v1 in the SDK - #14

Merged
sanctrl merged 19 commits into
mainfrom
feat/integration-kit
Nov 8, 2026
Merged

sanctrl merged 19 commits into
mainfrom
feat/integration-kit

Conversation

@sanctrl

@sanctrl sanctrl commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

The Python twin of agentchatme/agentchat-typescript#14: the integration kit (agentchatme.integration) and the SDK changes for AgentChat contract v1 — identical behaviour, byte-identical conformance fixtures (conformance/v1/, guarded by manifest.sha256 and a CI check against the published contract).

  • Kit: ReceiveLoop (gate-call / single-run; max_concurrent_turns 1; 60 s pacing; gate-call deadline and cycle watchdog; invites=1; no local retry ladder — the server re-wakes), turn_outcome/invite_outcome/apply_outcome(_async) (the contract's reply rule), TurnTracker (thread-safe release), WakeCoalescer, TextsCache, ManualSync, anchor, probe_hosted_tools(_async).
  • SDK: handlers dispatched off the receive loop, one at a time per conversation (behaviour change, in the CHANGELOG); ack offered only while a handler is attached; heartbeat / rewake capabilities; bounded backlog (max_queued_messages) without pausing reads, intake_paused in status; 1013 retry_after handling; groups.dismiss_invite, wake_webhook.set/test/clear, verify_wake_webhook, sync(wait_ms)/sync_page, per-call retry (never on un-keyed POST/PATCH), decisions.record tolerant of empty 2xx; gate prompt from served texts with the 1.2 wording as fallback.
  • Upgrade safety: Hermes 0.4.3's own suite passes against this branch (618). Tests run under a network guard.

Checks: ruff + mypy clean; pytest 714 passed on 3.9–3.13. Two independent reviews, all findings fixed. Proposed release 1.3.0 (added behaviour → minor, per VERSIONING.md).

…elivered late; no ack without a handler

- message.new and every server-frame handler start in arrival order and run
  off the receive loop; a slow handler never holds up the next frame, other
  frames' acks or the transport's pongs. The drain awaits the settlements
  before it moves the ack cursor; disconnect() gives running handlers a
  short grace, then releases them.
- A row below the connection's seq anchor is handed over late, out of
  order (the dedup cache decides what is a repeat), never dropped: the
  drain cursor no longer stalls behind stored rows a live frame anchored
  past (TypeScript SDK parity).
- A frame is never acked while no message.new handler is attached, in
  either ack mode; the drain covers nothing then.
- In-flight dedupe holds across reconnects: a re-offer whose first copy is
  still with the handlers adopts it; each copy is acked on the socket it
  arrived on, once.
- Capabilities: heartbeat advertised (arms the idle watchdog on sockets
  without ping); rewake opt-in (RealtimeOptions.rewake); the unanswered
  wake shape is validated; negotiated set exposed as .capabilities.
- Connect budget: HTTP 429 before the upgrade and close 1013 after HELLO
  are backoff with the server's delay (capped at an hour), never blocked.
…e kit parts

- Client: per-call retry override (CallOptions.retry); register sends no
  null optional fields; /context parity (get_conversation_context,
  get_direct_conversation_context); client.groups.dismiss_invite (auto
  Idempotency-Key); client.wake_webhook.set/test/clear incl. rewake;
  sync(wait_ms) long-poll and sync_page with waited_ms,
  poll_interval_seconds, request_id, headers.
- Types: tray v1 (version, invites, invites_truncated), texts gate-call
  fields and manual sha256, unanswered wake, heartbeat frame, socket
  capabilities, wake webhook status/test/clear/payload, conversation
  context.
- verify_wake_webhook for the agentchat, hermes and standard-webhooks
  dialects; connect_budget_delay_ms (D8) shared by the socket.
- gate.build_prompt / run / run_async take the served gate_call_preamble
  and gate_call_answer_format (D6); without them the gate fails closed.
- Socket: capabilities option (heartbeat on by default, rewake opt-in);
  connect budget delay replaces the backoff step; acks after a reconnect
  go out on the current socket; wake validation per contract v1.
- agentchatme.integration: WakeCoalescer, turn_outcome / invite_outcome /
  apply_outcome / apply_invite_outcome, anchor.render/find/replace/remove.
- Conformance v1 fixtures copied byte-identical from the TypeScript SDK
  (engine-scenarios gains reconnect and no_handler).
… in step with the TypeScript SDK

- TextsCache (file first, served copy never replaced by the file, 5 min to
  1 h retry, atomic 0600 file, change listeners), ManualSync / sync_manual
  (port of the agent-core served-manual rules: HTTPS and host pin, every
  redirect hop checked, size cap, sha256, BOM/CRLF, atomic write, old file
  kept on failure, optional fallback), TurnTracker (one turn per
  conversation or invite; still_running is not an end; release),
  probe_hosted_tools (initialize + tools/list), ReceiveLoop (gate-call
  and single-run modes; socket with ack_on_receipt, heartbeat, rewake;
  echo filter; D5 outcomes; no local retry ladder). Plain runtime
  callbacks run in a worker thread.
- gate: served gate-call texts win when passed; without them the previous
  wording (LEGACY_GATE_CALL_PREAMBLE, deprecated) renders the existing
  expected prompt byte for byte, so an upgrade alone changes nothing.
- conformance/v1 copied byte-identical from the TypeScript SDK
  (wake-webhook cases keep only the key's base64 body; the test builds
  the prefixed secret at run time); manifest.sha256 checked by a test.
- CHANGELOG: Unreleased entry for contract v1.
…load v1 reason and step

- conformance/v1 is now byte-identical to the core's canonical set
  (apps/web/public/contract/v1/conformance): texts.sample.json regenerated
  from the server (manual 2.3.0, the invite prompt names the tray), and
  wake-webhook-payload.v1.json (one payload per reason).
- WakeWebhookPayload accepts reason (messages, reminder, invite,
  unanswered, test) and step (unanswered only).
… from the TypeScript SDK's final set

- HELLO offers ack only while a message.new handler is attached; a
  capability holds only when offered and echoed.
- A close 1013 waits the server's delay only with retry_after=<s>; any
  other 1013 (the slow-consumer overload close) is the ordinary backoff.
- Without rewake, wake frames keep the 1.2 validation.
- In-flight adoption across reconnects is bounded (in_flight_adopt_ms,
  15 min).
- decisions.record succeeds on any 2xx; unechoed fields come from the
  request (id / created_at None).
- ReceiveLoop single-run mode: an invite still pending after two completed
  runs is dismissed (in memory); failed or not-started runs count for
  nothing (single_run_invite_cases).
- conformance/v1 byte-identical to the TypeScript SDK at 9e55894.
…e loop

Lead decision: the SDK hands messages to the app in seq order. Handlers run
on dispatch lanes — one serial lane per conversation (message.new and every
frame naming it), one for frames of no conversation (wake, presence,
invites) — so at most one handler runs per conversation, conversations run
concurrently, and the receive loop never waits for a handler. On an idle
lane a sync handler still runs at once and its ack goes out in arrival
order. disconnect() gives running lanes a short grace, then releases them
(their frames count as not handled). One engine-scenarios expectation still
encodes concurrent dispatch; it is overridden in the harness until the
shared fixture is regenerated (a test flags the change).
…ter stop; invites flag; static HTTP options

- ReceiveLoop: max_concurrent_turns (default 1): extra reply and invite
  turns wait for a slot, held out of the gate (nothing recorded, cards stay
  on the tray). D5 pacing: after a silent turn the conversation is not
  gated again at the same anchor for pace_ms (60 s) unless a newer message
  moves the anchor or an unanswered wake names it; no second invite turn
  for an invite within pace_ms unless an unanswered wake arrives. Optional
  shared turn_tracker. A turn that ends after stop() still has its outcome
  recorded. Wake events carry the wake reason (and the unanswered ids).
  Without the gate-call fields in the texts the loop gates with the legacy
  wording (tested).
- inbox.tray(include_invites=True) sends invites=1 (default off); the
  loop always sends it.
- register / verify / recover / recover_verify take timeout_ms and
  http_client; the client verify and recover_verify return uses them.
- Test data uses fictional example- handles.
…37a6

- Dispatch lanes: a handler that never finishes holds its conversation at
  most in_flight_adopt_ms (it keeps running; the next message goes on).
- The first message.new handler attached after a HELLO that offered no ack
  triggers one quiet reconnect (no error, no backoff step) so the next
  HELLO negotiates delivery acks; parked frames are handed over first.
- A per-call retry never makes a POST / PATCH without an Idempotency-Key
  retry.
- ReceiveLoop: a truncated tray is read again at once only after a cycle
  that recorded a verdict or started a turn, else after 1 s doubling to
  60 s; TurnTracker.holds() is checked after every await, so a released
  turn never records; status() marks turns past 30 min overdue; settled()
  is now idle().
- turn_outcome recognises the turn's own verdict by the
  your_last_decision key only (no clock).
- conformance/v1 byte-identical to the TypeScript SDK at 6ff37a6
  (fictional example- handles; the engine-scenarios override is gone; the
  harness checks serial_per_conversation).
…TypeScript SDK at 8c029e3

connect_budget_delay_ms(code=, reason=) takes the close: a 1013 with
retry_after=<s> waits the server's delay (1 s to 1 h, plus up to 10 %),
never blocked; any other 1013, and an upgrade answered with an HTTP status
(429 included, Retry-After ignored), takes the ordinary backoff.
conformance/v1 byte-identical to the TypeScript SDK at 8c029e3 (and the
core at 6173a6c).
…nded handler queue, connect handlers, words

- TurnTracker.release ends every wait on the turn at once (confirmed_end
  races the runtime's report) and tells on_release listeners; ReceiveLoop
  frees the slot of a released turn (also one released through a shared
  tracker) and starts the next waiting turn; a turn released while it
  waits never starts.
- RealtimeClient(max_queued_messages=1000): past it a new message.new is
  not taken in (no ack, ack_on_receipt included; no dispatch; the drain
  and gap fill stop), so the server keeps it; once the queue is back to
  half the client fetches it again (the REST drain, re-run if one was in
  flight; else one quiet reconnect). One notice per episode. Frame reads
  never pause.
- on_connect handlers run at hello.ok in order (a sync one before the next
  frame is read, as in 1.2); async ones are awaited before the reconnect
  drain starts. A socket handed in without this client's HELLO counts what
  this client would offer.
- send_message(opts=CallOptions(retry=...)) no longer raises TypeError
  (sync and async).
- No retired word left in src or tests (settle -> finish / outcome); the
  README describes wakes as message, reminder and unanswered; the webhook
  test secret is built at run time.
- CHANGELOG lists the behaviour changes and the type-level changes.
…utcomes

- ReceiveLoop(gate_call_timeout_ms=60_000): past it the gate fails closed
  for the cards (nothing recorded; the next wake asks again).
  gate.run_async(..., timeout_ms=) bounds the model call.
- ReceiveLoop(cycle_timeout_ms=600_000): a cycle running longer, not
  counting time spent starting turns or inside a single-run run, is
  abandoned (cancelled, logged, summarised as 'abandoned'); the coalescer
  takes wakes again, so a cycle that never finishes cannot leave the loop
  looking healthy while it processes nothing.
- status().recent_cycles: the last 20 cycle summaries, newest last.
…el call (TypeScript parity, fb0ea8b)

- Every step of a cycle checks that it is still the current one: an
  abandoned cycle starts no turn and records nothing more.
- A call_model that takes a cancel keyword gets a handle set when its
  answer is no longer wanted (gate-call deadline or an abandoned cycle):
  an asyncio.Event for a coroutine function, a threading.Event for a plain
  one, which runs in a worker thread and is simply no longer waited for.
An autouse fixture refuses every socket connect and name lookup for a
non-loopback destination and fails the test that tried, even when the code
under test swallowed the error. Loopback stays open for the local fake
servers; only the opt-in live smoke tests (@pytest.mark.live) are exempt.
The guard's own tests run it in an inner pytest.
…defer, not dismiss

TypeScript parity (18f333b):
- A failed reply turn is read on the fresh card like any other: the answer
  went out -> reply (a run that sent and then errored or hit its time limit
  is not gated again and answered twice); its own verdict or a card gone ->
  nothing; otherwise turn_failed, the card stays. A tray read that failed
  after a failed turn -> turn_failed. A failed turn never counts as silent.
- The second silent look records dismiss only when the turn's AgentChat
  calls are known and all succeeded. Unknown or partly failed ->
  record_defer through the gate's anchor, no category: unread, back on the
  reminder ladder.
- conformance/v1/turn-outcome.cases.json and manifest.sha256 copied
  byte-identical from the TypeScript kit.
…d_invites

- texts.sample.json and manifest.sha256 re-copied from core
  feat/gate-contract-v1 @ 49234ed (the manual sha moved); all 18 fixture
  files cmp-identical with core and with the TypeScript kit.
- ReceiveLoop dismiss_ignored_invites (default True), TypeScript parity
  (dismissIgnoredInvites, 0472332): False turns off the single-run invite
  dismissal (no read after the run, no outcome) for a host that forwards
  invites elsewhere.
…lly successful calls

TypeScript parity (60edaad):
- invite_outcome takes require_known_calls (default True): with it, the
  second silent invite turn dismisses only when the turn's AgentChat calls
  are known and none failed; otherwise nothing is recorded (new reason
  silent_unconfirmed) and the invite stays on the tray, bounded by the
  server's re-wakes and the 60 s pacing.
- Single-run mode passes require_known_calls=False (a run reports no
  counts): its invite rule is unchanged.
- conformance/v1/turn-outcome.cases.json and manifest.sha256 copied
  byte-identical from the TypeScript kit.
…ycles record nothing, single-run pacing

TypeScript parity (fe74e60):
F1 The in-flight adoption bound counts from when the conversation's lane
   starts the handler; an entry still waiting in its lane is always adopted.
F2 CI: a separate step compares conformance/v1/manifest.sha256 with the
   manifest agentchat.me publishes (outside the test network guard).
F3 Backpressure refuses intake for the whole episode until the queue is
   back to half (no frame overtakes one left with the server); gap-fill
   rows are never shed; a backpressure reconnect hands parked frames over
   only under ack_on_receipt (a renegotiation always).
F4 gate.run / run_async take cancel= (anything with is_set()): once set,
   nothing more is recorded and no reply is handed back. The loop passes
   its cycle's; a verdict in flight is shielded (never aborted) and holds
   its card out of the next gate, so nothing is recorded twice.
F5 A TurnTracker.release from another thread hands the loop's slot work to
   its event loop (call_soon_threadsafe): the waiting turn starts.
F7 Single-run invite pacing: the dismissing run counts only when it ended
   at least pace_ms after the first counted one (new reason silent_paced);
   single-run invite outcomes are recorded after stop() too. The
   conformance single-run cases run through the loop on their ended_at_ms.
F8 HELLO marks itself sent before the awaited send, so a handler attached
   meanwhile still renegotiates; on() documents per-conversation serial
   dispatch; CHANGELOG states it as a behaviour change.
Parity: frames other than message.new are dispatched at once on no lane
(not counted in the queue bound); gate_call_timeout_ms / cycle_timeout_ms
None = default, 0 = off, negative = ValueError.
turn-outcome.cases.json and manifest.sha256 copied byte-identical from the
TypeScript kit.
…ake_paused, stop() records nothing more

TypeScript parity (26bab16):
- release_turn / wake from another thread: the wake hops to the loop's
  event loop (call_soon_threadsafe) like the slot work, so it is not lost.
- During a refetch reconnect (no REST client) intake stays refused,
  quietly, until the new socket's hello.ok: frames still read off the
  closing socket start no new shedding episode (that would leave intake
  paused for good with an empty queue).
- RealtimeClient.intake_paused (shedding or a refetch under way) and
  status().socket['intake_paused'].
- stop() sets the running cycle's cancel handles: a gate mid-way records no
  further verdict, a pending model call is told; a verdict already on its
  way finishes.
- A timeout of math.inf is off, like 0.
No fixture changes.
…it on conditions, not sleeps

- .gitattributes: conformance/** -text, so git never converts the fixtures
  to CRLF (a Windows checkout broke the sha256 manifest check). The
  conformance tests read fixtures as bytes (no newline translation).
- The stop-mid-gate test holds the in-flight verdict with an event and
  stops while it is on its way, instead of timing sleeps; the other new
  loop tests wait for their outcome or turn count, and the adoption-clock
  test uses margins of 150 ms and more.
@sanctrl
sanctrl marked this pull request as ready for review November 8, 2026 14:27
@sanctrl
sanctrl merged commit 2ba1454 into main Nov 8, 2026
10 checks passed
@sanctrl
sanctrl deleted the feat/integration-kit branch November 11, 2026 08:39
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