gRPC API

Overview

Seshat currently has three core runtime entry points: the CLI app, the embedded Go SDK, and `cmd/grpc`. The Go SDK is the native same-process integration for Go hosts. gRPC is the network or language boundary when your host is not Go, when you want a separate runtime service, or when a future official SDK for Python, JS, Rust, Java, or another language needs a transport contract first.

Start Server

The entry point is `cmd/grpc`. By default it listens on `:50051` and builds the runtime host config from the same config loader used elsewhere in Seshat.

ANTHROPIC_API_KEY=sk-ant-... SESHAT_MODEL=anthropic:claude-sonnet-4-20250514 go run ./cmd/grpc

make build-grpc
SESHAT_GRPC_ENABLE_REFLECTION=true ./bin/seshat-grpc

• The server registers `SeshatService` only.
• Reflection is disabled by default and must be enabled explicitly.
• Shutdown is graceful on `SIGINT` and `SIGTERM`.

Server Config

There are two config layers to understand. First, the gRPC server has its own transport-level env vars. Second, it inherits the shared runtime host config from `pkg/config`, which controls the model default, session persistence, working directory, provider credentials, storage, browser settings, and more.

gRPC-specific environment

Shared runtime environment reused by gRPC

Service Contract

The current proto defines more than what `cmd/grpc` actually exposes. This table separates the live `SeshatService` surface from the proto-only services that still need implementation and server registration.

Unary Query

`Query` is the simplest call: one request, one completed turn, one final response. The server either creates a new persisted session or loads an existing one from `context_id`, applies any requested tool allowlist, runs the turn, and returns the latest assistant text plus usage totals.

`QueryRequest` fields and actual server behavior

grpcurl   -plaintext   -import-path pkg/grpc/proto   -proto seshat.proto   -d '{
    "prompt": "Audit this repository and summarize the biggest risks.",
    "model": "anthropic:claude-sonnet-4-20250514",
    "tools": ["read_file", "grep", "glob"],
    "max_tokens": 1800
  }'   localhost:50051   seshat.SeshatService/Query

grpcurl   -plaintext   -import-path pkg/grpc/proto   -proto seshat.proto   -d '{
    "prompt": "Continue from the previous analysis and propose a patch plan.",
    "context_id": "sess-42"
  }'   localhost:50051   seshat.SeshatService/Query

• `conversation_id` in the response is the underlying Seshat session id.
• Passing `tools` acts as an allowlist, not an additive tool request.
• Unknown tool names fail early with `InvalidArgument`.
• If `api_key` is present, it overrides host credential resolution for that request.

Streaming

`QueryStream` is the main protocol for live experiences. It reuses the same runtime execution path, but instead of waiting for the full turn it forwards response chunks and structured runtime events as they are emitted, then closes with one final message containing the completed assistant text and token usage totals.

`QueryResponse.item_type` values

grpcurl   -plaintext   -import-path pkg/grpc/proto   -proto seshat.proto   -d '{
    "prompt": "Inspect the project and stream your findings step by step.",
    "model": "anthropic:claude-sonnet-4-20250514"
  }'   localhost:50051   seshat.SeshatService/QueryStream

Skills, MCP, Models, and Health

gRPC is not only for prompting. The server also exposes part of the runtime surface around skills discovery, MCP server lifecycle, provider registry introspection, and health reporting.

# reflection mode if enabled
grpcurl -plaintext localhost:50051 list

grpcurl -plaintext -import-path pkg/grpc/proto -proto seshat.proto   -d '{"source_filter":"all"}' localhost:50051 seshat.SeshatService/ListSkills

grpcurl -plaintext -import-path pkg/grpc/proto -proto seshat.proto   -d '{}' localhost:50051 seshat.SeshatService/GetModels

grpcurl -plaintext -import-path pkg/grpc/proto -proto seshat.proto   -d '{"name":"github","type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-github"]}'   localhost:50051 seshat.SeshatService/ConnectMCP

grpcurl -plaintext -import-path pkg/grpc/proto -proto seshat.proto   -d '{}' localhost:50051 seshat.SeshatService/HealthCheck

• `ListSkills` reads from the current skills discovery path using the server working directory.
• `ConnectMCP` persists an MCP server config, then reconnects it immediately through the runtime manager.
• `GetModels` lists models from the provider catalog, not only from currently-authenticated providers.
• `HealthCheck` returns server uptime and version, but it is not a full dependency readiness probe.

Client Usage

Today, gRPC is the cleanest cross-language contract Seshat has. The Go SDK is native embedding. Future Python, JS, Rust, Java, or C# SDKs can realistically start as higher-level wrappers around this gRPC surface, then grow richer runtime ergonomics later.

Go client

conn, err := grpc.Dial(
    "localhost:50051",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := pb.NewSeshatServiceClient(conn)

resp, err := client.Query(ctx, &pb.QueryRequest{
    Prompt: "Review this repository and propose a refactor plan.",
    Model:  "anthropic:claude-sonnet-4-20250514",
    Tools:  []string{"read_file", "grep", "glob"},
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(resp.Content)
fmt.Println(resp.ConversationId)
fmt.Println(resp.TokenUsage.TotalTokens)

Python client

import grpc
from gen import seshat_pb2, seshat_pb2_grpc

channel = grpc.insecure_channel("localhost:50051")
client = seshat_pb2_grpc.SeshatServiceStub(channel)

resp = client.Query(
    seshat_pb2.QueryRequest(
        prompt="Summarize this project architecture.",
        model="anthropic:claude-sonnet-4-20250514",
        max_tokens=1200,
    )
)
print(resp.content)
print(resp.conversation_id)

stream = client.QueryStream(
    seshat_pb2.QueryRequest(
        prompt="Stream a code review of this repository.",
        context_id=resp.conversation_id,
    )
)
for item in stream:
    if item.item_type == "chunk":
        print(item.content, end="", flush=True)
    elif item.item_type == "runtime_event":
        print(f"\n[event] {item.runtime_event.type} {item.runtime_event.tool_name}")
    elif item.item_type == "final":
        print(f"\nfinal tokens={item.token_usage.total_tokens}")

Codegen & Regeneration

If you modify `pkg/grpc/proto/seshat.proto`, you must regenerate the Go stubs and then rebuild or retest the server. The generated Go files live in `pkg/grpc/seshat/`.

Regenerate Go stubs from the repo root

PATH="$HOME/.local/bin:$(go env GOPATH)/bin:$PATH" protoc   --proto_path=pkg/grpc/proto   --go_out=.   --go_opt=module=github.com/EngineerProjects/seshat   --go-grpc_out=.   --go-grpc_opt=module=github.com/EngineerProjects/seshat   pkg/grpc/proto/seshat.proto

Generate Python stubs

python -m grpc_tools.protoc   -I pkg/grpc/proto   --python_out=./gen   --grpc_python_out=./gen   pkg/grpc/proto/seshat.proto

Generate Node / JS stubs

# Node / JS stub generation example
npx grpc_tools_node_protoc   --proto_path=pkg/grpc/proto   --js_out=import_style=commonjs,binary:./gen   --grpc_out=grpc_js:./gen   pkg/grpc/proto/seshat.proto

• After regeneration, rebuild with go build ./cmd/grpc.
• Then verify behavior with go test ./cmd/grpc/....
• If you changed generated package names or method signatures, update any website examples and consumer wrappers as well.

How To Extend

Completing the gRPC surface is more than adding lines to the proto. A real extension path has four layers: the `.proto` contract, regenerated stubs, server implementation, and bufconn tests that lock the behavior down.

1. Edit `pkg/grpc/proto/seshat.proto` and add or change the RPC or message you need.
2. Regenerate the Go stubs in `pkg/grpc/seshat/` using `protoc`.
3. Implement the server method in `cmd/grpc/main.go` and map it to real runtime behavior instead of placeholder logic.
4. If you add a brand new service, register it explicitly on the gRPC server. The proto declaration alone does not expose it.
5. Add bufconn-backed integration tests in `cmd/grpc/main_test.go` so request validation, streaming shape, and cleanup behavior stay stable.
6. Rebuild, test, and then update docs so transport examples stay aligned with the real contract.

type FileServer struct {
    pb.UnimplementedFileServiceServer
}

func (s *FileServer) Read(ctx context.Context, req *pb.FileReadRequest) (*pb.FileReadResponse, error) {
    // map request to the runtime or filesystem layer here
    return &pb.FileReadResponse{Content: "..."}, nil
}

grpcServer := grpc.NewServer(...)
pb.RegisterSeshatServiceServer(grpcServer, NewSeshatServer(hostConfig))
pb.RegisterFileServiceServer(grpcServer, &FileServer{})

Current Gaps

This is the part that matters if your goal is to complete the gRPC surface rather than just consume it. These are the concrete gaps visible in the current implementation and proto contract.

The highest-value next steps are straightforward: wire `temperature`, either remove or implement the proto-only services, populate `GetSkillDetails.prompt` if exposing skill bodies is intended, and add a real auth or proxy story if the server is meant to live beyond localhost.