Skip to content

Common types

Shared messages and enums from commons.proto, and any declared type no method reaches.

Status frames on a stream

Some StreamChunk frames carry no output: they report that the stream is alive and how far the generation has got. They have empty text, is_final false, and say so in metadata. The keys are listed under Calling the API.

The judgement types

Judgement and JudgementSet come from runink/ui/judgement/v1/judgement.proto in org-runink/ui, vendored into grpc/api/proto-vendor/. See The judging ladder.

commons.proto

// User represents a PULSE platform user.
message User {
  string id = 1;
  string email = 2;
  string display_name = 3;
  string avatar_url = 4;
  string role = 5; // "admin", "editor", "viewer"
  google.protobuf.Timestamp created_at = 6;
  google.protobuf.Timestamp updated_at = 7;
}

// PaginationRequest allows clients to paginate through list results.
message PaginationRequest {
  int32 page = 1;
  int32 page_size = 2;
  string order_by = 3;   // e.g. "created_at desc"
  string filter = 4;     // free-form filter expression
}

// PaginationResponse returns pagination metadata alongside list results.
message PaginationResponse {
  int32 total_count = 1;
  int32 page = 2;
  int32 page_size = 3;
  int32 total_pages = 4;
}

// Channel represents a social/content distribution channel.
enum Channel {
  CHANNEL_UNSPECIFIED = 0;
  CHANNEL_LINKEDIN = 1;
  CHANNEL_INSTAGRAM = 2;
  CHANNEL_TIKTOK = 3;
  CHANNEL_BLOG = 4;
  CHANNEL_EMAIL = 5;
  CHANNEL_TWITTER = 6;
  CHANNEL_YOUTUBE = 7;
  CHANNEL_FACEBOOK = 8;
  CHANNEL_WHITEPAPER = 9;
  CHANNEL_BOOK_OUTLINE = 10;
  CHANNEL_WEBINAR = 11;
  CHANNEL_COURSE = 12;
  CHANNEL_PODCAST = 13;
  // Google Business Profile posts (update, offer, event): gbp.proto.
  CHANNEL_GOOGLE_BUSINESS = 14;
}

// ContentStatus tracks the lifecycle of generated content.
enum ContentStatus {
  CONTENT_STATUS_UNSPECIFIED = 0;
  CONTENT_STATUS_DRAFT = 1;
  CONTENT_STATUS_PENDING_REVIEW = 2;
  CONTENT_STATUS_APPROVED = 3;
  CONTENT_STATUS_REJECTED = 4;
  CONTENT_STATUS_PUBLISHED = 5;
  CONTENT_STATUS_ARCHIVED = 6;
}

// CampaignStatus tracks campaign lifecycle.
enum CampaignStatus {
  CAMPAIGN_STATUS_UNSPECIFIED = 0;
  CAMPAIGN_STATUS_DRAFT = 1;
  CAMPAIGN_STATUS_ACTIVE = 2;
  CAMPAIGN_STATUS_PAUSED = 3;
  CAMPAIGN_STATUS_COMPLETED = 4;
  CAMPAIGN_STATUS_ARCHIVED = 5;
}

// TaskStatus tracks follow-up task states.
enum TaskStatus {
  TASK_STATUS_UNSPECIFIED = 0;
  TASK_STATUS_TODO = 1;
  TASK_STATUS_IN_PROGRESS = 2;
  TASK_STATUS_DONE = 3;
  TASK_STATUS_SKIPPED = 4;
  TASK_STATUS_BLOCKED = 5;
}

// IntegrationStatus for external service connections.
enum IntegrationStatus {
  INTEGRATION_STATUS_UNSPECIFIED = 0;
  INTEGRATION_STATUS_DISCONNECTED = 1;
  INTEGRATION_STATUS_CONNECTED = 2;
  INTEGRATION_STATUS_ERROR = 3;
  INTEGRATION_STATUS_PENDING = 4;
}

// StreamChunk is the universal wrapper for server-streaming AI responses.
message StreamChunk {
  string text = 1;
  bool is_final = 2;
  string section = 3;      // semantic section marker (e.g. "positioning", "swot", "prescription")
  float progress = 4;      // 0.0 - 1.0
  map<string, string> metadata = 5;
  // Real, backend-verified actions taken while producing this chunk (e.g.
  // "Scraped live content from acme.com") — not model self-report. Sent as
  // one-off chunks alongside text chunks; a chunk with agent_tasks set may
  // have empty text. Same shape as ModelService.Complete's agent_tasks
  // tag convention, generalized onto the wire instead of text-embedded tags.
  repeated string agent_tasks = 6;
  // The assistant's server-side tool loop (assistant_tools.go): one tool it
  // ran, or refused, for this turn. Only ModelService.Complete sets it.
  AssistantToolEvent tool_event = 7;
  // An action the assistant proposes. Nothing has run: it runs only when the
  // user taps Confirm (ModelService.ConfirmAssistantAction).
  AssistantProposal proposal = 8;
}

// One tool step of the assistant. The client words it from `tool` and
// `status`; `detail` is the server's refusal or failure reason.
message AssistantToolEvent {
  string tool = 1;   // registry name, e.g. "list_leads"; empty for a loop-level event
  string status = 2; // running | done | refused | failed | blocked (the guard refused the message; detail = reason) | step_limit | deadline
  string detail = 3;
  int32 count = 4;   // rows the read returned; meaningful only when counted
  bool counted = 5;
}

// A proposed action, held server-side until it expires. `args` is shown to
// the user; Confirm runs the server's own copy, so the client cannot alter it.
message AssistantProposal {
  string id = 1;
  string tool = 2;
  map<string, string> args = 3;
  string route = 4; // the page the action changes
  google.protobuf.Timestamp expires_at = 5;
}

// DateRange for filtering by date.
message DateRange {
  google.protobuf.Timestamp start = 1;
  google.protobuf.Timestamp end = 2;
}

// KeyValue for generic key-value pairs.
message KeyValue {
  string key = 1;
  string value = 2;
}

// MetricPoint for time-series data.
message MetricPoint {
  google.protobuf.Timestamp timestamp = 1;
  double value = 2;
  string label = 3;
}

message Runner {
  string name = 1;
  string endpoint = 2;
  string state = 13;
  double compute_units = 4;
  string description = 5;
  string type = 6;
  int32 port = 7;
  int32 cpus = 8;
  string memory = 9;
  string image_repository = 10;
}

message Connection {
  string name = 1;
  string type = 2;
  string environment = 3;
  string runner = 4;
  string id = 5;
  map<string, string> properties = 17;
}

message ActionCard {
  string id = 1;
  string title = 2;
  string type = 3;
  string priority = 4;
  string impact = 5;
  string status = 6;
}

Types no method uses

Declared in the protos but reached by no method’s request or response.

// automation.proto
message AutomationStepKind {
  string kind = 1;
  bool trigger = 2;
  bool outbound = 3;
  // Can it do its work on this server now?
  bool available = 4;
  // Why not (the server's sentence), when not.
  string reason = 5;
  repeated string branches = 6;
}