@shipfox/api-runners-dto 2.0.0

package/src/schemas/provisioner-token.test.ts

@@ -0,0 +1,38 @@
+import {
+  createProvisionerTokenBodySchema,
+  MAX_PROVISIONER_TOKEN_TTL_SECONDS,
+  provisionerIdentityResponseSchema,
+} from './provisioner-token.js';
+
+describe('provisioner token schemas', () => {
+  it('accepts a valid create body', () => {
+    const result = createProvisionerTokenBodySchema.parse({
+      name: 'autoscaler',
+      ttl_seconds: MAX_PROVISIONER_TOKEN_TTL_SECONDS,
+    });
+
+    expect(result).toEqual({
+      name: 'autoscaler',
+      ttl_seconds: MAX_PROVISIONER_TOKEN_TTL_SECONDS,
+    });
+  });
+
+  it('rejects token TTLs above one year', () => {
+    const result = createProvisionerTokenBodySchema.safeParse({
+      ttl_seconds: MAX_PROVISIONER_TOKEN_TTL_SECONDS + 1,
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('parses provisioner identity responses', () => {
+    const identity = {
+      id: crypto.randomUUID(),
+      workspace_id: crypto.randomUUID(),
+    };
+
+    const result = provisionerIdentityResponseSchema.parse(identity);
+
+    expect(result).toEqual(identity);
+  });
+});

package/src/schemas/provisioner-token.ts

@@ -0,0 +1,64 @@
+import {z} from 'zod';
+
+export const MAX_PROVISIONER_TOKEN_TTL_SECONDS = 31_536_000;
+
+export const createProvisionerTokenBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  ttl_seconds: z.number().int().positive().max(MAX_PROVISIONER_TOKEN_TTL_SECONDS).optional(),
+});
+
+export type CreateProvisionerTokenBodyDto = z.infer<typeof createProvisionerTokenBodySchema>;
+
+export const createProvisionerTokenResponseSchema = z.object({
+  id: z.string().uuid(),
+  raw_token: z.string(),
+  prefix: z.string(),
+  name: z.string().nullable(),
+  workspace_id: z.string().uuid(),
+  created_by_user_id: z.string().uuid(),
+  revoked_by_user_id: z.string().uuid().nullable(),
+  expires_at: z.string().nullable(),
+  revoked_at: z.string().nullable(),
+  last_seen_at: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type CreateProvisionerTokenResponseDto = z.infer<
+  typeof createProvisionerTokenResponseSchema
+>;
+
+export const provisionerTokenDtoSchema = z.object({
+  id: z.string().uuid(),
+  workspace_id: z.string().uuid(),
+  prefix: z.string(),
+  name: z.string().nullable(),
+  created_by_user_id: z.string().uuid(),
+  revoked_by_user_id: z.string().uuid().nullable(),
+  expires_at: z.string().nullable(),
+  revoked_at: z.string().nullable(),
+  last_seen_at: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type ProvisionerTokenDto = z.infer<typeof provisionerTokenDtoSchema>;
+
+export const listProvisionerTokensResponseSchema = z.object({
+  tokens: z.array(provisionerTokenDtoSchema),
+});
+
+export type ListProvisionerTokensResponseDto = z.infer<typeof listProvisionerTokensResponseSchema>;
+
+export const revokeProvisionerTokenResponseSchema = provisionerTokenDtoSchema;
+
+export type RevokeProvisionerTokenResponseDto = z.infer<
+  typeof revokeProvisionerTokenResponseSchema
+>;
+
+export const provisionerIdentityResponseSchema = z.object({
+  id: z.string().uuid(),
+  workspace_id: z.string().uuid(),
+});
+
+export type ProvisionerIdentityResponseDto = z.infer<typeof provisionerIdentityResponseSchema>;

package/src/schemas/reconcile-provisioned-runners.test.ts

@@ -0,0 +1,85 @@
+import {
+  MAX_OBSERVED_PROVISIONED_RUNNER_ID_LENGTH,
+  MAX_RECONCILE_OBSERVED_RUNNERS,
+  reconcileProvisionedRunnersBodySchema,
+  reconcileProvisionedRunnersResponseSchema,
+} from './reconcile-provisioned-runners.js';
+
+describe('reconcileProvisionedRunnersBodySchema', () => {
+  it('accepts observed provisioned runner ids', () => {
+    const result = reconcileProvisionedRunnersBodySchema.safeParse({
+      observed_provisioned_runner_ids: ['01JPROVISIONEDRUNNER000001'],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts an empty observed set', () => {
+    const result = reconcileProvisionedRunnersBodySchema.safeParse({
+      observed_provisioned_runner_ids: [],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects observed sets above the reconcile limit', () => {
+    const result = reconcileProvisionedRunnersBodySchema.safeParse({
+      observed_provisioned_runner_ids: Array.from(
+        {length: MAX_RECONCILE_OBSERVED_RUNNERS + 1},
+        (_, index) => `runner-${index}`,
+      ),
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects over-length provisioned runner ids', () => {
+    const result = reconcileProvisionedRunnersBodySchema.safeParse({
+      observed_provisioned_runner_ids: ['a'.repeat(MAX_OBSERVED_PROVISIONED_RUNNER_ID_LENGTH + 1)],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects duplicate provisioned runner ids', () => {
+    const result = reconcileProvisionedRunnersBodySchema.safeParse({
+      observed_provisioned_runner_ids: ['provisioned-runner-1', 'provisioned-runner-1'],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects extra fields', () => {
+    const result = reconcileProvisionedRunnersBodySchema.safeParse({
+      observed_provisioned_runner_ids: [],
+      provisioner_hostname: 'worker-1',
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('reconcileProvisionedRunnersResponseSchema', () => {
+  it('parses reconciled provisioned runner responses', () => {
+    const result = reconcileProvisionedRunnersResponseSchema.safeParse({
+      runners: [
+        {
+          provisioned_runner_id: 'provisioned-runner-1',
+          state: 'running',
+          reservation_id: crypto.randomUUID(),
+          runner_session_id: crypto.randomUUID(),
+          bound_job: {
+            job_id: crypto.randomUUID(),
+            workflow_run_attempt_id: crypto.randomUUID(),
+            last_heartbeat_at: new Date().toISOString(),
+            cancellation_requested_at: null,
+          },
+          desired_intent: 'keep',
+        },
+      ],
+      terminated_absent_provisioned_runner_ids: ['provisioned-runner-2'],
+    });
+
+    expect(result.success).toBe(true);
+  });
+});

package/src/schemas/reconcile-provisioned-runners.ts

@@ -0,0 +1,61 @@
+import {z} from 'zod';
+import {provisionedRunnerStateSchema} from './report-provisioned-runners.js';
+
+export const MAX_RECONCILE_OBSERVED_RUNNERS = 5000;
+export const MAX_OBSERVED_PROVISIONED_RUNNER_ID_LENGTH = 255;
+
+export const reconcileProvisionedRunnersBodySchema = z
+  .object({
+    observed_provisioned_runner_ids: z
+      .array(z.string().min(1).max(MAX_OBSERVED_PROVISIONED_RUNNER_ID_LENGTH))
+      .max(MAX_RECONCILE_OBSERVED_RUNNERS),
+  })
+  .strict()
+  .refine(
+    (body) =>
+      new Set(body.observed_provisioned_runner_ids).size ===
+      body.observed_provisioned_runner_ids.length,
+    {
+      message: 'observed_provisioned_runner_ids values must be unique',
+      path: ['observed_provisioned_runner_ids'],
+    },
+  );
+
+export const reconcileDesiredIntentSchema = z.enum(['keep', 'terminate']);
+
+export const reconciledBoundJobSchema = z
+  .object({
+    job_id: z.string().uuid(),
+    workflow_run_attempt_id: z.string().uuid(),
+    last_heartbeat_at: z.string().datetime(),
+    cancellation_requested_at: z.string().datetime().nullable(),
+  })
+  .strict();
+
+export const reconciledProvisionedRunnerSchema = z
+  .object({
+    provisioned_runner_id: z.string(),
+    state: provisionedRunnerStateSchema.nullable(),
+    reservation_id: z.string().uuid().nullable(),
+    runner_session_id: z.string().uuid().nullable(),
+    bound_job: reconciledBoundJobSchema.nullable(),
+    desired_intent: reconcileDesiredIntentSchema,
+  })
+  .strict();
+
+export const reconcileProvisionedRunnersResponseSchema = z
+  .object({
+    runners: z.array(reconciledProvisionedRunnerSchema),
+    terminated_absent_provisioned_runner_ids: z.array(z.string()),
+  })
+  .strict();
+
+export type ReconcileProvisionedRunnersBodyDto = z.infer<
+  typeof reconcileProvisionedRunnersBodySchema
+>;
+export type ReconcileDesiredIntentDto = z.infer<typeof reconcileDesiredIntentSchema>;
+export type ReconciledBoundJobDto = z.infer<typeof reconciledBoundJobSchema>;
+export type ReconciledProvisionedRunnerDto = z.infer<typeof reconciledProvisionedRunnerSchema>;
+export type ReconcileProvisionedRunnersResponseDto = z.infer<
+  typeof reconcileProvisionedRunnersResponseSchema
+>;

package/src/schemas/register.ts

@@ -0,0 +1,28 @@
+import {
+  MAX_RUNNER_LABEL_LENGTH,
+  MAX_RUNNER_LABELS,
+  RUNNER_LABEL_PATTERN,
+} from '@shipfox/runner-labels';
+import {z} from 'zod';
+import {runnerToolCapabilitiesSchema} from './tool-capabilities.js';
+
+export const runnerLabelSchema = z
+  .string()
+  .min(1)
+  .max(MAX_RUNNER_LABEL_LENGTH)
+  .regex(new RegExp(RUNNER_LABEL_PATTERN.source, 'i'));
+
+export const registerRunnerBodySchema = z.object({
+  labels: z.array(runnerLabelSchema).min(1).max(MAX_RUNNER_LABELS),
+  capabilities: runnerToolCapabilitiesSchema.optional(),
+});
+
+export const registerRunnerResponseSchema = z.object({
+  session_token: z.string().min(1),
+  session_id: z.string().uuid(),
+  mode: z.enum(['manual', 'ephemeral']),
+  max_claims: z.number().int().positive().nullable(),
+});
+
+export type RegisterRunnerBodyDto = z.infer<typeof registerRunnerBodySchema>;
+export type RegisterRunnerResponseDto = z.infer<typeof registerRunnerResponseSchema>;

package/src/schemas/report-provisioned-runners.test.ts

@@ -0,0 +1,61 @@
+import {
+  MAX_PROVISIONED_RUNNER_REPORT_EVENTS,
+  provisionedRunnerReportEventSchema,
+  reportProvisionedRunnersBodySchema,
+} from './report-provisioned-runners.js';
+
+describe('provisionedRunnerReportEventSchema', () => {
+  it('accepts minimal provider-agnostic lifecycle events', () => {
+    const result = provisionedRunnerReportEventSchema.safeParse({
+      provisioned_runner_id: 'container-1',
+      labels: ['linux'],
+      state: 'starting',
+      reported_at: new Date().toISOString(),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts cleanup-confirmed terminated lifecycle events', () => {
+    const result = provisionedRunnerReportEventSchema.safeParse({
+      provisioned_runner_id: 'container-1',
+      labels: ['linux'],
+      state: 'terminated',
+      reported_at: new Date().toISOString(),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects provider-sensitive extra fields', () => {
+    const result = provisionedRunnerReportEventSchema.safeParse({
+      provisioned_runner_id: 'container-1',
+      labels: ['linux'],
+      state: 'running',
+      reported_at: new Date().toISOString(),
+      ip_address: '192.0.2.1',
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('reportProvisionedRunnersBodySchema', () => {
+  it('enforces the batch size limit', () => {
+    const event = {
+      provisioned_runner_id: 'container-1',
+      labels: ['linux'],
+      state: 'running',
+      reported_at: new Date().toISOString(),
+    };
+
+    const result = reportProvisionedRunnersBodySchema.safeParse({
+      events: Array.from({length: MAX_PROVISIONED_RUNNER_REPORT_EVENTS + 1}, (_, index) => ({
+        ...event,
+        provisioned_runner_id: `container-${index}`,
+      })),
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/report-provisioned-runners.ts

@@ -0,0 +1,75 @@
+import {MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
+import {z} from 'zod';
+import {runnerLabelSchema} from './register.js';
+
+export const MAX_PROVISIONED_RUNNER_REPORT_EVENTS = 1000;
+export const MAX_PROVISIONED_RUNNER_REASON_LENGTH = 500;
+export const MAX_PROVIDER_KIND_LENGTH = 64;
+
+export const provisionedRunnerStateSchema = z.enum([
+  'starting',
+  'running',
+  'stopping',
+  'stopped',
+  'failed',
+  'terminated',
+]);
+
+export const providerKindSchema = z.string().min(1).max(MAX_PROVIDER_KIND_LENGTH);
+
+export const provisionedRunnerReportEventSchema = z
+  .object({
+    provisioned_runner_id: z.string().min(1).max(255),
+    reservation_id: z.string().uuid().optional(),
+    template_key: z.string().min(1).max(255).optional(),
+    labels: z.array(runnerLabelSchema).min(1).max(MAX_RUNNER_LABELS),
+    state: provisionedRunnerStateSchema,
+    reason: z.string().min(1).max(MAX_PROVISIONED_RUNNER_REASON_LENGTH).optional(),
+    runner_session_id: z.string().uuid().optional(),
+    reported_at: z.string().datetime(),
+    provider_kind: providerKindSchema.optional(),
+  })
+  .strict();
+
+export const reportProvisionedRunnersBodySchema = z.object({
+  events: z
+    .array(provisionedRunnerReportEventSchema)
+    .min(1)
+    .max(MAX_PROVISIONED_RUNNER_REPORT_EVENTS),
+});
+
+export const reportProvisionedRunnersResponseSchema = z.object({
+  accepted: z.number().int().min(0),
+  reservations_released: z.number().int().min(0),
+});
+
+export const activeRunnerStateSchema = z.enum(['starting', 'running', 'stopping', 'busy']);
+
+export const activeRunnerDtoSchema = z.object({
+  runner_session_id: z.string().uuid().nullable(),
+  provisioned_runner_id: z.string().nullable(),
+  provisioner_id: z.string().uuid().nullable(),
+  state: activeRunnerStateSchema,
+  labels: z.array(z.string()),
+  template_key: z.string().nullable(),
+  provider_kind: z.string().nullable(),
+  job_id: z.string().uuid().nullable(),
+  workflow_run_attempt_id: z.string().uuid().nullable(),
+  project_id: z.string().uuid().nullable(),
+  reported_at: z.string().nullable(),
+  last_heartbeat_at: z.string().nullable(),
+});
+
+export const activeRunnersResponseSchema = z.object({
+  runners: z.array(activeRunnerDtoSchema),
+});
+
+export type ProvisionedRunnerStateDto = z.infer<typeof provisionedRunnerStateSchema>;
+export type ProvisionedRunnerReportEventDto = z.infer<typeof provisionedRunnerReportEventSchema>;
+export type ReportProvisionedRunnersBodyDto = z.infer<typeof reportProvisionedRunnersBodySchema>;
+export type ReportProvisionedRunnersResponseDto = z.infer<
+  typeof reportProvisionedRunnersResponseSchema
+>;
+export type ActiveRunnerStateDto = z.infer<typeof activeRunnerStateSchema>;
+export type ActiveRunnerDto = z.infer<typeof activeRunnerDtoSchema>;
+export type ActiveRunnersResponseDto = z.infer<typeof activeRunnersResponseSchema>;

package/src/schemas/tool-capabilities.test.ts

@@ -0,0 +1,64 @@
+import {runnerToolCapabilitiesSchema} from './tool-capabilities.js';
+
+describe('runnerToolCapabilitiesSchema', () => {
+  it('accepts a full capability report', () => {
+    const result = runnerToolCapabilitiesSchema.safeParse({
+      harnesses: {
+        pi: {tools: ['read', 'bash', 'web_search']},
+        claude: {tools: ['Read', 'Bash', 'WebSearch']},
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a partial capability report', () => {
+    const result = runnerToolCapabilitiesSchema.safeParse({
+      harnesses: {
+        pi: {tools: ['read']},
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts no harness support', () => {
+    const result = runnerToolCapabilitiesSchema.safeParse({harnesses: {}});
+
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts an empty tool array', () => {
+    const result = runnerToolCapabilitiesSchema.safeParse({
+      harnesses: {
+        claude: {tools: []},
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects duplicate tool names per harness', () => {
+    const result = runnerToolCapabilitiesSchema.safeParse({
+      harnesses: {
+        pi: {tools: ['read', 'read']},
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it.each([
+    null,
+    {},
+    {harnesses: {}, extra: true},
+    {harnesses: {pi: {tools: ['read']}, unknown: {tools: ['x']}}},
+    {harnesses: {pi: {tools: ['read'], extra: true}}},
+    {harnesses: {pi: {tools: ['']}}},
+    {harnesses: {pi: {tools: [42]}}},
+  ])('rejects malformed capability report %#', (value) => {
+    const result = runnerToolCapabilitiesSchema.safeParse(value);
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/tool-capabilities.ts

@@ -0,0 +1,35 @@
+import {z} from 'zod';
+
+export const runnerHarnessToolCapabilitiesSchema = z
+  .object({
+    tools: z.array(z.string().min(1)).superRefine((tools, ctx) => {
+      const seen = new Set<string>();
+      for (const [index, tool] of tools.entries()) {
+        if (!seen.has(tool)) {
+          seen.add(tool);
+          continue;
+        }
+
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Duplicate tool name',
+          path: [index],
+        });
+      }
+    }),
+  })
+  .strict();
+
+export const runnerToolCapabilitiesSchema = z
+  .object({
+    harnesses: z
+      .object({
+        pi: runnerHarnessToolCapabilitiesSchema.optional(),
+        claude: runnerHarnessToolCapabilitiesSchema.optional(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export type RunnerHarnessToolCapabilitiesDto = z.infer<typeof runnerHarnessToolCapabilitiesSchema>;
+export type RunnerToolCapabilitiesDto = z.infer<typeof runnerToolCapabilitiesSchema>;

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/node",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}