grpc-dev

Skill: grpc-dev

Activates when: Working on gRPC streaming, AG-UI event flow, WatchSessionMessages, control plane ↔ runner protocol, or debugging gRPC connectivity.

---

Architecture

Runner Pod (Claude Code)
  │  pushes AG-UI events via gRPC
  ▼
Control Plane (CP)
  │  fan-out multiplexer — one runner, N watchers
  ▼
WatchSessionMessages RPC (streaming)
  │
  ├── acpctl session messages -f
  ├── Go SDK session_watch.go
  ├── Python SDK _grpc_client.py
  └── TUI dashboard (acpctl ambient)

Proto Definitions

Location: components/ambient-api-server/proto/ambient/v1/sessions.proto

Key RPC:

rpc WatchSessionMessages(WatchSessionMessagesRequest)
    returns (stream SessionMessageEvent);

Generated stubs: pkg/api/grpc/ambient/v1/sessions_grpc.pb.go

Regen: cd components/ambient-api-server && make generate

AG-UI Event Types

Event	Direction	Meaning
RUN_STARTED	runner → CP → client	Session began executing
TEXT_MESSAGE_CONTENT	runner → CP → client	Token chunk (streaming)
TEXT_MESSAGE_END	runner → CP → client	Message complete
MESSAGES_SNAPSHOT	runner → CP → client	Full message history
RUN_FINISHED	runner → CP → client	Session done (terminal event)

RUN_FINISHED must be forwarded exactly once. CP must not duplicate or drop it.

Authentication

gRPC auth: pkg/middleware/bearer_token_grpc.go

Test token bypass: When a non-JWT token (e.g. test-user-token K8s secret) is used, the JWT username claim is absent from the gRPC context. The WatchSessionMessages handler MUST skip the per-user ownership check in this case:

username, ok := CallerUsernameFromContext(ctx)
if ok && username != session.Owner {
    return status.Error(codes.PermissionDenied, "not session owner")
}
// If !ok (no username in context), allow — non-JWT token

Fan-Out Pattern

The CP maintains a subscriber map per session ID. When a new WatchSessionMessages client connects: