Skip to content

feat(forward): add realtime conversations and history - #17

Merged
moonyue-w merged 2 commits into
mainfrom
codex/forward-realtime
Oct 13, 2026
Merged

moonyue-w merged 2 commits into
mainfrom
codex/forward-realtime

Conversation

@moonyue-w

Copy link
Copy Markdown
Collaborator

Summary

Add Forward Realtime Beta Conversation creation, authenticated Node.js WebSocket connections and persisted History with independent before pagination. Connections expose text/PCM16 input, typed and unknown events, Work progress, playback receipts, interruption and acknowledged graceful closure.

Why

The TypeScript SDK cannot currently use Forward's Realtime API. This adds the public creation/connection/history surface while reusing the existing authentication and HTTP resource conventions. The Node transport loads only when connecting so existing browser HTTP imports remain usable.

Verification

  • npm run build
  • npm run typecheck
  • npm test
  • npm run docs:check
  • Relevant examples run or import successfully (--help smoke checks)
  • Account-backed integration tests run

After merging the latest main: 3676 offline tests passed, 0 skipped; 59 focused Realtime checks. Package checks covered Node 20.12, CJS/ESM, HTTP/browser imports, public types and a local WebSocket connection from an installed tarball. Changelog/release-notes checks passed.

CN/Global × PAT/Forward-bound SAT: 4 text and 4 PCM scenarios passed through npm run test:live:realtime. These verify creation, ready, ping/pong, nonempty transcripts, decoded output audio, matching close acknowledgements and filtered History pagination. Temporary test Identities were cleaned up; existing Templates were preserved. Conversation IDs are retained because there is no public delete API. Audio devices were not tested.

Additional live Work checks observed accepted/running/completed and persisted announcements. The first matrix had 3 passes and a Global PAT History assertion failure. That single unchanged case passed on rerun after adding diagnostic detail; the initial cause remains undetermined and is not represented as a fixed SDK bug. Offline tests also cover receive handoff, iteration without connection closure, protocol validation, cancellation, redirects and bounded queues.

Impact

  • Public API or behavior changed
  • User-facing changes added to CHANGELOG.md under Unreleased
  • CommonJS, ESM, and subpath exports remain valid
  • Generated API documentation updated
  • Contract or wire-field fixtures updated
  • Go and Python parity considered
  • Migration notes added for a breaking change
  • No credentials, .env.live, logs, or generated test output committed

This is additive; migration notes are not required. Adds ws and its development types while retaining Node >=20.12. Realtime connections are Node-only. Stage deadlines are separate from HTTP request timeouts; connections do not automatically reconnect or replay input. Playback receipts remain application-owned.

Realtime SA access currently requires a Forward-issued bound SAT. The platform ServiceAccountCredential exchange does not create that binding; its SAT returned 403 during the initial live checks. Passing a Forward-issued SAT through the existing direct-token interface passed. The SAT issuance API is already merged into main (#16); this PR builds on it and does not change platform credential renewal. Template Realtime configuration APIs are outside this PR.

@moonyue-w
moonyue-w merged commit 1e374cd into main Oct 13, 2026
5 checks passed
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