@shipfox/api-runners-dto 12.2.0 → 12.4.0

package/package.json

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

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,

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(),