syntax = "proto3"; package state.v1; import "google/protobuf/timestamp.proto"; import "state/v1/types.proto"; service ExecutionService { // 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); 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); } 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; } // 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 {}