worker.proto

Generated from proto/blitz/v1/worker.proto by proto-gen-md-diagrams.

Imports

Import	Description
blitz/v1/turn.proto
google/protobuf/duration.proto
google/protobuf/timestamp.proto

Options

Name	Value	Description
go_package	github.com/retail-cortex/blitz/proto/blitz/v1

blitz.v1 Diagram

classDiagram
direction LR
%% Mermaid Diagram for package: blitz.v1

%% WorkerLimits bound one run.

class WorkerLimits {
  + int32 max_turns
  + double max_cost_usd
  + google.protobuf.Duration timeout
}

%% Worker describes a worker.

class Worker {
  + string workspace
  + string name
  + string description
  + string path
  + string hash
  + WorkerState state
  + string schedule
  + string cron
  + string timezone
  + google.protobuf.Timestamp next_run
  + string agent
  + string model
  + List~string~ permissions
  + WorkerLimits limits
  + List~string~ problems
  + WorkerRun last_run
  + string workflow
}
Worker --> `WorkerState`
Worker --> `WorkerLimits`
Worker --> `WorkerRun`

%% Request message for WorkerService.ListWorkers.

class ListWorkersRequest {
  + string workspace
}

%% Response message for WorkerService.ListWorkers.

class ListWorkersResponse {
  + List~Worker~ workers
}
ListWorkersResponse --> `Worker`

%% Request message for WorkerService.CreateWorker: WORKER.md's frontmatter fields and the workflow. Empty fields are left out.

class CreateWorkerRequest {
  + string workspace
  + string name
  + string description
  + string schedule
  + string timezone
  + string agent
  + string model
  + List~string~ permissions
  + int32 max_turns
  + double max_cost_usd
  + string timeout
  + string catch_up
  + string prompt
  + string workflow
}

%% WorkerDefinition is a WORKER.md as written: its frontmatter fields and the workflow. Empty fields are left out of the file.

class WorkerDefinition {
  + string name
  + string description
  + string schedule
  + string timezone
  + string agent
  + string model
  + List~string~ permissions
  + int32 max_turns
  + double max_cost_usd
  + string timeout
  + string catch_up
  + string prompt
  + string workflow
}

%% Request message for WorkerService.GetWorkerSpec.

class GetWorkerSpecRequest {
  + string workspace
  + string name
}

%% Response message for WorkerService.GetWorkerSpec.

class GetWorkerSpecResponse {
  + WorkerDefinition worker
  + string hash
}
GetWorkerSpecResponse --> `WorkerDefinition`

%% Request message for WorkerService.UpdateWorker.

class UpdateWorkerRequest {
  + string workspace
  + string hash
  + WorkerDefinition worker
}
UpdateWorkerRequest --> `WorkerDefinition`

%% Response message for WorkerService.UpdateWorker.

class UpdateWorkerResponse {
  + Worker worker
  + List~string~ problems
}
UpdateWorkerResponse --> `Worker`

%% Response message for WorkerService.CreateWorker.

class CreateWorkerResponse {
  + Worker worker
  + List~string~ problems
}
CreateWorkerResponse --> `Worker`

%% Request message for WorkerService.EnableWorker.

class EnableWorkerRequest {
  + string workspace
  + string name
  + string hash
}

%% Response message for WorkerService.EnableWorker.

class EnableWorkerResponse {
  + Worker worker
}
EnableWorkerResponse --> `Worker`

%% Request message for WorkerService.DisableWorker.

class DisableWorkerRequest {
  + string workspace
  + string name
}

%% Response message for WorkerService.DisableWorker.

class DisableWorkerResponse {
  + Worker worker
}
DisableWorkerResponse --> `Worker`

%% Request message for WorkerService.DeleteWorker.

class DeleteWorkerRequest {
  + string workspace
  + string name
}

%% Response message for WorkerService.DeleteWorker.

class DeleteWorkerResponse {
}

%% Refusal is an action a run wasn't permitted.

class Refusal {
  + string tool
  + ActionKind kind
  + string detail
  + google.protobuf.Timestamp time
}
Refusal --> `ActionKind`

%% WorkerRun is one run of a worker.

class WorkerRun {
  + string id
  + string workspace
  + string worker
  + string hash
  + RunStatus status
  + bool manual
  + google.protobuf.Timestamp started
  + google.protobuf.Duration duration
  + Usage usage
  + string session_id
  + List~Refusal~ refusals
  + ErrorInfo error
  + List~string~ files
}
WorkerRun --> `RunStatus`
WorkerRun --> `Usage`
WorkerRun --> `Refusal`
WorkerRun --> `ErrorInfo`

%% Request message for WorkerService.UndoWorkerRun.

class UndoWorkerRunRequest {
  + string workspace
  + string run_id
  + bool force
}

%% Response message for WorkerService.UndoWorkerRun.

class UndoWorkerRunResponse {
  + List~string~ restored
  + ErrorInfo error
}
UndoWorkerRunResponse --> `ErrorInfo`

%% Request message for WorkerService.RunWorker.

class RunWorkerRequest {
  + string workspace
  + string name
}

%% Response message for WorkerService.RunWorker.

class RunWorkerResponse {
  + WorkerRun run
}
RunWorkerResponse --> `WorkerRun`

%% Request message for WorkerService.ListWorkerRuns.

class ListWorkerRunsRequest {
  + string workspace
  + string name
  + int32 limit
}

%% Response message for WorkerService.ListWorkerRuns.

class ListWorkerRunsResponse {
  + List~WorkerRun~ runs
}
ListWorkerRunsResponse --> `WorkerRun`

%% Request message for WorkerService.GetWorkerRun.

class GetWorkerRunRequest {
  + string run_id
}

%% Response message for WorkerService.GetWorkerRun.

class GetWorkerRunResponse {
  + WorkerRun run
}
GetWorkerRunResponse --> `WorkerRun`

%% Request message for WorkerService.WatchWorkerRun.

class WatchWorkerRunRequest {
  + string run_id
}

%% Response message for WorkerService.WatchWorkerRun.

class WatchWorkerRunResponse {
  + TurnEvent event
}
WatchWorkerRunResponse --> `TurnEvent`

%% Request message for WorkerService.ListRunningWorkerRuns.

class ListRunningWorkerRunsRequest {
}

%% Response message for WorkerService.ListRunningWorkerRuns.

class ListRunningWorkerRunsResponse {
  + List~WorkerRun~ runs
}
ListRunningWorkerRunsResponse --> `WorkerRun`

%% Request message for WorkerService.StopWorkerRun.

class StopWorkerRunRequest {
  + string run_id
}

%% Response message for WorkerService.StopWorkerRun.

class StopWorkerRunResponse {
  + WorkerRun run
}
StopWorkerRunResponse --> `WorkerRun`

%% Request message for WorkerService.RewriteWorker.

class RewriteWorkerRequest {
  + string workspace
  + WorkerDefinition worker
}
RewriteWorkerRequest --> `WorkerDefinition`

%% Response message for WorkerService.RewriteWorker.

class RewriteWorkerResponse {
  + string prompt
  + List~string~ permissions
  + List~string~ changes
  + string problem
}

%% Request message for WorkerService.ListAllWorkers.

class ListAllWorkersRequest {
}

%% One workspace's workers, in ListAllWorkersResponse.

class WorkspaceWorkers {
  + string workspace
  + bool home
  + bool missing
  + List~Worker~ workers
  + string problem
}
WorkspaceWorkers --> `Worker`

%% Response message for WorkerService.ListAllWorkers.

class ListAllWorkersResponse {
  + string home
  + List~WorkspaceWorkers~ workspaces
  + WorkerPolicySettings policy
}
ListAllWorkersResponse --> `WorkspaceWorkers`
ListAllWorkersResponse --> `WorkerPolicySettings`

%% The global limits on every worker, as the settings have them ([workers.policy]; spec_workers_023 WK-63). A worker asks for permissions and limits; these remove what isn't allowed, fill in what it leaves out, and cap the rest.

class WorkerPolicySettings {
  + List~string~ allow
  + int32 default_max_turns
  + double default_max_cost_usd
  + string default_timeout
  + int32 max_turns
  + double max_cost_usd
  + string max_timeout
  + int32 max_concurrent
  + int32 running_max_concurrent
  + string path
}

%% Request message for WorkerService.ForgetWorkspaceWorkers.

class ForgetWorkspaceWorkersRequest {
  + string workspace
}

%% Response message for WorkerService.ForgetWorkspaceWorkers.

class ForgetWorkspaceWorkersResponse {
}
%% WorkerState is whether a worker may run.

class WorkerState{
  <<enumeration>>
  WORKER_STATE_UNSPECIFIED
  WORKER_STATE_NEW
  WORKER_STATE_ENABLED
  WORKER_STATE_DISABLED
  WORKER_STATE_CHANGED
  WORKER_STATE_INVALID
}
%% RunStatus is where a run stands.

class RunStatus{
  <<enumeration>>
  RUN_STATUS_UNSPECIFIED
  RUN_STATUS_RUNNING
  RUN_STATUS_SUCCEEDED
  RUN_STATUS_FAILED
  RUN_STATUS_LIMITED
  RUN_STATUS_SKIPPED
  RUN_STATUS_STOPPED
}
class WorkerService {
  <<service>>
  +ListWorkers(ListWorkersRequest) ListWorkersResponse
  +CreateWorker(CreateWorkerRequest) CreateWorkerResponse
  +GetWorkerSpec(GetWorkerSpecRequest) GetWorkerSpecResponse
  +UpdateWorker(UpdateWorkerRequest) UpdateWorkerResponse
  +EnableWorker(EnableWorkerRequest) EnableWorkerResponse
  +DisableWorker(DisableWorkerRequest) DisableWorkerResponse
  +DeleteWorker(DeleteWorkerRequest) DeleteWorkerResponse
  +RunWorker(RunWorkerRequest) RunWorkerResponse
  +ListWorkerRuns(ListWorkerRunsRequest) ListWorkerRunsResponse
  +GetWorkerRun(GetWorkerRunRequest) GetWorkerRunResponse
  +UndoWorkerRun(UndoWorkerRunRequest) UndoWorkerRunResponse
  +WatchWorkerRun(WatchWorkerRunRequest) Stream~WatchWorkerRunResponse~
  +ListRunningWorkerRuns(ListRunningWorkerRunsRequest) ListRunningWorkerRunsResponse
  +StopWorkerRun(StopWorkerRunRequest) StopWorkerRunResponse
  +RewriteWorker(RewriteWorkerRequest) RewriteWorkerResponse
  +ListAllWorkers(ListAllWorkersRequest) ListAllWorkersResponse
  +ForgetWorkspaceWorkers(ForgetWorkspaceWorkersRequest) ForgetWorkspaceWorkersResponse
}
WorkerService --> `ListWorkersRequest`
WorkerService --> `ListWorkersResponse`
WorkerService --> `CreateWorkerRequest`
WorkerService --> `CreateWorkerResponse`
WorkerService --> `GetWorkerSpecRequest`
WorkerService --> `GetWorkerSpecResponse`
WorkerService --> `UpdateWorkerRequest`
WorkerService --> `UpdateWorkerResponse`
WorkerService --> `EnableWorkerRequest`
WorkerService --> `EnableWorkerResponse`
WorkerService --> `DisableWorkerRequest`
WorkerService --> `DisableWorkerResponse`
WorkerService --> `DeleteWorkerRequest`
WorkerService --> `DeleteWorkerResponse`
WorkerService --> `RunWorkerRequest`
WorkerService --> `RunWorkerResponse`
WorkerService --> `ListWorkerRunsRequest`
WorkerService --> `ListWorkerRunsResponse`
WorkerService --> `GetWorkerRunRequest`
WorkerService --> `GetWorkerRunResponse`
WorkerService --> `UndoWorkerRunRequest`
WorkerService --> `UndoWorkerRunResponse`
WorkerService --> `WatchWorkerRunRequest`
WorkerService --o `WatchWorkerRunResponse` : server stream
WorkerService --> `ListRunningWorkerRunsRequest`
WorkerService --> `ListRunningWorkerRunsResponse`
WorkerService --> `StopWorkerRunRequest`
WorkerService --> `StopWorkerRunResponse`
WorkerService --> `RewriteWorkerRequest`
WorkerService --> `RewriteWorkerResponse`
WorkerService --> `ListAllWorkersRequest`
WorkerService --> `ListAllWorkersResponse`
WorkerService --> `ForgetWorkspaceWorkersRequest`
WorkerService --> `ForgetWorkspaceWorkersResponse`

Service: WorkerService

FQN: blitz.v1

WorkerService manages workers: scheduled workflows a workspace defines in .agents/workers/<name>/WORKER.md or workers/<name>/WORKER.md (ROADMAP item 24). The service finds them by scanning trusted workspaces; a worker runs only once enabled against its content hash, and editing it disables it again. Actions outside a worker's permissions are refused and recorded, never left waiting.

WorkerService Diagram

classDiagram
direction LR
class WorkerService {
  <<service>>
  +ListWorkers(ListWorkersRequest) ListWorkersResponse
  +CreateWorker(CreateWorkerRequest) CreateWorkerResponse
  +GetWorkerSpec(GetWorkerSpecRequest) GetWorkerSpecResponse
  +UpdateWorker(UpdateWorkerRequest) UpdateWorkerResponse
  +EnableWorker(EnableWorkerRequest) EnableWorkerResponse
  +DisableWorker(DisableWorkerRequest) DisableWorkerResponse
  +DeleteWorker(DeleteWorkerRequest) DeleteWorkerResponse
  +RunWorker(RunWorkerRequest) RunWorkerResponse
  +ListWorkerRuns(ListWorkerRunsRequest) ListWorkerRunsResponse
  +GetWorkerRun(GetWorkerRunRequest) GetWorkerRunResponse
  +UndoWorkerRun(UndoWorkerRunRequest) UndoWorkerRunResponse
  +WatchWorkerRun(WatchWorkerRunRequest) Stream~WatchWorkerRunResponse~
  +ListRunningWorkerRuns(ListRunningWorkerRunsRequest) ListRunningWorkerRunsResponse
  +StopWorkerRun(StopWorkerRunRequest) StopWorkerRunResponse
  +RewriteWorker(RewriteWorkerRequest) RewriteWorkerResponse
  +ListAllWorkers(ListAllWorkersRequest) ListAllWorkersResponse
  +ForgetWorkspaceWorkers(ForgetWorkspaceWorkersRequest) ForgetWorkspaceWorkersResponse
}
WorkerService --> `ListWorkersRequest`
WorkerService --> `ListWorkersResponse`
WorkerService --> `CreateWorkerRequest`
WorkerService --> `CreateWorkerResponse`
WorkerService --> `GetWorkerSpecRequest`
WorkerService --> `GetWorkerSpecResponse`
WorkerService --> `UpdateWorkerRequest`
WorkerService --> `UpdateWorkerResponse`
WorkerService --> `EnableWorkerRequest`
WorkerService --> `EnableWorkerResponse`
WorkerService --> `DisableWorkerRequest`
WorkerService --> `DisableWorkerResponse`
WorkerService --> `DeleteWorkerRequest`
WorkerService --> `DeleteWorkerResponse`
WorkerService --> `RunWorkerRequest`
WorkerService --> `RunWorkerResponse`
WorkerService --> `ListWorkerRunsRequest`
WorkerService --> `ListWorkerRunsResponse`
WorkerService --> `GetWorkerRunRequest`
WorkerService --> `GetWorkerRunResponse`
WorkerService --> `UndoWorkerRunRequest`
WorkerService --> `UndoWorkerRunResponse`
WorkerService --> `WatchWorkerRunRequest`
WorkerService --o `WatchWorkerRunResponse` : server stream
WorkerService --> `ListRunningWorkerRunsRequest`
WorkerService --> `ListRunningWorkerRunsResponse`
WorkerService --> `StopWorkerRunRequest`
WorkerService --> `StopWorkerRunResponse`
WorkerService --> `RewriteWorkerRequest`
WorkerService --> `RewriteWorkerResponse`
WorkerService --> `ListAllWorkersRequest`
WorkerService --> `ListAllWorkersResponse`
WorkerService --> `ForgetWorkspaceWorkersRequest`
WorkerService --> `ForgetWorkspaceWorkersResponse`

Method	Parameter (In)	Parameter (Out)	Description
ListWorkers	ListWorkersRequest	ListWorkersResponse	Returns a workspace’s workers, or every registered workspace’s.
CreateWorker	CreateWorkerRequest	CreateWorkerResponse	Writes a new worker’s WORKER.md (in the first of workers.paths, .agents/workers by default) from a form, once it would load as valid; otherwise writes nothing and says why (WORKER_INVALID; WORKER_EXISTS for a name the workspace has). It starts disabled.
GetWorkerSpec	GetWorkerSpecRequest	GetWorkerSpecResponse	Returns a worker’s WORKER.md as written (not as the policy caps it), for editing, with its current hash; it needn’t be valid (UNKNOWN_WORKER).
UpdateWorker	UpdateWorkerRequest	UpdateWorkerResponse	Rewrites a worker’s WORKER.md from a form, if it still has the hash the caller edited (HASH_MISMATCH) and the result would load as valid; otherwise writes nothing and says why. Its name can’t change. An enabled worker is suspended (changed) until it’s enabled again.
EnableWorker	EnableWorkerRequest	EnableWorkerResponse	Enables a worker at the content hash the caller reviewed (HASH_MISMATCH if the file changed since).
DisableWorker	DisableWorkerRequest	DisableWorkerResponse	Disables a worker.
DeleteWorker	DeleteWorkerRequest	DeleteWorkerResponse	Deletes a worker: its directory and whether it was enabled; its past runs stay. Refused while it runs (RUN_IN_PROGRESS); UNKNOWN_WORKER.
RunWorker	RunWorkerRequest	RunWorkerResponse	Starts a run now, outside the schedule (WORKER_DISABLED, RUN_IN_PROGRESS).
ListWorkerRuns	ListWorkerRunsRequest	ListWorkerRunsResponse	Returns a worker’s runs, newest first.
GetWorkerRun	GetWorkerRunRequest	GetWorkerRunResponse	Returns one run.
UndoWorkerRun	UndoWorkerRunRequest	UndoWorkerRunResponse	Restores the files a run changed as they were before it, refusing (UNDO_CONFLICT) when one changed since, unless force (NOTHING_TO_UNDO).
WatchWorkerRun	WatchWorkerRunRequest	Stream<WatchWorkerRunResponse>	Streams a run’s events: those already produced, then live ones until it finishes.
ListRunningWorkerRuns	ListRunningWorkerRunsRequest	ListRunningWorkerRunsResponse	Lists the runs going now, in every workspace (Studio › Workers and Settings › Workers).
StopWorkerRun	StopWorkerRunRequest	StopWorkerRunResponse	Stops a run going now: its turn is cancelled and it’s recorded as stopped (RUN_NOT_RUNNING when it isn’t going).
RewriteWorker	RewriteWorkerRequest	RewriteWorkerResponse	Has the model rewrite a worker’s instructions, as the form has them, for a good unattended run, with the permissions they need; nothing is saved. A model that fails gives problem instead of an error (NO_INSTRUCTIONS without instructions).
ListAllWorkers	ListAllWorkersRequest	ListAllWorkersResponse	Lists every workspace the service has workers on record for (enabled or disabled), and the home workspace the user’s global workers run in (~/.blitz/home, made when missing), each with its workers. A workspace whose folder is gone is listed as missing, with the workers on record; one that can’t be opened, with the problem.
ForgetWorkspaceWorkers	ForgetWorkspaceWorkersRequest	ForgetWorkspaceWorkersResponse	Forgets every worker of a workspace: none of them is enabled any more, and the service no longer looks for its folder. Their files aren’t touched. Refused while one of them runs (RUN_IN_PROGRESS).

Enum: WorkerState

FQN: blitz.v1.WorkerState

WorkerState is whether a worker may run.

Name	Ordinal	Description
WORKER_STATE_UNSPECIFIED	0
WORKER_STATE_NEW	1	Found but never enabled.
WORKER_STATE_ENABLED	2
WORKER_STATE_DISABLED	3
WORKER_STATE_CHANGED	4	Enabled at an older hash; the file has changed since.
WORKER_STATE_INVALID	5	WORKER.md can’t be used; problems says why.

Enum: RunStatus

FQN: blitz.v1.RunStatus

RunStatus is where a run stands.

Name	Ordinal	Description
RUN_STATUS_UNSPECIFIED	0
RUN_STATUS_RUNNING	1
RUN_STATUS_SUCCEEDED	2
RUN_STATUS_FAILED	3
RUN_STATUS_LIMITED	4	Stopped at a limit (turns, cost, time).
RUN_STATUS_SKIPPED	5	Not started: the previous run was still going (overlap: skip).
RUN_STATUS_STOPPED	6	Stopped by the user while it went (StopWorkerRun).

WorkerState Diagram

classDiagram
direction LR
%% WorkerState is whether a worker may run.

class WorkerState{
  <<enumeration>>
  WORKER_STATE_UNSPECIFIED
  WORKER_STATE_NEW
  WORKER_STATE_ENABLED
  WORKER_STATE_DISABLED
  WORKER_STATE_CHANGED
  WORKER_STATE_INVALID
}

RunStatus Diagram

classDiagram
direction LR
%% RunStatus is where a run stands.

class RunStatus{
  <<enumeration>>
  RUN_STATUS_UNSPECIFIED
  RUN_STATUS_RUNNING
  RUN_STATUS_SUCCEEDED
  RUN_STATUS_FAILED
  RUN_STATUS_LIMITED
  RUN_STATUS_SKIPPED
  RUN_STATUS_STOPPED
}

WorkerLimits Diagram

classDiagram
direction LR

%% WorkerLimits bound one run.

class WorkerLimits {
  + int32 max_turns
  + double max_cost_usd
  + google.protobuf.Duration timeout
}

Worker Diagram

classDiagram
direction LR

%% Worker describes a worker.

class Worker {
  + string workspace
  + string name
  + string description
  + string path
  + string hash
  + WorkerState state
  + string schedule
  + string cron
  + string timezone
  + google.protobuf.Timestamp next_run
  + string agent
  + string model
  + List~string~ permissions
  + WorkerLimits limits
  + List~string~ problems
  + WorkerRun last_run
  + string workflow
}
Worker --> `WorkerState`
Worker --> `WorkerLimits`
Worker --> `WorkerRun`

ListWorkersRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.ListWorkers.

class ListWorkersRequest {
  + string workspace
}

ListWorkersResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.ListWorkers.

class ListWorkersResponse {
  + List~Worker~ workers
}
ListWorkersResponse --> `Worker`

CreateWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.CreateWorker: WORKER.md's frontmatter fields and the workflow. Empty fields are left out.

class CreateWorkerRequest {
  + string workspace
  + string name
  + string description
  + string schedule
  + string timezone
  + string agent
  + string model
  + List~string~ permissions
  + int32 max_turns
  + double max_cost_usd
  + string timeout
  + string catch_up
  + string prompt
  + string workflow
}

WorkerDefinition Diagram

classDiagram
direction LR

%% WorkerDefinition is a WORKER.md as written: its frontmatter fields and the workflow. Empty fields are left out of the file.

class WorkerDefinition {
  + string name
  + string description
  + string schedule
  + string timezone
  + string agent
  + string model
  + List~string~ permissions
  + int32 max_turns
  + double max_cost_usd
  + string timeout
  + string catch_up
  + string prompt
  + string workflow
}

GetWorkerSpecRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.GetWorkerSpec.

class GetWorkerSpecRequest {
  + string workspace
  + string name
}

GetWorkerSpecResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.GetWorkerSpec.

class GetWorkerSpecResponse {
  + WorkerDefinition worker
  + string hash
}
GetWorkerSpecResponse --> `WorkerDefinition`

UpdateWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.UpdateWorker.

class UpdateWorkerRequest {
  + string workspace
  + string hash
  + WorkerDefinition worker
}
UpdateWorkerRequest --> `WorkerDefinition`

UpdateWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.UpdateWorker.

class UpdateWorkerResponse {
  + Worker worker
  + List~string~ problems
}
UpdateWorkerResponse --> `Worker`

CreateWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.CreateWorker.

class CreateWorkerResponse {
  + Worker worker
  + List~string~ problems
}
CreateWorkerResponse --> `Worker`

EnableWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.EnableWorker.

class EnableWorkerRequest {
  + string workspace
  + string name
  + string hash
}

EnableWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.EnableWorker.

class EnableWorkerResponse {
  + Worker worker
}
EnableWorkerResponse --> `Worker`

DisableWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.DisableWorker.

class DisableWorkerRequest {
  + string workspace
  + string name
}

DisableWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.DisableWorker.

class DisableWorkerResponse {
  + Worker worker
}
DisableWorkerResponse --> `Worker`

DeleteWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.DeleteWorker.

class DeleteWorkerRequest {
  + string workspace
  + string name
}

DeleteWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.DeleteWorker.

class DeleteWorkerResponse {
}

Refusal Diagram

classDiagram
direction LR

%% Refusal is an action a run wasn't permitted.

class Refusal {
  + string tool
  + ActionKind kind
  + string detail
  + google.protobuf.Timestamp time
}
Refusal --> `ActionKind`

WorkerRun Diagram

classDiagram
direction LR

%% WorkerRun is one run of a worker.

class WorkerRun {
  + string id
  + string workspace
  + string worker
  + string hash
  + RunStatus status
  + bool manual
  + google.protobuf.Timestamp started
  + google.protobuf.Duration duration
  + Usage usage
  + string session_id
  + List~Refusal~ refusals
  + ErrorInfo error
  + List~string~ files
}
WorkerRun --> `RunStatus`
WorkerRun --> `Usage`
WorkerRun --> `Refusal`
WorkerRun --> `ErrorInfo`

UndoWorkerRunRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.UndoWorkerRun.

class UndoWorkerRunRequest {
  + string workspace
  + string run_id
  + bool force
}

UndoWorkerRunResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.UndoWorkerRun.

class UndoWorkerRunResponse {
  + List~string~ restored
  + ErrorInfo error
}
UndoWorkerRunResponse --> `ErrorInfo`

RunWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.RunWorker.

class RunWorkerRequest {
  + string workspace
  + string name
}

RunWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.RunWorker.

class RunWorkerResponse {
  + WorkerRun run
}
RunWorkerResponse --> `WorkerRun`

ListWorkerRunsRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.ListWorkerRuns.

class ListWorkerRunsRequest {
  + string workspace
  + string name
  + int32 limit
}

ListWorkerRunsResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.ListWorkerRuns.

class ListWorkerRunsResponse {
  + List~WorkerRun~ runs
}
ListWorkerRunsResponse --> `WorkerRun`

GetWorkerRunRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.GetWorkerRun.

class GetWorkerRunRequest {
  + string run_id
}

GetWorkerRunResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.GetWorkerRun.

class GetWorkerRunResponse {
  + WorkerRun run
}
GetWorkerRunResponse --> `WorkerRun`

WatchWorkerRunRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.WatchWorkerRun.

class WatchWorkerRunRequest {
  + string run_id
}

WatchWorkerRunResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.WatchWorkerRun.

class WatchWorkerRunResponse {
  + TurnEvent event
}
WatchWorkerRunResponse --> `TurnEvent`

ListRunningWorkerRunsRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.ListRunningWorkerRuns.

class ListRunningWorkerRunsRequest {
}

ListRunningWorkerRunsResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.ListRunningWorkerRuns.

class ListRunningWorkerRunsResponse {
  + List~WorkerRun~ runs
}
ListRunningWorkerRunsResponse --> `WorkerRun`

StopWorkerRunRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.StopWorkerRun.

class StopWorkerRunRequest {
  + string run_id
}

StopWorkerRunResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.StopWorkerRun.

class StopWorkerRunResponse {
  + WorkerRun run
}
StopWorkerRunResponse --> `WorkerRun`

RewriteWorkerRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.RewriteWorker.

class RewriteWorkerRequest {
  + string workspace
  + WorkerDefinition worker
}
RewriteWorkerRequest --> `WorkerDefinition`

RewriteWorkerResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.RewriteWorker.

class RewriteWorkerResponse {
  + string prompt
  + List~string~ permissions
  + List~string~ changes
  + string problem
}

ListAllWorkersRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.ListAllWorkers.

class ListAllWorkersRequest {
}

WorkspaceWorkers Diagram

classDiagram
direction LR

%% One workspace's workers, in ListAllWorkersResponse.

class WorkspaceWorkers {
  + string workspace
  + bool home
  + bool missing
  + List~Worker~ workers
  + string problem
}
WorkspaceWorkers --> `Worker`

ListAllWorkersResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.ListAllWorkers.

class ListAllWorkersResponse {
  + string home
  + List~WorkspaceWorkers~ workspaces
  + WorkerPolicySettings policy
}
ListAllWorkersResponse --> `WorkspaceWorkers`
ListAllWorkersResponse --> `WorkerPolicySettings`

WorkerPolicySettings Diagram

classDiagram
direction LR

%% The global limits on every worker, as the settings have them ([workers.policy]; spec_workers_023 WK-63). A worker asks for permissions and limits; these remove what isn't allowed, fill in what it leaves out, and cap the rest.

class WorkerPolicySettings {
  + List~string~ allow
  + int32 default_max_turns
  + double default_max_cost_usd
  + string default_timeout
  + int32 max_turns
  + double max_cost_usd
  + string max_timeout
  + int32 max_concurrent
  + int32 running_max_concurrent
  + string path
}

ForgetWorkspaceWorkersRequest Diagram

classDiagram
direction LR

%% Request message for WorkerService.ForgetWorkspaceWorkers.

class ForgetWorkspaceWorkersRequest {
  + string workspace
}

ForgetWorkspaceWorkersResponse Diagram

classDiagram
direction LR

%% Response message for WorkerService.ForgetWorkspaceWorkers.

class ForgetWorkspaceWorkersResponse {
}

Message: WorkerLimits

FQN: blitz.v1.WorkerLimits

WorkerLimits bound one run.

Field	Ordinal	Type
max_turns	1	int32
max_cost_usd	2	double
timeout	3	google.protobuf.Duration

Message: Worker

FQN: blitz.v1.Worker

Worker describes a worker.

Field	Ordinal	Type	Label	Description
workspace	1	string
name	2	string
description	3	string
path	4	string		WORKER.md, absolute.
hash	5	string		Of WORKER.md and the worker’s other files.
state	6	WorkerState
schedule	7	string		As written (“Daily at 6 AM”), and as understood.
cron	8	string
timezone	9	string
next_run	10	google.protobuf.Timestamp
agent	11	string
model	12	string
permissions	13	string	Repeated	What the worker may do without asking, as its frontmatter asks, after the host policy’s cap.
limits	14	WorkerLimits
problems	15	string	Repeated	Why the worker is invalid, or what the policy removed.
last_run	16	WorkerRun		Its latest recorded run (unset: none yet).
workflow	17	string		The workflow it runs, its prompt the input (spec_workflows_043).

Message: ListWorkersRequest

FQN: blitz.v1.ListWorkersRequest

Request message for WorkerService.ListWorkers.

Field	Ordinal	Type	Label	Description
workspace	1	string		Empty for every registered workspace.

Message: ListWorkersResponse

FQN: blitz.v1.ListWorkersResponse

Response message for WorkerService.ListWorkers.

Field	Ordinal	Type	Label	Description
workers	1	Worker	Repeated

Message: CreateWorkerRequest

FQN: blitz.v1.CreateWorkerRequest

Request message for WorkerService.CreateWorker: WORKER.md's frontmatter fields and the workflow. Empty fields are left out.

Field	Ordinal	Type	Label	Description
workspace	1	string
name	2	string		Lowercase letters, digits, - and _: the worker’s directory.
description	3	string
schedule	4	string		A cron expression, a descriptor, or plain text (“Weekdays at 9:30”).
timezone	5	string		An IANA time zone; "" is the service machine’s.
agent	6	string
model	7	string
permissions	8	string	Repeated	“kind:pattern”, kind shell, write, delete, web or mcp.
max_turns	9	int32
max_cost_usd	10	double
timeout	11	string		A duration like “20m”.
catch_up	12	string		“”, “none” or “once”.
prompt	13	string		The workflow: WORKER.md’s body.
workflow	14	string		The workflow it runs, its prompt the input.

Message: WorkerDefinition

FQN: blitz.v1.WorkerDefinition

WorkerDefinition is a WORKER.md as written: its frontmatter fields and the workflow. Empty fields are left out of the file.

Field	Ordinal	Type	Label	Description
name	1	string		The worker’s directory; fixed once created.
description	2	string
schedule	3	string		A cron expression, a descriptor, or plain text (“Weekdays at 9:30”).
timezone	4	string		An IANA time zone; "" is the service machine’s.
agent	5	string
model	6	string
permissions	7	string	Repeated	“kind:pattern”, kind shell, write, delete, web or mcp.
max_turns	8	int32
max_cost_usd	9	double
timeout	10	string		A duration like “20m”.
catch_up	11	string		“”, “none” or “once”.
prompt	12	string		The workflow: WORKER.md’s body.
workflow	13	string		The workflow it runs, its prompt the input.

Message: GetWorkerSpecRequest

FQN: blitz.v1.GetWorkerSpecRequest

Request message for WorkerService.GetWorkerSpec.

Field	Ordinal	Type	Label	Description
workspace	1	string
name	2	string

Message: GetWorkerSpecResponse

FQN: blitz.v1.GetWorkerSpecResponse

Response message for WorkerService.GetWorkerSpec.

Field	Ordinal	Type	Label	Description
worker	1	WorkerDefinition
hash	2	string		The hash UpdateWorker must be given.

Message: UpdateWorkerRequest

FQN: blitz.v1.UpdateWorkerRequest

Request message for WorkerService.UpdateWorker.

Field	Ordinal	Type	Description
workspace	1	string
hash	2	string	The hash GetWorkerSpec returned: the content being replaced.
worker	3	WorkerDefinition

Message: UpdateWorkerResponse

FQN: blitz.v1.UpdateWorkerResponse

Response message for WorkerService.UpdateWorker.

Field	Ordinal	Type	Label	Description
worker	1	Worker		The worker as saved; unset when problems stopped it.
problems	2	string	Repeated	Why it wasn’t saved (nothing was written).

Message: CreateWorkerResponse

FQN: blitz.v1.CreateWorkerResponse

Response message for WorkerService.CreateWorker.

Field	Ordinal	Type	Label	Description
worker	1	Worker		The new worker; unset when problems stopped it.
problems	2	string	Repeated	Why the worker wasn’t created (nothing was written).

Message: EnableWorkerRequest

FQN: blitz.v1.EnableWorkerRequest

Request message for WorkerService.EnableWorker.

Field	Ordinal	Type	Description
workspace	1	string
name	2	string
hash	3	string	The hash the caller reviewed.

Message: EnableWorkerResponse

FQN: blitz.v1.EnableWorkerResponse

Response message for WorkerService.EnableWorker.

Field	Ordinal	Type	Label	Description
worker	1	Worker

Message: DisableWorkerRequest

FQN: blitz.v1.DisableWorkerRequest

Request message for WorkerService.DisableWorker.

Field	Ordinal	Type	Label	Description
workspace	1	string
name	2	string

Message: DisableWorkerResponse

FQN: blitz.v1.DisableWorkerResponse

Response message for WorkerService.DisableWorker.

Field	Ordinal	Type	Label	Description
worker	1	Worker

Message: DeleteWorkerRequest

FQN: blitz.v1.DeleteWorkerRequest

Request message for WorkerService.DeleteWorker.

Field	Ordinal	Type	Label	Description
workspace	1	string
name	2	string

Message: DeleteWorkerResponse

FQN: blitz.v1.DeleteWorkerResponse

Response message for WorkerService.DeleteWorker.

Field	Ordinal	Type	Label	Description

Message: Refusal

FQN: blitz.v1.Refusal

Refusal is an action a run wasn't permitted.

Field	Ordinal	Type
tool	1	string
kind	2	ActionKind
detail	3	string
time	4	google.protobuf.Timestamp

Message: WorkerRun

FQN: blitz.v1.WorkerRun

WorkerRun is one run of a worker.

Field	Ordinal	Type	Label	Description
id	1	string
workspace	2	string
worker	3	string
hash	4	string		The hash the run used.
status	5	RunStatus
manual	6	bool		Scheduled, or started by RunWorker.
started	7	google.protobuf.Timestamp
duration	8	google.protobuf.Duration
usage	9	Usage
session_id	10	string		The session holding the run’s conversation.
refusals	11	Refusal	Repeated
error	12	ErrorInfo		Why the run failed or stopped.
files	13	string	Repeated	The files the run changed (UndoWorkerRun restores them).

Message: UndoWorkerRunRequest

FQN: blitz.v1.UndoWorkerRunRequest

Request message for WorkerService.UndoWorkerRun.

Field	Ordinal	Type
workspace	1	string
run_id	2	string
force	3	bool

Message: UndoWorkerRunResponse

FQN: blitz.v1.UndoWorkerRunResponse

Response message for WorkerService.UndoWorkerRun.

Field	Ordinal	Type	Label	Description
restored	1	string	Repeated
error	2	ErrorInfo		Why the rest wasn’t restored, after a partial restore.

Message: RunWorkerRequest

FQN: blitz.v1.RunWorkerRequest

Request message for WorkerService.RunWorker.

Field	Ordinal	Type	Label	Description
workspace	1	string
name	2	string

Message: RunWorkerResponse

FQN: blitz.v1.RunWorkerResponse

Response message for WorkerService.RunWorker.

Field	Ordinal	Type	Label	Description
run	1	WorkerRun

Message: ListWorkerRunsRequest

FQN: blitz.v1.ListWorkerRunsRequest

Request message for WorkerService.ListWorkerRuns.

Field	Ordinal	Type	Description
workspace	1	string
name	2	string
limit	3	int32	At most this many (0: a default).

Message: ListWorkerRunsResponse

FQN: blitz.v1.ListWorkerRunsResponse

Response message for WorkerService.ListWorkerRuns.

Field	Ordinal	Type	Label	Description
runs	1	WorkerRun	Repeated

Message: GetWorkerRunRequest

FQN: blitz.v1.GetWorkerRunRequest

Request message for WorkerService.GetWorkerRun.

Field	Ordinal	Type	Label	Description
run_id	1	string

Message: GetWorkerRunResponse

FQN: blitz.v1.GetWorkerRunResponse

Response message for WorkerService.GetWorkerRun.

Field	Ordinal	Type	Label	Description
run	1	WorkerRun

Message: WatchWorkerRunRequest

FQN: blitz.v1.WatchWorkerRunRequest

Request message for WorkerService.WatchWorkerRun.

Field	Ordinal	Type	Label	Description
run_id	1	string

Message: WatchWorkerRunResponse

FQN: blitz.v1.WatchWorkerRunResponse

Response message for WorkerService.WatchWorkerRun.

Field	Ordinal	Type	Label	Description
event	1	TurnEvent

Message: ListRunningWorkerRunsRequest

FQN: blitz.v1.ListRunningWorkerRunsRequest

Request message for WorkerService.ListRunningWorkerRuns.

Field	Ordinal	Type	Label	Description

Message: ListRunningWorkerRunsResponse

FQN: blitz.v1.ListRunningWorkerRunsResponse

Response message for WorkerService.ListRunningWorkerRuns.

Field	Ordinal	Type	Label	Description
runs	1	WorkerRun	Repeated	Oldest first.

Message: StopWorkerRunRequest

FQN: blitz.v1.StopWorkerRunRequest

Request message for WorkerService.StopWorkerRun.

Field	Ordinal	Type	Label	Description
run_id	1	string

Message: StopWorkerRunResponse

FQN: blitz.v1.StopWorkerRunResponse

Response message for WorkerService.StopWorkerRun.

Field	Ordinal	Type	Label	Description
run	1	WorkerRun		The run as it was when asked to stop; it ends, recorded as stopped, once its turn has wound down (WatchWorkerRun’s finished event).

Message: RewriteWorkerRequest

FQN: blitz.v1.RewriteWorkerRequest

Request message for WorkerService.RewriteWorker.

Field	Ordinal	Type	Label	Description
workspace	1	string
worker	2	WorkerDefinition		The worker as the form has it (prompt required).

Message: RewriteWorkerResponse

FQN: blitz.v1.RewriteWorkerResponse

Response message for WorkerService.RewriteWorker.

Field	Ordinal	Type	Label	Description
prompt	1	string		The rewritten instructions (empty when problem is set).
permissions	2	string	Repeated	The permissions they need, “kind:pattern”, each valid.
changes	3	string	Repeated	What changed and why, a line each.
problem	4	string		Why there’s no rewrite: the model’s failure, redacted.

Message: ListAllWorkersRequest

FQN: blitz.v1.ListAllWorkersRequest

Request message for WorkerService.ListAllWorkers.

Field	Ordinal	Type	Label	Description

Message: WorkspaceWorkers

FQN: blitz.v1.WorkspaceWorkers

One workspace's workers, in ListAllWorkersResponse.

Field	Ordinal	Type	Label	Description
workspace	1	string		The workspace’s folder.
home	2	bool		Whether it’s the home workspace (the user’s global workers).
missing	3	bool		Whether its folder is gone: workers then has only each worker on record’s workspace, name and state (enabled or disabled).
workers	4	Worker	Repeated	Its workers, by name.
problem	5	string		Why its workers can’t be listed (it can’t be opened), redacted.

Message: ListAllWorkersResponse

FQN: blitz.v1.ListAllWorkersResponse

Response message for WorkerService.ListAllWorkers.

Field	Ordinal	Type	Label	Description
home	1	string		The home workspace, where the global workers run.
workspaces	2	WorkspaceWorkers	Repeated	The home workspace first, then the others by folder.
policy	3	WorkerPolicySettings		The global limits on every worker ([workers.policy]).

Message: WorkerPolicySettings

FQN: blitz.v1.WorkerPolicySettings

The global limits on every worker, as the settings have them ([workers.policy]; spec_workers_023 WK-63). A worker asks for permissions and limits; these remove what isn't allowed, fill in what it leaves out, and cap the rest.

Field	Ordinal	Type	Label	Description
allow	1	string	Repeated	The permission kinds a worker may be given: shell, write, delete, web, mcp (none: it may only read).
default_max_turns	2	int32		What a worker that sets no limit gets.
default_max_cost_usd	3	double
default_timeout	4	string
max_turns	5	int32		The most a worker may ask for.
max_cost_usd	6	double
max_timeout	7	string
max_concurrent	8	int32		How many worker runs may go at once, across workspaces, as set.
running_max_concurrent	9	int32		How many the service allows now: a change to max_concurrent applies when the service restarts.
path	10	string		The settings file they’re in.

Message: ForgetWorkspaceWorkersRequest

FQN: blitz.v1.ForgetWorkspaceWorkersRequest

Request message for WorkerService.ForgetWorkspaceWorkers.

Field	Ordinal	Type	Label	Description
workspace	1	string

Message: ForgetWorkspaceWorkersResponse

FQN: blitz.v1.ForgetWorkspaceWorkersResponse

Response message for WorkerService.ForgetWorkspaceWorkers.

Field	Ordinal	Type	Label	Description