@shipfox/api-runners 2.0.0

package/src/core/runner-sessions.test.ts

@@ -0,0 +1,209 @@
+import {verifyRunnerSessionToken} from '@shipfox/api-auth';
+import {and, eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {ephemeralRegistrationTokens} from '#db/schema/ephemeral-registration-tokens.js';
+import {provisionedRunners} from '#db/schema/provisioned-runners.js';
+import {runnerSessions} from '#db/schema/runner-sessions.js';
+import {
+  ephemeralRegistrationTokenFactory,
+  manualRegistrationTokenFactory,
+  provisionedRunnerFactory,
+} from '#test/index.js';
+import {
+  EmptyRunnerLabelsError,
+  RegistrationTokenConsumedError,
+  RegistrationTokenWorkspaceMismatchError,
+} from './errors.js';
+import {registerRunnerSession} from './runner-sessions.js';
+
+describe('registerRunnerSession', () => {
+  let workspaceId: string;
+  let registrationTokenId: string;
+
+  beforeEach(async () => {
+    workspaceId = crypto.randomUUID();
+    const token = await manualRegistrationTokenFactory.create({workspaceId});
+    registrationTokenId = token.id;
+  });
+
+  it('canonicalizes labels, stores them, and embeds them in the session token', async () => {
+    const result = await registerRunnerSession({
+      credential: {kind: 'manual', registrationTokenId, workspaceId},
+      labels: [' Linux ', 'x64', 'linux'],
+    });
+
+    expect(result.mode).toBe('manual');
+    expect(result.maxClaims).toBeNull();
+    expect(result.session.labels).toEqual(['linux', 'x64']);
+    expect(result.session.registrationTokenKind).toBe('manual');
+    expect(result.session.provisionerId).toBeNull();
+    expect(result.session.provisionedRunnerId).toBeNull();
+    expect(result.session.maxClaims).toBeNull();
+    expect(result.session.claimsUsed).toBe(0);
+
+    const rows = await db()
+      .select()
+      .from(runnerSessions)
+      .where(eq(runnerSessions.id, result.session.id));
+    expect(rows[0]?.labels).toEqual(['linux', 'x64']);
+
+    const claims = await verifyRunnerSessionToken(result.sessionToken);
+    expect(claims?.labels).toEqual(['linux', 'x64']);
+    expect(claims?.maxClaims).toBeNull();
+  });
+
+  it('throws EmptyRunnerLabelsError when labels canonicalize to empty', async () => {
+    await expect(
+      registerRunnerSession({
+        credential: {kind: 'manual', registrationTokenId, workspaceId},
+        labels: [' ', '\t'],
+      }),
+    ).rejects.toBeInstanceOf(EmptyRunnerLabelsError);
+  });
+
+  it('consumes an ephemeral token and creates a one-claim session', async () => {
+    const token = await ephemeralRegistrationTokenFactory.create({workspaceId});
+
+    const result = await registerRunnerSession({
+      credential: {
+        kind: 'ephemeral',
+        ephemeralTokenId: token.id,
+        workspaceId,
+        provisionerId: token.provisionerId,
+        reservationId: token.reservationId,
+        provisionedRunnerId: token.provisionedRunnerId,
+      },
+      labels: [' Linux ', 'x64'],
+    });
+
+    expect(result.mode).toBe('ephemeral');
+    expect(result.maxClaims).toBe(1);
+    expect(result.session.registrationTokenKind).toBe('ephemeral');
+    expect(result.session.provisionerId).toBe(token.provisionerId);
+    expect(result.session.provisionedRunnerId).toBe(token.provisionedRunnerId);
+    expect(result.session.maxClaims).toBe(1);
+    expect(result.session.claimsUsed).toBe(0);
+
+    const [consumed] = await db()
+      .select()
+      .from(ephemeralRegistrationTokens)
+      .where(eq(ephemeralRegistrationTokens.id, token.id));
+    expect(consumed?.consumedAt).toBeInstanceOf(Date);
+    expect(consumed?.consumedSessionId).toBe(result.session.id);
+
+    const [session] = await db()
+      .select()
+      .from(runnerSessions)
+      .where(eq(runnerSessions.id, result.session.id));
+    expect(session?.provisionerId).toBe(token.provisionerId);
+    expect(session?.provisionedRunnerId).toBe(token.provisionedRunnerId);
+
+    const claims = await verifyRunnerSessionToken(result.sessionToken);
+    expect(claims?.maxClaims).toBe(1);
+  });
+
+  it('links an existing provisioned runner row when consuming an ephemeral token', async () => {
+    const token = await ephemeralRegistrationTokenFactory.create({workspaceId});
+    await provisionedRunnerFactory.create({
+      workspaceId,
+      provisionerId: token.provisionerId,
+      provisionedRunnerId: token.provisionedRunnerId,
+      runnerSessionId: null,
+      state: 'starting',
+    });
+
+    const result = await registerRunnerSession({
+      credential: {
+        kind: 'ephemeral',
+        ephemeralTokenId: token.id,
+        workspaceId,
+        provisionerId: token.provisionerId,
+        reservationId: token.reservationId,
+        provisionedRunnerId: token.provisionedRunnerId,
+      },
+      labels: ['linux'],
+    });
+
+    const [provisionedRunner] = await db()
+      .select()
+      .from(provisionedRunners)
+      .where(
+        and(
+          eq(provisionedRunners.workspaceId, workspaceId),
+          eq(provisionedRunners.provisionerId, token.provisionerId),
+          eq(provisionedRunners.provisionedRunnerId, token.provisionedRunnerId),
+        ),
+      );
+    expect(provisionedRunner?.runnerSessionId).toBe(result.session.id);
+  });
+
+  it('rejects a second consume of the same ephemeral token', async () => {
+    const token = await ephemeralRegistrationTokenFactory.create({workspaceId});
+    const credential = {
+      kind: 'ephemeral' as const,
+      ephemeralTokenId: token.id,
+      workspaceId,
+      provisionerId: token.provisionerId,
+      reservationId: token.reservationId,
+      provisionedRunnerId: token.provisionedRunnerId,
+    };
+
+    await registerRunnerSession({credential, labels: ['linux']});
+
+    await expect(registerRunnerSession({credential, labels: ['linux']})).rejects.toBeInstanceOf(
+      RegistrationTokenConsumedError,
+    );
+  });
+
+  it('rejects consuming an ephemeral token for a different workspace', async () => {
+    const token = await ephemeralRegistrationTokenFactory.create({workspaceId});
+
+    await expect(
+      registerRunnerSession({
+        credential: {
+          kind: 'ephemeral',
+          ephemeralTokenId: token.id,
+          workspaceId: crypto.randomUUID(),
+          provisionerId: token.provisionerId,
+          reservationId: token.reservationId,
+          provisionedRunnerId: token.provisionedRunnerId,
+        },
+        labels: ['linux'],
+      }),
+    ).rejects.toBeInstanceOf(RegistrationTokenWorkspaceMismatchError);
+  });
+
+  it('rejects an ephemeral session row without a positive max claim cap', async () => {
+    await expect(
+      db()
+        .insert(runnerSessions)
+        .values({
+          workspaceId,
+          scope: 'workspace',
+          registrationTokenId: crypto.randomUUID(),
+          registrationTokenKind: 'ephemeral',
+          provisionerId: crypto.randomUUID(),
+          provisionedRunnerId: `provisioned-runner-${crypto.randomUUID()}`,
+          labels: ['linux'],
+          maxClaims: null,
+          claimsUsed: 0,
+        }),
+    ).rejects.toThrow();
+  });
+
+  it('rejects an ephemeral session row without a provisioned-runner link', async () => {
+    await expect(
+      db()
+        .insert(runnerSessions)
+        .values({
+          workspaceId,
+          scope: 'workspace',
+          registrationTokenId: crypto.randomUUID(),
+          registrationTokenKind: 'ephemeral',
+          labels: ['linux'],
+          maxClaims: 1,
+          claimsUsed: 0,
+        }),
+    ).rejects.toThrow();
+  });
+});

package/src/core/runner-sessions.ts

@@ -0,0 +1,66 @@
+import {issueRunnerSessionToken} from '@shipfox/api-auth';
+import type {RunnerToolCapabilitiesDto} from '@shipfox/api-runners-dto';
+import {canonicalizeLabels} from '@shipfox/runner-labels';
+import {createRunnerSessionConsumingEphemeralToken} from '#db/ephemeral-registration-tokens.js';
+import {createRunnerSession} from '#db/runner-sessions.js';
+import type {RunnerSession} from './entities/runner-session.js';
+import {EmptyRunnerLabelsError} from './errors.js';
+
+export interface RegisterRunnerSessionResult {
+  session: RunnerSession;
+  sessionToken: string;
+  mode: 'manual' | 'ephemeral';
+  maxClaims: number | null;
+}
+
+export type RunnerRegistrationCredential =
+  | {
+      kind: 'manual';
+      registrationTokenId: string;
+      workspaceId: string;
+    }
+  | {
+      kind: 'ephemeral';
+      ephemeralTokenId: string;
+      workspaceId: string;
+      provisionerId: string;
+      reservationId: string | null;
+      provisionedRunnerId: string;
+    };
+
+export async function registerRunnerSession(params: {
+  credential: RunnerRegistrationCredential;
+  labels: string[];
+  toolCapabilities?: RunnerToolCapabilitiesDto | null;
+}): Promise<RegisterRunnerSessionResult> {
+  const labels = [...canonicalizeLabels(params.labels)];
+  if (labels.length === 0) throw new EmptyRunnerLabelsError();
+
+  const mode = params.credential.kind;
+  const maxClaims = params.credential.kind === 'ephemeral' ? 1 : null;
+  const session =
+    params.credential.kind === 'manual'
+      ? await createRunnerSession({
+          workspaceId: params.credential.workspaceId,
+          scope: 'workspace',
+          registrationTokenId: params.credential.registrationTokenId,
+          labels,
+          toolCapabilities: params.toolCapabilities ?? null,
+        })
+      : await createRunnerSessionConsumingEphemeralToken({
+          ephemeralTokenId: params.credential.ephemeralTokenId,
+          workspaceId: params.credential.workspaceId,
+          labels,
+          toolCapabilities: params.toolCapabilities ?? null,
+          maxClaims: 1,
+        });
+  const sessionToken = await issueRunnerSessionToken({
+    runnerSessionId: session.id,
+    workspaceId: session.workspaceId,
+    scope: session.scope,
+    labels: session.labels,
+    maxClaims,
+  });
+
+  return {session, sessionToken, mode, maxClaims};
+}

package/src/core/runner-tool-capabilities.test.ts

@@ -0,0 +1,141 @@
+import type {RunnerToolCapabilitiesDto} from '@shipfox/api-runners-dto';
+import {eq, sql} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {runnerSessions} from '#db/schema/runner-sessions.js';
+import {runnerSessionFactory} from '#test/index.js';
+import {
+  effectiveRunnerToolCapabilities,
+  getEffectiveRunnerToolCapabilities,
+  unadvertisedRunnerTools,
+} from './runner-tool-capabilities.js';
+
+const capabilities: RunnerToolCapabilitiesDto = {
+  harnesses: {
+    pi: {tools: ['read', 'bash']},
+  },
+};
+
+describe('effectiveRunnerToolCapabilities', () => {
+  it('returns an empty set when the report is missing', () => {
+    const effective = effectiveRunnerToolCapabilities({
+      toolCapabilities: null,
+      reportedAt: new Date('2026-01-01T00:00:00.000Z'),
+      staleAfterSeconds: 10,
+      now: new Date('2026-01-01T00:00:01.000Z'),
+    });
+
+    expect(effective).toEqual({harnesses: {}});
+  });
+
+  it('returns an empty set when the report timestamp is missing', () => {
+    const effective = effectiveRunnerToolCapabilities({
+      toolCapabilities: capabilities,
+      reportedAt: null,
+      staleAfterSeconds: 10,
+      now: new Date('2026-01-01T00:00:01.000Z'),
+    });
+
+    expect(effective).toEqual({harnesses: {}});
+  });
+
+  it('returns an empty set when the report is stale', () => {
+    const effective = effectiveRunnerToolCapabilities({
+      toolCapabilities: capabilities,
+      reportedAt: new Date('2026-01-01T00:00:00.000Z'),
+      staleAfterSeconds: 10,
+      now: new Date('2026-01-01T00:00:11.000Z'),
+    });
+
+    expect(effective).toEqual({harnesses: {}});
+  });
+
+  it('returns exact persisted tools when the report is fresh', () => {
+    const effective = effectiveRunnerToolCapabilities({
+      toolCapabilities: capabilities,
+      reportedAt: new Date('2026-01-01T00:00:00.000Z'),
+      staleAfterSeconds: 10,
+      now: new Date('2026-01-01T00:00:10.000Z'),
+    });
+
+    expect(effective).toBe(capabilities);
+  });
+});
+
+describe('unadvertisedRunnerTools', () => {
+  it('returns no tools when every requested tool is advertised', () => {
+    const missing = unadvertisedRunnerTools({
+      harness: 'pi',
+      requestedTools: ['read', 'bash'],
+      capabilities,
+    });
+
+    expect(missing).toEqual([]);
+  });
+
+  it('returns the missing subset in requested order', () => {
+    const missing = unadvertisedRunnerTools({
+      harness: 'pi',
+      requestedTools: ['read', 'web_search', 'bash', 'get_search_content'],
+      capabilities,
+    });
+
+    expect(missing).toEqual(['web_search', 'get_search_content']);
+  });
+
+  it('returns every requested tool when the harness has no advertised tools', () => {
+    const missing = unadvertisedRunnerTools({
+      harness: 'claude',
+      requestedTools: ['read', 'bash'],
+      capabilities,
+    });
+
+    expect(missing).toEqual(['read', 'bash']);
+  });
+
+  it('matches tool names exactly across harnesses', () => {
+    const missing = unadvertisedRunnerTools({
+      harness: 'claude',
+      requestedTools: ['read', 'Read'],
+      capabilities: {harnesses: {claude: {tools: ['read']}, pi: {tools: ['Read']}}},
+    });
+
+    expect(missing).toEqual(['Read']);
+  });
+});
+
+describe('getEffectiveRunnerToolCapabilities', () => {
+  it('returns fresh capabilities and reports the harness as known', async () => {
+    const runnerSession = await runnerSessionFactory.create({toolCapabilities: capabilities});
+
+    const result = await getEffectiveRunnerToolCapabilities({runnerSessionId: runnerSession.id});
+
+    expect(result.capabilities).toEqual(capabilities);
+    expect(result.reportFresh).toBe(true);
+    expect(result.harnessKnown('pi')).toBe(true);
+    expect(result.harnessKnown('claude')).toBe(false);
+  });
+
+  it('treats missing capabilities as unknown', async () => {
+    const runnerSession = await runnerSessionFactory.create({toolCapabilities: null});
+
+    const result = await getEffectiveRunnerToolCapabilities({runnerSessionId: runnerSession.id});
+
+    expect(result.capabilities).toEqual({harnesses: {}});
+    expect(result.reportFresh).toBe(false);
+    expect(result.harnessKnown('pi')).toBe(false);
+  });
+
+  it('treats stale capabilities as unknown', async () => {
+    const runnerSession = await runnerSessionFactory.create({toolCapabilities: capabilities});
+    await db()
+      .update(runnerSessions)
+      .set({toolCapabilitiesReportedAt: sql`now() - interval '1 hour'`})
+      .where(eq(runnerSessions.id, runnerSession.id));
+
+    const result = await getEffectiveRunnerToolCapabilities({runnerSessionId: runnerSession.id});
+
+    expect(result.capabilities).toEqual({harnesses: {}});
+    expect(result.reportFresh).toBe(false);
+    expect(result.harnessKnown('pi')).toBe(false);
+  });
+});

package/src/core/runner-tool-capabilities.ts

@@ -0,0 +1,75 @@
+import type {RunnerToolCapabilitiesDto} from '@shipfox/api-runners-dto';
+import {config} from '#config.js';
+import {getRunnerSessionById} from '#db/runner-sessions.js';
+
+type RunnerToolHarness = keyof RunnerToolCapabilitiesDto['harnesses'];
+
+export const EMPTY_RUNNER_TOOL_CAPABILITIES: RunnerToolCapabilitiesDto = {
+  harnesses: {},
+};
+
+export function effectiveRunnerToolCapabilities(params: {
+  toolCapabilities: RunnerToolCapabilitiesDto | null;
+  reportedAt: Date | null;
+  staleAfterSeconds: number;
+  now?: Date;
+}): RunnerToolCapabilitiesDto {
+  if (!params.toolCapabilities || !params.reportedAt) return EMPTY_RUNNER_TOOL_CAPABILITIES;
+
+  const now = params.now ?? new Date();
+  const ageMs = now.getTime() - params.reportedAt.getTime();
+  if (ageMs > params.staleAfterSeconds * 1000) return EMPTY_RUNNER_TOOL_CAPABILITIES;
+
+  return params.toolCapabilities;
+}
+
+function runnerToolCapabilityReportIsFresh(params: {
+  toolCapabilities: RunnerToolCapabilitiesDto | null | undefined;
+  reportedAt: Date | null | undefined;
+  staleAfterSeconds: number;
+  now?: Date;
+}): boolean {
+  if (!params.toolCapabilities || !params.reportedAt) return false;
+
+  const now = params.now ?? new Date();
+  const ageMs = now.getTime() - params.reportedAt.getTime();
+  return ageMs <= params.staleAfterSeconds * 1000;
+}
+
+export function unadvertisedRunnerTools(params: {
+  harness: RunnerToolHarness;
+  requestedTools: readonly string[];
+  capabilities: RunnerToolCapabilitiesDto;
+}): string[] {
+  const advertised = new Set(params.capabilities.harnesses[params.harness]?.tools ?? []);
+  return params.requestedTools.filter((tool) => !advertised.has(tool));
+}
+
+export interface EffectiveRunnerToolCapabilitiesResult {
+  capabilities: RunnerToolCapabilitiesDto;
+  reportFresh: boolean;
+  harnessKnown(harness: RunnerToolHarness): boolean;
+}
+
+export async function getEffectiveRunnerToolCapabilities(params: {
+  runnerSessionId: string;
+}): Promise<EffectiveRunnerToolCapabilitiesResult> {
+  const runnerSession = await getRunnerSessionById(params.runnerSessionId);
+  const staleAfterSeconds = config.RUNNER_TOOL_CAPABILITIES_STALE_AFTER_SECONDS;
+  const capabilities = effectiveRunnerToolCapabilities({
+    toolCapabilities: runnerSession?.toolCapabilities ?? null,
+    reportedAt: runnerSession?.toolCapabilitiesReportedAt ?? null,
+    staleAfterSeconds,
+  });
+  const reportFresh = runnerToolCapabilityReportIsFresh({
+    toolCapabilities: runnerSession?.toolCapabilities,
+    reportedAt: runnerSession?.toolCapabilitiesReportedAt,
+    staleAfterSeconds,
+  });
+
+  return {
+    capabilities,
+    reportFresh,
+    harnessKnown: (harness) => capabilities.harnesses[harness] !== undefined,
+  };
+}

package/src/db/db.ts

@@ -0,0 +1,38 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {ephemeralRegistrationTokens} from './schema/ephemeral-registration-tokens.js';
+import {manualRegistrationTokens} from './schema/manual-registration-tokens.js';
+import {runnersOutbox} from './schema/outbox.js';
+import {pendingJobExecutions} from './schema/pending-job-executions.js';
+import {provisionedRunners} from './schema/provisioned-runners.js';
+import {provisionerTokens} from './schema/provisioner-tokens.js';
+import {runnersRateLimits} from './schema/rate-limits.js';
+import {reservations} from './schema/reservations.js';
+import {runnerSessions} from './schema/runner-sessions.js';
+import {runningJobExecutions} from './schema/running-job-executions.js';
+
+export const schema = {
+  ephemeralRegistrationTokens,
+  pendingJobExecutions,
+  provisionedRunners,
+  provisionerTokens,
+  runnersRateLimits,
+  reservations,
+  runnerSessions,
+  manualRegistrationTokens,
+  runningJobExecutions,
+  runnersOutbox,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}
+
+export type Tx = Parameters<Parameters<NodePgDatabase<typeof schema>['transaction']>[0]>[0];