Repository navigation
Integration kit + contract v1 in the SDK - #14
Merged
Merged
Conversation
…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.
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.
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 bymanifest.sha256and a CI check against the published contract).ReceiveLoop(gate-call / single-run;max_concurrent_turns1; 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).ackoffered only while a handler is attached;heartbeat/rewakecapabilities; bounded backlog (max_queued_messages) without pausing reads,intake_pausedin status; 1013retry_afterhandling;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.recordtolerant of empty 2xx; gate prompt from served texts with the 1.2 wording as fallback.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).