Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
10.6 KB
Raw Blame
/**
 * Integration contract tests for task-cancel v2.
 *
 * These tests verify cross-layer contracts that are not already covered by
 * the unit-level suites. They are intentionally distinct from:
 *   - lifecycle/__tests__/regressionBugs.test.ts  (BUG-1–6, unit-level)
 *   - __tests__/phaseC-contracts.test.ts          (MessageQueue 5-field shape + event sequence)
 *   - __tests__/server.cancel.contract.test.ts    (HTTP 204/404/501 status codes)
 *
 * Coverage added here:
 *   A. TaskLifecycle.getStats() v2 shape — 6 fields including `cancelled`.
 *      (phaseC covers MessageQueue.getStats() 5-field shape; this covers the
 *      underlying source-of-truth layer that drives /v1/runtime/status.)
 *   B. HTTP /v1/runtime/status response shape through the real RPCServer —
 *      verifies the onStatus wiring propagates the correct queue field names.
 *   C. Cancel-pending tombstone observed from the SessionProcessor.task:skipped
 *      perspective with enqueue-after-cancel ordering (vs. cancel-before-enqueue
 *      in regressionBugs BUG-1).
 */
import { describe, expect, it, vi } from 'vitest'
import type { AddressInfo } from 'net'

// ---------------------------------------------------------------------------
// A. TaskLifecycle.getStats() — v2 shape (6 fields, includes `cancelled`)
// ---------------------------------------------------------------------------

describe('Integration contract A: TaskLifecycle.getStats() v2 shape', () => {
  it('returns all 6 fields including `cancelled` after a mixed-state lifecycle', async () => {
    const { TaskLifecycle } = await import('../lifecycle/taskLifecycle')
    const { buildTask } = await import('../lifecycle/__tests__/helpers')

    const lc = new TaskLifecycle()

    const pending = buildTask({ id: 'ic-a-pending' })
    const processing = buildTask({ id: 'ic-a-processing' })
    const completed = buildTask({ id: 'ic-a-completed' })
    const cancelled = buildTask({ id: 'ic-a-cancelled' })

    lc.register(pending)
    lc.register(processing)
    lc.register(completed)
    lc.register(cancelled)

    lc.transition('ic-a-processing', 'processing', 'dispatched')
    lc.transition('ic-a-completed', 'processing', 'dispatched')
    lc.transition('ic-a-completed', 'completed', 'natural')
    lc.transition('ic-a-cancelled', 'cancelled', 'user_requested')

    const stats = lc.getStats()

    // Exact 6-field v2 shape (lifecycle layer).
    expect(Object.keys(stats).sort()).toEqual([
      'cancelled',
      'completed',
      'failed',
      'pending',
      'processing',
      'total',
    ])

    expect(stats.pending).toBe(1)
    expect(stats.processing).toBe(1)
    expect(stats.completed).toBe(1)
    expect(stats.cancelled).toBe(1)
    expect(stats.failed).toBe(0)
    expect(stats.total).toBe(4)
  })

  it('`cancelled` count is not exposed by MessageQueue.getStats() (no leak to legacy consumers)', async () => {
    const { TaskLifecycle } = await import('../lifecycle/taskLifecycle')
    const { MessageQueue } = await import('../queue/messageQueue')
    const { buildTask } = await import('../lifecycle/__tests__/helpers')

    const lc = new TaskLifecycle()
    const mq = new MessageQueue()
    mq.setLifecycle(lc)

    const task = buildTask({ id: 'ic-a-noleak' })
    lc.register(task)
    lc.transition('ic-a-noleak', 'cancelled', 'user_requested')

    // MessageQueue.getStats() strips the `cancelled` field for backward compatibility
    // (spec §4.2 — legacy consumers like /v1/runtime/status expect the 5-field shape).
    const mqStats = mq.getStats()
    expect(Object.keys(mqStats).sort()).toEqual([
      'completed',
      'failed',
      'pending',
      'processing',
      'total',
    ])
    expect((mqStats as unknown as Record<string, unknown>)['cancelled']).toBeUndefined()
  })
})

// ---------------------------------------------------------------------------
// B. HTTP /v1/runtime/status — wiring and field shape
// ---------------------------------------------------------------------------

vi.hoisted(() => {
  process.env.CLERUM_ENABLE_AUTH = 'false'
  process.env.CLERUM_HOST_NAME = 'chatllm'
})

describe('Integration contract B: GET /v1/runtime/status HTTP shape', () => {
  const rpcEdgeHeaders = {
    'x-clerum-edge-caller': 'rpc-proxy',
    'x-clerum-edge-host-ref': 'chatllm',
    'x-clerum-edge-user-id': 'user-1',
  }

  async function startServerWithStatus(
    statusPayload: Record<string, unknown>
  ): Promise<{ baseUrl: string; stop: () => Promise<void> }> {
    vi.resetModules()
    const { RPCServer } = await import('../server')
    const server = new RPCServer(0)
    server.onStatus(async () => statusPayload as any)
    await server.start()
    const address = (server as any).server.address() as AddressInfo
    return {
      baseUrl: `http://127.0.0.1:${address.port}`,
      stop: () => server.stop(),
    }
  }

  it('returns the onStatus payload verbatim with 200', async () => {
    const payload = {
      agent: {
        state: 'idle',
        currentTaskId: null,
        tasksProcessed: 0,
        tasksSucceeded: 0,
        tasksFailed: 0,
        uptime: 42,
      },
      queue: { pending: 0, processing: 0, completed: 0, failed: 0, total: 0 },
      cronJobs: 0,
    }
    const { baseUrl, stop } = await startServerWithStatus(payload)
    try {
      const res = await fetch(`${baseUrl}/v1/runtime/status`, { headers: rpcEdgeHeaders })
      expect(res.status).toBe(200)
      const body = (await res.json()) as typeof payload
      // The queue sub-object must match the 5-field legacy shape.
      expect(Object.keys(body.queue).sort()).toEqual([
        'completed',
        'failed',
        'pending',
        'processing',
        'total',
      ])
      // Cancelled must NOT appear in the HTTP response's queue shape.
      expect((body.queue as Record<string, unknown>)['cancelled']).toBeUndefined()
      expect(body.agent.state).toBe('idle')
      expect(body.cronJobs).toBe(0)
    } finally {
      await stop()
    }
  })

  it('returns 200 with a fallback message when no status handler is wired', async () => {
    vi.resetModules()
    const { RPCServer } = await import('../server')
    const server = new RPCServer(0)
    // Intentionally do NOT call server.onStatus(...)
    await server.start()
    const address = (server as any).server.address() as AddressInfo
    const baseUrl = `http://127.0.0.1:${address.port}`
    try {
      const res = await fetch(`${baseUrl}/v1/runtime/status`, { headers: rpcEdgeHeaders })
      expect(res.status).toBe(200)
      const body = (await res.json()) as Record<string, unknown>
      // Handler not configured → routes.ts returns { status: "ok", message: "..." }
      expect(body['status']).toBe('ok')
    } finally {
      await server.stop()
    }
  })
})

// ---------------------------------------------------------------------------
// C. Cancel-pending tombstone — enqueue-after-cancel ordering
// ---------------------------------------------------------------------------

describe('Integration contract C: Cancel-pending tombstone (enqueue-after-cancel)', () => {
  it('task cancelled BETWEEN enqueue and dispatch is skipped by SessionProcessor, executor not called', async () => {
    // This tests the *enqueue-then-cancel* interleaving:
    //   1. Session A occupies the single concurrency slot (blocker).
    //   2. Session B's task is enqueued — it queues because slot is taken.
    //   3. Cancel arrives while the task waits in session B's queue.
    //   4. When session A completes and the slot opens, SessionProcessor's
    //      check-before-dispatch sees task B is already terminal →
    //      emits task:skipped, executor is never called.
    //
    // The complementary test (cancel-BEFORE-enqueue) lives in
    // lifecycle/__tests__/regressionBugs.test.ts BUG-1.

    const { TaskLifecycle } = await import('../lifecycle/taskLifecycle')
    const { SessionProcessor } = await import('../session/sessionProcessor')
    const { buildTask } = await import('../lifecycle/__tests__/helpers')

    const lc = new TaskLifecycle()

    let resolveBlocker!: (value: boolean) => void
    const blockerDone = new Promise<boolean>(r => {
      resolveBlocker = r
    })

    const executorFn = vi.fn((task: any) => {
      // First call = blocker; returns a promise we control.
      // Second call = the to-be-cancelled task — should never happen.
      if (task.id === 'ic-c-blocker') return blockerDone
      return Promise.resolve(false)
    })

    // maxConcurrent=1 — only one session can run at a time.
    const sp = new SessionProcessor({ maxConcurrent: 1, executor: executorFn, lifecycle: lc })

    // Register + enqueue the blocker task to occupy the slot.
    const blocker = buildTask({ id: 'ic-c-blocker' })
    lc.register(blocker)
    sp.enqueue('session-a', blocker)
    // Slot is now occupied — blocker executor is running (holding blockerDone).

    // The to-be-cancelled task for session B.
    const target = buildTask({ id: 'ic-c-target' })
    lc.register(target)

    // Enqueue target in session B while slot is occupied → goes into queue, not dispatched yet.
    const skipped = new Promise<void>(r => sp.once('task:skipped', () => r()))
    sp.enqueue('session-b', target)

    // Cancel target now — it is pending in session B's queue (tombstone set).
    lc.transition('ic-c-target', 'cancelled', 'user_requested')

    // Release the blocker so the slot opens and SessionProcessor tries session B.
    resolveBlocker(false)

    // SessionProcessor check-before-dispatch finds target already_terminal → task:skipped.
    await skipped

    // Executor must only have been called for the blocker, never for target.
    expect(executorFn).toHaveBeenCalledTimes(1)
    expect(executorFn.mock.calls[0]?.[0]).toMatchObject({ id: 'ic-c-blocker' })
    expect(lc.getStatus('ic-c-target')).toBe('cancelled')
  })

  it('task:skipped event payload includes the outcome kind (already_terminal or illegal)', async () => {
    const { TaskLifecycle } = await import('../lifecycle/taskLifecycle')
    const { SessionProcessor } = await import('../session/sessionProcessor')
    const { buildTask } = await import('../lifecycle/__tests__/helpers')

    const lc = new TaskLifecycle()
    const executor = vi.fn().mockResolvedValue(false)
    const sp = new SessionProcessor({ maxConcurrent: 1, executor, lifecycle: lc })

    const task = buildTask({ id: 'ic-c-payload' })
    lc.register(task)
    lc.transition('ic-c-payload', 'cancelled', 'user_requested')

    const skippedEvent = new Promise<{ outcome: { kind: string } }>(r =>
      sp.once('task:skipped', (ev: any) => r(ev))
    )
    sp.enqueue('session-payload', task)
    const ev = await skippedEvent

    // The outcome kind tells callers WHY the task was skipped.
    expect(ev.outcome.kind).toBe('already_terminal')
  })
})