syntax = "proto3";

package sandlet.v1;
option go_package = "codeberg.org/sandlet/sandlet-sdk/proto/sandlet/v1;sandletv1";

service AgentService {
  rpc Describe(DescribeRequest) returns (DescribeResponse);
  rpc RunOnce(RunRequest) returns (RunResponse);
}

message DescribeRequest {}

message DescribeResponse {
  string agent_name = 1;
  string sdk_version = 2;
  repeated Module modules = 3;
  map<string, string> declared_limits = 4;
  map<string, string> metadata = 5;
}

message Module {
  string name = 1;
  string description = 2;
  repeated string capabilities = 3;
  repeated Function functions = 4;
  repeated ModuleParameter parameters = 5;
}

message ModuleParameter {
  string name = 1;
  string description = 2;
  bool secret = 3;
}

message Function {
  string name = 1;
  string description = 2;
  repeated string arg_names = 3;
  string return_type_hint = 4;
}

message RunRequest {
  // Script source passed directly as a string. No local file access.
  string script = 1;
  reserved 2;
  repeated string args = 3;
  RunLimits limits = 4;
  map<string, string> parameters = 5;
}

message RunLimits {
  optional uint64 max_script_bytes = 1;
  optional uint64 max_args = 2;
  optional uint64 max_arg_bytes = 3;
  optional uint64 max_output_bytes = 4;
  optional uint32 timeout_s = 5;
  optional uint64 max_temp_bytes = 6;
  optional string metadata = 7;
}

// Result wrapper for fallible operations.
message RunResponse {
  oneof result {
    RunSuccess success = 1;
    RunFailure failure = 2;
  }
}

message RunSuccess {
  reserved 1;
  string output = 2;
  repeated Diagnostic diagnostics = 3;
  repeated LogEntry logs = 4;
}

message RunFailure {
  string message = 1;
  repeated Diagnostic diagnostics = 2;
  ErrorKind kind = 3;
}

enum ErrorKind {
  ERROR_KIND_UNSPECIFIED = 0;
  INVALID_REQUEST = 1;
  COMPILE = 2;
  RUNTIME_CONTRACT = 3;
  RUNTIME_EXECUTION = 4;
  TRANSPORT = 5;
  RESOURCE_EXHAUSTED = 6;
  CANCELLED = 7;
  INTERNAL = 8;
  PANIC = 9;
}

// A structured diagnostic emitted during compilation or execution.
message Diagnostic {
  enum Category {
    CATEGORY_UNSPECIFIED = 0;
    INVALID_REQUEST = 1;
    COMPILE = 2;
    RUNTIME_CONTRACT = 3;
    RUNTIME_EXECUTION = 4;
    TRANSPORT = 5;
    RESOURCE_EXHAUSTED = 6;
    CANCELLED = 7;
    INTERNAL = 8;
    PANIC = 9;
  }

  enum Severity {
    SEVERITY_UNSPECIFIED = 0;
    ERROR = 1;
    WARNING = 2;
    INFO = 3;
    DEBUG = 4;
  }

  Category category = 1;
  Severity severity = 2;
  string message = 3;
  SourceLocation location = 4;
  string code = 5;
}

// A source location inside a script or module.
message SourceLocation {
  string file = 1;
  uint32 line = 2;
  uint32 column = 3;
  uint64 start_byte = 4;
  uint64 end_byte = 5;
}

// A single structured log entry emitted during a run.
message LogEntry {
  enum Severity {
    SEVERITY_UNSPECIFIED = 0;
    ERROR = 1;
    WARNING = 2;
    INFO = 3;
    DEBUG = 4;
  }

  Severity severity = 1;
  string message = 2;
}
