Skip to content

Add Runners service proto definitions and related proto changes #66

@rowan-stein

Description

@rowan-stein

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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions