User Request
Add proto definitions for the new Runners service and make additive changes to existing protos needed for the orchestrator refactoring.
Specification
1. New file: proto/agynio/api/runners/v1/runners.proto
Package: agynio.api.runners.v1
Go package: github.com/agynio/api/gen/agynio/api/runners/v1;runnersv1
Service: RunnersService with the following RPCs:
Runner Management
| RPC |
Description |
RegisterRunner |
Register a new runner |
GetRunner |
Get runner by ID |
ListRunners |
List runners (with optional org filter, pagination) |
DeleteRunner |
Delete a runner |
ValidateServiceToken |
Validate service token hash, resolve runner |
Workload State
| RPC |
Description |
CreateWorkload |
Record a new workload (caller-provided ID) |
UpdateWorkloadStatus |
Update workload status and containers |
DeleteWorkload |
Remove a workload record |
GetWorkload |
Get workload by ID |
ListWorkloadsByThread |
List workloads for a thread (paginated) |
ListWorkloads |
List all workloads with status filter (paginated) — used by orchestrator |
Messages
Runner:
EntityMeta (id, created_at, updated_at)
Runner (meta, name, organization_id?, identity_id, status)
RunnerStatus enum: UNSPECIFIED, PENDING, ENROLLED, OFFLINE
Workload:
Workload (meta, runner_id, thread_id, agent_id, organization_id, status, containers[], ziti_identity_id)
WorkloadStatus enum: UNSPECIFIED, STARTING, RUNNING, STOPPING, STOPPED, FAILED
Container (container_id, name, role, image, status)
ContainerRole enum: UNSPECIFIED, MAIN, SIDECAR, INIT
ContainerStatus enum: UNSPECIFIED, RUNNING, TERMINATED, WAITING
Conventions to follow:
EntityMeta pattern from apps/v1/apps.proto
optional string organization_id on Runner (nullable for cluster-scoped)
- Non-optional
organization_id on Workload
- Service token:
RegisterRunnerResponse returns plaintext token; ValidateServiceTokenRequest takes token_hash; Runner message excludes hash
- All enums prefixed with type name per Buf STANDARD lint
- Pagination:
page_size/page_token/next_page_token
2. New file: proto/agynio/api/gateway/v1/runners.proto
Service: RunnersGateway exposing only:
ListWorkloadsByThread — reuses request/response from internal proto
GetWorkload — reuses request/response from internal proto
Pattern: Same as gateway/v1/agents.proto — import internal messages, fully-qualified types.
3. Additive change: proto/agynio/api/runner/v1/runner.proto
Add runner_id field to StartWorkloadResponse:
message StartWorkloadResponse {
string id = 1;
WorkloadContainers containers = 2;
WorkloadStatus status = 3;
WorkloadFailure failure = 4;
string runner_id = 5; // NEW
}
4. Additive change: proto/agynio/api/agents/v1/agents.proto
Add organization_id field to Agent message (find appropriate field number — likely next available after existing fields).
Validation
- All changes must pass
buf lint with the repo's existing config
buf breaking should pass (all changes are additive)
User Request
Add proto definitions for the new Runners service and make additive changes to existing protos needed for the orchestrator refactoring.
Specification
1. New file:
proto/agynio/api/runners/v1/runners.protoPackage:
agynio.api.runners.v1Go package:
github.com/agynio/api/gen/agynio/api/runners/v1;runnersv1Service:
RunnersServicewith the following RPCs:Runner Management
RegisterRunnerGetRunnerListRunnersDeleteRunnerValidateServiceTokenWorkload State
CreateWorkloadUpdateWorkloadStatusDeleteWorkloadGetWorkloadListWorkloadsByThreadListWorkloadsMessages
Runner:
EntityMeta(id, created_at, updated_at)Runner(meta, name, organization_id?, identity_id, status)RunnerStatusenum: UNSPECIFIED, PENDING, ENROLLED, OFFLINEWorkload:
Workload(meta, runner_id, thread_id, agent_id, organization_id, status, containers[], ziti_identity_id)WorkloadStatusenum: UNSPECIFIED, STARTING, RUNNING, STOPPING, STOPPED, FAILEDContainer(container_id, name, role, image, status)ContainerRoleenum: UNSPECIFIED, MAIN, SIDECAR, INITContainerStatusenum: UNSPECIFIED, RUNNING, TERMINATED, WAITINGConventions to follow:
EntityMetapattern fromapps/v1/apps.protooptional string organization_idon Runner (nullable for cluster-scoped)organization_idon WorkloadRegisterRunnerResponsereturns plaintext token;ValidateServiceTokenRequesttakestoken_hash;Runnermessage excludes hashpage_size/page_token/next_page_token2. New file:
proto/agynio/api/gateway/v1/runners.protoService:
RunnersGatewayexposing only:ListWorkloadsByThread— reuses request/response from internal protoGetWorkload— reuses request/response from internal protoPattern: Same as
gateway/v1/agents.proto— import internal messages, fully-qualified types.3. Additive change:
proto/agynio/api/runner/v1/runner.protoAdd
runner_idfield toStartWorkloadResponse:4. Additive change:
proto/agynio/api/agents/v1/agents.protoAdd
organization_idfield toAgentmessage (find appropriate field number — likely next available after existing fields).Validation
buf lintwith the repo's existing configbuf breakingshould pass (all changes are additive)