Implement AgentStateService (Go) with Postgres + docker-compose + e2e tests

[rowan-stein]

Goal

Implement the AgentStateService in Go per the merged schema in agynio/api, using Postgres as the backing store. Do not commit .proto files; fetch via buf. Provide full e2e tests and docker-compose for DB.

References

• API schema: https://github.com/agynio/api/tree/main/proto/agynio/api/agent_state/v1
• Module name (buf): buf.build/agynio/api

Requirements

• Language: Go
• RPC: gRPC (protoc-gen-go + protoc-gen-go-grpc)
• Proto fetching: buf (buf.yaml/lock in this repo, no proto vendoring)
• DB: PostgreSQL (docker-compose provided for local/e2e)
• Schema model:
  • Conversations, Messages, Conversation ordering (position), Snapshots, Snapshot items
  • Ordered list semantics with range Replace/Delete and Append to tail
• Implement RPCs:
  • AppendConversationMessages
  • ListConversationMessages (ordered oldest→newest)
  • ReplaceConversationMessagesRange (optional from_id/to_id semantics per proto comments)
  • DeleteConversationMessagesRange (optional from_id/to_id semantics per proto comments)
  • GetConversation
  • ListConversationMessageIds (ordered oldest→newest)
  • CreateSnapshot
  • ListSnapshotMessages
  • ListSnapshotMessageIds
• Typed messages:
  • TextBody for user/assistant/system
  • ToolOutputBody { ToolTextOutput | ToolImageOutput(external_url only) }

Implementation notes

• DB schema:
  • conversations(id uuid pk, message_count, updated_at, version bigint default 0)
  • messages(id uuid pk, conversation_id fk, role, kind, body_text, tool_name, tool_call_id, tool_text, tool_image_external_url, tool_image_mime_type, tool_image_detail, width, height, sha256, created_at)
  • conversation_items(conversation_id, position bigserial, message_id fk, primary key(conversation_id, position))
  • snapshots(id uuid pk, conversation_id, created_at)
  • snapshot_items(snapshot_id, order_idx, message_id, denormalized body fields as needed)
• Keep ordering deterministic via position (bigserial) per conversation.
• Transactions: perform Replace/Delete ranges atomically.
• E2E tests (Go): bring up Postgres via docker-compose, run migrations, start server, and exercise all RPCs including range semantics and snapshots. Verify ordering and payloads.
• CI: GitHub Actions matrix (lint, buf deps/generate, go build/test), service docker build optional.

Definition of Done

• Passing e2e tests in CI
• docker-compose up runs DB; README documents dev workflow
• No proto sources committed; buf dep + generate documented

[casey-brooks]

Implemented the AgentStateService backend with Postgres storage, migrations, docker-compose harness, and gRPC server in PR #2.