@shipfox/api-runners-dto 12.2.0 → 13.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners-dto",
   "license": "MIT",
-  "version": "12.2.0",
+  "version": "13.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/events.ts

@@ -4,7 +4,6 @@ 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({
@@ -15,15 +14,6 @@ export const runnerJobLeaseExpiredEventSchema = z.object({
 });
 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,
@@ -35,12 +25,10 @@ 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

@@ -76,6 +76,9 @@ export {
   providerRunnerStateSchema,
   provisionerIdentityResponseSchema,
   provisionerTokenDtoSchema,
+  RECONCILE_RUNNER_INSTANCES_INTENDED_RESERVATION_HEADER,
+  RECONCILE_RUNNER_INSTANCES_INTENDED_RESERVATION_HEADER_VALUE,
+  RESERVATION_EXPIRED_ERROR_CODE,
   type ReconcileDesiredIntentDto,
   type ReconciledBoundJobDto,
   type ReconciledRunnerInstanceDto,
@@ -91,6 +94,7 @@ export {
   type RevokeManualRegistrationTokenResponseDto,
   type RevokeProvisionerTokenResponseDto,
   RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS,
+  RUNNER_INSTANCE_NOT_ASSIGNABLE_ERROR_CODE,
   RUNNER_SESSION_EXHAUSTED_CODE,
   type RunnerAdministratorInstanceDto,
   type RunnerAssignmentPollQueryDto,
@@ -134,13 +138,10 @@ export {
 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/inter-module.test.ts

@@ -1,22 +1,6 @@
 import {runnersInterModuleContract} from './inter-module.js';
 
-const id = '00000000-0000-4000-8000-000000000001';
-
 describe('runnersInterModuleContract', () => {
-  test('accepts stable job-execution identities for idempotent commands', () => {
-    const input = runnersInterModuleContract.methods.enqueueJobExecution.input.parse({
-      workspaceId: id,
-      workflowRunId: id,
-      workflowRunAttemptId: id,
-      jobId: id,
-      jobExecutionId: id,
-      projectId: id,
-      requiredLabels: ['linux'],
-    });
-
-    expect(input.jobExecutionId).toBe(id);
-  });
-
   test('exposes bounded JSON capability results', () => {
     const result =
       runnersInterModuleContract.methods.getEffectiveRunnerToolCapabilities.output.parse({
@@ -29,12 +13,4 @@ describe('runnersInterModuleContract', () => {
       reportFresh: true,
     });
   });
-
-  test('defines the scheduling validation failure', () => {
-    const details = runnersInterModuleContract.methods.enqueueJobExecution.errors[
-      'empty-required-labels'
-    ].parse({});
-
-    expect(details).toEqual({});
-  });
 });

package/src/inter-module.ts

@@ -7,29 +7,6 @@ const idSchema = z.string().uuid();
 export const runnersInterModuleContract = defineInterModuleContract({
   module: 'runners',
   methods: {
-    enqueueJobExecution: {
-      input: z.object({
-        workspaceId: idSchema,
-        workflowRunId: idSchema,
-        workflowRunAttemptId: idSchema,
-        jobId: idSchema,
-        jobExecutionId: idSchema,
-        projectId: idSchema,
-        requiredLabels: z.array(z.string()),
-      }),
-      output: z.object({}),
-      errors: {
-        'empty-required-labels': z.object({}),
-      },
-    },
-    releaseJobExecution: {
-      input: z.object({jobExecutionId: idSchema}),
-      output: z.object({}),
-    },
-    cancelJobs: {
-      input: z.object({jobIds: z.array(idSchema)}),
-      output: z.object({}),
-    },
     getLeaseState: {
       input: z.object({
         jobId: idSchema,

package/src/schemas/assign-runner-instances.ts

@@ -1,5 +1,8 @@
 import {z} from 'zod';
 
+export const RESERVATION_EXPIRED_ERROR_CODE = 'reservation-expired';
+export const RUNNER_INSTANCE_NOT_ASSIGNABLE_ERROR_CODE = 'runner-instance-not-assignable';
+
 export const assignRunnerInstancesBodySchema = z
   .object({
     reservation_id: z.string().uuid(),

package/src/schemas/index.ts

@@ -33,6 +33,8 @@ export {
   type AssignRunnerInstancesResponseDto,
   assignRunnerInstancesBodySchema,
   assignRunnerInstancesResponseSchema,
+  RESERVATION_EXPIRED_ERROR_CODE,
+  RUNNER_INSTANCE_NOT_ASSIGNABLE_ERROR_CODE,
 } from './assign-runner-instances.js';
 export {
   type ClaimedJobResponseDto,
@@ -94,6 +96,8 @@ export {
 export {
   MAX_OBSERVED_PROVIDER_RUNNER_ID_LENGTH,
   MAX_RECONCILE_OBSERVED_RUNNERS,
+  RECONCILE_RUNNER_INSTANCES_INTENDED_RESERVATION_HEADER,
+  RECONCILE_RUNNER_INSTANCES_INTENDED_RESERVATION_HEADER_VALUE,
   type ReconcileDesiredIntentDto,
   type ReconciledBoundJobDto,
   type ReconciledRunnerInstanceDto,

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

@@ -67,6 +67,7 @@ describe('pollDemandResponseSchema', () => {
           expires_at: 'not-a-date',
         },
       ],
+      newly_reserved_count: 1,
       terminate_provider_runner_ids: [],
     });
 

package/src/schemas/poll-demand.ts

@@ -42,6 +42,14 @@ export const reservationGrantSchema = z.object({
 export const pollDemandResponseSchema = z.object({
   stats: z.array(demandStatSchema),
   reservations: z.array(reservationGrantSchema),
+  newly_reserved_count: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      'Reservation units created by this poll, including units satisfied by adopted runners.',
+    ),
   terminate_provider_runner_ids: z.array(z.string()),
 });
 

package/src/schemas/reconcile-runner-instances.test.ts

@@ -60,12 +60,33 @@ describe('reconcileRunnerInstancesBodySchema', () => {
 });
 
 describe('reconcileRunnerInstancesResponseSchema', () => {
-  it('parses reconciled provisioned runner responses', () => {
-    const result = reconcileRunnerInstancesResponseSchema.safeParse({
+  it('keeps the optional field absent for responses from older servers', () => {
+    const result = reconcileRunnerInstancesResponseSchema.parse({
       runners: [
         {
           provider_runner_id: 'provisioned-runner-1',
           state: 'running',
+          reservation_id: null,
+          runner_session_id: null,
+          bound_job: null,
+          desired_intent: 'keep',
+        },
+      ],
+      terminated_absent_provider_runner_ids: [],
+    });
+
+    const runner = result.runners[0];
+    if (!runner) throw new Error('Expected one parsed runner');
+    expect(Object.hasOwn(runner, 'intended_reservation_id')).toBe(false);
+  });
+
+  it('keeps an explicit null field present for current responses', () => {
+    const result = reconcileRunnerInstancesResponseSchema.parse({
+      runners: [
+        {
+          provider_runner_id: 'provisioned-runner-1',
+          state: 'running',
+          intended_reservation_id: null,
           reservation_id: crypto.randomUUID(),
           runner_session_id: crypto.randomUUID(),
           bound_job: {
@@ -80,6 +101,9 @@ describe('reconcileRunnerInstancesResponseSchema', () => {
       terminated_absent_provider_runner_ids: ['provisioned-runner-2'],
     });
 
-    expect(result.success).toBe(true);
+    const runner = result.runners[0];
+    if (!runner) throw new Error('Expected one parsed runner');
+    expect(Object.hasOwn(runner, 'intended_reservation_id')).toBe(true);
+    expect(runner.intended_reservation_id).toBeNull();
   });
 });

package/src/schemas/reconcile-runner-instances.ts

@@ -3,6 +3,9 @@ import {providerRunnerStateSchema} from './report-runner-instances.js';
 
 export const MAX_RECONCILE_OBSERVED_RUNNERS = 5000;
 export const MAX_OBSERVED_PROVIDER_RUNNER_ID_LENGTH = 255;
+export const RECONCILE_RUNNER_INSTANCES_INTENDED_RESERVATION_HEADER =
+  'x-shipfox-reconcile-intended-reservation';
+export const RECONCILE_RUNNER_INSTANCES_INTENDED_RESERVATION_HEADER_VALUE = '1';
 
 export const reconcileRunnerInstancesBodySchema = z
   .object({
@@ -35,6 +38,7 @@ export const reconciledRunnerInstanceSchema = z
   .object({
     provider_runner_id: z.string(),
     state: providerRunnerStateSchema.nullable(),
+    intended_reservation_id: z.string().uuid().nullable().optional(),
     reservation_id: z.string().uuid().nullable(),
     runner_session_id: z.string().uuid().nullable(),
     bound_job: reconciledBoundJobSchema.nullable(),

package/src/schemas/runner-enrollment.ts

@@ -24,8 +24,16 @@ export const createRunnerInstancesBodySchema = z
   .strict();
 export const createRunnerInstancesResponseSchema = z.object({
   runner_instances: z.array(
-    z.object({runner_instance_id: z.string().uuid(), bootstrap_token: z.string().min(1)}),
+    z.object({
+      runner_instance_id: z.string().uuid(),
+      bootstrap_token: z.string().min(1),
+      // Accepted instances retain their request position for short responses.
+      request_index: z.number().int().nonnegative().optional(),
+    }),
   ),
+  // A demand reservation can be consumed or stale between demand polling and launch.
+  // The field is omitted for the normal and warm-launch paths.
+  reservation_unavailable: z.literal(true).optional(),
 });
 export const runnerBootstrapExchangeResponseSchema = z.object({
   runner_instance_id: z.string().uuid(),