@promus/cli 0.24.17

package/src/sandbox/client.test.ts

@@ -0,0 +1,251 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import type http from 'node:http'
+import { encryptToPubkey, generateBootstrapKeypair } from '@promus/core'
+import {
+  ApprovalRelay,
+  EventHub,
+  type RuntimeConfig,
+  StubRuntime,
+  createGatewayServer,
+  createSession,
+} from '@promus/gateway'
+import { type Hex, hexToBytes } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { SandboxClient } from './client'
+
+const INFT_REF = {
+  contract: '0x9e71d79f06f956d4d2666b5c93dafab721c84721' as const,
+  tokenId: '6',
+}
+
+const CONFIG: RuntimeConfig = {
+  network: '0g-mainnet',
+  brain: { provider: '0x0000000000000000000000000000000000000111', model: 'glm-5' },
+  identity: {
+    iNFT: INFT_REF,
+    agent: '0x1111111111111111111111111111111111111111',
+  },
+}
+
+interface Fixture {
+  server: http.Server
+  base: string
+  client: SandboxClient
+  sandboxId: string
+  operatorPriv: Hex
+  agentPriv: Hex
+  bootstrapPubkey: Hex
+}
+
+async function listenOnRandomPort(server: http.Server): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address()
+      if (addr && typeof addr !== 'string') resolve(addr.port)
+      else reject(new Error('no-port'))
+    })
+  })
+}
+
+async function setupFixture(): Promise<Fixture> {
+  const operatorPriv = generatePrivateKey()
+  const operator = privateKeyToAccount(operatorPriv)
+  const events = new EventHub()
+  const session = createSession({
+    bootstrap: generateBootstrapKeypair(),
+    expectedOperatorAddress: operator.address,
+    sandboxId: 'sbx-cli-test',
+    events,
+    approvals: new ApprovalRelay(events),
+    runtime: new StubRuntime(),
+  })
+  const server = createGatewayServer({ session })
+  const port = await listenOnRandomPort(server)
+  const base = `http://127.0.0.1:${port}`
+  const client = new SandboxClient({
+    endpoint: base,
+    sandboxId: session.sandboxId,
+    operator,
+  })
+  return {
+    server,
+    base,
+    client,
+    sandboxId: session.sandboxId,
+    operatorPriv,
+    agentPriv: generatePrivateKey(),
+    bootstrapPubkey: session.bootstrap.pubkeyHexCompressed,
+  }
+}
+
+async function provisionViaClient(fix: Fixture): Promise<void> {
+  const envelope = encryptToPubkey({
+    recipientPubkey: fix.bootstrapPubkey,
+    plaintext: hexToBytes(fix.agentPriv),
+  })
+  await fix.client.provision({ envelope, iNFTRef: INFT_REF, config: CONFIG }, fix.bootstrapPubkey)
+  await fix.client.waitReady({ timeoutMs: 5000, intervalMs: 30 })
+}
+
+describe('SandboxClient', () => {
+  let fix: Fixture
+
+  beforeEach(async () => {
+    fix = await setupFixture()
+  })
+  afterEach(() => {
+    fix.server.close()
+  })
+
+  test('pubkey + health round-trip', async () => {
+    const pk = await fix.client.pubkey()
+    expect(pk.pubkeyHex).toBe(fix.bootstrapPubkey)
+    const h = await fix.client.health()
+    expect(h.state).toBe('Bootstrapping')
+    expect(h.runtimeReady).toBe(false)
+  })
+
+  test('provision + waitReady transitions to Ready', async () => {
+    await provisionViaClient(fix)
+    const h = await fix.client.health()
+    expect(h.state).toBe('Ready')
+    expect(h.runtimeReady).toBe(true)
+    expect(h.agentAddress).toBe(privateKeyToAccount(fix.agentPriv).address)
+  })
+
+  test('chat returns response from runtime', async () => {
+    await provisionViaClient(fix)
+    const result = await fix.client.chat('hello sandbox')
+    expect(result.response).toContain('hello sandbox')
+    expect(result.toolCalls.length).toBeGreaterThan(0)
+  })
+
+  test('events iterator yields chat-turn indicators', async () => {
+    await provisionViaClient(fix)
+    const controller = new AbortController()
+    const collected: string[] = []
+    const collect = (async () => {
+      for await (const ev of fix.client.events({ signal: controller.signal })) {
+        collected.push(ev.kind)
+        if (collected.includes('turn-end')) {
+          controller.abort()
+          break
+        }
+      }
+    })()
+    // give SSE a tick to subscribe before sending the chat
+    await new Promise(resolve => setTimeout(resolve, 100))
+    await fix.client.chat('event test')
+    await Promise.race([collect, new Promise(resolve => setTimeout(resolve, 3000))])
+    expect(collected).toContain('turn-start')
+    expect(collected).toContain('tool-call-start')
+    expect(collected).toContain('turn-end')
+  })
+
+  test('approve resolves a pending request', async () => {
+    await provisionViaClient(fix)
+    const session = await fix.client.health()
+    expect(session.state).toBe('Ready')
+
+    // Direct relay-driven approval round-trip is exercised in
+    // harness/src/server.test.ts where the relay is reachable from the test
+    // fixture. Here we just confirm /healthz reports ready, since the SSE
+    // events iterator is already covered above.
+    const resp = await fix.client.health()
+    expect(resp.runtimeReady).toBe(true)
+  })
+
+  // v0.24.4: approvePairing signs the same `adminTickHash('pairing-approve',
+  // ts, sandboxId)` payload as autotopup-tick / profile-key. We assert by
+  // intercepting fetch and confirming the signature recovers to the operator
+  // address — this proves the SandboxClient is signing what the server expects
+  // without needing a live PairingStore in the gateway test fixture.
+  test('approvePairing posts signed body to /admin/pairing/approve', async () => {
+    interface CapturedBody {
+      platform: string
+      code: string
+      ts: number
+      signature: Hex
+    }
+    const captured: { body: CapturedBody | null; url: string | null } = { body: null, url: null }
+    const mockFetch = (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+      captured.url = typeof input === 'string' ? input : input.toString()
+      captured.body = JSON.parse(String(init?.body ?? '{}')) as CapturedBody
+      return new Response(JSON.stringify({ ok: true, userId: '42', userName: 'bob' }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    }) as unknown as typeof fetch
+    const operator = privateKeyToAccount(fix.operatorPriv)
+    const client = new SandboxClient({
+      endpoint: 'http://stub.local',
+      sandboxId: 'sbx-pair-sign',
+      operator,
+      fetchImpl: mockFetch,
+    })
+
+    const result = await client.approvePairing('telegram', 'ABCDEFGH')
+    expect(result.ok).toBe(true)
+    expect(result.userId).toBe('42')
+    expect(result.userName).toBe('bob')
+    expect(captured.url).toBe('http://stub.local/admin/pairing/approve')
+    expect(captured.body).not.toBeNull()
+    const body = captured.body
+    if (!body) throw new Error('captured.body is null')
+    expect(body.platform).toBe('telegram')
+    expect(body.code).toBe('ABCDEFGH')
+    expect(typeof body.ts).toBe('number')
+    expect(body.signature).toMatch(/^0x[0-9a-fA-F]+$/)
+
+    // Recover address from signature + reconstructed hash; assert operator.
+    const { adminTickHash } = await import('@promus/gateway')
+    const { recoverMessageAddress } = await import('viem')
+    const hash = adminTickHash({
+      action: 'pairing-approve',
+      ts: body.ts,
+      sandboxId: 'sbx-pair-sign',
+    })
+    const recovered = await recoverMessageAddress({
+      message: { raw: hash },
+      signature: body.signature,
+    })
+    expect(recovered.toLowerCase()).toBe(operator.address.toLowerCase())
+  })
+
+  test('approvePairing surfaces ok:false reason from gateway', async () => {
+    const mockFetch = (async () => {
+      return new Response(JSON.stringify({ ok: false, reason: 'locked-out' }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    }) as unknown as typeof fetch
+    const operator = privateKeyToAccount(fix.operatorPriv)
+    const client = new SandboxClient({
+      endpoint: 'http://stub.local',
+      sandboxId: 'sbx-pair-lock',
+      operator,
+      fetchImpl: mockFetch,
+    })
+    const result = await client.approvePairing('telegram', 'ABCDEFGH')
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe('locked-out')
+  })
+
+  test('approvePairing throws on 401', async () => {
+    const mockFetch = (async () => {
+      return new Response(JSON.stringify({ error: 'unauthorized', reason: 'sig-mismatch' }), {
+        status: 401,
+        headers: { 'content-type': 'application/json' },
+      })
+    }) as unknown as typeof fetch
+    const operator = privateKeyToAccount(fix.operatorPriv)
+    const client = new SandboxClient({
+      endpoint: 'http://stub.local',
+      sandboxId: 'sbx-pair-401',
+      operator,
+      fetchImpl: mockFetch,
+    })
+    await expect(client.approvePairing('telegram', 'ABCDEFGH')).rejects.toThrow(/auth failed/)
+  })
+})

package/src/sandbox/client.ts

@@ -0,0 +1,424 @@
+import type { PermissionDecision } from '@promus/core'
+import {
+  type GatewayEventKind,
+  type ProvisionEnvelope,
+  type RuntimeConfig,
+  adminTickHash,
+  approvalResponseHash,
+  chatMessageHash,
+  provisionMessageHash,
+} from '@promus/gateway'
+import type { Address, Hex, LocalAccount } from 'viem'
+
+export interface SandboxClientOpts {
+  /** Full base URL of the sandbox harness, e.g. `http://8080-<id>.43.106.147.28.nip.io:4000`. */
+  endpoint: string
+  /** Sandbox id (also embedded in nip.io URL). Used in chat sig anchoring. */
+  sandboxId: string
+  /** Operator wallet account that signs chat / approval / provision messages. */
+  operator: LocalAccount
+  /** Optional custom fetch implementation (used in tests). */
+  fetchImpl?: typeof fetch
+  /**
+   * Optional unix socket path. When set, every fetch call routes via the
+   * socket using Bun's `fetch(url, {unix: '/path'})` option. The endpoint
+   * URL's host doesn't matter (kernel routes via socket); we use
+   * `http://localhost` as the conventional placeholder. Used by the local
+   * gateway path where chat.tsx talks to `~/.promus/agents/<id>/gateway.sock`.
+   */
+  unixSocketPath?: string
+}
+
+export interface ChatResponse {
+  response: string
+  toolCalls: Array<{ name: string; ok: boolean; durationMs: number }>
+  durationMs: number
+  syncTx?: string
+}
+
+export interface BootstrapPubkeyResponse {
+  pubkeyHex: Hex
+  version: string
+  sandboxId: string
+  state: string
+  bootedAt: number
+}
+
+export interface HealthzResponse {
+  state: string
+  sandboxId: string
+  version: string
+  uptimeMs: number
+  bootedAt: number
+  provisionedAt: number | null
+  readyAt: number | null
+  agentAddress: Address | null
+  runtimeReady: boolean
+  eventsLastSeq: number
+  subscribers: number
+  pendingApprovals: number
+  /** v0.21.12: per-listener state. */
+  listeners?: Record<string, 'active' | 'disabled' | 'failed'>
+  /** v0.21.13: current permission mode (used by TUI thin client to seed statusline). */
+  permsMode?: 'off' | 'prompt' | 'strict'
+}
+
+export interface ProvisionPayload {
+  envelope: ProvisionEnvelope
+  /** Optional second envelope for harness secrets (telegram bot token etc). */
+  secretsEnvelope?: ProvisionEnvelope
+  iNFTRef: { contract: Address; tokenId: string }
+  config: RuntimeConfig
+}
+
+export interface ParsedSseEvent {
+  seq: number
+  kind: GatewayEventKind
+  ts: number
+  data: unknown
+}
+
+/**
+ * Thin client the laptop CLI uses to talk to the sandbox-resident harness.
+ *
+ * - Wraps EIP-191 signing for /chat, /provision, /approval/:id/respond
+ * - Provides an async iterator over /events SSE
+ * - Reconnects on stream drop using the last-event-id header
+ */
+export class SandboxClient {
+  #fetch: typeof fetch
+  endpoint: string
+  sandboxId: string
+  operator: LocalAccount
+
+  constructor(opts: SandboxClientOpts) {
+    this.endpoint = opts.endpoint.replace(/\/$/, '')
+    this.sandboxId = opts.sandboxId
+    this.operator = opts.operator
+    const baseFetch = opts.fetchImpl ?? globalThis.fetch
+    if (opts.unixSocketPath) {
+      const sock = opts.unixSocketPath
+      // Bun's fetch supports `{unix: '/path'}` to route over a unix socket.
+      // The URL's host portion is ignored once unix is set; we still pass
+      // the full URL so Bun can parse the path component.
+      this.#fetch = ((input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+        const url = typeof input === 'string' ? input : input.toString()
+        const merged = { ...(init ?? {}), unix: sock } as RequestInit & { unix: string }
+        return baseFetch(url, merged as RequestInit)
+      }) as typeof fetch
+    } else {
+      this.#fetch = baseFetch
+    }
+  }
+
+  async pubkey(): Promise<BootstrapPubkeyResponse> {
+    const r = await this.#fetch(`${this.endpoint}/bootstrap/pubkey`)
+    if (!r.ok) throw new Error(`pubkey: ${r.status}`)
+    return (await r.json()) as BootstrapPubkeyResponse
+  }
+
+  async health(): Promise<HealthzResponse> {
+    const r = await this.#fetch(`${this.endpoint}/healthz`)
+    if (!r.ok) throw new Error(`healthz: ${r.status}`)
+    return (await r.json()) as HealthzResponse
+  }
+
+  async waitReady(
+    opts: { timeoutMs?: number; intervalMs?: number } = {},
+  ): Promise<HealthzResponse> {
+    const timeoutMs = opts.timeoutMs ?? 120_000
+    const intervalMs = opts.intervalMs ?? 1000
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      try {
+        const h = await this.health()
+        if (h.state === 'Ready' && h.runtimeReady) return h
+      } catch {
+        // ignore transient errors during boot
+      }
+      await new Promise(resolve => setTimeout(resolve, intervalMs))
+    }
+    throw new Error(`waitReady timeout (${timeoutMs}ms)`)
+  }
+
+  async provision(
+    payload: ProvisionPayload,
+    bootstrapPubkey: Hex,
+  ): Promise<{
+    ok: boolean
+    agentAddress: Address
+    state: string
+  }> {
+    const ts = Date.now()
+    const request = {
+      envelope: payload.envelope,
+      secretsEnvelope: payload.secretsEnvelope,
+      operatorAddress: this.operator.address,
+      iNFTRef: payload.iNFTRef,
+      config: payload.config,
+      ts,
+    }
+    const hash = provisionMessageHash(request, bootstrapPubkey)
+    const signature = await this.operator.signMessage({ message: { raw: hash } })
+
+    const r = await this.#fetch(`${this.endpoint}/bootstrap/provision`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ ...request, signature }),
+    })
+    if (!r.ok) {
+      const detail = await r.text().catch(() => '')
+      throw new Error(`provision failed (${r.status}): ${detail}`)
+    }
+    return (await r.json()) as { ok: boolean; agentAddress: Address; state: string }
+  }
+
+  async chat(message: string): Promise<ChatResponse> {
+    const ts = Date.now()
+    const hash = chatMessageHash(message, ts, this.sandboxId)
+    const signature = await this.operator.signMessage({ message: { raw: hash } })
+
+    const r = await this.#fetch(`${this.endpoint}/chat`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ message, ts, signature }),
+    })
+    if (!r.ok) {
+      const detail = await r.text().catch(() => '')
+      throw new Error(`chat failed (${r.status}): ${detail}`)
+    }
+    return (await r.json()) as ChatResponse
+  }
+
+  async sync(): Promise<{ tx?: string; slots: string[] }> {
+    // /sync uploads the full activity log + memory tree to 0G Storage and
+    // anchors via one updateSlots tx. For large activity logs (multi-MB)
+    // the upload can take minutes per segment. Bun's default fetch timeout
+    // is 5 min, which was tripping on real-size logs. Bump to 15 min — the
+    // gateway side never blocks indefinitely (0G SDK retries with backoff),
+    // so a long client wait is the right ceiling.
+    const r = await this.#fetch(`${this.endpoint}/sync`, {
+      method: 'POST',
+      signal: AbortSignal.timeout(15 * 60 * 1000),
+    })
+    if (!r.ok) throw new Error(`sync failed (${r.status})`)
+    return (await r.json()) as { tx?: string; slots: string[] }
+  }
+
+  /**
+   * v0.21.9: live-fire the AutoTopupManager to skip the 5-min poll wait.
+   * Signs `adminTickHash('autotopup-tick', ts, sandboxId)` over EIP-191 so
+   * the sandbox endpoint accepts it without trustLocal. Returns the tick
+   * result (`{ ok: true }` or `{ ok: false, reason }`).
+   */
+  async triggerAutoTopupTick(): Promise<{ ok: boolean; reason?: string }> {
+    const ts = Date.now()
+    const hash = adminTickHash({ action: 'autotopup-tick', ts, sandboxId: this.sandboxId })
+    const signature = await this.operator.signMessage({ message: { raw: hash } })
+    const r = await this.#fetch(`${this.endpoint}/admin/autotopup/tick`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ ts, signature }),
+    })
+    if (r.status === 401) {
+      const detail = (await r.json().catch(() => null)) as { reason?: string } | null
+      throw new Error(`autotopup-tick auth failed: ${detail?.reason ?? '401'}`)
+    }
+    if (r.status === 501) {
+      throw new Error('autotopup-tick not supported (runtime missing triggerTopupTick)')
+    }
+    return (await r.json()) as { ok: boolean; reason?: string }
+  }
+
+  /**
+   * v0.23.0: ship the operator-scoped PROFILE AES key into the sandbox. Same
+   * EIP-191 auth as `triggerAutoTopupTick` but with action='profile-key'.
+   * The 32-byte key is sent in the body — sandbox endpoints are operator-only
+   * via network policy.
+   */
+  async setProfileKey(
+    profileScopeKeyHex: `0x${string}`,
+  ): Promise<{ ok: boolean; reason?: string }> {
+    const ts = Date.now()
+    const hash = adminTickHash({ action: 'profile-key', ts, sandboxId: this.sandboxId })
+    const signature = await this.operator.signMessage({ message: { raw: hash } })
+    const r = await this.#fetch(`${this.endpoint}/admin/profile-key`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ ts, signature, profileScopeKeyHex }),
+    })
+    if (r.status === 401) {
+      const detail = (await r.json().catch(() => null)) as { reason?: string } | null
+      throw new Error(`profile-key auth failed: ${detail?.reason ?? '401'}`)
+    }
+    if (r.status === 501) {
+      throw new Error('profile-key not supported (runtime missing setProfileKey)')
+    }
+    return (await r.json()) as { ok: boolean; reason?: string }
+  }
+
+  /**
+   * v0.24.4: forward an operator pair-mode approval to the sandbox so the
+   * container's pairing dir gets the approved user. Same EIP-191 auth as
+   * `triggerAutoTopupTick` / `setProfileKey` but with action='pairing-approve'.
+   * Returns the result shape from `BuiltRuntime.approvePairing` so the
+   * `promus pairing approve` command can print user details on success or
+   * a clean error on locked-out / unknown-code.
+   */
+  async approvePairing(
+    platform: string,
+    code: string,
+  ): Promise<{ ok: boolean; userId?: string; userName?: string; reason?: string }> {
+    const ts = Date.now()
+    const hash = adminTickHash({ action: 'pairing-approve', ts, sandboxId: this.sandboxId })
+    const signature = await this.operator.signMessage({ message: { raw: hash } })
+    const r = await this.#fetch(`${this.endpoint}/admin/pairing/approve`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ platform, code, ts, signature }),
+    })
+    if (r.status === 401) {
+      const detail = (await r.json().catch(() => null)) as { reason?: string } | null
+      throw new Error(`pairing-approve auth failed: ${detail?.reason ?? '401'}`)
+    }
+    if (r.status === 501) {
+      throw new Error('pairing-approve not supported (runtime missing approvePairing)')
+    }
+    if (r.status === 400) {
+      const detail = (await r.json().catch(() => null)) as {
+        error?: string
+        reason?: string
+      } | null
+      throw new Error(
+        `pairing-approve bad-request: ${detail?.error ?? '400'}${detail?.reason ? ` (${detail.reason})` : ''}`,
+      )
+    }
+    if (r.status === 409) {
+      throw new Error('pairing-approve gateway not Ready')
+    }
+    return (await r.json()) as {
+      ok: boolean
+      userId?: string
+      userName?: string
+      reason?: string
+    }
+  }
+
+  /**
+   * Forward an operator approval decision to the harness. Maps promus's
+   * `PermissionDecision` (`allow-once | allow-session | deny`) onto the
+   * sandbox-server wire format (`allow | allow-session | deny`) since
+   * `allow-once` collapses to `allow` over the wire — the harness's
+   * ApprovalRelay only sees a once-shot resolve and the permission service
+   * already handled session-allow caching there.
+   */
+  async approve(approvalId: string, decision: PermissionDecision): Promise<void> {
+    const wireDecision: 'allow' | 'allow-session' | 'deny' =
+      decision === 'allow-once' ? 'allow' : decision
+    const ts = Date.now()
+    const hash = approvalResponseHash({
+      approvalId,
+      decision: wireDecision,
+      ts,
+      sandboxId: this.sandboxId,
+    })
+    const signature = await this.operator.signMessage({ message: { raw: hash } })
+    const r = await this.#fetch(`${this.endpoint}/approval/${approvalId}/respond`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ decision: wireDecision, ts, signature }),
+    })
+    if (!r.ok) {
+      const detail = await r.text().catch(() => '')
+      throw new Error(`approve failed (${r.status}): ${detail}`)
+    }
+  }
+
+  /**
+   * Subscribe to /events SSE. Yields parsed events. On stream drop, reconnects
+   * with the last seen seq via the last-event-id header so we don't miss events.
+   * Cancel via the AbortSignal in opts.
+   */
+  async *events(
+    opts: {
+      signal?: AbortSignal
+      sinceSeq?: number
+      clientKind?: 'tui' | 'dashboard' | 'other'
+    } = {},
+  ): AsyncGenerator<ParsedSseEvent> {
+    let lastSeq = opts.sinceSeq
+    const signal = opts.signal
+    // v0.24.14: tag subscriber kind so the daemon's TG forward gate can
+    // distinguish a live operator TUI from passive web dashboards.
+    // Default `other` keeps back-compat for callers that don't set it.
+    const clientKind = opts.clientKind ?? 'other'
+    while (true) {
+      if (signal?.aborted) return
+      const headers: Record<string, string> = { accept: 'text/event-stream' }
+      if (typeof lastSeq === 'number') headers['last-event-id'] = String(lastSeq)
+      let res: Response
+      try {
+        res = await this.#fetch(`${this.endpoint}/events?client=${clientKind}`, { headers, signal })
+      } catch {
+        if (signal?.aborted) return
+        await new Promise(resolve => setTimeout(resolve, 1000))
+        continue
+      }
+      if (!res.ok || !res.body) {
+        await new Promise(resolve => setTimeout(resolve, 1000))
+        continue
+      }
+      const reader = res.body.getReader()
+      const decoder = new TextDecoder()
+      let buf = ''
+      try {
+        while (true) {
+          if (signal?.aborted) return
+          const { value, done } = await reader.read()
+          if (done) break
+          buf += decoder.decode(value, { stream: true })
+          for (;;) {
+            const sep = buf.indexOf('\n\n')
+            if (sep === -1) break
+            const chunk = buf.slice(0, sep)
+            buf = buf.slice(sep + 2)
+            const ev = parseSseChunk(chunk)
+            if (!ev) continue
+            lastSeq = ev.seq
+            yield ev
+          }
+        }
+      } catch {
+        // fallthrough: reconnect
+      }
+      if (signal?.aborted) return
+      await new Promise(resolve => setTimeout(resolve, 500))
+    }
+  }
+}
+
+function parseSseChunk(chunk: string): ParsedSseEvent | null {
+  let id: number | null = null
+  let kind: GatewayEventKind | null = null
+  let dataLine = ''
+  for (const rawLine of chunk.split('\n')) {
+    const line = rawLine.trimEnd()
+    if (!line || line.startsWith(':')) continue
+    if (line.startsWith('id: ')) {
+      const n = Number.parseInt(line.slice(4), 10)
+      if (Number.isFinite(n)) id = n
+    } else if (line.startsWith('event: ')) {
+      kind = line.slice(7) as GatewayEventKind
+    } else if (line.startsWith('data: ')) {
+      dataLine = dataLine ? `${dataLine}\n${line.slice(6)}` : line.slice(6)
+    }
+  }
+  if (id == null || !kind || !dataLine) return null
+  let parsed: { ts: number; data: unknown }
+  try {
+    parsed = JSON.parse(dataLine)
+  } catch {
+    return null
+  }
+  return { seq: id, kind, ts: parsed.ts, data: parsed.data }
+}