Files
archie/proto/state/v1/state.proto
T
sam 6fa7c15398 fix(staterpc): carry each model provider's credential reference
The State Store wire described a provider's class, base URL and key variable
but never where its key lives, so every provider reached the daemon
credential-less. A task then built its runtime with no key: the egress session
had nothing to bind and the agent parked on 'APIKey is required'.

Carry api_key_engine and api_key_key alongside the provider. They are a
reference, not a secret; the key is still resolved daemon-side and never
travels to a container.
2026-10-20 07:10:58 +11:00

1838 lines
70 KiB
Protocol Buffer

syntax = "proto3";
package state.v1;
import "logging/v1/logging.proto";
import "google/protobuf/timestamp.proto";
// StateStore is the single gRPC service fronting archie's PostgreSQL database.
// See docs/prds/state-store-contract.md for the ownership split: the
// workflow-domain Store view (Update/Transition/InsertEvent) is consumer-owned
// in internal/domain/workflow, while the rest of this surface is
// producer-owned in internal/domain/storecontract. Both are served by the same
// service over internal/infrastructure/postgres; the proto bypasses the Go
// interfacebloat cap (max 8), like gateway.v1.ChatService does.
service StateStoreService {
rpc RecentLogs(RecentLogsRequest) returns (RecentLogsResponse);
// Installed Archie packages. Administrative until org-scoped principals land.
rpc InstallPackage(InstallPackageRequest) returns (InstallPackageResponse);
// ListCatalogue returns the packages the instance's verified catalogue
// offers; InstallFromCatalogue installs one by name at the digest it lists.
rpc ListCatalogue(ListCatalogueRequest) returns (ListCatalogueResponse);
rpc InstallFromCatalogue(InstallFromCatalogueRequest) returns (InstallFromCatalogueResponse);
rpc GetInstalledPackage(GetInstalledPackageRequest) returns (GetInstalledPackageResponse);
rpc ListInstalledPackages(ListInstalledPackagesRequest) returns (ListInstalledPackagesResponse);
// AcceptPackageAuthority records the operator's accepted authority against
// the pinned digest (the approve action; install is the create action).
// Administrative until org-scoped principals land.
rpc AcceptPackageAuthority(AcceptPackageAuthorityRequest) returns (AcceptPackageAuthorityResponse);
rpc RemoveInstalledPackage(RemoveInstalledPackageRequest) returns (RemoveInstalledPackageResponse);
// UpdatePackage moves a package to the digest the verified catalogue lists:
// a non-widening update applies, a widening one waits as pending.
// ApprovePackageUpdate applies the pending update and accepts its authority;
// RollbackPackage restores the previous digest and its accepted authority.
rpc UpdatePackage(UpdatePackageRequest) returns (UpdatePackageResponse);
rpc ApprovePackageUpdate(ApprovePackageUpdateRequest) returns (ApprovePackageUpdateResponse);
rpc RollbackPackage(RollbackPackageRequest) returns (RollbackPackageResponse);
// SetPackageUpdatePolicy sets "manual" or "auto"; the State Store updates
// auto packages on a timer.
rpc SetPackageUpdatePolicy(SetPackageUpdatePolicyRequest) returns (SetPackageUpdatePolicyResponse);
// Administrative task credential lifecycle. Worker credentials cannot call these.
rpc RegisterTaskGrant(RegisterTaskGrantRequest) returns (RegisterTaskGrantResponse);
rpc RevokeTaskGrant(RevokeTaskGrantRequest) returns (RevokeTaskGrantResponse);
rpc ResolveTaskGrant(ResolveTaskGrantRequest) returns (ResolveTaskGrantResponse);
// Identity domain. Task-scoped grants cannot call these administrative RPCs.
rpc ListIdentities(ListIdentitiesRequest) returns (ListIdentitiesResponse);
rpc GetAuthenticationSettings(GetAuthenticationSettingsRequest) returns (GetAuthenticationSettingsResponse);
rpc SaveAuthenticationSettings(SaveAuthenticationSettingsRequest) returns (SaveAuthenticationSettingsResponse);
rpc BeginPasskey(BeginPasskeyRequest) returns (BeginPasskeyResponse);
rpc FinishPasskey(FinishPasskeyRequest) returns (FinishPasskeyResponse);
rpc ListPasskeys(ListPasskeysRequest) returns (ListPasskeysResponse);
rpc DeletePasskey(DeletePasskeyRequest) returns (DeletePasskeyResponse);
rpc OpenAccountSession(OpenAccountSessionRequest) returns (OpenAccountSessionResponse);
rpc RequireFreshAccountSession(RequireFreshAccountSessionRequest) returns (RequireFreshAccountSessionResponse);
rpc CreateAccountRecovery(CreateAccountRecoveryRequest) returns (CreateAccountRecoveryResponse);
rpc RecoverAccount(RecoverAccountRequest) returns (RecoverAccountResponse);
rpc AccountSetup(AccountSetupRequest) returns (AccountSetupResponse);
rpc RegisterAccount(RegisterAccountRequest) returns (RegisterAccountResponse);
rpc SignInAccount(SignInAccountRequest) returns (SignInAccountResponse);
rpc ResolveAccountSession(ResolveAccountSessionRequest) returns (ResolveAccountSessionResponse);
rpc SignOutAccount(SignOutAccountRequest) returns (SignOutAccountResponse);
rpc ChangeAccountPassword(ChangeAccountPasswordRequest) returns (ChangeAccountPasswordResponse);
rpc GetIdentity(GetIdentityRequest) returns (GetIdentityResponse);
rpc CreateIdentity(CreateIdentityRequest) returns (CreateIdentityResponse);
rpc RenameIdentity(RenameIdentityRequest) returns (RenameIdentityResponse);
rpc SuspendIdentity(SuspendIdentityRequest) returns (SuspendIdentityResponse);
rpc ReactivateIdentity(ReactivateIdentityRequest) returns (ReactivateIdentityResponse);
rpc RetireIdentity(RetireIdentityRequest) returns (RetireIdentityResponse);
// Subject bindings. A verified provider subject is resolved to the identity it
// is bound to; the authenticating process calls these rather than owning the
// identity store.
rpc ResolveIdentitySubject(ResolveIdentitySubjectRequest) returns (ResolveIdentitySubjectResponse);
rpc BindIdentitySubject(BindIdentitySubjectRequest) returns (BindIdentitySubjectResponse);
rpc ClaimIdentitySubject(ClaimIdentitySubjectRequest) returns (ClaimIdentitySubjectResponse);
// Personal API tokens act on the caller's own principal: the State Store
// refuses a call that carries none.
rpc AddPersonalToken(AddPersonalTokenRequest) returns (AddPersonalTokenResponse);
rpc ListPersonalTokens(ListPersonalTokensRequest) returns (ListPersonalTokensResponse);
rpc RevokePersonalToken(RevokePersonalTokenRequest) returns (RevokePersonalTokenResponse);
// Lifecycle
rpc EnqueueIssue(EnqueueIssueRequest) returns (EnqueueIssueResponse);
rpc EnqueueChatTask(EnqueueChatTaskRequest) returns (EnqueueChatTaskResponse);
rpc ActiveTasksByOrigin(ActiveTasksByOriginRequest) returns (ActiveTasksByOriginResponse);
// UnpostedOutcomes lists finished chat tasks whose outcome has not yet been
// posted to their conversation; MarkOutcomePosted records that it was.
rpc UnpostedOutcomes(UnpostedOutcomesRequest) returns (UnpostedOutcomesResponse);
rpc MarkOutcomePosted(MarkOutcomePostedRequest) returns (MarkOutcomePostedResponse);
rpc ClaimNext(ClaimNextRequest) returns (ClaimNextResponse);
rpc ClaimByIssue(ClaimByIssueRequest) returns (ClaimByIssueResponse);
rpc Transition(TransitionRequest) returns (TransitionResponse);
rpc Update(UpdateRequest) returns (UpdateResponse);
// Step executions (docs/prds/execution-tree-state-machine.md). The run
// credential authorises both on its own execution only.
rpc StartStep(StartStepRequest) returns (StartStepResponse);
// RecordUsage appends one model call's usage record. A run credential may
// record usage only for its own task.
rpc RecordUsage(RecordUsageRequest) returns (RecordUsageResponse);
// TaskModels answers what a task's models resolve against: the aliases its
// org may use and the org's own providers. The org is the task's, never
// the caller's.
rpc TaskModels(TaskModelsRequest) returns (TaskModelsResponse);
// TaskInstructions answers the instance and organisation instructions a
// task's agent runs follow. Organisation is empty for a system-org task.
rpc TaskInstructions(TaskInstructionsRequest) returns (TaskInstructionsResponse);
// CallerModels answers the model aliases the caller's org may use. The org
// is the calling principal's; a call with none is the system org's.
rpc CallerModels(CallerModelsRequest) returns (CallerModelsResponse);
rpc FinishStep(FinishStepRequest) returns (FinishStepResponse);
// Cancellation. Deliberately administrative (deny-by-default for a
// task-scoped grant): a cancel is a dashboard, API and dispatch action
// decided by the Authorizer, not a worker call.
rpc CancelExecution(CancelExecutionRequest) returns (CancelExecutionResponse);
// ListSteps is a dashboard/API/dispatch action (Authorizer: read on the
// run), not task-scoped-grant callable like StartStep/FinishStep.
rpc ListSteps(ListStepsRequest) returns (ListStepsResponse);
// Harness OAuth secrets (docs/prds/external-agent-harness.md,
// Credentials). Administrative: the setup terminal (an `update` action on
// the secret, Authorizer-gated) and the egress proxy's token-endpoint
// interception (acting as the daemon, not a worker) are the only callers.
rpc GetHarnessSecret(GetHarnessSecretRequest) returns (GetHarnessSecretResponse);
rpc PutHarnessSecret(PutHarnessSecretRequest) returns (PutHarnessSecretResponse);
rpc Requeue(RequeueRequest) returns (RequeueResponse);
rpc ParkTask(ParkTaskRequest) returns (ParkTaskResponse);
rpc RecoverStale(RecoverStaleRequest) returns (RecoverStaleResponse);
// Archive / Retry
rpc ArchiveTask(ArchiveTaskRequest) returns (ArchiveTaskResponse);
rpc RetryTask(RetryTaskRequest) returns (RetryTaskResponse);
// RespondReviewGate is the operator's answer to the review gate
// (docs/prds/pr-review-operator-response.md, Decision 2): one guarded
// requeue that records the answer, increments rereview_rounds for a
// re-review, and refuses a re-review past cap with the ErrRereviewCapReached
// wire sentinel. Admin-only, like every other operator surface: a
// task-scoped grant never reaches it.
rpc RespondReviewGate(RespondReviewGateRequest) returns (RespondReviewGateResponse);
rpc BeginRemediation(BeginRemediationRequest) returns (BeginRemediationResponse);
rpc UpdateReviewPayload(UpdateReviewPayloadRequest) returns (UpdateReviewPayloadResponse);
rpc SetReviewCursors(SetReviewCursorsRequest) returns (SetReviewCursorsResponse);
// Queries
rpc TaskByIssue(TaskByIssueRequest) returns (TaskByIssueResponse);
rpc OpenTaskByPR(OpenTaskByPRRequest) returns (OpenTaskByPRResponse);
rpc TaskByID(TaskByIDRequest) returns (TaskByIDResponse);
rpc OpenPRs(OpenPRsRequest) returns (OpenPRsResponse);
rpc ClearTerminalTasks(ClearTerminalTasksRequest) returns (ClearTerminalTasksResponse);
rpc Tasks(TasksRequest) returns (TasksResponse);
rpc StatusCounts(StatusCountsRequest) returns (StatusCountsResponse);
// Events
rpc InsertEvent(InsertEventRequest) returns (InsertEventResponse);
rpc EventsSince(EventsSinceRequest) returns (EventsSinceResponse);
rpc TaskEvents(TaskEventsRequest) returns (TaskEventsResponse);
rpc WorkflowStats(WorkflowStatsRequest) returns (WorkflowStatsResponse);
rpc StageStats(StageStatsRequest) returns (StageStatsResponse);
rpc TokensByDay(TokensByDayRequest) returns (TokensByDayResponse);
// Configuration snapshot: the running configuration as the dashboard
// renders it, published by the owner of configuration for the process that
// displays it. PutConfigSnapshot is administrative; GetConfigSnapshot is
// the UI's read (docs/architecture/migration-decisions.md, "Dashboard
// configuration page").
rpc PutConfigSnapshot(PutConfigSnapshotRequest) returns (PutConfigSnapshotResponse);
rpc GetConfigSnapshot(GetConfigSnapshotRequest) returns (GetConfigSnapshotResponse);
// Channel status is what the process HOSTING the channels observes about them:
// one row per channel, written by the Messaging Service and read by the UI
// process. Administrative like the config snapshot, and for the same reason --
// a task-scoped grant reaches neither, so authorizesTaskScopedCall admits only
// the administrative token. It is runtime state rather than a settings
// document, which is why it is not a ControlPlaneService resource kind.
rpc PutChannelStatus(PutChannelStatusRequest) returns (PutChannelStatusResponse);
rpc ListChannelStatus(ListChannelStatusRequest) returns (ListChannelStatusResponse);
// Apply status: which version of a control-plane resource each process is
// running, and why it could not. Every process that applies a resource
// publishes; the UI process reads (docs/prds/control-plane-apply-status.md).
// Both are administrative.
rpc PutApplyStatus(PutApplyStatusRequest) returns (PutApplyStatusResponse);
rpc ListApplyStatus(ListApplyStatusRequest) returns (ListApplyStatusResponse);
// Presence: every running service instance re-stamps one record, so a
// record past the staleness window means that instance is down.
// Administrative.
rpc PutPresence(PutPresenceRequest) returns (PutPresenceResponse);
// Capture refusals: events the network rules refused at the receiver,
// counted per source. Administrative.
rpc RecordCaptureRefusal(RecordCaptureRefusalRequest) returns (RecordCaptureRefusalResponse);
rpc ListCaptureRefusals(ListCaptureRefusalsRequest) returns (ListCaptureRefusalsResponse);
rpc ListPresence(ListPresenceRequest) returns (ListPresenceResponse);
// Task log: one task attempt's persisted log. Task log files live in the
// state directory this process owns, so the dashboard reads them over this
// contract rather than opening them itself
// (docs/prds/ui-service-boundary.md).
rpc ReadTaskLog(ReadTaskLogRequest) returns (ReadTaskLogResponse);
// StreamTaskLogContent returns one attempt's log verbatim, one chunk per
// message, for a download. A log file is unbounded input (it rotates at
// DefaultMaxSizeMB), so a unary response would exceed gRPC's 4MiB message
// cap on a real log -- the same reason ListCaptures was superseded by
// StreamCaptures.
rpc StreamTaskLogContent(StreamTaskLogContentRequest) returns (stream StreamTaskLogContentResponse);
// Capture
rpc InsertCapture(InsertCaptureRequest) returns (InsertCaptureResponse);
// StreamCaptures returns one capture per message: a batch of large capture
// bodies can exceed gRPC's 4MiB unary message cap
// (docs/prds/state-store-contract.md).
rpc StreamCaptures(StreamCapturesRequest) returns (stream StreamCapturesResponse);
// Mapping
rpc InsertMapping(InsertMappingRequest) returns (InsertMappingResponse);
rpc GetMapping(GetMappingRequest) returns (GetMappingResponse);
rpc ListMappings(ListMappingsRequest) returns (ListMappingsResponse);
rpc UpdateMapping(UpdateMappingRequest) returns (UpdateMappingResponse);
rpc DeleteMapping(DeleteMappingRequest) returns (DeleteMappingResponse);
// RecordMappingMatch counts one event a mapping resolved; the same
// (mapping, capture) twice counts once.
rpc RecordMappingMatch(RecordMappingMatchRequest) returns (RecordMappingMatchResponse);
// EventType (docs/prds/event-automation.md, "Event types"). Insert and
// Update refuse an overlapping or malformed type.
rpc InsertEventType(InsertEventTypeRequest) returns (InsertEventTypeResponse);
rpc UpdateEventType(UpdateEventTypeRequest) returns (UpdateEventTypeResponse);
rpc DeleteEventType(DeleteEventTypeRequest) returns (DeleteEventTypeResponse);
rpc ListEventTypes(ListEventTypesRequest) returns (ListEventTypesResponse);
// Binding
rpc InsertBinding(InsertBindingRequest) returns (InsertBindingResponse);
rpc GetBinding(GetBindingRequest) returns (GetBindingResponse);
rpc ListBindings(ListBindingsRequest) returns (ListBindingsResponse);
rpc ListDispatches(ListDispatchesRequest) returns (ListDispatchesResponse);
rpc UpdateBinding(UpdateBindingRequest) returns (UpdateBindingResponse);
rpc DeleteBinding(DeleteBindingRequest) returns (DeleteBindingResponse);
rpc ApproveBinding(ApproveBindingRequest) returns (ApproveBindingResponse);
rpc PauseBinding(PauseBindingRequest) returns (PauseBindingResponse);
rpc ResumeBinding(ResumeBindingRequest) returns (ResumeBindingResponse);
// Source (event-automation.md "Sources"): the capture endpoint and its
// signing setting. Secrets travel in plaintext; the store encrypts at rest.
rpc InsertSource(InsertSourceRequest) returns (InsertSourceResponse);
rpc GetSource(GetSourceRequest) returns (GetSourceResponse);
rpc ListSources(ListSourcesRequest) returns (ListSourcesResponse);
rpc SetSourceSigning(SetSourceSigningRequest) returns (SetSourceSigningResponse);
rpc SetSourceSecret(SetSourceSecretRequest) returns (SetSourceSecretResponse);
rpc SetSourceName(SetSourceNameRequest) returns (SetSourceNameResponse);
rpc SetSourceDeliveryHeader(SetSourceDeliveryHeaderRequest) returns (SetSourceDeliveryHeaderResponse);
rpc DeleteSource(DeleteSourceRequest) returns (DeleteSourceResponse);
// Dispatch
rpc ArmedBindingsForSource(ArmedBindingsForSourceRequest) returns (ArmedBindingsForSourceResponse);
rpc RecordDispatch(RecordDispatchRequest) returns (RecordDispatchResponse);
// Playbook dispatch ledger (eda-playbook-engine.md gap 2): one durable
// at-most-once record per (playbook, version, event, action) for the
// side-effecting positions. Administrative, like RecordDispatch: a
// task-scoped grant cannot reach either (see TaskGrants).
rpc RecordPlaybookDispatch(RecordPlaybookDispatchRequest) returns (RecordPlaybookDispatchResponse);
rpc DeletePlaybookDispatches(DeletePlaybookDispatchesRequest) returns (DeletePlaybookDispatchesResponse);
rpc StreamUndispatchedCaptures(StreamUndispatchedCapturesRequest) returns (stream StreamUndispatchedCapturesResponse);
// BindingTaskCreator: claims the binding's dispatch of a capture and
// enqueues its task in one transaction, so a failure leaves neither and a
// replayed delivery is refused with AlreadyExists.
rpc EnqueueBindingTask(EnqueueBindingTaskRequest) returns (EnqueueBindingTaskResponse);
// WorkflowCaller: a workflow.call step starts its callee and, with
// wait:true, reads it back while waiting. Both are the one sanctioned
// widening of a task-scoped grant -- the callee is the caller's child
// (docs/prds/workflow-calls.md). CallStatus re-checks the parent-child
// relation server-side, so the grant only names the caller.
rpc EnqueueCallTask(EnqueueCallTaskRequest) returns (EnqueueCallTaskResponse);
rpc WorkflowCallStatus(WorkflowCallStatusRequest) returns (WorkflowCallStatusResponse);
// Access: the stored policy chain and its denial records
// (docs/prds/orgs-and-access.md). ListPolicies is the engine's snapshot;
// the writes are administrative. RecordDenial is the dashboard's and
// dispatch's write path; ListDenials is the operator surface.
// The principal assembly the Authorizer evaluates: an identity, the org
// it serves, and its memberships (internal/domain/access).
rpc GetPrincipal(GetPrincipalRequest) returns (GetPrincipalResponse);
rpc ListPolicies(ListPoliciesRequest) returns (ListPoliciesResponse);
rpc PutPolicy(PutPolicyRequest) returns (PutPolicyResponse);
rpc DeletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse);
rpc EnsureShippedOrgPolicies(EnsureShippedOrgPoliciesRequest) returns (EnsureShippedOrgPoliciesResponse);
rpc RecordDenial(RecordDenialRequest) returns (RecordDenialResponse);
rpc ListDenials(ListDenialsRequest) returns (ListDenialsResponse);
// Orgs, workspaces, memberships and agent assignments
// (docs/prds/orgs-and-access.md). Every request names an org, but the
// State Store acts in the org the caller's principal carries: a request
// org that is not the caller's is ignored, so the contract cannot reach
// another tenant. Instance-admin widening is a later change.
rpc ListOrgs(ListOrgsRequest) returns (ListOrgsResponse);
rpc GetOrg(GetOrgRequest) returns (GetOrgResponse);
rpc CreateOrg(CreateOrgRequest) returns (CreateOrgResponse);
rpc ListWorkspaces(ListWorkspacesRequest) returns (ListWorkspacesResponse);
rpc CreateWorkspace(CreateWorkspaceRequest) returns (CreateWorkspaceResponse);
rpc ListMembers(ListMembersRequest) returns (ListMembersResponse);
rpc SetMembership(SetMembershipRequest) returns (SetMembershipResponse);
rpc RemoveMembership(RemoveMembershipRequest) returns (RemoveMembershipResponse);
rpc ListOrgAgents(ListOrgAgentsRequest) returns (ListOrgAgentsResponse);
rpc AssignAgent(AssignAgentRequest) returns (AssignAgentResponse);
// Operator alerts (internal/domain/alert). A caller acting for a principal
// reads, dismisses and raises only in that principal's org; a request org is
// ignored for it. A service acting for no one names the org itself.
// RaiseAlert and ResolveAlert are idempotent, so a periodic check can call
// them every tick. ClaimAlertDeliveries and RecordAlertAttempt serve the
// outbound webhook and refuse a caller scoped to an org.
rpc RaiseAlert(RaiseAlertRequest) returns (RaiseAlertResponse);
rpc ResolveAlert(ResolveAlertRequest) returns (ResolveAlertResponse);
rpc DismissAlert(DismissAlertRequest) returns (DismissAlertResponse);
rpc ListAlerts(ListAlertsRequest) returns (ListAlertsResponse);
rpc ClaimAlertDeliveries(ClaimAlertDeliveriesRequest) returns (ClaimAlertDeliveriesResponse);
rpc RecordAlertAttempt(RecordAlertAttemptRequest) returns (RecordAlertAttemptResponse);
}
message RegisterTaskGrantRequest {
int64 task_id = 1;
string token = 2;
int64 lifetime_seconds = 3;
}
message RegisterTaskGrantResponse {}
message RevokeTaskGrantRequest {
string token = 1;
}
message RevokeTaskGrantResponse {}
// ResolveTaskGrantRequest names a run credential; the response is the task
// it was issued for.
message ResolveTaskGrantRequest { string token = 1; }
message ResolveTaskGrantResponse {
int64 task_id = 1;
// Canonical execution identity; empty names the instance root RPC route.
string execution_identity = 2;
// Canonical principal, including the instance root.
string principal_id = 3;
}
message Identity {
string id = 1;
string kind = 2;
string display_name = 3;
string lifecycle = 4;
int64 version = 5;
google.protobuf.Timestamp created_at = 6;
google.protobuf.Timestamp updated_at = 7;
}
message IdentityAudit {
string actor_id = 1;
string source = 2;
string request_id = 3;
}
message ListIdentitiesRequest {}
message ListIdentitiesResponse { repeated Identity identities = 1; }
message GetIdentityRequest { string id = 1; }
message GetIdentityResponse { Identity identity = 1; }
message CreateIdentityRequest {
string id = 1;
string kind = 2;
string display_name = 3;
IdentityAudit audit = 4;
}
message RenameIdentityRequest {
string id = 1;
int64 expected_version = 2;
string display_name = 3;
IdentityAudit audit = 4;
}
message SuspendIdentityRequest { string id = 1; int64 expected_version = 2; IdentityAudit audit = 3; }
message ReactivateIdentityRequest { string id = 1; int64 expected_version = 2; IdentityAudit audit = 3; }
message RetireIdentityRequest { string id = 1; int64 expected_version = 2; IdentityAudit audit = 3; }
message CreateIdentityResponse { Identity identity = 1; }
message RenameIdentityResponse { Identity identity = 1; }
message SuspendIdentityResponse { Identity identity = 1; }
message ReactivateIdentityResponse { Identity identity = 1; }
message RetireIdentityResponse { Identity identity = 1; }
message ResolveIdentitySubjectRequest {
string issuer = 1;
string subject = 2;
}
message ResolveIdentitySubjectResponse { Identity identity = 1; }
message BindIdentitySubjectRequest {
string id = 1;
string issuer = 2;
string subject = 3;
IdentityAudit audit = 4;
}
message BindIdentitySubjectResponse { Identity identity = 1; }
message ClaimIdentitySubjectRequest {
string issuer = 1;
string placeholder = 2;
string subject = 3;
}
message ClaimIdentitySubjectResponse { Identity identity = 1; }
// PersonalToken identifies a token by the SHA-256 it binds as; the token
// itself never reaches the State Store.
message PersonalToken {
string id = 1;
google.protobuf.Timestamp created_at = 2;
}
message AddPersonalTokenRequest { string id = 1; }
message AddPersonalTokenResponse {}
message ListPersonalTokensRequest {}
message ListPersonalTokensResponse { repeated PersonalToken tokens = 1; }
message RevokePersonalTokenRequest { string id = 1; }
message RevokePersonalTokenResponse {}
// Task mirrors internal/domain/workflow.Task.
message Task {
int64 id = 1;
string owner = 2;
string repo = 3;
int64 issue_number = 4;
string title = 5;
string body = 6;
string labels = 7;
string status = 8;
string workflow = 9;
// Retired: the per-task "current stage" column was overwritten as
// workflow.Run advanced and carried no history. step_executions is the
// durable per-step record now (docs/prds/execution-tree-state-machine.md);
// ListSteps is its read.
string stage = 10 [deprecated = true];
string branch = 11;
string plan = 12;
string notes = 13;
int64 pr_number = 14;
int64 tokens_used = 15;
int64 iterations = 16;
int64 attempt = 17;
string park_reason = 18;
int64 retry_count = 19;
int64 watch_comment_id = 20;
string source = 21;
string identity = 22;
string binding_id = 23;
int64 binding_version = 24;
google.protobuf.Timestamp created_at = 25;
google.protobuf.Timestamp updated_at = 26;
// review_payload is the JSON-encoded review unit the remediate workflow's
// current run must address (docs/prds/pr-review-remediation.md decision 4).
string review_payload = 27;
// The workflow pin: the exact definition version this run started with.
// It has to cross the wire for the daemon's digest guard to hold, because
// a retry reads the task back over this contract before deciding whether
// to reuse the pinned YAML (docs/prds/runtime-control-plane.md:95).
int64 workflow_definition_version = 28;
string workflow_definition_digest = 29;
string workflow_definition_yaml = 30;
// review_cursor is the poll backstop's high-water mark over forge review
// IDs for this task. It is separate from watch_comment_id (the review-
// comment cursor) because the two forge sequences are independent; one
// combined cursor would silently skip reviews once a larger comment ID
// landed (docs/prds/pr-review-remediation.md decision 2).
int64 review_cursor = 31;
// park_class is the producer-recorded answer to "what kind of
// intervention does this park need?" (taskstate.ParkClass:
// needs_human, transient, terminal). Store-side normalization makes
// empty and unknown values needs_human, so the class is advisory on
// the wire and authoritative only as recorded at the park site.
string park_class = 32;
// remediation_rounds counts review-triggered remediation rounds
// separately from retry_count, so an operator's manual retries no
// longer draw down the review-remediation budget (and vice versa).
int32 remediation_rounds = 33;
// inputs_json is the JSON object of workflow inputs a binding dispatch
// resolved (task.EncodeInputs); empty for a task no binding started.
string inputs_json = 34;
// org is the org the task belongs to, derived store-side from the task's
// identity when the row is written; a task of a single-operator install
// belongs to the default org (docs/prds/orgs-and-access.md).
string org = 35;
// The workflow.call linkage (docs/prds/workflow-calls.md): the task whose
// workflow.call step started this one (0 on a root run) and how many
// call hops this row is from that root. Columns default, so an older
// writer reads as a depth-0 root run.
int64 call_parent_task_id = 36;
int32 call_depth = 37;
// outputs_json is the JSON object of declared-output values this run wrote
// (task.EncodeOutputs), empty for a run that wrote none. The container's
// Update sends the whole row, so a column the message cannot carry is a
// column that write drops (docs/prds/workflow-call-outputs.md, "Storage and
// wire").
string outputs_json = 38;
// review_gate is the operator-approval gate's whole conversation with the
// operator (docs/prds/pr-review-operator-response.md): the offer the gate
// wrote before waiting, and the answer the response path filled in. It is
// opaque here -- internal/domain/workflow/prreview owns the encoding -- but
// it must cross so the dashboard can render the offer and the resumed run
// can read the answer.
string review_gate = 39;
// rereview_rounds counts granted operator re-reviews, capped by
// prreview.MaxRereviewRounds in the guarded response write. It is separate
// from retry_count and remediation_rounds for the same reason those are
// separate from each other.
int64 rereview_rounds = 40;
// retry_mode is the operator's worktree choice for the next dispatch
// (taskstate.RetryMode: refresh_onto_base, continue_pushed_work). The retry
// action writes it and the daemon's prepareWorkspace reads it, so it must
// cross the wire for a retry to land on the source the operator chose. The
// empty string reads as refresh_onto_base.
string retry_mode = 41;
// resume_from is the stage the next attempt starts at; empty runs every
// stage. resume_results are the step results (JSON) it starts with.
string resume_from = 42;
bytes resume_results = 43;
// origin names the conversation that created the task; empty for none.
string origin = 44;
// workspace is the workspace of its org the task belongs to; read-only
// here.
string workspace = 45;
// binding_signature and binding_addr are the signature result and address
// of the captured event that started a binding task.
string binding_signature = 46;
string binding_addr = 47;
// park_blocker names what a parked task is missing (taskstate.Blocker),
// recorded at the park site; empty when the park has no known fix.
string park_blocker = 48;
}
// Event mirrors internal/events.Event. Data is carried as a JSON object
// string (matching the store's own on-disk representation) rather than
// google.protobuf.Struct, to stay a direct mirror of the existing column.
message Event {
int64 id = 1;
google.protobuf.Timestamp at = 2;
string kind = 3;
int64 task_id = 4;
string repo = 5;
int64 issue = 6;
string workflow = 7;
string stage = 8;
// attempt is the run this event belongs to. Zero means UNATTRIBUTED, not a
// first attempt: rows written before the field existed, and the deliberately
// task-agnostic producers, all carry zero. A reader must report those as
// unattributable rather than presenting them as one run.
int64 attempt = 11;
string detail = 9;
string data_json = 10;
// Attribution. actor_id is the identity that performed the action and
// actor_kind its kind, so a reader can tell an agent's action from a person's
// without resolving the identity. principal_id is the identity whose authority
// the action used, which is a different fact when an agent acts under a
// person's standing approval; empty means unattributed. All three must cross
// this boundary: a record whose attribution survives only in `detail` is not
// queryable, which is the attribution this design exists to replace.
string actor_id = 12;
string actor_kind = 13;
string principal_id = 14;
}
// CapturedEvent mirrors storecontract.CapturedEvent.
message CapturedEvent {
string id = 1;
google.protobuf.Timestamp received_at = 2;
string source = 3;
string remote_addr = 4;
string content_type = 5;
string headers = 6;
string body = 7;
bool authenticated = 8;
// event_type is the ID of the event type the capture was identified as on
// arrival; empty is unidentified.
string event_type = 9;
// unsigned marks an event taken on an approved unsigned source.
bool unsigned = 10;
// delivery names the sender's delivery; a retry of one delivery shares it.
// Intake sets it from the source's delivery header; empty takes the
// capture ID.
string delivery = 11;
}
// EventTypeHeaderCondition mirrors internal/domain/eventtype.HeaderCondition.
message EventTypeHeaderCondition {
string name = 1;
string value = 2;
}
// EventTypePayloadCondition mirrors internal/domain/eventtype.PayloadCondition.
message EventTypePayloadCondition {
string path = 1;
string op = 2;
string value = 3;
}
// EventType mirrors internal/domain/eventtype.EventType. header_conditions and
// payload_conditions are its rule; schema maps each payload path to its type.
message EventType {
string id = 1;
string source = 2;
string name = 3;
repeated EventTypeHeaderCondition header_conditions = 4;
repeated EventTypePayloadCondition payload_conditions = 5;
map<string, string> schema = 6;
google.protobuf.Timestamp created_at = 7;
google.protobuf.Timestamp updated_at = 8;
// workspace_id is its source's workspace; read-only here.
string workspace_id = 9;
}
// MappingField mirrors internal/domain/mapping.Field.
message MappingField {
string name = 1;
string path = 2;
string type = 3;
bool required = 4;
}
// Mapping mirrors internal/domain/mapping.Mapping.
message Mapping {
string id = 1;
string name = 2;
string source_hint = 3;
repeated MappingField fields = 4;
google.protobuf.Timestamp created_at = 5;
google.protobuf.Timestamp updated_at = 6;
string event_type_id = 7;
// match_count and last_matched_at are read-only: the store counts them.
int64 match_count = 8;
google.protobuf.Timestamp last_matched_at = 9;
// workspace_id is its event type's workspace; read-only here.
string workspace_id = 10;
}
// BindingMatcher mirrors internal/domain/binding.Matcher.
message BindingMatcher {
string source = 1;
}
// Binding mirrors internal/domain/binding.Binding.
message Binding {
string id = 1;
string name = 2;
BindingMatcher matcher = 3;
string mapping_id = 4;
string workflow = 5;
string owner = 6;
string repo = 7;
int64 version = 8;
string status = 9;
reserved 10;
reserved "secret";
google.protobuf.Timestamp created_at = 11;
google.protobuf.Timestamp updated_at = 12;
string filter = 13;
// inputs_json assigns workflow inputs, a JSON object of
// {"param": name} or {"value": constant} per input.
string inputs_json = 14;
// repo_param names the mapped parameter holding "owner/name".
string repo_param = 15;
// org_id is the org that owns the binding; it is read-only here.
string org_id = 16;
// workspace_id is its source's workspace; read-only here.
string workspace_id = 17;
}
// Source mirrors internal/domain/source.Source.
message Source {
string path = 1;
string signing = 2;
string secret = 3;
google.protobuf.Timestamp created_at = 4;
google.protobuf.Timestamp updated_at = 5;
string name = 6;
string delivery_header = 7;
// org_id is the source's owning org, read-only here. workspace_id is the
// org's workspace it is created in, the default one when empty.
string org_id = 8;
string workspace_id = 9;
}
// WorkflowStat mirrors storecontract.WorkflowStat.
message WorkflowStat {
string workflow = 1;
int64 runs = 2;
int64 merged = 3;
int64 pr_open = 4;
int64 parked = 5;
int64 avg_tokens = 6;
double avg_steps = 7;
int64 total_tokens = 8;
int64 completed = 9;
}
// StageStat mirrors storecontract.StageStat.
message StageStat {
string workflow = 1;
string stage = 2;
int64 runs = 3;
int64 avg_ms = 4;
int64 errors = 5;
}
// DayTokens mirrors storecontract.DayTokens.
message DayTokens {
string day = 1;
int64 tokens = 2;
}
message EnqueueIssueRequest {
string owner = 1;
string repo = 2;
int64 number = 3;
string title = 4;
string body = 5;
string labels = 6;
string identity = 7;
}
message EnqueueIssueResponse { bool inserted = 1; }
message ActiveTasksByOriginRequest { string origin = 1; }
message ActiveTasksByOriginResponse { repeated Task tasks = 1; }
message UnpostedOutcomesRequest {}
message UnpostedOutcomesResponse { repeated Task tasks = 1; }
message MarkOutcomePostedRequest { int64 task_id = 1; }
message MarkOutcomePostedResponse {}
message EnqueueChatTaskRequest {
string owner = 1;
string repo = 2;
string title = 3;
string body = 4;
string workflow = 5;
string identity = 6;
// inputs_json assigns workflow inputs, a JSON object of the same form
// EnqueueBindingTaskRequest carries. A chat task sets them at insert
// time: it has no binding provenance to stamp afterwards.
string inputs_json = 7;
// origin names the conversation that created the task; empty for none.
string origin = 8;
// draft_yaml, when set, makes the task a test run of that unsaved
// definition: it is pinned to it and writes nothing to a forge.
string draft_yaml = 9;
}
message EnqueueChatTaskResponse { Task task = 1; }
message ClaimNextRequest {}
message ClaimNextResponse {
Task task = 1;
bool found = 2;
}
message ClaimByIssueRequest {
string owner = 1;
string repo = 2;
int64 number = 3;
}
message ClaimByIssueResponse {
Task task = 1;
bool found = 2;
}
message TransitionRequest {
int64 task_id = 1;
string from = 2;
string to = 3;
string detail = 4;
}
message TransitionResponse {}
message StartStepRequest {
// execution_id is the WorkflowExecution (the tasks row) the step belongs
// to, and the task ID the run credential is scoped to.
int64 execution_id = 1;
int64 attempt = 2;
// parent_id is 0 when the step is a stage; otherwise it names the enclosing
// StepExecution, from which the store derives depth.
int64 parent_id = 3;
// kind is stage, agent or call.
string kind = 4;
string name = 5;
// called_execution_id names the WorkflowExecution a `call` step started;
// the store verifies it is this execution's own callee.
int64 called_execution_id = 6;
}
message StartStepResponse {
int64 step_id = 1;
// event is the transition's stage_start row, already persisted; the caller
// publishes it to its bus after the write commits (the daemon's event sink
// skips already-persisted rows by their assigned ID).
Event event = 2;
}
message FinishStepRequest {
// execution_id names the run the step belongs to. The grant check verifies
// it against the credential, and the store verifies the step really is that
// execution's, so a caller cannot move another run's step by naming it.
int64 execution_id = 1;
int64 step_id = 2;
string from = 3;
string to = 4;
string detail = 5;
int64 tokens_used = 6;
// results is the run's step results (JSON, by step id) after a stage the
// run moves past; empty otherwise. A resumed attempt starts from them.
bytes results = 7;
}
message FinishStepResponse {
// event is the transition's stage_finish row, already persisted.
Event event = 1;
}
message CancelExecutionRequest {
int64 task_id = 1;
// reason records why the run was stopped, in the execution's park reason
// when the cancel lands there, and on every step event it writes.
string reason = 2;
// to is the execution's destination: the transition table routes it, and
// the operator actions name parked or closed_wont_do.
string to = 3;
}
message CancelExecutionResponse {
reserved 1;
reserved "cancelled_step_ids";
// cancelled_callee_ids are the executions the caller was waiting on that
// were cancelled with it, nested callees included; the caller stops their
// runs as well as its own.
repeated int64 cancelled_callee_ids = 2;
}
// StepExecution mirrors internal/domain/workflow/task.StepExecution.
message StepExecution {
int64 id = 1;
int64 execution_id = 2;
int64 attempt = 3;
// parent_id is 0 for a stage at the tree's root.
int64 parent_id = 4;
int32 depth = 5;
string kind = 6;
string name = 7;
string status = 8;
string detail = 9;
int64 tokens_used = 10;
google.protobuf.Timestamp started_at = 11;
google.protobuf.Timestamp finished_at = 12;
// called_execution_id is the callee task a workflow.call step started.
int64 called_execution_id = 13;
}
message ListStepsRequest {
int64 execution_id = 1;
// attempt selects one attempt's steps; 0 lists every attempt of the
// execution, oldest first -- the dashboard's run-detail rail renders every
// attempt from a single call rather than one per attempt.
int64 attempt = 2;
}
message ListStepsResponse { repeated StepExecution steps = 1; }
// HarnessSecret mirrors internal/domain/harnesssecret.Secret -- one org's
// captured OAuth token set for a credential binding's service
// (docs/prds/external-agent-harness.md, Credentials).
message HarnessSecret {
reserved 1;
reserved "org";
string service = 2;
string access_token = 3;
string refresh_token = 4;
string token_type = 5;
google.protobuf.Timestamp expires_at = 6;
google.protobuf.Timestamp updated_at = 7;
repeated string scopes = 8;
}
message GetHarnessSecretRequest {
reserved 1;
reserved "org";
string service = 2;
string run_credential = 3;
}
message GetHarnessSecretResponse {
HarnessSecret secret = 1;
string org = 2;
}
message PutHarnessSecretRequest {
HarnessSecret secret = 1;
string run_credential = 2;
}
message PutHarnessSecretResponse {}
message UpdateRequest { Task task = 1; }
message UpdateResponse {}
message RequeueRequest {
int64 task_id = 1;
string from_status = 2;
string workflow = 3;
}
message RequeueResponse {}
message ParkTaskRequest {
int64 task_id = 1;
string from = 2;
string detail = 3;
string class = 4;
string blocker = 5;
}
message ParkTaskResponse {}
message RecoverStaleRequest {}
message RecoverStaleResponse { int64 count = 1; }
message ArchiveTaskRequest {
int64 task_id = 1;
string from_status = 2;
Event audit = 3;
}
message ArchiveTaskResponse { int64 event_id = 1; }
message RetryTaskRequest {
int64 task_id = 1;
string from_status = 2;
string workflow = 3;
// retry_mode is the operator's worktree choice (taskstate.RetryMode) the
// requeue persists. Empty reads as refresh_onto_base.
string retry_mode = 4;
// resume_from is the stage the attempt starts at, and resume_after the
// stage before it whose recorded results it starts with (task.Resume).
string resume_from = 5;
string resume_after = 6;
// current_definition clears the pinned definition so the next dispatch
// pins the workflow's current stored version.
bool current_definition = 7;
}
message RetryTaskResponse {}
message RespondReviewGateRequest {
int64 task_id = 1;
string from_status = 2;
// gate is the whole review_gate document the caller computed: the offer
// with the answer filled in. The store persists it unread.
string gate = 3;
// rereview increments rereview_rounds in the same write; an approve must
// pass false and bumps nothing.
bool rereview = 4;
// cap is the domain's re-review bound (prreview.MaxRereviewRounds). It
// crosses so the guard is enforced where the row is locked rather than by
// the caller's stale read.
int64 cap = 5;
}
message RespondReviewGateResponse {}
message BeginRemediationRequest {
int64 task_id = 1;
string payload = 2;
}
message BeginRemediationResponse {}
// UpdateReviewPayloadRequest merges payload's comments into the unclaimed
// review unit with the same review id, active or pending.
message UpdateReviewPayloadRequest {
int64 task_id = 1;
string payload = 2;
}
message UpdateReviewPayloadResponse {}
message SetReviewCursorsRequest {
int64 task_id = 1;
int64 review_cursor = 2;
int64 comment_cursor = 3;
}
message SetReviewCursorsResponse {}
message TaskByIssueRequest {
string owner = 1;
string repo = 2;
int64 number = 3;
}
message TaskByIssueResponse {
Task task = 1;
bool found = 2;
}
message OpenTaskByPRRequest {
string owner = 1;
string repo = 2;
int64 number = 3;
}
message OpenTaskByPRResponse {
Task task = 1;
bool found = 2;
}
message TaskByIDRequest { int64 task_id = 1; }
message TaskByIDResponse {
Task task = 1;
bool found = 2;
}
message OpenPRsRequest {}
message OpenPRsResponse { repeated Task tasks = 1; }
message ClearTerminalTasksRequest {}
message ClearTerminalTasksResponse { int64 count = 1; }
// TasksRequest selects one page of tasks, most recently updated first. Empty
// statuses matches every status; after_id 0 starts at the newest task.
message TasksRequest {
int64 limit = 1;
repeated string statuses = 2;
google.protobuf.Timestamp after_updated_at = 3;
int64 after_id = 4;
// workflow, when set, keeps only that workflow's tasks.
string workflow = 5;
}
message TasksResponse { repeated Task tasks = 1; }
message StatusCountsRequest {}
message StatusCountsResponse { map<string, int64> counts = 1; }
message InsertEventRequest { Event event = 1; }
message InsertEventResponse { int64 id = 1; }
message EventsSinceRequest {
// since_id is the opaque resume cursor returned by the previous page (the SSE
// id: field, echoed back as Last-Event-ID). Empty means "from the
// beginning". The field keeps its name and number so the wire name stays
// put; only its type widened, from the SQLite rowid to the fixed-width
// "<at>|<row id>" cursor.
string since_id = 1;
int64 limit = 2;
}
message EventsSinceResponse { repeated Event events = 1; }
message TaskEventsRequest { int64 task_id = 1; }
message TaskEventsResponse { repeated Event events = 1; }
message WorkflowStatsRequest {}
message WorkflowStatsResponse { repeated WorkflowStat stats = 1; }
message StageStatsRequest {}
message StageStatsResponse { repeated StageStat stats = 1; }
message TokensByDayRequest { int64 days = 1; }
message TokensByDayResponse { repeated DayTokens tokens = 1; }
// ConfigSnapshot carries the dashboard's configuration projection. document
// is opaque to the store: its shape belongs to the producer and the page that
// reads it, and schema names that shape so a reader can refuse one it does
// not understand. It is secret-free at the producer -- the projection carries
// an API key's environment variable name and whether it resolved, never a
// value.
message ConfigSnapshot {
string schema = 1;
bytes document = 2;
google.protobuf.Timestamp published_at = 3;
}
message PutConfigSnapshotRequest { ConfigSnapshot snapshot = 1; }
message PutConfigSnapshotResponse {}
message GetConfigSnapshotRequest {}
message GetConfigSnapshotResponse {
ConfigSnapshot snapshot = 1;
bool found = 2;
}
// ChannelStatus is one channel's runtime state, as the process hosting it
// observes it. ReloadSupported is a capability declaration, not a request: the
// service reports it, so a reader may offer a reload action -- but asking for one
// travels on its own surface, because a transient request and a durable state do
// not share a lifetime.
message ChannelStatus {
string id = 1;
string name = 2;
string state = 3;
string detail = 4;
bool configured = 5;
bool reload_supported = 6;
google.protobuf.Timestamp observed_at = 7;
}
message PutChannelStatusRequest { repeated ChannelStatus channels = 1; }
message PutChannelStatusResponse {}
message ListChannelStatusRequest {}
message ListChannelStatusResponse { repeated ChannelStatus channels = 1; }
// ApplyStatus is one process's report about one control-plane resource kind.
// applied_version is the version that process is running; error is set when it
// could not apply what the store returned, and leaves applied_version at the
// last version it did apply. reported_at is re-stamped on an interval, so a
// record older than the staleness window belongs to a process that has stopped
// running (docs/prds/control-plane-apply-status.md).
message ApplyStatus {
string process = 1;
string kind = 2;
int64 applied_version = 3;
string error = 4;
google.protobuf.Timestamp reported_at = 5;
}
message PutApplyStatusRequest { ApplyStatus status = 1; }
message PutApplyStatusResponse {}
message ListApplyStatusRequest {}
message ListApplyStatusResponse { repeated ApplyStatus statuses = 1; }
// Presence is one running service instance. ready and detail summarise its
// readiness probes; detail names the degraded ones.
message DependencyCheck {
string name = 1;
string status = 2;
bool ready = 3;
string detail = 4;
}
message Presence {
string service = 1;
string instance_id = 2;
string version = 3;
string install_type = 4;
google.protobuf.Timestamp started_at = 5;
google.protobuf.Timestamp reported_at = 6;
bool ready = 7;
string detail = 8;
repeated DependencyCheck checks = 9;
}
message RecordCaptureRefusalRequest {
string source = 1;
string addr = 2;
google.protobuf.Timestamp refused_at = 3;
}
message RecordCaptureRefusalResponse {}
message ListCaptureRefusalsRequest { google.protobuf.Timestamp since = 1; }
message CaptureRefusals {
string source = 1;
int64 refused = 2;
int64 accepted = 3;
repeated string addrs = 4;
}
message ListCaptureRefusalsResponse { repeated CaptureRefusals sources = 1; }
message PutPresenceRequest { Presence presence = 1; }
message PutPresenceResponse {}
message ListPresenceRequest {}
message ListPresenceResponse { repeated Presence presences = 1; }
// TaskLogEntry mirrors internal/logging.Entry: one decoded log line. fields
// carries every remaining key as a JSON object string, the same way Event
// carries its data, so structured context survives the hop without this
// contract having to know what a call site attached.
message TaskLogEntry {
int64 id = 1;
google.protobuf.Timestamp time = 2;
string level = 3;
string msg = 4;
string fields_json = 5;
}
// ReadTaskLog returns a page of one task attempt's decoded log. attempt is the
// attempt the caller resolved (the dashboard sends the task's current attempt
// when the request omitted one). levels, component, contains, since and until
// carry the whole query the logging package's Tail accepts -- the wire mirrors
// that query rather than a subset of it, so a filter cannot silently stop
// working by crossing the boundary. limit is caller-capped
// (docs/prds/state-store-contract.md §8: the log cap is 2000).
message ReadTaskLogRequest {
int64 task_id = 1;
int64 attempt = 2;
int64 limit = 3;
repeated string levels = 4;
string component = 5;
string contains = 6;
google.protobuf.Timestamp since = 7;
google.protobuf.Timestamp until = 8;
// stage filters on an entry's own "stage" field. Only entries a stage
// tagged carry one -- agent and tool output is logged without a stage, so a
// stage filter narrows the file rather than covering it. Empty means any.
string stage = 9;
// before_id is the byte-offset cursor a previous page returned as cursor: the
// read returns the most recent matching entries ending at or before it. Zero
// reads the tail, which is the page the dashboard opens on.
int64 before_id = 10;
}
// found=false is not an error: the task has no log file for that attempt.
// That is a different condition from a process that cannot read logs at all
// (codes.Unavailable), and the dashboard reports them differently.
message ReadTaskLogResponse {
repeated TaskLogEntry entries = 1;
bool truncated = 2;
int64 attempt = 3;
bool found = 4;
repeated string components = 5;
// file is the path read, so the page can name where the log came from. It
// is the state directory's own layout, reported to an already-authenticated
// operator; no caller is expected to open it.
string file = 6;
// more_available reports matching entries did not fit in this page; cursor
// is the before_id for the next older one. truncated is separate: it means
// the log is larger than the readable scan window, so its oldest entries
// cannot be reached by paging at all.
bool more_available = 7;
int64 cursor = 8;
}
// StreamTaskLogContent returns one attempt's log verbatim, for a download. The
// bytes are the file's own JSONL, not a re-encoding of it: this contract
// transports the log, it does not restate the format. found=false, with no
// chunks, means the attempt has no log file -- not an error.
message StreamTaskLogContentRequest {
int64 task_id = 1;
int64 attempt = 2;
}
message StreamTaskLogContentResponse {
bytes chunk = 1;
int64 attempt = 2;
bool found = 3;
}
message InsertCaptureRequest {
CapturedEvent capture = 1;
int64 retention_seconds = 2;
int64 max_events = 3;
}
message InsertCaptureResponse { string id = 1; }
message StreamCapturesRequest { int64 limit = 1; }
// Streamed one capture per message; see StreamCaptures above.
message StreamCapturesResponse { CapturedEvent capture = 1; }
message InsertMappingRequest { Mapping mapping = 1; }
message InsertMappingResponse { string id = 1; }
message GetMappingRequest { string id = 1; }
message GetMappingResponse {
Mapping mapping = 1;
bool found = 2;
}
message ListMappingsRequest {}
message ListMappingsResponse { repeated Mapping mappings = 1; }
message UpdateMappingRequest { Mapping mapping = 1; }
message UpdateMappingResponse {}
message DeleteMappingRequest { string id = 1; }
message DeleteMappingResponse {}
message RecordMappingMatchRequest {
string mapping_id = 1;
string capture_id = 2;
}
message RecordMappingMatchResponse {}
message InsertEventTypeRequest { EventType event_type = 1; }
message InsertEventTypeResponse { string id = 1; }
message UpdateEventTypeRequest { EventType event_type = 1; }
message UpdateEventTypeResponse {}
message DeleteEventTypeRequest { string id = 1; }
message DeleteEventTypeResponse {}
message ListEventTypesRequest {}
message ListEventTypesResponse { repeated EventType event_types = 1; }
message InsertBindingRequest { Binding binding = 1; }
message InsertBindingResponse { string id = 1; }
message GetBindingRequest { string id = 1; }
message GetBindingResponse {
Binding binding = 1;
bool found = 2;
}
message ListBindingsRequest {}
message ListBindingsResponse { repeated Binding bindings = 1; }
message UpdateBindingRequest { Binding binding = 1; }
message UpdateBindingResponse {}
message DeleteBindingRequest { string id = 1; }
message DeleteBindingResponse {}
message ApproveBindingRequest { string id = 1; }
message ApproveBindingResponse {}
message SetSourceNameRequest {
string path = 1;
string name = 2;
}
message SetSourceNameResponse {}
message SetSourceDeliveryHeaderRequest {
string path = 1;
string header = 2;
}
message SetSourceDeliveryHeaderResponse {}
message DeleteSourceRequest { string path = 1; }
message DeleteSourceResponse {}
message PauseBindingRequest { string id = 1; }
message PauseBindingResponse {}
message ResumeBindingRequest { string id = 1; }
message ResumeBindingResponse {}
message InsertSourceRequest { Source source = 1; }
message InsertSourceResponse {}
message GetSourceRequest { string path = 1; }
message GetSourceResponse {
Source source = 1;
bool found = 2;
}
message ListSourcesRequest {}
message ListSourcesResponse { repeated Source sources = 1; }
message SetSourceSigningRequest {
string path = 1;
string from = 2;
string to = 3;
}
message SetSourceSigningResponse {}
message SetSourceSecretRequest {
string path = 1;
string secret = 2;
}
message SetSourceSecretResponse {}
message ArmedBindingsForSourceRequest { string source = 1; }
message ArmedBindingsForSourceResponse { repeated Binding bindings = 1; }
message RecordDispatchRequest {
string binding_id = 1;
int64 binding_version = 2;
string capture_id = 3;
// task_id addresses the tasks table.
int64 task_id = 4;
// reason is empty for a dispatch and names why an evaluated capture
// started no task.
string reason = 5;
}
message RecordDispatchResponse {}
// ListDispatchesRequest filters the binding dispatch ledger; empty fields
// match any row.
message ListDispatchesRequest {
string binding_id = 1;
string capture_id = 2;
int64 task_id = 3;
int32 limit = 4;
}
message Dispatch {
string binding_id = 1;
int64 binding_version = 2;
string capture_id = 3;
int64 task_id = 4;
string reason = 5;
google.protobuf.Timestamp dispatched_at = 6;
}
message ListDispatchesResponse { repeated Dispatch dispatches = 1; }
message RecordPlaybookDispatchRequest {
string playbook_id = 1;
string playbook_version = 2;
string event_id = 3;
string action_id = 4;
}
message RecordPlaybookDispatchResponse {}
message DeletePlaybookDispatchesRequest { string playbook_id = 1; }
message DeletePlaybookDispatchesResponse {}
message StreamUndispatchedCapturesRequest {
reserved 1;
reserved "sources";
// Bindings are the ids of the armed bindings, on enabled workflows, the
// captures are listed for.
repeated string bindings = 3;
int64 limit = 2;
}
// Streamed one capture per message; see StreamUndispatchedCaptures above.
message StreamUndispatchedCapturesResponse { CapturedEvent capture = 1; }
message EnqueueBindingTaskRequest {
string owner = 1;
string repo = 2;
string title = 3;
string body = 4;
string workflow = 5;
string identity = 6;
string binding_id = 7;
int64 binding_version = 8;
string inputs_json = 9;
string capture_id = 10;
}
message EnqueueBindingTaskResponse { Task task = 1; }
// workflow.call: the caller's grant names the caller; the store derives the
// rest from the caller's row (docs/prds/workflow-calls.md).
message EnqueueCallTaskRequest {
int64 caller_task_id = 1;
string workflow = 2;
string inputs_json = 3;
// call_key is the call site's durable identity: the call step's declared
// path within the run, plus the workflow it starts (so one task running a
// second definition at a colliding path does not reuse the first callee's
// child). The store stamps it on the child and, when the caller already
// started a child under it, returns that child instead of starting a second
// one. Required: a retry of one call site carries the same key, so the retry
// cannot duplicate the child's work.
string call_key = 4;
}
message EnqueueCallTaskResponse {
Task task = 1;
bool accepted = 2;
}
message WorkflowCallStatusRequest {
int64 caller_task_id = 1;
int64 call_task_id = 2;
}
message WorkflowCallStatusResponse {
// status is the callee's task status and detail its latest transition
// detail (empty before the callee first moves). outputs_json is the
// callee's written outputs (task.EncodeOutputs), so a wait:true caller can
// publish one as its own (docs/prds/workflow-call-outputs.md, "Storage and
// wire").
string status = 1;
string detail = 2;
string outputs_json = 3;
}
message InstalledPackage {
string org_id = 1;
string name = 2;
string reference = 3;
string digest = 4;
bytes descriptor_json = 5;
bytes layer = 6;
string update_policy = 7;
// The operator's accepted authority, recorded against the pinned digest.
// Absent until the operator accepts (docs/prds/store.md, "Authority").
PackageAuthority accepted_authority = 8;
// An update waiting for approval of widened authority; the live pin above
// is unchanged until then.
PackagePin pending = 9;
// The pin the last update or rollback replaced, with the authority accepted
// against it.
PackagePin previous = 10;
PackageAuthority previous_accepted_authority = 11;
// What the pending update declares.
PackageAuthority pending_authority = 12;
}
message PackagePin {
string reference = 1;
string digest = 2;
}
// PackageAuthority mirrors storepkg.Authority: the grants a package needs to
// operate. An acceptance record is an upper bound, checked field by field.
message PackageAuthority {
repeated string credential_services = 1;
repeated string egress_hosts = 2;
repeated string forge_permissions = 3;
repeated string triggers = 4;
repeated string tools = 5;
repeated string env = 6;
}
// Package and denial requests act in the org the State Store derives from the
// caller's principal, else the default org.
message InstallPackageRequest {
reserved 1;
reserved "org_id";
string name = 2;
string reference = 3;
string digest = 4;
}
message InstallPackageResponse { InstalledPackage package = 1; }
message CatalogueEntry {
string name = 1;
string surface = 2;
string version = 3;
string description = 4;
string reference = 5;
string digest = 6;
}
message ListCatalogueRequest {}
message ListCatalogueResponse { repeated CatalogueEntry packages = 1; }
message InstallFromCatalogueRequest { string name = 1; }
message InstallFromCatalogueResponse { InstalledPackage package = 1; }
message GetInstalledPackageRequest {
reserved 1;
reserved "org_id";
string name = 2;
}
message GetInstalledPackageResponse { InstalledPackage package = 1; }
message ListInstalledPackagesRequest {
reserved 1;
reserved "org_id";
}
message ListInstalledPackagesResponse { repeated InstalledPackage packages = 1; }
message AcceptPackageAuthorityRequest {
reserved 1;
reserved "org_id";
string name = 2;
PackageAuthority accepted = 3;
}
message AcceptPackageAuthorityResponse { InstalledPackage package = 1; }
message RemoveInstalledPackageRequest {
reserved 1;
reserved "org_id";
string name = 2;
}
message RemoveInstalledPackageResponse {}
message UpdatePackageRequest { string name = 1; }
message UpdatePackageResponse { InstalledPackage package = 1; }
message ApprovePackageUpdateRequest { string name = 1; }
message ApprovePackageUpdateResponse { InstalledPackage package = 1; }
message RollbackPackageRequest { string name = 1; }
message RollbackPackageResponse { InstalledPackage package = 1; }
message SetPackageUpdatePolicyRequest {
string name = 1;
string policy = 2;
}
message SetPackageUpdatePolicyResponse { InstalledPackage package = 1; }
// Task mirrors internal/domain/workflow.Task.
message GetPrincipalRequest { string identity_id = 1; }
// PrincipalMembership mirrors org.Membership: an identity's role in an org,
// or in one workspace of it.
message PrincipalMembership {
string org_id = 1;
string workspace_id = 2;
string role = 3;
}
// PrincipalWorkspace is one workspace of the principal's org, as policies
// read it.
message PrincipalWorkspace {
string workspace_id = 1;
string environment = 2;
}
message AccessPrincipal {
string identity_id = 1;
string org_id = 2;
repeated PrincipalMembership memberships = 3;
// workspaces are the workspaces of org_id.
repeated PrincipalWorkspace workspaces = 4;
}
message GetPrincipalResponse { AccessPrincipal principal = 1; }
// AccessPolicy mirrors internal/domain/access.Policy: one Cedar policy
// document and the level-scope tuple that places it in the chain.
message AccessPolicy {
string policy_id = 1;
string level = 2;
string org_id = 3;
string workspace_id = 4;
string object_kind = 5;
string object_id = 6;
string text = 7;
}
message ListPoliciesRequest {}
message ListPoliciesResponse { repeated AccessPolicy policies = 1; }
message PutPolicyRequest { AccessPolicy policy = 1; }
message PutPolicyResponse { int64 version = 1; }
message DeletePolicyRequest { AccessPolicy policy = 1; }
message DeletePolicyResponse {}
message EnsureShippedOrgPoliciesRequest { string org_id = 1; }
message EnsureShippedOrgPoliciesResponse {}
// AccessDenial mirrors internal/domain/access.Denial: one refusal with the
// level that decided it and the deciding policies. The store coalesces
// identical denials within a minute into one row with a count.
message AccessDenial {
string org_id = 1;
string principal = 2;
string action = 3;
string resource_kind = 4;
string resource_id = 5;
string level = 6;
repeated string policies = 7;
int64 count = 8;
google.protobuf.Timestamp at = 9;
}
message RecordDenialRequest { AccessDenial denial = 1; }
message RecordDenialResponse {}
message ListDenialsRequest {
reserved 1;
reserved "org_id";
int32 limit = 2;
}
message ListDenialsResponse { repeated AccessDenial denials = 1; }
// Org mirrors internal/domain/org.Org: one tenant.
message Org {
string id = 1;
string name = 2;
}
// Workspace mirrors internal/domain/org.Workspace: a division of an org.
message Workspace {
string id = 1;
string org_id = 2;
string name = 3;
string environment = 4;
}
// Member mirrors internal/domain/org.Member: a membership with the identity
// it names, as the dashboard lists it.
message Member {
string identity_id = 1;
string kind = 2;
string display_name = 3;
string workspace_id = 4;
string role = 5;
}
message ListOrgsRequest {}
message ListOrgsResponse { repeated Org orgs = 1; }
message GetOrgRequest { string org_id = 1; }
message GetOrgResponse { Org org = 1; }
// CreateOrgRequest creates an org with its default workspace and its first
// owner. Only an instance admin may.
message CreateOrgRequest {
string id = 1;
string name = 2;
string owner_identity_id = 3;
}
message CreateOrgResponse { Org org = 1; }
message ListWorkspacesRequest { string org_id = 1; }
message ListWorkspacesResponse { repeated Workspace workspaces = 1; }
message CreateWorkspaceRequest {
string org_id = 1;
string id = 2;
string name = 3;
string environment = 4;
}
message CreateWorkspaceResponse { Workspace workspace = 1; }
message ListMembersRequest { string org_id = 1; }
message ListMembersResponse { repeated Member members = 1; }
message SetMembershipRequest {
string org_id = 1;
string identity_id = 2;
string workspace_id = 3;
string role = 4;
}
message SetMembershipResponse {}
message RemoveMembershipRequest {
string org_id = 1;
string identity_id = 2;
string workspace_id = 3;
}
message RemoveMembershipResponse {}
message AssignAgentRequest {
string org_id = 1;
string identity_id = 2;
}
message AssignAgentResponse {}
message RecentLogsRequest { logging.v1.LogQuery query = 1; }
message RecentLogsResponse { logging.v1.LogSnapshot snapshot = 1; }
// UsageRecord mirrors usage.Record. A task's record belongs to the task's
// org; any other belongs to the calling principal's org.
message UsageRecord {
reserved 1;
reserved "org_id";
// source is task, chat or curator.
string source = 2;
int64 task_id = 3;
int64 attempt = 4;
string workflow = 5;
string step = 6;
string alias = 7;
string provider = 8;
string model = 9;
int64 input_tokens = 10;
int64 output_tokens = 11;
int64 cached_tokens = 12;
google.protobuf.Timestamp at = 13;
}
message RecordUsageRequest { UsageRecord record = 1; }
message RecordUsageResponse {}
message TaskModelsRequest { int64 task_id = 1; }
message TaskInstructionsRequest { int64 task_id = 1; }
message TaskInstructionsResponse {
string instance = 1;
string organisation = 2;
}
message TaskModelsResponse {
string org_id = 1;
map<string, string> aliases = 2;
map<string, ModelProvider> providers = 3;
}
// ModelProvider is an org's own provider. Its key is the org's credential
// binding named after it.
message ModelProvider {
string class = 1;
string base_url = 2;
string api_key_env = 3;
// The provider's credential reference: where its key lives, never the key
// itself. A daemon resolves a model egress credential from it; without it
// every provider arrives credential-less and no runtime can be built.
string api_key_engine = 4;
string api_key_key = 5;
}
message CallerModelsRequest {}
message CallerModelsResponse {
string org_id = 1;
map<string, string> aliases = 2;
}
// Alert mirrors internal/domain/alert.Alert. Severity is info, warning or
// action; state is open, resolved or dismissed.
message Alert {
int64 id = 1;
string org_id = 2;
string kind = 3;
string subject = 4;
string severity = 5;
string title = 6;
string body = 7;
string link = 8;
bool condition = 9;
string state = 10;
google.protobuf.Timestamp first_raised = 11;
google.protobuf.Timestamp last_seen = 12;
int64 count = 13;
string closed_by = 14;
google.protobuf.Timestamp closed_at = 15;
repeated AlertDelivery deliveries = 16;
}
// AlertDelivery is one outbound notice an alert owed. Event is raised or
// resolved; state is pending, delivered, failed or skipped.
message AlertDelivery {
int64 id = 1;
string event = 2;
string state = 3;
google.protobuf.Timestamp created_at = 4;
repeated AlertAttempt attempts = 5;
}
message AlertAttempt {
int64 n = 1;
google.protobuf.Timestamp at = 2;
int64 status_code = 3;
string error = 4;
}
message RaiseAlertRequest {
string org_id = 1;
string kind = 2;
string subject = 3;
string severity = 4;
string title = 5;
string body = 6;
string link = 7;
// condition is true when the raiser resolves the alert itself once the
// condition clears; an event alert stays until dismissed.
bool condition = 8;
}
message RaiseAlertResponse { Alert alert = 1; }
message ResolveAlertRequest {
string org_id = 1;
string kind = 2;
string subject = 3;
}
message ResolveAlertResponse {}
message DismissAlertRequest {
string org_id = 1;
int64 id = 2;
}
message DismissAlertResponse {}
message ListAlertsRequest {
string org_id = 1;
// states defaults to open.
repeated string states = 2;
int32 limit = 3;
}
message ListAlertsResponse { repeated Alert alerts = 1; }
message ClaimAlertDeliveriesRequest { int32 limit = 1; }
message DueAlertDelivery {
AlertDelivery delivery = 1;
Alert alert = 2;
// attempt is the number of this try, counting from one.
int64 attempt = 3;
}
message ClaimAlertDeliveriesResponse { repeated DueAlertDelivery due = 1; }
message RecordAlertAttemptRequest {
int64 delivery_id = 1;
bool skipped = 2;
int64 status_code = 3;
// error is empty on success.
string error = 4;
}
message RecordAlertAttemptResponse {}
message AccountSetupRequest {}
message AccountSetupResponse { bool required = 1; }
message RegisterAccountRequest {
string email = 1;
string display_name = 2;
string password = 3;
string role = 4;
bool bootstrap = 5;
string organisation_name = 6;
string workspace_name = 7;
string public_url = 8;
}
message RegisterAccountResponse { Identity identity = 1; }
message SignInAccountRequest { string email = 1; string password = 2; }
message SignInAccountResponse {
Identity identity = 1;
string token = 2;
google.protobuf.Timestamp expires_at = 3;
}
message ResolveAccountSessionRequest { string token = 1; }
message ResolveAccountSessionResponse { Identity identity = 1; }
message SignOutAccountRequest { string token = 1; }
message SignOutAccountResponse {}
message ChangeAccountPasswordRequest { string current_password = 1; string new_password = 2; }
message ChangeAccountPasswordResponse {}
message AuthenticationSettings {
string public_url = 1;
string oidc_issuer = 2;
string oidc_audience = 3;
string oidc_client_id = 4;
}
message GetAuthenticationSettingsRequest {}
message GetAuthenticationSettingsResponse { AuthenticationSettings settings = 1; }
message SaveAuthenticationSettingsRequest { AuthenticationSettings settings = 1; }
message SaveAuthenticationSettingsResponse {}
message BeginPasskeyRequest { bool registration = 1; }
message BeginPasskeyResponse { string token = 1; bytes options = 2; }
message FinishPasskeyRequest { string token = 1; bytes credential = 2; bool registration = 3; string name = 4; }
message FinishPasskeyResponse { Identity identity = 1; string token = 2; google.protobuf.Timestamp expires_at = 3; }
message Passkey { string id = 1; string name = 2; }
message ListPasskeysRequest {}
message ListPasskeysResponse { repeated Passkey passkeys = 1; }
message DeletePasskeyRequest { string id = 1; }
message DeletePasskeyResponse {}
message OpenAccountSessionRequest { google.protobuf.Timestamp expires_at = 1; }
message OpenAccountSessionResponse { Identity identity = 1; string token = 2; google.protobuf.Timestamp expires_at = 3; }
message RequireFreshAccountSessionRequest { string token = 1; }
message RequireFreshAccountSessionResponse {}
message CreateAccountRecoveryRequest {}
message CreateAccountRecoveryResponse { string code = 1; }
message RecoverAccountRequest { string email = 1; string code = 2; string password = 3; }
message RecoverAccountResponse {}
message ListOrgAgentsRequest { string org_id = 1; }
message AgentAssignment {
string identity_id = 1;
string org_id = 2;
}
message ListOrgAgentsResponse { repeated AgentAssignment agents = 1; }