Generated TypeScript Client Types

• gen/ts/korvus/v1/incident_pb.ts
• gen/ts/korvus/v1/session_pb.ts
• gen/ts/korvus/v1/system_pb.ts

Korvus speaks Connect/gRPC from a Go server, but the people who use Korvus are often not Go programs — they are the operator's web UI, a small script that opens an incident from a shell, a dashboard that lists MCP servers. Those consumers want TypeScript. The gen/ts/korvus/v1/ tree exists so that a TypeScript client can be written against the same contract the server implements, without hand-written mirrors of the protobuf messages that drift out of date within a week.

This page covers the three generated TypeScript files that make up that client surface: incident_pb.ts, session_pb.ts and system_pb.ts. They are not hand-written and they are not imported by the Go server: they are a build artifact of the same .proto files that produce the Go protobuf types and Connect handlers described in Generated Korvus v1 Protobuf and Connect API. The Go side of the API is implemented in Connect API Server and Service Handlers and the wire-level conversions live in Watch Streams, Read APIs, Webhooks and Proto Conversion.

How it works

Where the files come from

Every file in gen/ts/ starts with a header saying who wrote it and from which proto file it was derived, for example the incident file's // @generated by protoc-gen-es v2.10.1 with parameter "target=ts" line src/gen/ts/korvus/v1/incident_pb.ts#L1-L2. The generator is pinned in buf.gen.yaml as a remote buf plugin, buf.build/bufbuild/es:v2.10.1, writing into gen/ts with the target=ts option src/buf.gen.yaml#L30-L33. Because it is a remote plugin, no local protoc-gen-es binary has to be installed — buf generate runs the plugin server-side. The proto inputs live under the api module declared in buf.yaml src/buf.yaml#L1-L3.

The buf.gen.yaml header also records an important architectural decision: in Connect-ES v2 the standalone @connectrpc/protoc-gen-connect-es plugin was deprecated, and service codegen moved into protoc-gen-es v2 itself src/buf.gen.yaml#L14-L18. That is why these TypeScript files contain service descriptors rather than generated client classes — the descriptor is turned into a live client at runtime by createClient(Service, transport) from @connectrpc/connect v2.

The anatomy of a generated file

All three files follow the same four-part layout.

First, the imports from the protobuf-es v2 code-generation runtime: the type-only imports for GenEnum, GenFile, GenMessage and GenService, plus the runtime helpers enumDesc, fileDesc, messageDesc and serviceDesc src/gen/ts/korvus/v1/incident_pb.ts#L5-L9. system_pb.ts imports only GenFile, GenMessage and GenService because it declares no enums src/gen/ts/korvus/v1/system_pb.ts#L5-L9.

Second, a single file descriptor: a base64-encoded FileDescriptorProto handed to fileDesc, together with the descriptors of any imported well-known files. The incident file pulls in the timestamp well-known type because its messages carry google.protobuf.Timestamp fields src/gen/ts/korvus/v1/incident_pb.ts#L14-L15. The session file additionally pulls in google.protobuf.Struct, because tool arguments and outputs are carried as a ListValue/JsonObject pair src/gen/ts/korvus/v1/session_pb.ts#L5-L9.

Third, for every message, a TypeScript type and a runtime schema. The type is an intersection of the runtime Message<"korvus.v1.Incident"> marker with a plain object of the message's fields, so a message is both typed at compile time and usable by the protobuf-es runtime at runtime — for example the Incident type carries id, title, description, status, severity, origin, fingerprint, string maps for labels and annotations, and optional Timestamp fields for startedAt, createdAt and closedAt src/gen/ts/korvus/v1/incident_pb.ts#L23. The schema is the runtime counterpart, created by messageDesc and indexed by the message's position within the file — MCPServerSchema is index 0 in system.proto src/gen/ts/korvus/v1/system_pb.ts#L57-L58. Enums follow the same pattern: a native TypeScript enum plus a GenEnum descriptor built by enumDesc src/gen/ts/korvus/v1/incident_pb.ts#L601-L602.

Fourth, for every service, a GenService descriptor built by serviceDesc, listing each RPC with its methodKind and the input/output schemas src/gen/ts/korvus/v1/incident_pb.ts#L727.

What each file exposes

incident_pb.ts covers the incident lifecycle: the Incident message, the Alert message with its own AlertStatus, and the four enums that drive the incident state machine — IncidentStatus (unspecified, open, investigating, resolved, cancelled) src/gen/ts/korvus/v1/incident_pb.ts#L560-L578, IncidentOrigin (manual or alert) src/gen/ts/korvus/v1/incident_pb.ts#L611, AlertStatus and IncidentEventType (created, updated, closed, alert received) src/gen/ts/korvus/v1/incident_pb.ts#L709-L710. The IncidentService descriptor carries six unary RPCs and one server-streaming RPC; watchIncidents is the streaming one, and its comment records that the stream is backed by PostgreSQL LISTEN/NOTIFY so events survive a restart on the publishing side src/gen/ts/korvus/v1/incident_pb.ts#L801-L804. The stream payload is WatchIncidentsResponse, whose incident and alert fields are optional because they are populated selectively per event type src/gen/ts/korvus/v1/incident_pb.ts#L690-L705. The semantics behind these types are documented in Incident Manager: Open, List, Update, Close and Alert Ingestion, Fingerprinting and Debounce.

session_pb.ts is the largest of the three, and it is the richest in domain vocabulary: Session, Turn, Report, Artifact, ContextRef and their request/response wrappers. Its enums include SessionKind, SessionStatus src/gen/ts/korvus/v1/session_pb.ts#L1390-L1391, TurnRole (user, assistant, tool) and ArtifactKind (report, agent output, attachment, workspace archive) src/gen/ts/korvus/v1/session_pb.ts#L1476-L1477. The SessionService descriptor contains the eleven RPCs of the session API, including watchSession, the second server-streaming method in the surface src/gen/ts/korvus/v1/session_pb.ts#L1604-L1607. The sendMessage entry documents the reopen semantics — it continues a finished session's conversation from stored turns and lands the next report revision — which matches the behaviour described in Session Persistence, Reopen and Scratch Seeding and Agent Session State, Resume and Event Broadcasting. Report revisions and the report payload itself are covered by Incident Report Schema.

system_pb.ts carries the process-level view: MCPServer (with its discovered tools and last connection error), Tool, Skill, Template, and the GetSystemStatus / ListMCPServers / ListSkills / ListTemplates / SyncWorkspace / TriggerAlert requests and responses. Its SystemService descriptor is the admin surface, and syncWorkspace documents that already-running sessions keep the workspace revision they started on src/gen/ts/korvus/v1/system_pb.ts#L549-L550. TriggerAlertResponse is the interesting one for demos: it reports the alert that was written, the incident it attached to (new or deduplicated against), and whether the alert was suppressed src/gen/ts/korvus/v1/system_pb.ts#L468-L469. The underlying subsystems are described in MCP Client, Registry and Server Connection, Skill Catalog and Frontmatter Parsing and Workspace Sync, Checkout and Materialization.

Using them from a client

A consumer imports the service descriptor and hands it to createClient together with a Connect transport. Nothing in the repository does this today — these files exist for the UI container and for external clients — but the descriptor is the whole contract. Two consequences are worth internalising.

Because the descriptors are data rather than classes, the generated code carries /*@__PURE__*/ annotations on every descriptor construction so that bundlers can drop them when unused, and every file starts with /* eslint-disable */ because the generated formatting does not satisfy the project's lint rules.

Because the TypeScript is generated from the same protos as the Go side, the two cannot disagree about the wire format. The server-side counterpart of IncidentService is NewIncidentServiceHandler in the Go Connect package src/gen/korvus/v1/korvusv1connect/incident.connect.go#L222, and all three Go handlers are mounted on one h2c-wrapped mux so a single port speaks gRPC, gRPC-Web and Connect src/internal/transport/transport.go#L1-L7.

Keeping the tree honest

The generated tree is a committed artifact, so it can go stale. CI closes that gap with a single buf:verify job that lints the protos, builds them, regenerates the whole gen/ tree, and then fails if git diff is non-empty — with the message x gen/ is stale relative to api/*.proto. and the instruction to run make generate src/.gitlab-ci.yml#L411-L419. Because the TypeScript and Go outputs are produced by the same buf generate invocation, the drift gate catches a stale TypeScript file in exactly the same run that catches a stale Go file.

Relationships

graph LR
  gen["buf generate"] --> tsInc["gen/ts/korvus/v1/incident_pb.ts"]
  gen --> tsSess["gen/ts/korvus/v1/session_pb.ts"]
  gen --> tsSys["gen/ts/korvus/v1/system_pb.ts"]
  tsInc --> fInc["`file_korvus_v1_incident`"]
  tsInc --> Incident["`Incident`"]
  tsInc --> IncidentService["`IncidentService`"]
  tsInc --> WatchIncidentsResponse["`WatchIncidentsResponse`"]
  tsSess --> fSess["`file_korvus_v1_session`"]
  tsSess --> Session["`Session`"]
  tsSess --> SessionService["`SessionService`"]
  tsSys --> fSys["`file_korvus_v1_system`"]
  tsSys --> MCPServer["`MCPServer`"]
  tsSys --> SystemService["`SystemService`"]
  IncidentService --> goInc["`NewIncidentServiceHandler`"]
  SessionService --> goSess["`NewSessionServiceClient`"]
  SystemService --> goSys["`NewSystemServiceClient`"]

The three generated files are the TypeScript half of a single contract whose Go half is documented in Generated Korvus v1 Protobuf and Connect API; the services they describe are implemented by the handlers covered in Connect API Server and Service Handlers, and the incident/session/system domains behind them are explained in Incident Manager: Open, List, Update, Close, Session Manager and Lifecycle and korvus CLI and Process Wiring. For the wider repository story, start at Korvus Overview.

Reference

Generated by astrolabe from commit 0c2dca73 on branch main.