@camstack/server 0.1.3

package/src/__tests__/streaming-scale.test.ts

@@ -0,0 +1,280 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument -- test file, mock typing */
+/**
+ * Scale test — how many sub-streams can we decode for motion analysis?
+ * Run: FRIGATE_HOST=192.168.1.128 npx vitest run server/backend/src/__tests__/streaming-scale.test.ts --reporter verbose
+ */
+import { describe, it, expect, afterAll } from 'vitest'
+import http from 'node:http'
+import { StreamBrokerManager, FfmpegDecoderProvider } from '@camstack/addon-pipeline/stream-broker'
+import type { FrameHandle, IStreamBroker } from '@camstack/types'
+import type { IScopedLogger } from '@camstack/types'
+
+const FRIGATE = process.env.FRIGATE_HOST ?? ''
+
+const mockLogger: IScopedLogger = {
+  debug: () => {}, info: () => {}, warn: console.warn, error: console.error,
+  child: () => mockLogger,
+}
+const mockLoggingService = { createLogger: () => mockLogger }
+
+function wait(ms: number) { return new Promise(r => setTimeout(r, ms)) }
+
+/**
+ * Poll-based replacement for the removed `IStreamBroker.onDecodedFrame`
+ * callback (Phase 5 / D9 — decoded frames now travel as shm `FrameHandle`s).
+ * Opens a frame-handle subscription, drains `pullFrameHandles` on a 50ms
+ * timer, and invokes `onHandle` once per decoded frame. The returned
+ * function tears the subscription down. `byteLength` stands in for the old
+ * `DecodedFrame.data.length`.
+ */
+async function subscribeDecodedFrames(
+  broker: IStreamBroker,
+  maxFps: number,
+  onHandle: (handle: FrameHandle) => void,
+): Promise<() => Promise<void>> {
+  const { subscriptionId } = await broker.subscribeFrameHandles({ format: 'rgb', maxFps })
+  const iv = setInterval(() => {
+    for (const handle of broker.pullFrameHandles(subscriptionId, 8)) {
+      onHandle(handle)
+    }
+  }, 50)
+  return async () => {
+    clearInterval(iv)
+    await broker.unsubscribeFrameHandles(subscriptionId)
+  }
+}
+
+/** Fetch detect sub-stream URLs from Frigate config */
+async function discoverSubStreams(): Promise<Array<{ name: string; url: string }>> {
+  return new Promise((resolve, reject) => {
+    const req = http.get(`http://${FRIGATE}:5000/api/config`, (res) => {
+      let data = ''
+      res.on('data', (chunk: Buffer) => { data += chunk })
+      res.on('end', () => {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- 
+          const config = JSON.parse(data)
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- 
+          const cameras = config.cameras || {}
+          const streams: Array<{ name: string; url: string }> = []
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 
+          for (const [name, cam] of Object.entries(cameras) as [string, any][]) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- 
+            if (!cam.enabled && cam.enabled !== undefined) continue
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- 
+            const inputs = cam?.ffmpeg?.inputs || []
+            for (const inp of inputs) {
+              // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+              if (inp.roles?.includes('detect') && inp.path) {
+                let streamName: string
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+                if (inp.path.includes('8554/')) {
+                  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+                  streamName = inp.path.split('8554/').pop()!
+                } else {
+                  streamName = `${name}_sub`
+                }
+                streams.push({ name, url: `rtsp://${FRIGATE}:8554/${streamName}` })
+              }
+            }
+          }
+          resolve(streams)
+        } catch (e) { reject(e) }
+      })
+    })
+    req.on('error', reject)
+    req.setTimeout(5000, () => { req.destroy(); reject(new Error('Timeout')) })
+  })
+}
+
+describe.skipIf(!FRIGATE)('Streaming Scale Test (requires Frigate)', () => {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call -- @camstack/addon-stream-broker types resolve as any in this test context
+  const manager = new StreamBrokerManager([new FfmpegDecoderProvider()], mockLogger)
+
+  afterAll(async () => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+    await manager.destroyAll()
+    // Wait for ffmpeg processes to exit
+    await wait(2000)
+  })
+
+  it('progressive scale: 5 → 10 → 20 → 30 sub-streams @ 2fps for motion', async () => {
+    // Discover real streams, then duplicate to simulate more cameras
+    const realStreams = await discoverSubStreams()
+
+    // Test which streams actually respond (filter out 404s)
+    const workingStreams: typeof realStreams = []
+    for (const s of realStreams.slice(0, 5)) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        const broker = await manager.createBroker(`probe-${s.name}`, {
+          type: 'rtsp', url: s.url, videoCodec: 'h264',
+        })
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        await (broker as any).start({ type: 'rtsp', url: s.url, videoCodec: 'h264' })
+        const ok = await new Promise<boolean>((resolve) => {
+          const timeout = setTimeout(() => resolve(false), 5000)
+          let unsub: (() => Promise<void>) | undefined
+          subscribeDecodedFrames(broker, 2, () => {
+            clearTimeout(timeout)
+            void unsub?.()
+            resolve(true)
+          }).then((fn) => { unsub = fn }).catch(() => resolve(false))
+        })
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        await broker.stop()
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        await manager.destroyBroker(`probe-${s.name}`)
+        if (ok) workingStreams.push(s)
+      } catch { /* skip */ }
+    }
+
+    console.log(`\nDiscovered ${realStreams.length} sub-streams, ${workingStreams.length} responding`)
+    if (workingStreams.length === 0) {
+      console.log('  No working sub-streams, skipping')
+      return
+    }
+
+    // Generate virtual streams by duplicating working ones (same RTSP URL, different broker ID)
+    function generateStreams(count: number) {
+      const streams: Array<{ name: string; url: string }> = []
+      for (let i = 0; i < count; i++) {
+        const real = workingStreams[i % workingStreams.length]!
+        streams.push({ name: `cam-${String(i).padStart(2, '0')}-${real.name}`, url: real.url })
+      }
+      return streams
+    }
+
+    const scaleLevels = [5, 10, 20, 30]
+
+    for (const targetCount of scaleLevels) {
+
+      console.log(`\n=== Scale: ${targetCount} sub-streams @ 2fps ===`)
+
+      const memBefore = process.memoryUsage()
+      const cpuBefore = process.cpuUsage()
+      const brokerIds: string[] = []
+      const unsubs: Array<() => Promise<void>> = []
+      const perCamera: Record<string, { frames: number; totalBytes: number }> = {}
+      let connectFailures = 0
+
+      // Start N brokers IN PARALLEL (using duplicated working streams)
+      const streams = generateStreams(targetCount)
+      const startTime = Date.now()
+
+      // Launch all brokers concurrently — don't wait for keyframe sequentially
+      const connectPromises = streams.map(async (s) => {
+        const brokerId = `scale-${s.name}`
+        brokerIds.push(brokerId)
+        perCamera[s.name] = { frames: 0, totalBytes: 0 }
+
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+          const broker = await manager.createBroker(brokerId, {
+            type: 'rtsp', url: s.url, videoCodec: 'h264',
+          })
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+          await (broker as any).start({ type: 'rtsp', url: s.url, videoCodec: 'h264' })
+
+          // Wait for first frame with tight timeout
+          await new Promise<void>((resolve) => {
+            const timeout = setTimeout(() => {
+              connectFailures++
+              resolve()
+            }, 10000)
+            let unsub: (() => Promise<void>) | undefined
+            subscribeDecodedFrames(broker, 2, () => {
+              clearTimeout(timeout)
+              void unsub?.()
+              resolve()
+            }).then((fn) => { unsub = fn }).catch(() => resolve())
+          })
+
+          // Subscribe for motion analysis
+          const unsub = await subscribeDecodedFrames(broker, 2, (handle: FrameHandle) => {
+            perCamera[s.name]!.frames++
+            perCamera[s.name]!.totalBytes += handle.byteLength
+          })
+          unsubs.push(unsub)
+        } catch (err) {
+          connectFailures++
+        }
+      })
+
+      await Promise.all(connectPromises)
+
+      const connectTime = Date.now() - startTime
+      console.log(`  Connected ${targetCount - connectFailures}/${targetCount} in ${(connectTime / 1000).toFixed(1)}s`)
+
+      // Run for 5 seconds of actual streaming
+      const measureStart = Date.now()
+      const cpuMeasureStart = process.cpuUsage()
+      await wait(5000)
+      const cpuMeasure = process.cpuUsage(cpuMeasureStart)
+      const measureDuration = (Date.now() - measureStart) / 1000
+
+      // Unsubscribe
+      for (const unsub of unsubs) await unsub()
+
+      // Calculate metrics
+      const cpuAfter = process.cpuUsage(cpuBefore)
+      const memAfter = process.memoryUsage()
+
+      let totalFrames = 0
+      let totalBytes = 0
+      let activeCameras = 0
+      let starvingCameras = 0
+
+      for (const [name, data] of Object.entries(perCamera)) {
+        totalFrames += data.frames
+        totalBytes += data.totalBytes
+        if (data.frames > 0) activeCameras++
+        if (data.frames < 3) starvingCameras++ // less than 3 frames in 5s = starving
+      }
+
+      const cpuPct = ((cpuMeasure.user + cpuMeasure.system) / (measureDuration * 1_000_000) * 100).toFixed(1)
+      const rssMB = (memAfter.rss / 1024 / 1024).toFixed(0)
+      const heapMB = (memAfter.heapUsed / 1024 / 1024).toFixed(0)
+      const combinedFps = (totalFrames / measureDuration).toFixed(1)
+      const avgFrameKB = totalFrames > 0 ? (totalBytes / totalFrames / 1024).toFixed(0) : '0'
+      const bwMBs = (totalBytes / 1024 / 1024 / measureDuration).toFixed(1)
+
+      console.log(`  Active: ${activeCameras}/${targetCount} cameras producing frames`)
+      console.log(`  Starving: ${starvingCameras} cameras (<3 frames in 5s)`)
+      console.log(`  Total frames: ${totalFrames} (${combinedFps} fps combined)`)
+      console.log(`  Avg frame: ${avgFrameKB} KB`)
+      console.log(`  Decode BW: ${bwMBs} MB/s`)
+      console.log(`  CPU: ${cpuPct}%`)
+      console.log(`  RSS: ${rssMB} MB | Heap: ${heapMB} MB`)
+
+      // Per-camera breakdown
+      console.log(`  ---`)
+      const sorted = Object.entries(perCamera).sort((a, b) => b[1].frames - a[1].frames)
+      for (const [name, data] of sorted) {
+        const fps = (data.frames / measureDuration).toFixed(1)
+        const avgKB = data.frames > 0 ? (data.totalBytes / data.frames / 1024).toFixed(0) : '-'
+        const status = data.frames >= 3 ? '✓' : data.frames > 0 ? '⚠' : '✗'
+        console.log(`  ${status} ${name.padEnd(35)} ${fps.padStart(4)} fps  ${avgKB.padStart(5)} KB/f  (${data.frames} frames)`)
+      }
+
+      // Cleanup for next scale level
+      for (const id of brokerIds) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        const b = manager.getBroker(id)
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        if (b) await b.stop()
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- 
+        await manager.destroyBroker(id)
+      }
+      brokerIds.length = 0
+      unsubs.length = 0
+      Object.keys(perCamera).forEach(k => delete perCamera[k])
+
+      // Expect at least 80% of cameras producing
+      expect(activeCameras).toBeGreaterThanOrEqual(Math.floor(targetCount * 0.8))
+
+      // Pause between levels for cleanup
+      await wait(2000)
+    }
+  }, 300000) // 5 min timeout for the full progressive test
+})

package/src/agent-status-page.ts

@@ -0,0 +1,121 @@
+export interface AgentStatusData {
+  readonly agentId: string
+  readonly agentName: string
+  readonly hubUrl: string
+  readonly connected: boolean
+  readonly activeTaskCount: number
+  readonly taskTypes: readonly string[]
+  readonly platform: string
+  readonly arch: string
+  readonly cpuCores: number
+  readonly memoryTotalMB: number
+  readonly memoryFreeMB: number
+  readonly uptime: number
+}
+
+function formatUptime(seconds: number): string {
+  const days = Math.floor(seconds / 86400)
+  const hours = Math.floor((seconds % 86400) / 3600)
+  const mins = Math.floor((seconds % 3600) / 60)
+  const parts: string[] = []
+  if (days > 0) parts.push(`${days}d`)
+  if (hours > 0) parts.push(`${hours}h`)
+  parts.push(`${mins}m`)
+  return parts.join(' ')
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/**
+ * Render a minimal server-rendered HTML status page for the agent.
+ * No React, no build system. Pure HTML + inline CSS.
+ * Designed for local debugging only.
+ */
+export function renderAgentStatusPage(data: AgentStatusData): string {
+  const statusColor = data.connected ? '#22c55e' : '#ef4444'
+  const statusText = data.connected ? 'Connected' : 'Disconnected'
+  const memUsedMB = data.memoryTotalMB - data.memoryFreeMB
+  const memPercent = Math.round((memUsedMB / data.memoryTotalMB) * 100)
+
+  const taskTypesList = data.taskTypes.length > 0
+    ? data.taskTypes.map((t) => `<li>${escapeHtml(t)}</li>`).join('')
+    : '<li class="muted">No task handlers registered</li>'
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="refresh" content="5">
+  <title>CamStack Agent: ${escapeHtml(data.agentName)}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, monospace; background: #0f172a; color: #e2e8f0; padding: 2rem; }
+    h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+    .subtitle { color: #94a3b8; font-size: 0.875rem; margin-bottom: 2rem; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; }
+    .card { background: #1e293b; border-radius: 0.75rem; padding: 1.25rem; }
+    .card h2 { font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.05em; color: #94a3b8; margin-bottom: 0.75rem; }
+    .stat { font-size: 1.25rem; font-weight: 600; margin-bottom: 0.25rem; }
+    .stat-label { font-size: 0.75rem; color: #64748b; }
+    .status-dot { display: inline-block; width: 10px; height: 10px; border-radius: 50%; margin-right: 0.5rem; }
+    dl { display: grid; grid-template-columns: auto 1fr; gap: 0.25rem 1rem; }
+    dt { color: #94a3b8; font-size: 0.8125rem; }
+    dd { font-size: 0.8125rem; }
+    ul { list-style: none; padding: 0; }
+    li { font-size: 0.8125rem; padding: 0.25rem 0; font-family: monospace; }
+    .muted { color: #64748b; font-style: italic; }
+    .bar { height: 6px; background: #334155; border-radius: 3px; overflow: hidden; margin-top: 0.5rem; }
+    .bar-fill { height: 100%; border-radius: 3px; }
+  </style>
+</head>
+<body>
+  <h1>CamStack Agent</h1>
+  <p class="subtitle">${escapeHtml(data.agentId)} &mdash; auto-refreshes every 5s</p>
+
+  <div class="grid">
+    <div class="card">
+      <h2>Connection</h2>
+      <div class="stat">
+        <span class="status-dot" style="background:${statusColor}"></span>
+        ${statusText}
+      </div>
+      <dl>
+        <dt>Name</dt><dd>${escapeHtml(data.agentName)}</dd>
+        <dt>Hub URL</dt><dd>${escapeHtml(data.hubUrl)}</dd>
+      </dl>
+    </div>
+
+    <div class="card">
+      <h2>Hardware</h2>
+      <dl>
+        <dt>Platform</dt><dd>${escapeHtml(data.platform)} / ${escapeHtml(data.arch)}</dd>
+        <dt>CPU Cores</dt><dd>${data.cpuCores}</dd>
+        <dt>Uptime</dt><dd>${formatUptime(data.uptime)}</dd>
+      </dl>
+      <div style="margin-top:0.75rem">
+        <div class="stat-label">Memory: ${memUsedMB} / ${data.memoryTotalMB} MB (${memPercent}%)</div>
+        <div class="bar"><div class="bar-fill" style="width:${memPercent}%;background:${memPercent > 90 ? '#ef4444' : memPercent > 70 ? '#f59e0b' : '#22c55e'}"></div></div>
+      </div>
+    </div>
+
+    <div class="card">
+      <h2>Tasks</h2>
+      <div class="stat">${data.activeTaskCount}</div>
+      <div class="stat-label">Active tasks</div>
+    </div>
+
+    <div class="card">
+      <h2>Registered Task Handlers</h2>
+      <ul>${taskTypesList}</ul>
+    </div>
+  </div>
+</body>
+</html>`
+}

package/src/api/__tests__/addons-custom.spec.ts

@@ -0,0 +1,134 @@
+/**
+ * Tests for `api.addons.custom` — the generic addon custom-action dispatcher
+ * built in Task 7.2 of the device-proxy redesign.
+ *
+ * Verifies:
+ *   - dispatch to a registered action returns the addon's value
+ *   - input is round-tripped through the action's Zod schema
+ *   - unknown (addonId, action) → NOT_FOUND
+ *   - unauthenticated caller → UNAUTHORIZED
+ *   - per-action `auth: 'admin'` is enforced (viewer rejected, admin allowed)
+ *   - per-action `auth: 'public'` allows anonymous callers
+ *   - addon output that violates its own schema → BAD_REQUEST (Zod parse)
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import { z } from 'zod'
+import { TRPCError } from '@trpc/server'
+import { customAction, defineCustomActions } from '@camstack/types'
+import { CustomActionRegistry } from '@camstack/kernel'
+import { trpcRouter } from '../trpc/trpc.middleware.js'
+import { createAddonsCustomProcedures } from '../addons-custom.router.js'
+import { makeCtx } from '../../__tests__/cap-routers/harness.js'
+
+const catalog = defineCustomActions({
+  ping: customAction(z.void(), z.literal('pong')),
+  echo: customAction(z.object({ msg: z.string() }), z.object({ msg: z.string() })),
+  adminOnly: customAction(z.void(), z.literal('ok'), { kind: 'mutation', auth: 'admin' }),
+  open: customAction(z.void(), z.literal('open'), { auth: 'public' }),
+  badOutput: customAction(z.void(), z.literal('expected')),
+})
+
+function buildRouter(registry: CustomActionRegistry) {
+  return trpcRouter({
+    ...createAddonsCustomProcedures({ getCustomActionRegistry: () => registry }),
+  })
+}
+
+describe('api.addons.custom', () => {
+  let registry: CustomActionRegistry
+  let router: ReturnType<typeof buildRouter>
+
+  beforeEach(() => {
+    registry = new CustomActionRegistry()
+    registry.registerAddon('benchmark', catalog, async (action, input) => {
+      switch (action) {
+        case 'ping': return 'pong'
+        case 'echo': return { msg: (input as { msg: string }).msg }
+        case 'adminOnly': return 'ok'
+        case 'open': return 'open'
+        case 'badOutput': return 'WRONG' // will fail output validation
+        default: throw new Error(`unknown action ${action}`)
+      }
+    })
+    router = buildRouter(registry)
+  })
+
+  it('dispatches a void/literal action and returns the addon value', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    const result = await caller.custom({ addonId: 'benchmark', action: 'ping', input: undefined })
+    expect(result).toBe('pong')
+  })
+
+  it('round-trips structured input through the action schema', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    const result = await caller.custom({ addonId: 'benchmark', action: 'echo', input: { msg: 'hi' } })
+    expect(result).toEqual({ msg: 'hi' })
+  })
+
+  it('rejects unknown (addonId, action) with NOT_FOUND', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    await expect(
+      caller.custom({ addonId: 'benchmark', action: 'missing', input: {} }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' })
+
+    await expect(
+      caller.custom({ addonId: 'unknown-addon', action: 'ping', input: undefined }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' })
+  })
+
+  it('rejects unauthenticated callers with UNAUTHORIZED', async () => {
+    const caller = router.createCaller(makeCtx('anonymous'))
+    await expect(
+      caller.custom({ addonId: 'benchmark', action: 'ping', input: undefined }),
+    ).rejects.toMatchObject({ code: 'UNAUTHORIZED' })
+  })
+
+  it('enforces per-action auth: admin-only action rejects viewer', async () => {
+    const caller = router.createCaller(makeCtx('viewer'))
+    await expect(
+      caller.custom({ addonId: 'benchmark', action: 'adminOnly', input: undefined }),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' })
+  })
+
+  it('enforces per-action auth: admin-only action allows admin', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    const result = await caller.custom({ addonId: 'benchmark', action: 'adminOnly', input: undefined })
+    expect(result).toBe('ok')
+  })
+
+  it('rejects bad input against the action schema', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    await expect(
+      caller.custom({ addonId: 'benchmark', action: 'echo', input: { msg: 123 } }),
+    ).rejects.toBeInstanceOf(Error)
+  })
+
+  it('rejects bad addon output against the action schema (crash-early)', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    await expect(
+      caller.custom({ addonId: 'benchmark', action: 'badOutput', input: undefined }),
+    ).rejects.toBeInstanceOf(Error)
+  })
+
+  // The outer `protectedProcedure` runs before the per-action auth check, so
+  // even a `public` action requires authentication today. This documents the
+  // intentional behavior: addons cannot expose anonymous endpoints through
+  // the generic dispatcher.
+  it('the outer protectedProcedure short-circuits even for public-auth actions', async () => {
+    const caller = router.createCaller(makeCtx('anonymous'))
+    await expect(
+      caller.custom({ addonId: 'benchmark', action: 'open', input: undefined }),
+    ).rejects.toMatchObject({ code: 'UNAUTHORIZED' })
+  })
+
+  it('TRPCError carries a descriptive message for unknown actions', async () => {
+    const caller = router.createCaller(makeCtx('admin'))
+    try {
+      await caller.custom({ addonId: 'benchmark', action: 'missing', input: {} })
+      expect.fail('should have thrown')
+    } catch (err) {
+      expect(err).toBeInstanceOf(TRPCError)
+      expect((err as TRPCError).message).toMatch(/no custom action 'missing'/)
+    }
+  })
+})

package/src/api/__tests__/capabilities.router.test.ts

@@ -0,0 +1,47 @@
+ 
+// server/backend/src/api/__tests__/capabilities.router.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { CapabilityRegistry } from '@camstack/kernel'
+import type { IScopedLogger } from '@camstack/types'
+
+function createMockLogger(): IScopedLogger {
+  return {
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    child: vi.fn().mockReturnThis(),
+  }
+}
+
+describe('capabilities tRPC router logic', () => {
+  let registry: CapabilityRegistry
+
+  beforeEach(() => {
+    registry = new CapabilityRegistry(createMockLogger())
+    registry.ready()
+  })
+
+  it('listCapabilities returns all declared capabilities', () => {
+    registry.declareCapability({ name: 'storage', scope: 'system', mode: 'singleton', methods: {} })
+    registry.declareCapability({ name: 'log-destination', scope: 'system', mode: 'collection', methods: {} })
+
+    const list = registry.listCapabilities()
+    expect(list).toHaveLength(2)
+    expect(list.map((c) => c.name)).toContain('storage')
+    expect(list.map((c) => c.name)).toContain('log-destination')
+  })
+
+  it('setActiveSingleton throws for unknown capability', async () => {
+    await expect(
+      registry.setActiveSingleton('nonexistent', 'some-addon', true),
+    ).rejects.toThrow(/[Uu]nknown/)
+  })
+
+  it('setActiveSingleton throws for collection capability', async () => {
+    registry.declareCapability({ name: 'log-destination', scope: 'system', mode: 'collection', methods: {} })
+    await expect(
+      registry.setActiveSingleton('log-destination', 'winston', true),
+    ).rejects.toThrow(/singleton/)
+  })
+})