Skip to content

feat: add hosted agent SDK stack examples#233

Merged
roackb2 merged 3 commits into
mainfrom
codex/sdk-stack-examples
Jul 11, 2026
Merged

feat: add hosted agent SDK stack examples#233
roackb2 merged 3 commits into
mainfrom
codex/sdk-stack-examples

Conversation

@roackb2

@roackb2 roackb2 commented Jul 11, 2026

Copy link
Copy Markdown
Owner

What changed

  • add a transport-neutral HostedAgentService example on top of ConversationRunService
  • add an Express + Zod HTTP/SSE adapter for start, cursor-based subscribe, and cancel
  • add a framework-neutral browser fetch/SSE client using eventsource-parser
  • organize the SDK examples as a visible customization ladder from 01-interactive-chat through 05-hosted-agent
  • split the hosted stack into numbered 01-hosted-service, 02-http-sse-api, and 03-browser-client stages
  • add a public integration-layer guide and per-stage READMEs covering prerequisites, assumptions, ownership boundaries, stack selection, extension points, and production adaptation
  • remove the transport-neutral service dependency on the HTTP wire-contract module
  • add focused integration coverage for replay, disconnect-without-cancel, auth isolation, cursor validation, Last-Event-ID, query precedence, and cancellation

Why

The public run lifecycle is now used by Heddle's own CLI and web clients. These examples teach external TypeScript hosts and their coding agents how to build the same reconnectable conversational experience without coupling Heddle core to Express, SSE, React, authentication, or a deployment model.

The numbered structure also makes it clear which layer to copy for an existing tRPC, Fastify, Hono, Nest, WebSocket, Express, or browser stack. Users can stop at the lowest layer matching their host instead of installing the whole sample stack.

Boundary taught by the examples

  • Heddle owns durable conversation semantics, model/tool execution, traces, artifacts, ordered run events, replay, and cancellation.
  • The host owns identity and tenancy, stable product session IDs, engine composition, repositories, approval decisions, public API schemas, transport, deployment, and UI state.
  • HostedAgentService is example host application code, not a new required Heddle wrapper.
  • Express/SSE and the browser client are optional adapters layered above the transport-neutral service.

Validation

  • yarn typecheck
  • yarn lint
  • yarn test — 109 unit files / 626 tests; 30 integration files / 288 tests
  • yarn build
  • relative Markdown link validation for all revised guides
  • public repository search remains free of private integration names
  • earlier commits were smoke-tested with a real hosted service run and a real HTTP/SSE browser-client reconnect flow

@roackb2 roackb2 marked this pull request as ready for review July 11, 2026 10:20
@roackb2 roackb2 merged commit 4789400 into main Jul 11, 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