@shipfox/api-runners 2.0.0

package/src/db/schema/running-job-executions.ts

@@ -0,0 +1,50 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {check, index, text, timestamp, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+import {runnerSessions} from './runner-sessions.js';
+
+export const runningJobExecutions = pgTable(
+  'running_jobs',
+  {
+    id: uuidv7PrimaryKey(),
+    workspaceId: uuid('workspace_id').notNull(),
+    workflowRunId: uuid('workflow_run_id').notNull(),
+    workflowRunAttemptId: uuid('workflow_run_attempt_id').notNull(),
+    jobId: uuid('job_id').notNull(),
+    jobExecutionId: uuid('job_execution_id').notNull().unique(),
+    projectId: uuid('project_id').notNull(),
+    runnerSessionId: uuid('runner_session_id')
+      .notNull()
+      .references(() => runnerSessions.id),
+    provisionerId: uuid('provisioner_id'),
+    provisionedRunnerId: text('provisioned_runner_id'),
+    requiredLabels: text('required_labels').array().notNull(),
+    runnerLabels: text('runner_labels').array().notNull(),
+    startedAt: timestamp('started_at', {withTimezone: true}).notNull().defaultNow(),
+    firstHeartbeatAt: timestamp('first_heartbeat_at', {withTimezone: true}),
+    lastHeartbeatAt: timestamp('last_heartbeat_at', {withTimezone: true}).notNull().defaultNow(),
+    cancellationRequestedAt: timestamp('cancellation_requested_at', {withTimezone: true}),
+  },
+  (table) => [
+    index('runners_running_jobs_no_first_heartbeat_started_idx')
+      .on(table.startedAt)
+      .where(sql`"first_heartbeat_at" IS NULL`),
+    index('runners_running_jobs_last_heartbeat_at_idx').on(table.lastHeartbeatAt),
+    index('runners_running_jobs_provisioned_runner_started_idx')
+      .on(table.workspaceId, table.provisionerId, table.provisionedRunnerId, table.startedAt.desc())
+      .where(sql`"provisioner_id" IS NOT NULL`),
+    index('runners_running_jobs_cancellation_requested_idx')
+      .on(table.workspaceId, table.provisionerId, table.provisionedRunnerId)
+      .where(sql`"cancellation_requested_at" IS NOT NULL`),
+    index('runners_running_jobs_job_id_idx').on(table.jobId),
+    index('runners_running_jobs_runner_session_id_idx').on(table.runnerSessionId),
+    check(
+      'runners_running_jobs_link_ck',
+      sql`(${table.provisionerId} IS NULL) = (${table.provisionedRunnerId} IS NULL)`,
+    ),
+  ],
+);
+
+export type RunningJobExecutionDb = typeof runningJobExecutions.$inferSelect;
+export type RunningJobExecutionInsertDb = typeof runningJobExecutions.$inferInsert;

package/src/index.ts

@@ -0,0 +1,63 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runnersEventSchemas} from '@shipfox/api-runners-dto';
+import {
+  WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
+  type WorkflowsEventMapDto,
+} from '@shipfox/api-workflows-dto';
+import {type ShipfoxModule, subscriberFactory} from '@shipfox/node-module';
+import {db, migrationsPath, runnersOutbox} from '#db/index.js';
+import {registerRunnersServiceMetrics} from '#metrics/index.js';
+import {
+  createProvisionerTokenAuthMethod,
+  createRunnerRegistrationTokenAuthMethod,
+  onWorkflowsJobExecutionTimedOut,
+  routes,
+} from '#presentation/index.js';
+import {createRunnersMaintenanceActivities} from '#temporal/activities/index.js';
+import {RUNNERS_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
+
+export {
+  type MintEphemeralRegistrationTokenParams,
+  type MintEphemeralRegistrationTokenResult,
+  type MintEphemeralRegistrationTokensBatchParams,
+  type MintEphemeralRegistrationTokensBatchProvisionedRunner,
+  type MintEphemeralRegistrationTokensBatchResult,
+  mintEphemeralRegistrationToken,
+  mintEphemeralRegistrationTokensBatch,
+} from '#core/ephemeral-registration-tokens.js';
+export {
+  type EffectiveRunnerToolCapabilitiesResult,
+  getEffectiveRunnerToolCapabilities,
+  unadvertisedRunnerTools,
+} from '#core/runner-tool-capabilities.js';
+export {
+  cancelRunnerJobs,
+  type EnqueueJobExecutionParams,
+  enqueueJobExecution,
+  isJobLeaseActive,
+  releaseJobExecution,
+} from '#db/index.js';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const workflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
+
+const subscriber = subscriberFactory<WorkflowsEventMapDto>();
+
+export const runnersModule: ShipfoxModule = {
+  name: 'runners',
+  database: {db, migrationsPath},
+  auth: [createRunnerRegistrationTokenAuthMethod(), createProvisionerTokenAuthMethod()],
+  routes,
+  metrics: registerRunnersServiceMetrics,
+  publishers: [{name: 'runners', table: runnersOutbox, db, eventSchemas: runnersEventSchemas}],
+  subscribers: [subscriber(WORKFLOWS_JOB_EXECUTION_TIMED_OUT, onWorkflowsJobExecutionTimedOut)],
+  workers: [
+    {
+      taskQueue: RUNNERS_MAINTENANCE_TASK_QUEUE,
+      workflowsPath,
+      activities: createRunnersMaintenanceActivities,
+      workflows: [{name: 'stuckJobDetector', id: 'stuck-job-detector', cronSchedule: '* * * * *'}],
+    },
+  ],
+};

package/src/metrics/index.ts

@@ -0,0 +1,13 @@
+export {
+  jobExecutionClaimedCount,
+  jobExecutionEnqueuedCount,
+  jobExecutionLeaseExpiredCount,
+  provisionedRunnerAbsentTerminatedCount,
+  provisionedRunnerCountDivergenceCount,
+  provisionedRunnerReconcileCallCount,
+  provisionedRunnerTerminateIntentHonoredCount,
+  provisionedRunnerTerminateIntentIssuedCount,
+  recordRunnersRateLimitCheck,
+  recordRunnersRateLimitPruneFailure,
+} from './instance.js';
+export {registerRunnersServiceMetrics} from './service.js';

package/src/metrics/instance.ts

@@ -0,0 +1,115 @@
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+
+const meter = instanceMetrics.getMeter('runners');
+
+export const jobExecutionEnqueuedCount = meter.createCounter<Record<string, never>>(
+  'runners_job_execution_enqueued',
+  {
+    description: 'Job executions added to the pending queue',
+  },
+);
+
+export const jobExecutionClaimedCount = meter.createCounter<{outcome: 'claimed' | 'empty'}>(
+  'runners_job_execution_claimed',
+  {description: 'Job execution claim attempts by outcome'},
+);
+
+export const jobExecutionLeaseExpiredCount = meter.createCounter<Record<string, never>>(
+  'runners_job_execution_lease_expired',
+  {description: 'Job execution leases reaped after passing the heartbeat threshold'},
+);
+
+export const provisionedRunnerReportCount = meter.createCounter<{
+  state: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'terminated';
+}>('runners_provisioned_runner_reported', {
+  description: 'Provisioned runner lifecycle reports accepted by state',
+});
+
+export const provisionedRunnerReapedCount = meter.createCounter<Record<string, never>>(
+  'runners_provisioned_runner_reaped',
+  {
+    description: 'Stale provisioned runners marked failed by backend maintenance',
+  },
+);
+
+export const provisionedRunnerCountDivergenceCount = meter.createCounter<{
+  template_key?: string;
+  state: 'starting' | 'running';
+  direction: 'backend-higher' | 'advertised-higher';
+}>('runners_provisioned_runner_count_divergence', {
+  description:
+    'Absolute difference between provisioner-advertised and backend-observed provisioned runner counts',
+});
+
+export const provisionedRunnerReconcileCallCount = meter.createCounter<Record<string, never>>(
+  'runners_provisioned_runner_reconcile_called',
+  {description: 'Provisioned runner reconcile calls completed successfully'},
+);
+
+export const provisionedRunnerAbsentTerminatedCount = meter.createCounter<Record<string, never>>(
+  'runners_provisioned_runner_absent_terminated',
+  {
+    description:
+      'Owned provisioned runners marked terminated because they were absent from reconcile',
+  },
+);
+
+export const provisionedRunnerTerminateIntentIssuedCount = meter.createCounter<{
+  surface: 'poll-demand' | 'reconcile';
+  reason: 'job-cancelled' | 'terminal-state';
+}>('runners_provisioned_runner_terminate_intent_issued', {
+  description: 'Provisioned runner terminate intents returned to provisioners',
+});
+
+export const provisionedRunnerTerminateIntentHonoredCount = meter.createCounter<{
+  reason: 'job-cancelled';
+}>('runners_provisioned_runner_terminate_intent_honored', {
+  description: 'Provisioned runner terminate intents honored by first transition to terminated',
+});
+
+export const reservationReleasedCount = meter.createCounter<Record<string, never>>(
+  'runners_reservation_released',
+  {description: 'Reservation units released from terminal provisioned runner reports'},
+);
+
+export type RunnersRateLimitAction = 'provisioner-mint' | 'ephemeral-register';
+export type RunnersRateLimitScope = 'provisioner' | 'ephemeral-token';
+export type RunnersRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
+
+const rateLimitCheckCount = meter.createCounter<{
+  action: RunnersRateLimitAction;
+  scope: RunnersRateLimitScope;
+  outcome: RunnersRateLimitOutcome;
+}>('runners_rate_limit_checks', {
+  description: 'Runners rate limit checks by action, scope, and outcome',
+});
+
+const rateLimitPruneFailureCount = meter.createCounter('runners_rate_limit_prune_failures', {
+  description: 'Runners rate limit prune failures',
+});
+
+function recordMetric(record: () => void): void {
+  try {
+    record();
+  } catch {
+    // Metrics must not affect runner or provisioner request outcomes.
+  }
+}
+
+export function recordRunnersRateLimitCheck(params: {
+  action: RunnersRateLimitAction;
+  scope: RunnersRateLimitScope;
+  outcome: RunnersRateLimitOutcome;
+}): void {
+  recordMetric(() =>
+    rateLimitCheckCount.add(1, {
+      action: params.action,
+      scope: params.scope,
+      outcome: params.outcome,
+    }),
+  );
+}
+
+export function recordRunnersRateLimitPruneFailure(): void {
+  recordMetric(() => rateLimitPruneFailureCount.add(1));
+}

package/src/metrics/service.ts

@@ -0,0 +1,22 @@
+import {getServiceMetricsProvider} from '@shipfox/node-opentelemetry';
+import {getJobExecutionQueueDepth} from '#db/job-executions.js';
+
+export function registerRunnersServiceMetrics(): void {
+  const meter = getServiceMetricsProvider().getMeter('runners');
+
+  const pendingJobExecutions = meter.createObservableGauge('runners_pending_job_executions', {
+    description: 'Job executions currently waiting in the queue to be claimed',
+  });
+  const runningJobExecutions = meter.createObservableGauge('runners_running_job_executions', {
+    description: 'Job executions currently claimed by a runner and in progress',
+  });
+
+  meter.addBatchObservableCallback(
+    async (observer) => {
+      const depth = await getJobExecutionQueueDepth();
+      observer.observe(pendingJobExecutions, depth.pendingJobExecutions);
+      observer.observe(runningJobExecutions, depth.runningJobExecutions);
+    },
+    [pendingJobExecutions, runningJobExecutions],
+  );
+}

package/src/presentation/auth/index.ts

@@ -0,0 +1,6 @@
+export {createProvisionerTokenAuthMethod} from './provisioner-token-auth.js';
+export {
+  createRunnerRegistrationTokenAuthMethod,
+  getRunnerContext,
+  type RunnerRegistrationContext,
+} from './runner-registration-token-auth.js';

package/src/presentation/auth/provisioner-token-auth.ts

@@ -0,0 +1,76 @@
+import {
+  AUTH_PROVISIONER_TOKEN,
+  type ProvisionerContext,
+  setProvisionerContext,
+} from '@shipfox/api-auth-context';
+import {type AuthMethod, ClientError, extractBearerToken} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import {extractDisplayPrefix, getTokenType, hashOpaqueToken} from '@shipfox/node-tokens';
+import {config} from '#config.js';
+import {resolveProvisionerTokenByHash, touchProvisionerLastSeen} from '#db/provisioner-tokens.js';
+
+type AuthFailureReason = 'missing' | 'type' | 'not-found' | 'revoked' | 'expired';
+
+export function createProvisionerTokenAuthMethod(): AuthMethod {
+  return {
+    name: AUTH_PROVISIONER_TOKEN,
+    authenticate: async (request) => {
+      const rawToken = extractBearerToken(request.headers.authorization);
+      if (!rawToken) {
+        logAuthFailure({reason: 'missing'});
+        throw new ClientError('Missing or invalid Authorization header', 'unauthorized', {
+          status: 401,
+        });
+      }
+
+      if (getTokenType(rawToken) !== 'provisionerToken') {
+        logAuthFailure({rawToken, reason: 'type'});
+        throw new ClientError('Invalid provisioner token', 'unauthorized', {status: 401});
+      }
+
+      const provisionerToken = await resolveProvisionerTokenByHash(hashOpaqueToken(rawToken));
+      if (!provisionerToken) {
+        logAuthFailure({rawToken, reason: 'not-found'});
+        throw new ClientError('Invalid provisioner token', 'unauthorized', {status: 401});
+      }
+
+      if (provisionerToken.revokedAt) {
+        logAuthFailure({rawToken, reason: 'revoked'});
+        throw new ClientError('Provisioner token has been revoked', 'provisioner-token-revoked', {
+          status: 401,
+        });
+      }
+
+      if (provisionerToken.expiresAt && provisionerToken.expiresAt <= new Date()) {
+        logAuthFailure({rawToken, reason: 'expired'});
+        throw new ClientError('Provisioner token has expired', 'provisioner-token-expired', {
+          status: 401,
+        });
+      }
+
+      const context: ProvisionerContext = {
+        provisionerTokenId: provisionerToken.id,
+        workspaceId: provisionerToken.workspaceId,
+      };
+
+      await touchProvisionerLastSeen({
+        tokenId: provisionerToken.id,
+        throttleSeconds: config.PROVISIONER_LAST_SEEN_THROTTLE_SECONDS,
+      }).catch((error: unknown) => {
+        logger().warn({error, provisionerTokenId: provisionerToken.id}, 'last-seen touch failed');
+      });
+
+      setProvisionerContext(request, context);
+    },
+  };
+}
+
+function logAuthFailure(params: {rawToken?: string | undefined; reason: AuthFailureReason}): void {
+  logger().warn(
+    {
+      prefix: params.rawToken ? extractDisplayPrefix(params.rawToken) : undefined,
+      reason: params.reason,
+    },
+    'provisioner token auth failed',
+  );
+}

package/src/presentation/auth/runner-registration-token-auth.ts

@@ -0,0 +1,105 @@
+import {AUTH_RUNNER_REGISTRATION_TOKEN} from '@shipfox/api-auth-context';
+import {type AuthMethod, ClientError, extractBearerToken} from '@shipfox/node-fastify';
+import {getTokenType, hashOpaqueToken} from '@shipfox/node-tokens';
+import type {FastifyRequest} from 'fastify';
+import {resolveEphemeralRegistrationTokenByHash} from '#db/ephemeral-registration-tokens.js';
+import {resolveManualRegistrationTokenByHash} from '#db/manual-registration-tokens.js';
+
+const RUNNER_CONTEXT_KEY = 'runner';
+
+export type RunnerRegistrationContext =
+  | {
+      kind: 'manual';
+      registrationTokenId: string;
+      workspaceId: string;
+    }
+  | {
+      kind: 'ephemeral';
+      ephemeralTokenId: string;
+      workspaceId: string;
+      provisionerId: string;
+      reservationId: string | null;
+      provisionedRunnerId: string;
+    };
+
+export function getRunnerContext(request: FastifyRequest): RunnerRegistrationContext {
+  const context = (request as unknown as Record<string, unknown>)[RUNNER_CONTEXT_KEY] as
+    | RunnerRegistrationContext
+    | undefined;
+  if (!context) {
+    throw new Error('Runner context is not available on this request');
+  }
+  return context;
+}
+
+export function createRunnerRegistrationTokenAuthMethod(): AuthMethod {
+  return {
+    name: AUTH_RUNNER_REGISTRATION_TOKEN,
+    authenticate: async (request) => {
+      const rawToken = extractBearerToken(request.headers.authorization);
+      if (!rawToken) {
+        throw new ClientError('Missing or invalid Authorization header', 'unauthorized', {
+          status: 401,
+        });
+      }
+
+      const tokenType = getTokenType(rawToken);
+
+      if (tokenType === 'ephemeralRegistrationToken') {
+        const ephemeralToken = await resolveEphemeralRegistrationTokenByHash(
+          hashOpaqueToken(rawToken),
+        );
+        if (!ephemeralToken) {
+          throw new ClientError('Invalid runner registration token', 'unauthorized', {
+            status: 401,
+          });
+        }
+        if (ephemeralToken.expiresAt < new Date()) {
+          throw new ClientError(
+            'Ephemeral registration token has expired',
+            'registration-token-expired',
+            {status: 401},
+          );
+        }
+
+        (request as unknown as Record<string, unknown>)[RUNNER_CONTEXT_KEY] = {
+          kind: 'ephemeral',
+          ephemeralTokenId: ephemeralToken.id,
+          workspaceId: ephemeralToken.workspaceId,
+          provisionerId: ephemeralToken.provisionerId,
+          reservationId: ephemeralToken.reservationId,
+          provisionedRunnerId: ephemeralToken.provisionedRunnerId,
+        } satisfies RunnerRegistrationContext;
+        return;
+      }
+
+      if (tokenType !== 'manualRegistrationToken') {
+        throw new ClientError('Invalid runner registration token', 'unauthorized', {status: 401});
+      }
+
+      const token = await resolveManualRegistrationTokenByHash(hashOpaqueToken(rawToken));
+      if (!token) {
+        throw new ClientError('Invalid runner registration token', 'unauthorized', {status: 401});
+      }
+
+      if (token.expiresAt && token.expiresAt < new Date()) {
+        throw new ClientError('Registration token has expired', 'registration-token-expired', {
+          status: 401,
+        });
+      }
+      if (token.revokedAt) {
+        throw new ClientError(
+          'Manual registration token has been revoked',
+          'manual-registration-token-revoked',
+          {status: 401},
+        );
+      }
+
+      (request as unknown as Record<string, unknown>)[RUNNER_CONTEXT_KEY] = {
+        kind: 'manual',
+        registrationTokenId: token.id,
+        workspaceId: token.workspaceId,
+      } satisfies RunnerRegistrationContext;
+    },
+  };
+}

package/src/presentation/dto/active-provisioner.ts

@@ -0,0 +1,15 @@
+import type {ActiveProvisionerToken} from '#core/entities/provisioner-token.js';
+
+export function toActiveProvisionerDto(token: ActiveProvisionerToken): {
+  id: string;
+  name: string | null;
+  prefix: string;
+  last_seen_at: string;
+} {
+  return {
+    id: token.id,
+    name: token.name,
+    prefix: token.prefix,
+    last_seen_at: token.lastSeenAt.toISOString(),
+  };
+}

package/src/presentation/dto/index.ts

@@ -0,0 +1,13 @@
+export {toActiveProvisionerDto} from './active-provisioner.js';
+export {toManualRegistrationTokenDto} from './manual-registration-token.js';
+export {
+  toMintRegistrationTokensProvisionedRunners,
+  toMintRegistrationTokensResponseDto,
+} from './mint-registration-tokens.js';
+export {toPollDemandResponseDto} from './poll-demand.js';
+export {
+  toActiveRunnersResponseDto,
+  toReconcileProvisionedRunnersResponseDto,
+  toReportProvisionedRunnersResponseDto,
+} from './provisioned-runners.js';
+export {toProvisionerTokenDto} from './provisioner-token.js';

package/src/presentation/dto/manual-registration-token.ts

@@ -0,0 +1,23 @@
+import type {ManualRegistrationToken} from '#core/entities/manual-registration-token.js';
+
+export function toManualRegistrationTokenDto(token: ManualRegistrationToken): {
+  id: string;
+  workspace_id: string;
+  prefix: string;
+  name: string | null;
+  expires_at: string | null;
+  revoked_at: string | null;
+  created_at: string;
+  updated_at: string;
+} {
+  return {
+    id: token.id,
+    workspace_id: token.workspaceId,
+    prefix: token.prefix,
+    name: token.name,
+    expires_at: token.expiresAt?.toISOString() ?? null,
+    revoked_at: token.revokedAt?.toISOString() ?? null,
+    created_at: token.createdAt.toISOString(),
+    updated_at: token.updatedAt.toISOString(),
+  };
+}

package/src/presentation/dto/mint-registration-tokens.ts

@@ -0,0 +1,35 @@
+import type {
+  MintedRegistrationTokenDto,
+  MintRegistrationTokensBatchResponseDto,
+  MintRegistrationTokensProvisionedRunnerDto,
+} from '@shipfox/api-runners-dto';
+import type {
+  MintEphemeralRegistrationTokensBatchProvisionedRunner,
+  MintEphemeralRegistrationTokensBatchResult,
+} from '#core/ephemeral-registration-tokens.js';
+
+export function toMintRegistrationTokensProvisionedRunners(
+  provisionedRunners: MintRegistrationTokensProvisionedRunnerDto[],
+): MintEphemeralRegistrationTokensBatchProvisionedRunner[] {
+  return provisionedRunners.map((provisionedRunner) => ({
+    provisionedRunnerId: provisionedRunner.provisioned_runner_id,
+  }));
+}
+
+export function toMintRegistrationTokensResponseDto(
+  result: MintEphemeralRegistrationTokensBatchResult[],
+): MintRegistrationTokensBatchResponseDto {
+  return {
+    tokens: result.map(toMintedRegistrationTokenDto),
+  };
+}
+
+function toMintedRegistrationTokenDto(
+  result: MintEphemeralRegistrationTokensBatchResult,
+): MintedRegistrationTokenDto {
+  return {
+    provisioned_runner_id: result.provisionedRunnerId,
+    registration_token: result.rawToken,
+    expires_at: result.token.expiresAt.toISOString(),
+  };
+}

package/src/presentation/dto/poll-demand.ts

@@ -0,0 +1,20 @@
+import type {PollDemandResponseDto} from '@shipfox/api-runners-dto';
+import type {PollDemandResult} from '#core/demand.js';
+
+export function toPollDemandResponseDto(result: PollDemandResult): PollDemandResponseDto {
+  return {
+    stats: result.stats.map((stat) => ({
+      labels: stat.labels,
+      queued: stat.queued,
+      reserved: stat.reserved,
+      oldest_queued_at: stat.oldestQueuedAt.toISOString(),
+    })),
+    reservations: result.reservations.map((reservation) => ({
+      reservation_id: reservation.reservationId,
+      labels: reservation.labels,
+      count: reservation.count,
+      expires_at: reservation.expiresAt.toISOString(),
+    })),
+    terminate_provisioned_runner_ids: result.terminateProvisionedRunnerIds,
+  };
+}

package/src/presentation/dto/provisioned-runners.ts

@@ -0,0 +1,88 @@
+import type {
+  ActiveRunner,
+  ReconcileProvisionedRunnersResult,
+  ReportProvisionedRunnersResult,
+} from '#core/provisioned-runners.js';
+
+export function toReportProvisionedRunnersResponseDto(result: ReportProvisionedRunnersResult): {
+  accepted: number;
+  reservations_released: number;
+} {
+  return {
+    accepted: result.accepted,
+    reservations_released: result.reservationsReleased,
+  };
+}
+
+export function toReconcileProvisionedRunnersResponseDto(
+  result: ReconcileProvisionedRunnersResult,
+): {
+  runners: Array<{
+    provisioned_runner_id: string;
+    state: ReconcileProvisionedRunnersResult['runners'][number]['state'];
+    reservation_id: string | null;
+    runner_session_id: string | null;
+    bound_job: {
+      job_id: string;
+      workflow_run_attempt_id: string;
+      last_heartbeat_at: string;
+      cancellation_requested_at: string | null;
+    } | null;
+    desired_intent: ReconcileProvisionedRunnersResult['runners'][number]['desiredIntent'];
+  }>;
+  terminated_absent_provisioned_runner_ids: string[];
+} {
+  return {
+    runners: result.runners.map((runner) => ({
+      provisioned_runner_id: runner.provisionedRunnerId,
+      state: runner.state,
+      reservation_id: runner.reservationId,
+      runner_session_id: runner.runnerSessionId,
+      bound_job: runner.boundJobExecution
+        ? {
+            job_id: runner.boundJobExecution.jobId,
+            workflow_run_attempt_id: runner.boundJobExecution.workflowRunAttemptId,
+            last_heartbeat_at: runner.boundJobExecution.lastHeartbeatAt.toISOString(),
+            cancellation_requested_at:
+              runner.boundJobExecution.cancellationRequestedAt?.toISOString() ?? null,
+          }
+        : null,
+      desired_intent: runner.desiredIntent,
+    })),
+    terminated_absent_provisioned_runner_ids: result.terminatedAbsentProvisionedRunnerIds,
+  };
+}
+
+export function toActiveRunnersResponseDto(runners: ActiveRunner[]): {
+  runners: Array<{
+    runner_session_id: string | null;
+    provisioned_runner_id: string | null;
+    provisioner_id: string | null;
+    state: ActiveRunner['state'];
+    labels: string[];
+    template_key: string | null;
+    provider_kind: string | null;
+    job_id: string | null;
+    workflow_run_attempt_id: string | null;
+    project_id: string | null;
+    reported_at: string | null;
+    last_heartbeat_at: string | null;
+  }>;
+} {
+  return {
+    runners: runners.map((runner) => ({
+      runner_session_id: runner.runnerSessionId,
+      provisioned_runner_id: runner.provisionedRunnerId,
+      provisioner_id: runner.provisionerId,
+      state: runner.state,
+      labels: runner.labels,
+      template_key: runner.templateKey,
+      provider_kind: runner.providerKind,
+      job_id: runner.jobId,
+      workflow_run_attempt_id: runner.workflowRunAttemptId,
+      project_id: runner.projectId,
+      reported_at: runner.reportedAt?.toISOString() ?? null,
+      last_heartbeat_at: runner.lastHeartbeatAt?.toISOString() ?? null,
+    })),
+  };
+}