@shipfox/api-runners-dto 2.0.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@shipfox/api-runners-dto",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/runners-dto"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@shipfox/runner-labels": "0.1.0"
+  },
+  "devDependencies": {
+    "@shipfox/depcruise": "1.0.1",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/swc": "1.2.5"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/events.ts

@@ -0,0 +1,46 @@
+import {z} from 'zod';
+
+const nonEmptyStringSchema = z.string().nonempty();
+const isoDateTimeSchema = z.string().datetime();
+
+export const RUNNER_JOB_LEASE_EXPIRED = 'runners.job.lease_expired' as const;
+export const RUNNER_JOB_QUEUED = 'runners.job.queued' as const;
+export const RUNNER_JOB_CLAIMED = 'runners.job.claimed' as const;
+
+export const runnerJobLeaseExpiredEventSchema = z.object({
+  workflowRunId: nonEmptyStringSchema,
+  workflowRunAttemptId: nonEmptyStringSchema,
+  jobId: nonEmptyStringSchema,
+  jobExecutionId: nonEmptyStringSchema,
+});
+export type RunnerJobLeaseExpiredEvent = z.infer<typeof runnerJobLeaseExpiredEventSchema>;
+
+export const runnerJobQueuedEventSchema = z.object({
+  workflowRunId: nonEmptyStringSchema,
+  workflowRunAttemptId: nonEmptyStringSchema,
+  jobId: nonEmptyStringSchema,
+  jobExecutionId: nonEmptyStringSchema,
+  queuedAt: isoDateTimeSchema,
+});
+export type RunnerJobQueuedEvent = z.infer<typeof runnerJobQueuedEventSchema>;
+
+export const runnerJobClaimedEventSchema = z.object({
+  workflowRunId: nonEmptyStringSchema,
+  workflowRunAttemptId: nonEmptyStringSchema,
+  jobId: nonEmptyStringSchema,
+  jobExecutionId: nonEmptyStringSchema,
+  claimedAt: isoDateTimeSchema,
+});
+export type RunnerJobClaimedEvent = z.infer<typeof runnerJobClaimedEventSchema>;
+
+export interface RunnersEventMap {
+  [RUNNER_JOB_LEASE_EXPIRED]: RunnerJobLeaseExpiredEvent;
+  [RUNNER_JOB_QUEUED]: RunnerJobQueuedEvent;
+  [RUNNER_JOB_CLAIMED]: RunnerJobClaimedEvent;
+}
+
+export const runnersEventSchemas = {
+  [RUNNER_JOB_LEASE_EXPIRED]: runnerJobLeaseExpiredEventSchema,
+  [RUNNER_JOB_QUEUED]: runnerJobQueuedEventSchema,
+  [RUNNER_JOB_CLAIMED]: runnerJobClaimedEventSchema,
+} satisfies Record<keyof RunnersEventMap, z.ZodType>;

package/src/index.ts

@@ -0,0 +1,107 @@
+export {
+  type ActiveProvisionerDto,
+  type ActiveRunnerDto,
+  type ActiveRunnerStateDto,
+  type ActiveRunnersResponseDto,
+  activeProvisionerDtoSchema,
+  activeRunnerDtoSchema,
+  activeRunnerStateSchema,
+  activeRunnersResponseSchema,
+  type ClaimedJobResponseDto,
+  type CreateManualRegistrationTokenBodyDto,
+  type CreateManualRegistrationTokenResponseDto,
+  type CreateProvisionerTokenBodyDto,
+  type CreateProvisionerTokenResponseDto,
+  claimedJobResponseSchema,
+  createManualRegistrationTokenBodySchema,
+  createManualRegistrationTokenResponseSchema,
+  createProvisionerTokenBodySchema,
+  createProvisionerTokenResponseSchema,
+  type DemandStatDto,
+  demandStatSchema,
+  type HeartbeatBodyDto,
+  type HeartbeatResponseDto,
+  heartbeatBodySchema,
+  heartbeatResponseSchema,
+  type ListActiveProvisionersResponseDto,
+  type ListManualRegistrationTokensResponseDto,
+  type ListProvisionerTokensResponseDto,
+  listActiveProvisionersResponseSchema,
+  listManualRegistrationTokensResponseSchema,
+  listProvisionerTokensResponseSchema,
+  MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS,
+  MAX_OBSERVED_PROVISIONED_RUNNER_ID_LENGTH,
+  MAX_PROVIDER_KIND_LENGTH,
+  MAX_PROVISIONED_RUNNER_REASON_LENGTH,
+  MAX_PROVISIONED_RUNNER_REPORT_EVENTS,
+  MAX_PROVISIONER_TOKEN_TTL_SECONDS,
+  MAX_RECONCILE_OBSERVED_RUNNERS,
+  type ManualRegistrationTokenDto,
+  type MintedRegistrationTokenDto,
+  type MintRegistrationTokensBatchBodyDto,
+  type MintRegistrationTokensBatchResponseDto,
+  type MintRegistrationTokensProvisionedRunnerDto,
+  manualRegistrationTokenDtoSchema,
+  mintedRegistrationTokenSchema,
+  mintRegistrationTokensBatchBodySchema,
+  mintRegistrationTokensBatchResponseSchema,
+  mintRegistrationTokensProvisionedRunnerSchema,
+  type PollDemandBodyDto,
+  type PollDemandResponseDto,
+  type PollDemandTemplateDto,
+  type ProvisionedRunnerReportEventDto,
+  type ProvisionedRunnerStateDto,
+  type ProvisionerIdentityResponseDto,
+  type ProvisionerTokenDto,
+  pollDemandBodySchema,
+  pollDemandResponseSchema,
+  pollDemandTemplateSchema,
+  providerKindSchema,
+  provisionedRunnerReportEventSchema,
+  provisionedRunnerStateSchema,
+  provisionerIdentityResponseSchema,
+  provisionerTokenDtoSchema,
+  REGISTRATION_TOKEN_BATCH_HARD_MAX,
+  type ReconcileDesiredIntentDto,
+  type ReconciledBoundJobDto,
+  type ReconciledProvisionedRunnerDto,
+  type ReconcileProvisionedRunnersBodyDto,
+  type ReconcileProvisionedRunnersResponseDto,
+  type RegisterRunnerBodyDto,
+  type RegisterRunnerResponseDto,
+  type ReportProvisionedRunnersBodyDto,
+  type ReportProvisionedRunnersResponseDto,
+  type ReservationGrantDto,
+  type RevokeManualRegistrationTokenResponseDto,
+  type RevokeProvisionerTokenResponseDto,
+  RUNNER_SESSION_EXHAUSTED_CODE,
+  type RunnerHarnessToolCapabilitiesDto,
+  type RunnerToolCapabilitiesDto,
+  reconcileDesiredIntentSchema,
+  reconciledBoundJobSchema,
+  reconciledProvisionedRunnerSchema,
+  reconcileProvisionedRunnersBodySchema,
+  reconcileProvisionedRunnersResponseSchema,
+  registerRunnerBodySchema,
+  registerRunnerResponseSchema,
+  reportProvisionedRunnersBodySchema,
+  reportProvisionedRunnersResponseSchema,
+  reservationGrantSchema,
+  revokeManualRegistrationTokenResponseSchema,
+  revokeProvisionerTokenResponseSchema,
+  runnerHarnessToolCapabilitiesSchema,
+  runnerToolCapabilitiesSchema,
+} from '#schemas/index.js';
+export {
+  RUNNER_JOB_CLAIMED,
+  RUNNER_JOB_LEASE_EXPIRED,
+  RUNNER_JOB_QUEUED,
+  type RunnerJobClaimedEvent,
+  type RunnerJobLeaseExpiredEvent,
+  type RunnerJobQueuedEvent,
+  type RunnersEventMap,
+  runnerJobClaimedEventSchema,
+  runnerJobLeaseExpiredEventSchema,
+  runnerJobQueuedEventSchema,
+  runnersEventSchemas,
+} from './events.js';

package/src/schemas/claim-job.test.ts

@@ -0,0 +1,53 @@
+import {claimedJobResponseSchema} from './claim-job.js';
+
+describe('claimedJobResponseSchema', () => {
+  it('parses a step-less claim response', () => {
+    const parsed = claimedJobResponseSchema.parse({
+      job_id: crypto.randomUUID(),
+      job_execution_id: crypto.randomUUID(),
+      workflow_run_id: crypto.randomUUID(),
+      workflow_run_attempt_id: crypto.randomUUID(),
+      lease_token: 'lease-abc',
+    });
+
+    expect(parsed.lease_token).toBe('lease-abc');
+  });
+
+  it('rejects a missing lease token', () => {
+    const parse = () =>
+      claimedJobResponseSchema.parse({
+        job_id: crypto.randomUUID(),
+        job_execution_id: crypto.randomUUID(),
+        workflow_run_id: crypto.randomUUID(),
+        workflow_run_attempt_id: crypto.randomUUID(),
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an empty lease token', () => {
+    const parse = () =>
+      claimedJobResponseSchema.parse({
+        job_id: crypto.randomUUID(),
+        job_execution_id: crypto.randomUUID(),
+        workflow_run_id: crypto.randomUUID(),
+        workflow_run_attempt_id: crypto.randomUUID(),
+        lease_token: '',
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a non-uuid job id', () => {
+    const parse = () =>
+      claimedJobResponseSchema.parse({
+        job_id: 'not-a-uuid',
+        job_execution_id: crypto.randomUUID(),
+        workflow_run_id: crypto.randomUUID(),
+        workflow_run_attempt_id: crypto.randomUUID(),
+        lease_token: 'lease-abc',
+      });
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/claim-job.ts

@@ -0,0 +1,13 @@
+import {z} from 'zod';
+
+export const RUNNER_SESSION_EXHAUSTED_CODE = 'runner-session-exhausted' as const;
+
+export const claimedJobResponseSchema = z.object({
+  workflow_run_id: z.string().uuid(),
+  workflow_run_attempt_id: z.string().uuid(),
+  job_id: z.string().uuid(),
+  job_execution_id: z.string().uuid(),
+  lease_token: z.string().min(1),
+});
+
+export type ClaimedJobResponseDto = z.infer<typeof claimedJobResponseSchema>;

package/src/schemas/heartbeat.ts

@@ -0,0 +1,16 @@
+import {z} from 'zod';
+import {runnerToolCapabilitiesSchema} from './tool-capabilities.js';
+
+export const heartbeatBodySchema = z
+  .object({
+    capabilities: runnerToolCapabilitiesSchema.optional(),
+  })
+  .strict();
+
+export const heartbeatResponseSchema = z.object({
+  cancel: z.boolean(),
+  lease_token: z.string().min(1),
+});
+
+export type HeartbeatBodyDto = z.infer<typeof heartbeatBodySchema>;
+export type HeartbeatResponseDto = z.infer<typeof heartbeatResponseSchema>;

package/src/schemas/index.ts

@@ -0,0 +1,115 @@
+export {
+  type ClaimedJobResponseDto,
+  claimedJobResponseSchema,
+  RUNNER_SESSION_EXHAUSTED_CODE,
+} from './claim-job.js';
+export {
+  type HeartbeatBodyDto,
+  type HeartbeatResponseDto,
+  heartbeatBodySchema,
+  heartbeatResponseSchema,
+} from './heartbeat.js';
+export {
+  type ActiveProvisionerDto,
+  activeProvisionerDtoSchema,
+  type ListActiveProvisionersResponseDto,
+  listActiveProvisionersResponseSchema,
+} from './list-active-provisioners.js';
+export {
+  type CreateManualRegistrationTokenBodyDto,
+  type CreateManualRegistrationTokenResponseDto,
+  createManualRegistrationTokenBodySchema,
+  createManualRegistrationTokenResponseSchema,
+  type ListManualRegistrationTokensResponseDto,
+  listManualRegistrationTokensResponseSchema,
+  MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS,
+  type ManualRegistrationTokenDto,
+  manualRegistrationTokenDtoSchema,
+  type RevokeManualRegistrationTokenResponseDto,
+  revokeManualRegistrationTokenResponseSchema,
+} from './manual-registration-token.js';
+export {
+  type MintedRegistrationTokenDto,
+  type MintRegistrationTokensBatchBodyDto,
+  type MintRegistrationTokensBatchResponseDto,
+  type MintRegistrationTokensProvisionedRunnerDto,
+  mintedRegistrationTokenSchema,
+  mintRegistrationTokensBatchBodySchema,
+  mintRegistrationTokensBatchResponseSchema,
+  mintRegistrationTokensProvisionedRunnerSchema,
+  REGISTRATION_TOKEN_BATCH_HARD_MAX,
+} from './mint-registration-tokens.js';
+export {
+  type DemandStatDto,
+  demandStatSchema,
+  type PollDemandBodyDto,
+  type PollDemandResponseDto,
+  type PollDemandTemplateDto,
+  pollDemandBodySchema,
+  pollDemandResponseSchema,
+  pollDemandTemplateSchema,
+  type ReservationGrantDto,
+  reservationGrantSchema,
+} from './poll-demand.js';
+export {
+  type CreateProvisionerTokenBodyDto,
+  type CreateProvisionerTokenResponseDto,
+  createProvisionerTokenBodySchema,
+  createProvisionerTokenResponseSchema,
+  type ListProvisionerTokensResponseDto,
+  listProvisionerTokensResponseSchema,
+  MAX_PROVISIONER_TOKEN_TTL_SECONDS,
+  type ProvisionerIdentityResponseDto,
+  type ProvisionerTokenDto,
+  provisionerIdentityResponseSchema,
+  provisionerTokenDtoSchema,
+  type RevokeProvisionerTokenResponseDto,
+  revokeProvisionerTokenResponseSchema,
+} from './provisioner-token.js';
+export {
+  MAX_OBSERVED_PROVISIONED_RUNNER_ID_LENGTH,
+  MAX_RECONCILE_OBSERVED_RUNNERS,
+  type ReconcileDesiredIntentDto,
+  type ReconciledBoundJobDto,
+  type ReconciledProvisionedRunnerDto,
+  type ReconcileProvisionedRunnersBodyDto,
+  type ReconcileProvisionedRunnersResponseDto,
+  reconcileDesiredIntentSchema,
+  reconciledBoundJobSchema,
+  reconciledProvisionedRunnerSchema,
+  reconcileProvisionedRunnersBodySchema,
+  reconcileProvisionedRunnersResponseSchema,
+} from './reconcile-provisioned-runners.js';
+export {
+  type RegisterRunnerBodyDto,
+  type RegisterRunnerResponseDto,
+  registerRunnerBodySchema,
+  registerRunnerResponseSchema,
+  runnerLabelSchema,
+} from './register.js';
+export {
+  type ActiveRunnerDto,
+  type ActiveRunnerStateDto,
+  type ActiveRunnersResponseDto,
+  activeRunnerDtoSchema,
+  activeRunnerStateSchema,
+  activeRunnersResponseSchema,
+  MAX_PROVIDER_KIND_LENGTH,
+  MAX_PROVISIONED_RUNNER_REASON_LENGTH,
+  MAX_PROVISIONED_RUNNER_REPORT_EVENTS,
+  type ProvisionedRunnerReportEventDto,
+  type ProvisionedRunnerStateDto,
+  providerKindSchema,
+  provisionedRunnerReportEventSchema,
+  provisionedRunnerStateSchema,
+  type ReportProvisionedRunnersBodyDto,
+  type ReportProvisionedRunnersResponseDto,
+  reportProvisionedRunnersBodySchema,
+  reportProvisionedRunnersResponseSchema,
+} from './report-provisioned-runners.js';
+export {
+  type RunnerHarnessToolCapabilitiesDto,
+  type RunnerToolCapabilitiesDto,
+  runnerHarnessToolCapabilitiesSchema,
+  runnerToolCapabilitiesSchema,
+} from './tool-capabilities.js';

package/src/schemas/list-active-provisioners.ts

@@ -0,0 +1,17 @@
+import {z} from 'zod';
+
+export const activeProvisionerDtoSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().nullable(),
+  prefix: z.string(),
+  last_seen_at: z.string(),
+});
+
+export const listActiveProvisionersResponseSchema = z.object({
+  provisioners: z.array(activeProvisionerDtoSchema),
+});
+
+export type ActiveProvisionerDto = z.infer<typeof activeProvisionerDtoSchema>;
+export type ListActiveProvisionersResponseDto = z.infer<
+  typeof listActiveProvisionersResponseSchema
+>;

package/src/schemas/manual-registration-token.test.ts

@@ -0,0 +1,36 @@
+import {
+  createManualRegistrationTokenBodySchema,
+  MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS,
+} from './manual-registration-token.js';
+
+describe('manual registration token schemas', () => {
+  it('accepts a valid create body', () => {
+    const result = createManualRegistrationTokenBodySchema.parse({
+      name: 'builder',
+      ttl_seconds: MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS,
+    });
+
+    expect(result).toEqual({
+      name: 'builder',
+      ttl_seconds: MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS,
+    });
+  });
+
+  it('accepts omitted TTL for never-expiring tokens', () => {
+    const result = createManualRegistrationTokenBodySchema.parse({
+      name: 'builder',
+    });
+
+    expect(result).toEqual({
+      name: 'builder',
+    });
+  });
+
+  it('rejects token TTLs above one year', () => {
+    const result = createManualRegistrationTokenBodySchema.safeParse({
+      ttl_seconds: MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS + 1,
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/manual-registration-token.ts

@@ -0,0 +1,58 @@
+import {z} from 'zod';
+
+export const MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS = 31_536_000;
+
+export const createManualRegistrationTokenBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  ttl_seconds: z
+    .number()
+    .int()
+    .positive()
+    .max(MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS)
+    .optional(),
+});
+
+export type CreateManualRegistrationTokenBodyDto = z.infer<
+  typeof createManualRegistrationTokenBodySchema
+>;
+
+export const createManualRegistrationTokenResponseSchema = z.object({
+  id: z.string().uuid(),
+  raw_token: z.string(),
+  prefix: z.string(),
+  name: z.string().nullable(),
+  workspace_id: z.string().uuid(),
+  expires_at: z.string().nullable(),
+  created_at: z.string(),
+});
+
+export type CreateManualRegistrationTokenResponseDto = z.infer<
+  typeof createManualRegistrationTokenResponseSchema
+>;
+
+export const manualRegistrationTokenDtoSchema = z.object({
+  id: z.string().uuid(),
+  workspace_id: z.string().uuid(),
+  prefix: z.string(),
+  name: z.string().nullable(),
+  expires_at: z.string().nullable(),
+  revoked_at: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type ManualRegistrationTokenDto = z.infer<typeof manualRegistrationTokenDtoSchema>;
+
+export const listManualRegistrationTokensResponseSchema = z.object({
+  manual_registration_tokens: z.array(manualRegistrationTokenDtoSchema),
+});
+
+export type ListManualRegistrationTokensResponseDto = z.infer<
+  typeof listManualRegistrationTokensResponseSchema
+>;
+
+export const revokeManualRegistrationTokenResponseSchema = manualRegistrationTokenDtoSchema;
+
+export type RevokeManualRegistrationTokenResponseDto = z.infer<
+  typeof revokeManualRegistrationTokenResponseSchema
+>;

package/src/schemas/mint-registration-tokens.test.ts

@@ -0,0 +1,28 @@
+import {
+  mintRegistrationTokensBatchBodySchema,
+  mintRegistrationTokensProvisionedRunnerSchema,
+} from './mint-registration-tokens.js';
+
+describe('mintRegistrationTokensProvisionedRunnerSchema', () => {
+  it('accepts provisioned runner ids up to the lifecycle report limit', () => {
+    const result = mintRegistrationTokensProvisionedRunnerSchema.safeParse({
+      provisioned_runner_id: 'a'.repeat(255),
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('mintRegistrationTokensBatchBodySchema', () => {
+  it('rejects duplicate provisioned runner ids', () => {
+    const result = mintRegistrationTokensBatchBodySchema.safeParse({
+      reservation_id: crypto.randomUUID(),
+      provisioned_runners: [
+        {provisioned_runner_id: 'provisioned-runner-1'},
+        {provisioned_runner_id: 'provisioned-runner-1'},
+      ],
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/mint-registration-tokens.ts

@@ -0,0 +1,46 @@
+import {z} from 'zod';
+
+export const REGISTRATION_TOKEN_BATCH_HARD_MAX = 1000;
+
+export const mintRegistrationTokensProvisionedRunnerSchema = z.object({
+  provisioned_runner_id: z.string().min(1).max(255),
+});
+
+export const mintRegistrationTokensBatchBodySchema = z
+  .object({
+    reservation_id: z.string().uuid(),
+    provisioned_runners: z
+      .array(mintRegistrationTokensProvisionedRunnerSchema)
+      .min(1)
+      .max(REGISTRATION_TOKEN_BATCH_HARD_MAX),
+  })
+  .refine(
+    (body) =>
+      new Set(
+        body.provisioned_runners.map(
+          (provisionedRunner) => provisionedRunner.provisioned_runner_id,
+        ),
+      ).size === body.provisioned_runners.length,
+    {message: 'provisioned_runner_id values must be unique', path: ['provisioned_runners']},
+  );
+
+export const mintedRegistrationTokenSchema = z.object({
+  provisioned_runner_id: z.string(),
+  registration_token: z.string(),
+  expires_at: z.string().datetime(),
+});
+
+export const mintRegistrationTokensBatchResponseSchema = z.object({
+  tokens: z.array(mintedRegistrationTokenSchema),
+});
+
+export type MintRegistrationTokensProvisionedRunnerDto = z.infer<
+  typeof mintRegistrationTokensProvisionedRunnerSchema
+>;
+export type MintRegistrationTokensBatchBodyDto = z.infer<
+  typeof mintRegistrationTokensBatchBodySchema
+>;
+export type MintedRegistrationTokenDto = z.infer<typeof mintedRegistrationTokenSchema>;
+export type MintRegistrationTokensBatchResponseDto = z.infer<
+  typeof mintRegistrationTokensBatchResponseSchema
+>;

package/src/schemas/poll-demand.test.ts

@@ -0,0 +1,27 @@
+import {pollDemandResponseSchema} from './poll-demand.js';
+
+describe('pollDemandResponseSchema', () => {
+  it('requires datetime response fields to be ISO datetimes', () => {
+    const result = pollDemandResponseSchema.safeParse({
+      stats: [
+        {
+          labels: ['linux'],
+          queued: 1,
+          reserved: 1,
+          oldest_queued_at: 'not-a-date',
+        },
+      ],
+      reservations: [
+        {
+          reservation_id: crypto.randomUUID(),
+          labels: ['linux'],
+          count: 1,
+          expires_at: 'not-a-date',
+        },
+      ],
+      terminate_provisioned_runner_ids: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/poll-demand.ts

@@ -0,0 +1,49 @@
+import {MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
+import {z} from 'zod';
+import {runnerLabelSchema} from './register.js';
+
+export const pollDemandTemplateSchema = z.object({
+  template_key: z.string().min(1),
+  labels: z.array(runnerLabelSchema).min(1).max(MAX_RUNNER_LABELS),
+  available_slots: z.number().int().min(0).max(100_000),
+  starting: z.number().int().min(0).max(100_000),
+  running: z.number().int().min(0).max(100_000),
+});
+
+export const pollDemandBodySchema = z.object({
+  wait_seconds: z.number().int().min(0).optional(),
+  max_reservations: z.number().int().min(0).max(1000),
+  templates: z.array(pollDemandTemplateSchema).min(1).max(100),
+});
+
+export const demandStatSchema = z.object({
+  labels: z.array(z.string()),
+  queued: z.number().int().min(0),
+  reserved: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      'Active reservations for this label set; advisory, may exceed `queued` during heavy claiming.',
+    ),
+  oldest_queued_at: z.string().datetime(),
+});
+
+export const reservationGrantSchema = z.object({
+  reservation_id: z.string().uuid(),
+  labels: z.array(z.string()),
+  count: z.number().int().positive(),
+  expires_at: z.string().datetime(),
+});
+
+export const pollDemandResponseSchema = z.object({
+  stats: z.array(demandStatSchema),
+  reservations: z.array(reservationGrantSchema),
+  terminate_provisioned_runner_ids: z.array(z.string()),
+});
+
+export type PollDemandTemplateDto = z.infer<typeof pollDemandTemplateSchema>;
+export type PollDemandBodyDto = z.infer<typeof pollDemandBodySchema>;
+export type DemandStatDto = z.infer<typeof demandStatSchema>;
+export type ReservationGrantDto = z.infer<typeof reservationGrantSchema>;
+export type PollDemandResponseDto = z.infer<typeof pollDemandResponseSchema>;