behest 0.3.1

syntax = "proto3";

package agent.v1;

import "agent/v1/common.proto";
import "google/protobuf/timestamp.proto";

// Agent event emitted during a run.
message AgentEvent {
  uint64 sequence = 1;
  string run_id = 2;
  oneof event {
    RunStartedEvent run_started = 3;
    ContextBuiltEvent context_built = 4;
    ModelStartedEvent model_started = 5;
    TextDeltaEvent text_delta = 6;
    ToolCallStartedEvent tool_call_started = 7;
    ToolCallDeltaEvent tool_call_delta = 8;
    ToolCallCompletedEvent tool_call_completed = 9;
    ToolExecutionStartedEvent tool_execution_started = 10;
    ToolExecutionFinishedEvent tool_execution_finished = 11;
    AssistantMessageCommittedEvent assistant_message_committed = 12;
    ToolMessageCommittedEvent tool_message_committed = 13;
    UsageRecordedEvent usage_recorded = 14;
    RunCompletedEvent run_completed = 15;
    RunFailedEvent run_failed = 16;
    RunCancelledEvent run_cancelled = 17;
    DoomLoopDetectedEvent doom_loop_detected = 18;
    CompactionCircuitOpenedEvent compaction_circuit_opened = 19;
  }
  google.protobuf.Timestamp timestamp = 20;
  // W3C trace context: trace ID (hex string, empty if unavailable).
  string trace_id = 21;
  // W3C trace context: span ID (hex string, empty if unavailable).
  string span_id = 22;
}

// Event payloads (run_id and timestamp are on the enclosing AgentEvent).

message RunStartedEvent {
  string session_id = 1;
  string provider = 2;
  string model = 3;
}

message ContextBuiltEvent {
  uint32 message_count = 1;
}

message ModelStartedEvent {
  string provider = 1;
  string model = 2;
  uint32 iteration = 3;
}

message TextDeltaEvent {
  string delta = 1;
}

message ToolCallStartedEvent {
  string call_id = 1;
  string tool_name = 2;
}

message ToolCallDeltaEvent {
  string call_id = 1;
  string delta = 2;
}

message ToolCallCompletedEvent {
  ToolCall call = 1;
}

message ToolExecutionStartedEvent {
  string call_id = 1;
  string tool_name = 2;
}

message ToolExecutionFinishedEvent {
  string call_id = 1;
  string tool_name = 2;
  uint64 duration_ms = 3;
}

message AssistantMessageCommittedEvent {
  string message_id = 1;
}

message ToolMessageCommittedEvent {
  string message_id = 1;
}

message UsageRecordedEvent {
  TokenUsage usage = 1;
}

message RunCompletedEvent {
  FinishReason finish_reason = 1;
  uint32 iterations = 2;
}

message RunFailedEvent {
  string error = 1;
}

message RunCancelledEvent {}

message DoomLoopDetectedEvent {
  string description = 1;
}

message CompactionCircuitOpenedEvent {
  uint32 consecutive_failures = 1;
}

// Run record.
message RunRecord {
  string id = 1;
  string session_id = 2;
  RunStatus status = 3;
  ProviderId provider = 4;
  ModelName model = 5;
  string metadata = 6; // JSON
  google.protobuf.Timestamp created_at = 7;
  google.protobuf.Timestamp updated_at = 8;
}

// Run output.
message RunOutput {
  string run_id = 1;
  string session_id = 2;
  uint32 iterations = 3;
  FinishReason finish_reason = 4;
  TokenUsage total_usage = 5;
  repeated Message messages = 6; // assistant messages produced
}

// Create run request.
message CreateRunRequest {
  string session_id = 1; // optional, creates new session if empty
  ProviderId provider = 2;
  ModelName model = 3;
  string input = 4;
  string metadata = 5;   // JSON, optional
  string tool_choice = 6; // "auto", "none", "required"
  string client_request_id = 7; // optional idempotency key
}

// Create run response (async).
message CreateRunResponse {
  string run_id = 1;
  string session_id = 2;
}

// List runs request.
message ListRunsRequest {
  string session_id = 1; // optional filter
  RunStatus status = 2;  // optional filter
  Pagination pagination = 3;
}

// List runs response.
message ListRunsResponse {
  repeated RunRecord runs = 1;
}

// Get run request.
message GetRunRequest {
  string run_id = 1;
}

// Get run response.
message GetRunResponse {
  RunRecord run = 1;
}

// Get run output request.
message GetRunOutputRequest {
  string run_id = 1;
}

// Get run output response.
message GetRunOutputResponse {
  RunOutput output = 1;
}

// Cancel run request.
message CancelRunRequest {
  string run_id = 1;
}

// Cancel run response.
message CancelRunResponse {}

// Watch events request (SSE equivalent).
message WatchRunEventsRequest {
  string run_id = 1;
  uint64 last_event_id = 2; // for reconnection
}

// Run service.
service RunService {
  // Create a run (async, returns immediately).
  rpc CreateRun(CreateRunRequest) returns (CreateRunResponse);
  // Create a run and stream events (server-streaming).
  rpc CreateRunStream(CreateRunRequest) returns (stream AgentEvent);
  // List runs (optionally filtered by session/status).
  rpc ListRuns(ListRunsRequest) returns (ListRunsResponse);
  // Get a run record.
  rpc GetRun(GetRunRequest) returns (GetRunResponse);
  // Get final run output.
  rpc GetRunOutput(GetRunOutputRequest) returns (GetRunOutputResponse);
  // Cancel an active run.
  rpc CancelRun(CancelRunRequest) returns (CancelRunResponse);
  // Watch events for a run (server-streaming, replay + live).
  rpc WatchRunEvents(WatchRunEventsRequest) returns (stream AgentEvent);
}

// --- Compaction service ---

// Get compaction config request.
message GetCompactionConfigRequest {}

// Get compaction config response.
message GetCompactionConfigResponse {
  bool auto = 1;
  bool prune = 2;
  uint64 buffer_tokens = 3;
  uint64 keep_tokens = 4;
  uint32 tail_turns = 5;
  string model = 6;
  string provider = 7;
  uint32 circuit_breaker_threshold = 8;
}

// Update compaction config request.
message UpdateCompactionConfigRequest {
  bool auto = 1;
  bool prune = 2;
  uint64 buffer_tokens = 3;
  uint64 keep_tokens = 4;
  uint32 tail_turns = 5;
  string model = 6;
  string provider = 7;
  uint32 circuit_breaker_threshold = 8;
}

// Update compaction config response.
message UpdateCompactionConfigResponse {}

// Get circuit breaker state request.
message GetCircuitBreakerRequest {}

// Get circuit breaker state response.
message GetCircuitBreakerResponse {
  bool is_open = 1;
  uint32 consecutive_failures = 2;
}

// Compaction service.
service CompactionService {
  rpc GetCompactionConfig(GetCompactionConfigRequest) returns (GetCompactionConfigResponse);
  rpc UpdateCompactionConfig(UpdateCompactionConfigRequest) returns (UpdateCompactionConfigResponse);
  rpc GetCircuitBreaker(GetCircuitBreakerRequest) returns (GetCircuitBreakerResponse);
}

// --- Snapshot service ---

// Snapshot info.
message SnapshotInfo {
  string run_id = 1;
  string session_id = 2;
  RunStatus status = 3;
  uint32 iteration = 4;
  TokenUsage total_usage = 5;
  google.protobuf.Timestamp timestamp = 6;
}

// List snapshots request.
message ListSnapshotsRequest {}

// List snapshots response.
message ListSnapshotsResponse {
  repeated SnapshotInfo snapshots = 1;
}

// Get snapshot request.
message GetSnapshotRequest {
  string run_id = 1;
}

// Get snapshot response.
message GetSnapshotResponse {
  SnapshotInfo snapshot = 1;
}

// Delete snapshot request.
message DeleteSnapshotRequest {
  string run_id = 1;
}

// Delete snapshot response.
message DeleteSnapshotResponse {}

// Snapshot service.
service SnapshotService {
  rpc ListSnapshots(ListSnapshotsRequest) returns (ListSnapshotsResponse);
  rpc GetSnapshot(GetSnapshotRequest) returns (GetSnapshotResponse);
  rpc DeleteSnapshot(DeleteSnapshotRequest) returns (DeleteSnapshotResponse);
}