Kontext Protocol Buffers

Shared contract between the Kontext CLI (Go client) and the Kontext API (NestJS server).

Services

kontext.agent.v1.AgentService

The core governance service. Handles session lifecycle, hook event streaming, credential exchange, and policy sync.

RPC	Type	Purpose
CreateSession	Unary	Start a governed agent session
ProcessHookEvent	Bidi stream	Stream tool call events, receive policy decisions
Heartbeat	Unary	Keep session alive
EndSession	Unary	Terminate session
ExchangeCredential	Unary	Resolve provider credentials
SyncPolicy	Server stream	Push policy updates for local evaluation

Usage

Go (CLI)

# buf.gen.yaml
version: v2
deps:
  - buf.build/kontext/proto
plugins:
  - local: protoc-gen-go
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-connect-go
    out: gen
    opt: paths=source_relative

TypeScript (API)

# buf.gen.yaml
version: v2
deps:
  - buf.build/kontext/proto
plugins:
  - local: protoc-gen-es
    out: gen
    opt: target=ts
  - local: protoc-gen-connect-es
    out: gen
    opt: target=ts

CI

Every PR runs:

• buf lint — proto style enforcement
• buf breaking --against .git#branch=main — backward compatibility check

Consumer repos (CLI, API) run buf breaking against this repo's main branch to catch incompatible changes before merge.

Development

# Lint
buf lint

# Check breaking changes
buf breaking --against .git#branch=main

# Format
buf format -w