Skip to content

The agent that grows with you

fix(gateway): replay missed events and prompts after a legacy reconnect

David Dudok de Wit6930e77a1bfd
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index 8ddd7b8745c..12a05f2b0bd 100644
--- a/apps/shared/src/gateway-contract.generated.ts
+++ b/apps/shared/src/gateway-contract.generated.ts
@@ -3619,6 +3619,7 @@ export interface SessionEventsSinceParams {
session_id: string
profile?: string | null
last_seen?: number | null
+ replay_epoch?: string | null
}
export interface SessionEventsSinceResult {
events: Record<string, unknown>[]
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index 63a15992b38..31983ec2ce7 100644
--- a/apps/shared/src/gateway-contract.openrpc.json
+++ b/apps/shared/src/gateway-contract.openrpc.json
@@ -36487,6 +36487,18 @@
],
"default": null,
"title": "Last Seen"
+ },
+ "replay_epoch": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Replay Epoch"
}
},
"required": [
diff --git a/apps/shared/src/json-rpc-gateway-legacy-replay.test.ts b/apps/shared/src/json-rpc-gateway-legacy-replay.test.ts
new file mode 100644
index 00000000000..e8d8aa1a8cf
--- /dev/null
+++ b/apps/shared/src/json-rpc-gateway-legacy-replay.test.ts
@@ -0,0 +1,131 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { JsonRpcGatewayClient } from './json-rpc-gateway'
+
+// Desktop in URL, Cloud or SSH mode (no `native_dial`) talks to a standalone `hermes serve`
+// on `/api/ws`. That socket announces a process epoch on gateway.ready. A serve that does not
+// know `replay_epoch` validates `session.events.since` with extra="forbid" and answers 4000
+// to any other key. The fake server below mirrors that contract.
+class FakeWebSocket extends EventTarget {
+ static instances: FakeWebSocket[] = []
+ readyState = 0
+ sent: string[] = []
+
+ constructor(public url: string) {
+ super()
+ FakeWebSocket.instances.push(this)
+ }
+
+ send(data: string): void {
+ this.sent.push(data)
+ }
+
+ close(): void {
+ this.readyState = 3
+ this.dispatchEvent(new CloseEvent('close'))
+ }
+
+ open(): void {
+ this.readyState = 1
+ this.dispatchEvent(new Event('open'))
+ }
+
+ serverFrame(obj: unknown): void {
+ this.dispatchEvent(new MessageEvent('message', { data: JSON.stringify(obj) }))
+ }
+
+ request(method: string): { id: string; method: string; params: Record<string, unknown> } | undefined {
+ return this.sent.map(frame => JSON.parse(frame)).find(frame => frame.method === method)
+ }
+}
+
+const LEGACY_KEYS = ['session_id', 'last_seen', 'profile']
+
+const ready = (epoch: string) => ({
+ jsonrpc: '2.0', method: 'event', params: { type: 'gateway.ready', payload: { replay_epoch: epoch } }
+})
+
+function makeClient(): JsonRpcGatewayClient {
+ return new JsonRpcGatewayClient({
+ socketFactory: url => new FakeWebSocket(url) as unknown as WebSocket,
+ heartbeatIntervalMs: 0,
+ heartbeatDeadlineMs: 0,
+ connectTimeoutMs: 1000
+ })
+}
+
+async function reconnect(client: JsonRpcGatewayClient): Promise<FakeWebSocket> {
+ client.invalidate('drop')
+ const pending = client.connect('ws://x')
+ const sock = FakeWebSocket.instances.at(-1)!
+ sock.open()
+ await pending
+ sock.serverFrame(ready('proc-1'))
+
+ return sock
+}
+
+describe('reconnect replay against a legacy backend', () => {
+ beforeEach(() => {
+ FakeWebSocket.instances = []
+ })
+
+ it('replays the missed events and re-delivers the pending approval', async () => {
+ const client = makeClient()
+ const seen: string[] = []
+ const prompts: Array<{ id: string; method: string; replayed?: boolean }> = []
+ client.on('message.complete', () => seen.push('complete'))
+ client.onRequest(req => void prompts.push({ id: req.id, method: req.method, replayed: req.replayed }))
+
+ const first = client.connect('ws://x')
+ const firstSock = FakeWebSocket.instances.at(-1)!
+ firstSock.open()
+ await first
+ firstSock.serverFrame(ready('proc-1'))
+ firstSock.serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 3 } })
+
+ const sock = await reconnect(client)
+ await vi.waitFor(() => expect(sock.request('session.events.since')).toBeDefined())
+ const req = sock.request('session.events.since')!
+ const extra = Object.keys(req.params).filter(key => !LEGACY_KEYS.includes(key))
+
+ sock.serverFrame(extra.length
+ ? { jsonrpc: '2.0', id: req.id, error: { code: 4000, message: `${extra.join(', ')}: Extra inputs are not permitted` } }
+ : {
+ jsonrpc: '2.0', id: req.id,
+ result: {
+ events: [{ type: 'message.complete', session_id: 's1', seq: 4 }],
+ latest_seq: 4,
+ truncated: false,
+ count: 1,
+ epoch: 'proc-1',
+ open_requests: [{ id: 'srq-1', method: 'approval', params: { session_id: 's1' } }]
+ }
+ })
+
+ await vi.waitFor(() => expect(seen).toEqual(['complete']))
+ expect(req.params).toEqual({ session_id: 's1', last_seen: 3 })
+ expect(prompts).toEqual([{ id: 'srq-1', method: 'approval', replayed: true }])
+ client.close()
+ })
+
+ it('still qualifies a canonical replay with that session epoch', async () => {
+ const client = makeClient()
+ const first = client.connect('ws://x')
+ const firstSock = FakeWebSocket.instances.at(-1)!
+ firstSock.open()
+ await first
+ firstSock.serverFrame(ready('proc-1'))
+ firstSock.serverFrame({
+ jsonrpc: '2.0', method: 'event',
+ params: { type: 'message.delta', session_id: 's1', seq: 5, replay_epoch: 's1-A' }
+ })
+
+ const sock = await reconnect(client)
+ await vi.waitFor(() => expect(sock.request('session.events.since')).toBeDefined())
+ expect(sock.request('session.events.since')!.params).toEqual({
+ session_id: 's1', last_seen: 5, replay_epoch: 's1-A'
+ })
+ client.close()
+ })
+})
diff --git a/apps/shared/src/json-rpc-gateway-replay.test.ts b/apps/shared/src/json-rpc-gateway-replay.test.ts
index ff72608297d..3baa20a2610 100644
--- a/apps/shared/src/json-rpc-gateway-replay.test.ts
+++ b/apps/shared/src/json-rpc-gateway-replay.test.ts
@@ -347,12 +347,12 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
expect(requests.map(req => req.params)).toEqual(expect.arrayContaining([
{ session_id: 's1', last_seen: 1, replay_epoch: 's1-B' },
{ session_id: 's2', last_seen: 9, replay_epoch: 's2-A' },
- { session_id: 'legacy', last_seen: 20, replay_epoch: 'gateway-A' }
+ { session_id: 'legacy', last_seen: 20 }
]))
for (const req of requests) {
const sid = req.params.session_id
- const epoch = req.params.replay_epoch
+ const epoch = req.params.replay_epoch ?? 'gateway-A'
const seq = Number(req.params.last_seen) + 1
sock.serverFrame({
jsonrpc: '2.0', id: req.id,
diff --git a/apps/shared/src/json-rpc-gateway.ts b/apps/shared/src/json-rpc-gateway.ts
index a81557a1577..de2d09ee4bb 100644
--- a/apps/shared/src/json-rpc-gateway.ts
+++ b/apps/shared/src/json-rpc-gateway.ts
@@ -573,7 +573,11 @@ export class JsonRpcGatewayClient {
}
try {
- const sessionEpochBefore = this.replayEpochBySession.get(sid) ?? this.replayEpoch
+ // Only a canonical session's own epoch qualifies the watermark on the wire. The legacy
+ // process epoch (gateway.ready) is compared with the answer's `epoch` in applyReplayEpochs.
+ // An older legacy `session.events.since` refuses any other key, so sending the process
+ // epoch here makes the reconnect replay fail and drops pending approval and clarify requests.
+ const sessionEpochBefore = this.replayEpochBySession.get(sid)
// `open_requests` on the answer are re-delivered by the channel itself.
const result = await this.request<{
diff --git a/tests/tui_gateway/test_legacy_events_since_replay_epoch.py b/tests/tui_gateway/test_legacy_events_since_replay_epoch.py
new file mode 100644
index 00000000000..2131fed54a5
--- /dev/null
+++ b/tests/tui_gateway/test_legacy_events_since_replay_epoch.py
@@ -0,0 +1,89 @@
+"""Legacy ``session.events.since`` replays a reconnect that includes ``replay_epoch``.
+
+Desktop in URL, Cloud or SSH mode (no ``native_dial``) speaks the legacy
+``/api/ws`` contract of a standalone ``hermes serve``. A session with no epoch
+of its own used to send the process epoch from ``gateway.ready``. The legacy
+params model refused that key, so the replay never ran and a pending approval
+or clarify request was not delivered again. The process epoch is compared with
+the answer's ``epoch``; it does not select events. Any other unknown key is
+still refused.
+"""
+
+import pytest
+
+from tui_gateway import event_replay
+
+
[email protected](autouse=True)
+def _clean_replay_ring():
+ event_replay.reset_replay_state()
+ yield
+ event_replay.reset_replay_state()
+
+
+def _contract():
+ # Importing the package registers every method contract, including session.events.since.
+ from tui_gateway.contracts import registry as contracts
+
+ return contracts, contracts.METHODS["session.events.since"]
+
+
+def test_legacy_events_since_accepts_the_process_epoch_clients_send():
+ contracts, contract = _contract()
+ _, problem = contracts.validate_params(
+ contract, {"session_id": "s1", "last_seen": 3, "replay_epoch": "proc-1"}
+ )
+
+ assert problem is None, problem
+
+
+def test_legacy_events_since_still_refuses_other_unknown_keys():
+ contracts, contract = _contract()
+ _, problem = contracts.validate_params(
+ contract, {"session_id": "s1", "last_seen": 3, "bogus": 1}
+ )
+
+ assert problem is not None and "bogus" in problem
+
+
+ "params",
+ [
+ {"session_id": "s-legacy", "last_seen": 1, "replay_epoch": "proc-1"},
+ {"session_id": "s-legacy", "last_seen": 1},
+ ],
+ ids=["with-replay-epoch", "without-replay-epoch"],
+)
+def test_legacy_events_since_replays_missed_events_and_open_requests(params):
+ from tui_gateway import server, server_requests
+
+ for n in (1, 2):
+ event_replay._stamp_event(
+ {
+ "jsonrpc": "2.0",
+ "method": "event",
+ "params": {
+ "type": "message.delta",
+ "session_id": "s-legacy",
+ "payload": {"n": n},
+ },
+ }
+ )
+ req = server_requests.ServerRequest(
+ "s-legacy", "clarify", {"question": "Ship it?", "choices": ["yes", "no"]}
+ )
+ server_requests._open[req.id] = req
+ try:
+ response = server.handle_request(
+ {"id": "r1", "method": "session.events.since", "params": params}
+ )
+ finally:
+ server_requests._open.pop(req.id, None)
+
+ assert "error" not in response, response
+ result = response["result"]
+ assert [event["payload"]["n"] for event in result["events"]] == [2]
+ assert [(entry["id"], entry["method"]) for entry in result["open_requests"]] == [
+ (req.id, "clarify")
+ ]
+ assert result["epoch"] == event_replay.replay_epoch()
diff --git a/tui_gateway/contracts/sessions.py b/tui_gateway/contracts/sessions.py
index 10f19a975d4..800dbb0d643 100644
--- a/tui_gateway/contracts/sessions.py
+++ b/tui_gateway/contracts/sessions.py
@@ -721,6 +721,10 @@ method("terminal.resize", params=TerminalResizeParams, result=TerminalResizeResu
class SessionEventsSinceParams(SessionParams):
last_seen: int | None = None
+ # Accepted and ignored. Legacy seqs are per process, and the client compares the answer's
+ # ``epoch`` with the process epoch from ``gateway.ready``. Clients that still send that
+ # process epoch here must replay; any other unknown key stays refused.
+ replay_epoch: str | None = None
class SessionEventsSinceResult(Result):