@camstack/server 0.1.3

package/src/__tests__/addon-upload.spec.ts

@@ -0,0 +1,355 @@
+/**
+ * Integration test for the `/api/addons/upload` route.
+ *
+ * Uses a real Fastify instance to exercise the multipart parser end-to-end
+ * with mock dependencies for the AddonBridgeService, AuthService, and
+ * MoleculerService. Verifies:
+ *
+ * 1. Auth enforcement (401 without token, 403 for non-admin)
+ * 2. File extension validation (.tgz / .tar.gz only)
+ * 3. Hub install path (nodeId = 'hub' or absent → AddonInstaller.installFromTgz)
+ * 4. Agent deploy path (nodeId = 'agent-x' → moleculer.broker.call with nodeID)
+ * 5. Agent failure → 502 response
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import Fastify from 'fastify'
+import type { FastifyInstance } from 'fastify'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { execFileSync } from 'node:child_process'
+import { registerAddonUploadRoute } from '../api/addon-upload.js'
+import type { AddonBridgeService } from '../core/addon-bridge/addon-bridge.service.js'
+import type { AuthService } from '../core/auth/auth.service.js'
+import type { MoleculerService } from '../core/moleculer/moleculer.service.js'
+import type { AddonRegistryService } from '../core/addon/addon-registry.service.js'
+import type { IScopedLogger } from '@camstack/types'
+
+/**
+ * Build a minimal valid addon tarball containing a `package/package.json`
+ * with the given name + version. `validateTarball` on the server extracts
+ * just that file via `tar -xzO`, so nothing else is needed for the happy
+ * path tests. Returns a Buffer.
+ */
+function buildValidTarball(manifest: { name: string; version: string }): Buffer {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vitest-tarball-'))
+  try {
+    fs.mkdirSync(path.join(tmpDir, 'package'), { recursive: true })
+    fs.writeFileSync(
+      path.join(tmpDir, 'package', 'package.json'),
+      JSON.stringify(manifest),
+    )
+    const tgz = path.join(tmpDir, 'out.tgz')
+    execFileSync('tar', ['-czf', tgz, '-C', tmpDir, 'package'])
+    return fs.readFileSync(tgz)
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  }
+}
+
+interface MockAuthPayload {
+  readonly isAdmin: boolean
+}
+
+interface FormDataLike {
+  readonly file: { filename: string; content: Buffer }
+  readonly nodeId?: string
+  readonly addonId?: string
+}
+
+function buildMultipart(boundary: string, body: FormDataLike): Buffer {
+  const parts: Buffer[] = []
+  const push = (s: string) => parts.push(Buffer.from(s))
+  push(`--${boundary}\r\n`)
+  push(`Content-Disposition: form-data; name="file"; filename="${body.file.filename}"\r\n`)
+  push('Content-Type: application/gzip\r\n\r\n')
+  parts.push(body.file.content)
+  push('\r\n')
+  if (body.nodeId !== undefined) {
+    push(`--${boundary}\r\n`)
+    push('Content-Disposition: form-data; name="nodeId"\r\n\r\n')
+    push(body.nodeId)
+    push('\r\n')
+  }
+  if (body.addonId !== undefined) {
+    push(`--${boundary}\r\n`)
+    push('Content-Disposition: form-data; name="addonId"\r\n\r\n')
+    push(body.addonId)
+    push('\r\n')
+  }
+  push(`--${boundary}--\r\n`)
+  return Buffer.concat(parts)
+}
+
+function makeAuth(kind: 'admin' | 'non-admin' | 'invalid' = 'admin'): AuthService {
+  return {
+    verifyToken: vi.fn(() => {
+      if (kind === 'invalid') throw new Error('invalid token')
+      const payload: MockAuthPayload = { isAdmin: kind === 'admin' }
+      return payload
+    }),
+  } as unknown as AuthService
+}
+
+function makeAddonBridge(installed?: { name: string; version: string }): AddonBridgeService {
+  return {
+    getInstaller: vi.fn(() => installed === undefined ? null : ({
+      installFromTgz: vi.fn(async () => installed),
+    })),
+    reloadPackages: vi.fn(async () => {}),
+  } as unknown as AddonBridgeService
+}
+
+function makeMoleculer(call: ReturnType<typeof vi.fn>): MoleculerService {
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- test stub: vi.fn isn't typed against the broker's internal call shape, but the runtime contract is what we exercise
+    broker: { call } as unknown as MoleculerService['broker'],
+  } as unknown as MoleculerService
+}
+
+function makeAddonRegistry(): AddonRegistryService {
+  return {
+    // Returns an empty list — no addons currently tied to any package.
+    // `installToHub` uses this to build `preInstallAddonIds`; an empty
+    // result means no background `restartAddon` calls are fired.
+    listAddons: vi.fn(() => []),
+    // Simulates a successful filesystem scan that found no new addons.
+    loadNewAddons: vi.fn(async () => ({ loaded: [] as string[], failed: [] as string[] })),
+    // Not reached in the default happy-path (preInstallAddonIds is empty),
+    // but stubbed for completeness and per-test overrides.
+    restartAddon: vi.fn(async (_id: string) => ({ success: true })),
+    // Returns a minimal cap-registry stub. `validateScopedTokenViaCap`
+    // calls `getSingleton('user-management')` — returning null means no
+    // singleton is mounted, so scoped-token auth is skipped. All happy-
+    // path tests authenticate via the JWT path (`Bearer t` → isAdmin),
+    // so this is the correct safe default.
+    getCapabilityRegistry: vi.fn(() => ({
+      getSingleton: vi.fn((_name: string) => null),
+    })),
+  } as unknown as AddonRegistryService
+}
+
+function makeLogger(): IScopedLogger {
+  return {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(function (this: IScopedLogger) { return this }),
+    withTags: vi.fn(function (this: IScopedLogger) { return this }),
+  } as unknown as IScopedLogger
+}
+
+async function makeServer(opts: {
+  auth: AuthService
+  bridge: AddonBridgeService
+  moleculer: MoleculerService
+  addonRegistry?: AddonRegistryService
+  logger?: IScopedLogger
+}): Promise<FastifyInstance> {
+  const fastify = Fastify({ logger: false })
+  await registerAddonUploadRoute(
+    fastify,
+    opts.bridge,
+    opts.auth,
+    opts.moleculer,
+    opts.addonRegistry ?? makeAddonRegistry(),
+    opts.logger ?? makeLogger(),
+  )
+  await fastify.ready()
+  return fastify
+}
+
+const TGZ_BOUNDARY = '----vitestboundary'
+const VALID_TARBALL = buildValidTarball({ name: 'addon-x', version: '1.0.0' })
+const INVALID_TARBALL = Buffer.from('fake-not-a-tarball')
+
+describe('POST /api/addons/upload', () => {
+  let fastify: FastifyInstance | null = null
+
+  afterEach(async () => {
+    if (fastify) {
+      await fastify.close()
+      fastify = null
+    }
+  })
+
+  describe('auth', () => {
+    beforeEach(async () => {
+      fastify = await makeServer({
+        auth: makeAuth('admin'),
+        bridge: makeAddonBridge({ name: 'addon-x', version: '1.0.0' }),
+        moleculer: makeMoleculer(vi.fn()),
+      })
+    })
+
+    it('returns 401 when Authorization header is missing', async () => {
+      const res = await fastify!.inject({
+        method: 'POST',
+        url: '/api/addons/upload',
+        headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}` },
+        payload: buildMultipart(TGZ_BOUNDARY, { file: { filename: 'addon-x.tgz', content: VALID_TARBALL } }),
+      })
+      expect(res.statusCode).toBe(401)
+    })
+
+    it('returns 403 when token is not admin', async () => {
+      await fastify!.close()
+      fastify = await makeServer({
+        auth: makeAuth('non-admin'),
+        bridge: makeAddonBridge({ name: 'addon-x', version: '1.0.0' }),
+        moleculer: makeMoleculer(vi.fn()),
+      })
+      const res = await fastify.inject({
+        method: 'POST',
+        url: '/api/addons/upload',
+        headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer token' },
+        payload: buildMultipart(TGZ_BOUNDARY, { file: { filename: 'addon-x.tgz', content: VALID_TARBALL } }),
+      })
+      expect(res.statusCode).toBe(403)
+    })
+  })
+
+  it('returns 400 when filename is not a tarball', async () => {
+    fastify = await makeServer({
+      auth: makeAuth('admin'),
+      bridge: makeAddonBridge({ name: 'addon-x', version: '1.0.0' }),
+      moleculer: makeMoleculer(vi.fn()),
+    })
+    const res = await fastify.inject({
+      method: 'POST',
+      url: '/api/addons/upload',
+      headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer t' },
+      payload: buildMultipart(TGZ_BOUNDARY, { file: { filename: 'evil.exe', content: VALID_TARBALL } }),
+    })
+    expect(res.statusCode).toBe(400)
+  })
+
+  it('routes to hub installer when nodeId is absent', async () => {
+    // Hub install writes a `.install-source` marker into
+    // `${CAMSTACK_DATA}/addons/<addonName>/`. Point CAMSTACK_DATA at an
+    // isolated temp dir for the test so the side effect doesn't escape.
+    const tmpRoot = await import('node:fs/promises').then(fs => fs.mkdtemp('/tmp/camstack-upload-test-'))
+    const previous = process.env['CAMSTACK_DATA']
+    process.env['CAMSTACK_DATA'] = tmpRoot
+    const fsSync = await import('node:fs')
+    fsSync.mkdirSync(`${tmpRoot}/addons/addon-x`, { recursive: true })
+
+    try {
+      const bridge = makeAddonBridge({ name: 'addon-x', version: '2.0.0' })
+      fastify = await makeServer({
+        auth: makeAuth('admin'),
+        bridge,
+        moleculer: makeMoleculer(vi.fn()),
+      })
+      const res = await fastify.inject({
+        method: 'POST',
+        url: '/api/addons/upload',
+        headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer t' },
+        payload: buildMultipart(TGZ_BOUNDARY, { file: { filename: 'addon-x.tgz', content: VALID_TARBALL } }),
+      })
+      expect(res.statusCode).toBe(200)
+      const body = res.json() as { success: boolean; target: string; packageName: string; version: string }
+      expect(body).toMatchObject({ success: true, target: 'hub', packageName: 'addon-x', version: '2.0.0' })
+    } finally {
+      if (previous === undefined) delete process.env['CAMSTACK_DATA']
+      else process.env['CAMSTACK_DATA'] = previous
+      fsSync.rmSync(tmpRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('routes to $agent.deploy when nodeId is provided', async () => {
+    const call = vi.fn(async () => ({ success: true, addonId: 'addon-x', path: '/agent/addons/addon-x' }))
+    fastify = await makeServer({
+      auth: makeAuth('admin'),
+      bridge: makeAddonBridge(),
+      moleculer: makeMoleculer(call),
+    })
+    const res = await fastify.inject({
+      method: 'POST',
+      url: '/api/addons/upload',
+      headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer t' },
+      payload: buildMultipart(TGZ_BOUNDARY, {
+        file: { filename: 'addon-x-1.2.3.tgz', content: VALID_TARBALL },
+        nodeId: 'agent-frigate',
+        addonId: 'addon-x',
+      }),
+    })
+    expect(res.statusCode).toBe(200)
+    const body = res.json() as { success: boolean; target: string; addonId: string; path: string }
+    expect(body.target).toBe('agent-frigate')
+    expect(body.addonId).toBe('addon-x')
+
+    expect(call).toHaveBeenCalledWith(
+      '$agent.deploy',
+      { addonId: 'addon-x', bundle: VALID_TARBALL },
+      { nodeID: 'agent-frigate', timeout: 60_000 },
+    )
+  })
+
+  it('returns 502 when $agent.deploy throws', async () => {
+    const call = vi.fn(async () => { throw new Error('agent unreachable') })
+    fastify = await makeServer({
+      auth: makeAuth('admin'),
+      bridge: makeAddonBridge(),
+      moleculer: makeMoleculer(call),
+    })
+    const res = await fastify.inject({
+      method: 'POST',
+      url: '/api/addons/upload',
+      headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer t' },
+      payload: buildMultipart(TGZ_BOUNDARY, {
+        file: { filename: 'addon-x.tgz', content: VALID_TARBALL },
+        nodeId: 'agent-frigate',
+      }),
+    })
+    expect(res.statusCode).toBe(502)
+    const body = res.json() as { error: string }
+    expect(body.error).toMatch(/agent unreachable/)
+  })
+
+  it('uses manifest.name as addonId fallback when client omits the hint', async () => {
+    const call = vi.fn(async () => ({ success: true, addonId: 'addon-foo' }))
+    const tarball = buildValidTarball({ name: 'addon-foo', version: '1.2.3' })
+    fastify = await makeServer({
+      auth: makeAuth('admin'),
+      bridge: makeAddonBridge(),
+      moleculer: makeMoleculer(call),
+    })
+    await fastify.inject({
+      method: 'POST',
+      url: '/api/addons/upload',
+      headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer t' },
+      payload: buildMultipart(TGZ_BOUNDARY, {
+        // Filename is intentionally different from manifest.name to prove
+        // that the server reads the manifest, not the filename.
+        file: { filename: 'unrelated-name-9.tgz', content: tarball },
+        nodeId: 'agent-frigate',
+      }),
+    })
+    expect(call).toHaveBeenCalledWith(
+      '$agent.deploy',
+      expect.objectContaining({ addonId: 'addon-foo' }),
+      expect.anything(),
+    )
+  })
+
+  it('returns 400 when the tarball has no valid package.json', async () => {
+    fastify = await makeServer({
+      auth: makeAuth('admin'),
+      bridge: makeAddonBridge(),
+      moleculer: makeMoleculer(vi.fn()),
+    })
+    const res = await fastify.inject({
+      method: 'POST',
+      url: '/api/addons/upload',
+      headers: { 'content-type': `multipart/form-data; boundary=${TGZ_BOUNDARY}`, authorization: 'Bearer t' },
+      payload: buildMultipart(TGZ_BOUNDARY, {
+        file: { filename: 'bogus.tgz', content: INVALID_TARBALL },
+      }),
+    })
+    expect(res.statusCode).toBe(400)
+    const body = res.json() as { error: string }
+    expect(body.error).toMatch(/package\.json/)
+  })
+})

package/src/__tests__/agent-registry.spec.ts

@@ -0,0 +1,162 @@
+/**
+ * AgentRegistryService — node.connected + cold-scan event emission.
+ *
+ * Regression guard for the race between hub boot and remote agents: when
+ * a dev.sh cluster starts hub + agents simultaneously, agents can register
+ * with Moleculer BEFORE the hub's `AgentRegistryService.onModuleInit`
+ * wires its `$node.connected` listener. Without the cold-scan below,
+ * those agents never produced an `agent.online` event, so alert-center
+ * and admin-ui lost their lifecycle view of the cluster.
+ *
+ * These specs validate both the hot path (new connections fire the
+ * listener) and the cold path (already-connected nodes retroactively
+ * emit on init).
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { AgentRegistryService } from '../core/agent/agent-registry.service.js'
+import type { EventBusService } from '../core/events/event-bus.service.js'
+import type { MoleculerService } from '../core/moleculer/moleculer.service.js'
+import type { CapabilityService } from '../core/capability/capability.service.js'
+import type { SystemEvent } from '@camstack/types'
+
+interface CapturedEmits {
+  readonly events: SystemEvent[]
+}
+
+function createFakes(opts: { preExistingNodeIds?: readonly string[] } = {}) {
+  const emits: CapturedEmits = { events: [] }
+  const fakeEventBus = {
+    emit: (event: SystemEvent) => { emits.events.push(event) },
+  } as unknown as EventBusService
+
+  const localBus = new EventEmitter()
+  const nodeList = (opts.preExistingNodeIds ?? []).map((id) => ({ id }))
+  // D3: setOnAgentRegistered is called by AgentRegistryService.onModuleInit
+  // to wire the handshake-driven reconcile trigger. The fake captures the
+  // callback but does not invoke it (reconcile tests are out of scope here).
+  const fakeMoleculer = {
+    broker: {
+      nodeID: 'hub',
+      localBus,
+      registry: {
+        getNodeList: ({ onlyAvailable }: { onlyAvailable: boolean }) => {
+          void onlyAvailable
+          return nodeList
+        },
+      },
+    },
+    setOnAgentRegistered: (_cb: (nodeId: string) => void) => { /* no-op in unit tests */ },
+  } as unknown as MoleculerService
+
+  const fakeCapability = {} as unknown as CapabilityService
+  const service = new AgentRegistryService(fakeEventBus, fakeMoleculer, fakeCapability)
+
+  return { service, emits, localBus }
+}
+
+describe('AgentRegistryService — agent.online event lifecycle', () => {
+  let captured: CapturedEmits
+  let service: AgentRegistryService
+  let localBus: EventEmitter
+
+  describe('hot path: $node.connected fired after onModuleInit', () => {
+    beforeEach(() => {
+      const fakes = createFakes()
+      service = fakes.service
+      captured = fakes.emits
+      localBus = fakes.localBus
+      service.onModuleInit()
+    })
+
+    it('emits agent.online with the agentId when a new node connects', () => {
+      localBus.emit('$node.connected', { node: { id: 'dev-agent-0' } })
+      expect(captured.events).toHaveLength(1)
+      expect(captured.events[0]!.category).toBe('agent.online')
+      expect((captured.events[0]!.data as Record<string, unknown>).agentId).toBe('dev-agent-0')
+    })
+
+    it('emits agent.offline on $node.disconnected', () => {
+      localBus.emit('$node.disconnected', { node: { id: 'dev-agent-0' } })
+      expect(captured.events).toHaveLength(1)
+      expect(captured.events[0]!.category).toBe('agent.offline')
+    })
+
+    it('handles burst of connections without loss', () => {
+      for (let i = 0; i < 5; i++) {
+        localBus.emit('$node.connected', { node: { id: `agent-${i}` } })
+      }
+      expect(captured.events).toHaveLength(5)
+      expect(captured.events.map((e) => (e.data as Record<string, unknown>).agentId))
+        .toEqual(['agent-0', 'agent-1', 'agent-2', 'agent-3', 'agent-4'])
+    })
+  })
+
+  describe('cold path: nodes already connected before onModuleInit', () => {
+    it('retroactively emits agent.online for pre-existing remote agents and worker.online for sub-workers', () => {
+      const fakes = createFakes({
+        preExistingNodeIds: ['dev-agent-0', 'dev-agent-1', 'hub/benchmark'],
+      })
+      fakes.service.onModuleInit()
+      // Skip the self-node ('hub'). Bare ids → agents (`agent.online`);
+      // `hub/<x>` ids → in-process workers (`worker.online`). The split
+      // is intentional — see "Event system: separate WorkerOnline /
+      // WorkerOffline events split from agent lifecycle" in
+      // `agent-registry.service.ts::onModuleInit`.
+      const agentIds = fakes.emits.events
+        .filter((e) => e.category === 'agent.online')
+        .map((e) => (e.data as Record<string, unknown>).agentId)
+      const workerIds = fakes.emits.events
+        .filter((e) => e.category === 'worker.online')
+        .map((e) => (e.data as Record<string, unknown>).workerId)
+      expect(agentIds.sort()).toEqual(['dev-agent-0', 'dev-agent-1'])
+      expect(workerIds).toEqual(['hub/benchmark'])
+    })
+
+    it('skips the hub self-node on cold-scan', () => {
+      const fakes = createFakes({ preExistingNodeIds: ['hub', 'dev-agent-0'] })
+      fakes.service.onModuleInit()
+      const ids = fakes.emits.events
+        .filter((e) => e.category === 'agent.online')
+        .map((e) => (e.data as Record<string, unknown>).agentId)
+      expect(ids).toEqual(['dev-agent-0'])
+      expect(ids).not.toContain('hub')
+    })
+
+    it('combined cold-scan + hot-path: no duplicates, both sources produce events', () => {
+      const fakes = createFakes({ preExistingNodeIds: ['dev-agent-0'] })
+      fakes.service.onModuleInit()
+      // One from cold-scan.
+      expect(fakes.emits.events).toHaveLength(1)
+      // New connection fires the hot path.
+      fakes.localBus.emit('$node.connected', { node: { id: 'dev-agent-1' } })
+      expect(fakes.emits.events).toHaveLength(2)
+      expect((fakes.emits.events[1]!.data as Record<string, unknown>).agentId).toBe('dev-agent-1')
+    })
+  })
+
+  describe('resilience: malformed registry shape', () => {
+    it('does not throw if broker.registry.getNodeList is missing', () => {
+      const emits: CapturedEmits = { events: [] }
+      const fakeEventBus = { emit: (e: SystemEvent) => emits.events.push(e) } as unknown as EventBusService
+      const fakeMoleculer = {
+        broker: { nodeID: 'hub', localBus: new EventEmitter(), registry: {} },
+        setOnAgentRegistered: (_cb: (nodeId: string) => void) => { /* no-op */ },
+      } as unknown as MoleculerService
+      const svc = new AgentRegistryService(fakeEventBus, fakeMoleculer, {} as CapabilityService)
+      expect(() => svc.onModuleInit()).not.toThrow()
+      expect(emits.events).toHaveLength(0)
+    })
+
+    it('does not throw if broker.registry itself is missing', () => {
+      const emits: CapturedEmits = { events: [] }
+      const fakeEventBus = { emit: (e: SystemEvent) => emits.events.push(e) } as unknown as EventBusService
+      const fakeMoleculer = {
+        broker: { nodeID: 'hub', localBus: new EventEmitter() },
+        setOnAgentRegistered: (_cb: (nodeId: string) => void) => { /* no-op */ },
+      } as unknown as MoleculerService
+      const svc = new AgentRegistryService(fakeEventBus, fakeMoleculer, {} as CapabilityService)
+      expect(() => svc.onModuleInit()).not.toThrow()
+    })
+  })
+})

package/src/__tests__/agent-status-page.spec.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest'
+import { renderAgentStatusPage, type AgentStatusData } from '../agent-status-page'
+
+const makeStatusData = (overrides: Partial<AgentStatusData> = {}): AgentStatusData => ({
+  agentId: 'agent-abc12345',
+  agentName: 'test-agent',
+  hubUrl: 'ws://localhost:4443/agent',
+  connected: true,
+  activeTaskCount: 3,
+  taskTypes: ['pipeline.decode', 'pipeline.detect'],
+  platform: 'darwin',
+  arch: 'arm64',
+  cpuCores: 8,
+  memoryTotalMB: 16384,
+  memoryFreeMB: 8192,
+  uptime: 3661,
+  ...overrides,
+})
+
+describe('renderAgentStatusPage', () => {
+  it('renders valid HTML', () => {
+    const html = renderAgentStatusPage(makeStatusData())
+    expect(html).toContain('<!DOCTYPE html>')
+    expect(html).toContain('</html>')
+  })
+
+  it('includes agent name and ID', () => {
+    const html = renderAgentStatusPage(makeStatusData())
+    expect(html).toContain('test-agent')
+    expect(html).toContain('agent-abc12345')
+  })
+
+  it('shows connected status with green dot', () => {
+    const html = renderAgentStatusPage(makeStatusData({ connected: true }))
+    expect(html).toContain('Connected')
+    expect(html).toContain('#22c55e')
+  })
+
+  it('shows disconnected status with red dot', () => {
+    const html = renderAgentStatusPage(makeStatusData({ connected: false }))
+    expect(html).toContain('Disconnected')
+    expect(html).toContain('#ef4444')
+  })
+
+  it('displays task types', () => {
+    const html = renderAgentStatusPage(makeStatusData())
+    expect(html).toContain('pipeline.decode')
+    expect(html).toContain('pipeline.detect')
+  })
+
+  it('shows "no task handlers" when list is empty', () => {
+    const html = renderAgentStatusPage(makeStatusData({ taskTypes: [] }))
+    expect(html).toContain('No task handlers registered')
+  })
+
+  it('displays hardware info', () => {
+    const html = renderAgentStatusPage(makeStatusData())
+    expect(html).toContain('darwin')
+    expect(html).toContain('arm64')
+    expect(html).toContain('8')
+  })
+
+  it('calculates memory usage', () => {
+    const html = renderAgentStatusPage(
+      makeStatusData({ memoryTotalMB: 16384, memoryFreeMB: 4096 }),
+    )
+    // 12288 / 16384 = 75%
+    expect(html).toContain('12288')
+    expect(html).toContain('75%')
+  })
+
+  it('escapes HTML in user-provided strings', () => {
+    const html = renderAgentStatusPage(
+      makeStatusData({ agentName: '<script>alert("xss")</script>' }),
+    )
+    expect(html).not.toContain('<script>')
+    expect(html).toContain('&lt;script&gt;')
+  })
+
+  it('auto-refreshes every 5 seconds', () => {
+    const html = renderAgentStatusPage(makeStatusData())
+    expect(html).toContain('http-equiv="refresh" content="5"')
+  })
+})

package/src/__tests__/auth-session-cookie.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest'
+import { buildSessionCookie, clearSessionCookie, SESSION_COOKIE } from '../auth/session-cookie.js'
+
+describe('session cookie', () => {
+  it('buildSessionCookie produces an httpOnly lax cookie carrying the token', () => {
+    const c = buildSessionCookie('jwt-abc', 3600)
+    expect(c.name).toBe(SESSION_COOKIE)
+    expect(c.value).toBe('jwt-abc')
+    expect(c.options.httpOnly).toBe(true)
+    expect(c.options.sameSite).toBe('lax')
+    expect(c.options.secure).toBe(true)
+    expect(c.options.path).toBe('/')
+    expect(c.options.maxAge).toBe(3600)
+  })
+
+  it('clearSessionCookie expires the cookie', () => {
+    const c = clearSessionCookie()
+    expect(c.name).toBe(SESSION_COOKIE)
+    expect(c.options.maxAge).toBe(0)
+  })
+})

package/src/__tests__/cap-providers/cap-usage-graph.spec.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { __resetCapUsageRegistryForTests, getCapUsageRegistry } from '@camstack/kernel'
+import { buildNodesProvider } from '../../api/core/cap-providers'
+
+describe('nodes.getCapUsageGraph provider', () => {
+  beforeEach(() => { __resetCapUsageRegistryForTests() })
+
+  it('returns recorded edges projected through the cap-usage registry', async () => {
+    const reg = getCapUsageRegistry()
+    const t0 = Date.now() - 5_000
+    reg.recordCall({ callerAddonId: 'A', providerAddonId: 'B', capName: 'foo', methodName: 'm', atMs: t0 })
+    reg.recordCall({ callerAddonId: 'A', providerAddonId: 'B', capName: 'foo', methodName: 'm', atMs: t0 + 1000 })
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const provider = buildNodesProvider({} as any, { broker: { call: vi.fn() } } as any)
+    const out = await provider.getCapUsageGraph({ windowSeconds: 60 })
+    expect(out).toHaveLength(1)
+    expect(out[0]!.callerAddonId).toBe('A')
+    expect(out[0]!.providerAddonId).toBe('B')
+    expect(out[0]!.capName).toBe('foo')
+    expect(out[0]!.callsPerMin).toBeGreaterThan(0)
+  })
+})