@ossy/platform 3.16.0 → 3.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -29,7 +29,8 @@
     "./locale": "./src/locale.js",
     "./verify-sign-in-session": "./src/verify-sign-in-session.js",
     "./storage-keys": "./src/storage/storage-keys.js",
-    "./mcp": "./src/mcp/mount-platform-mcp.js"
+    "./mcp": "./src/mcp/mount-platform-mcp.js",
+    "./metering": "./src/metering/index.js"
   },
   "scripts": {
     "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\"",
@@ -48,15 +49,15 @@
     "@ossy/config": "^3.0.9",
     "@ossy/event-store": "^3.12.0",
     "@ossy/locale": "^3.4.0",
-    "@ossy/manifest": "^3.16.0",
+    "@ossy/manifest": "^3.17.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/router": "^3.0.9",
-    "@ossy/schema": "^3.16.0",
-    "@ossy/sdk": "^3.16.0",
+    "@ossy/schema": "^3.17.0",
+    "@ossy/sdk": "^3.17.0",
     "@ossy/tokens": "^3.11.1",
-    "@ossy/users": "^3.16.0",
-    "@ossy/workspaces": "^3.16.0",
+    "@ossy/users": "^3.17.0",
+    "@ossy/workspaces": "^3.17.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -77,5 +78,5 @@
     "Dockerfile",
     "docker-healthcheck.js"
   ],
-  "gitHead": "1872fb1467bf656284aae35881c34960c3860807"
+  "gitHead": "91ff7dffe9b0bddcb823daee67213d2008eb64e9"
 }

package/src/audit/audit-helpers.js

@@ -22,6 +22,32 @@ export function summarizeResult (result) {
   return previewValue(result, 0)
 }
 
+/**
+ * Generic usage extraction for any task result — ADR 0017. A task's `run()`
+ * returns `usage: { model, promptTokens, completionTokens, totalTokens? }`
+ * (e.g. OpenRouter-backed tasks) and `TaskRunService` forwards it into
+ * `MeteringService.record()` without needing to know which integration
+ * produced it.
+ *
+ * @param {unknown} result
+ * @returns {{ model: string | null, promptTokens: number | null, completionTokens: number | null, totalTokens: number | null } | null}
+ */
+export function extractUsage (result) {
+  const usage = result && typeof result === 'object' ? result.usage : null
+  if (!usage || typeof usage !== 'object') return null
+
+  const model = typeof usage.model === 'string' ? usage.model : null
+  const promptTokens = typeof usage.promptTokens === 'number' ? usage.promptTokens : null
+  const completionTokens = typeof usage.completionTokens === 'number' ? usage.completionTokens : null
+  if (model == null && promptTokens == null && completionTokens == null) return null
+
+  const totalTokens = typeof usage.totalTokens === 'number'
+    ? usage.totalTokens
+    : (promptTokens != null || completionTokens != null ? (promptTokens ?? 0) + (completionTokens ?? 0) : null)
+
+  return { model, promptTokens, completionTokens, totalTokens }
+}
+
 /**
  * Resolved task inputs for the run detail. Empty maps are omitted.
  *

package/src/audit/audit-helpers.spec.js

@@ -0,0 +1,42 @@
+import { describe, expect, it } from '@jest/globals'
+import { extractUsage } from './audit-helpers.js'
+
+describe('extractUsage', () => {
+  it('returns null when the result has no usage', () => {
+    expect(extractUsage(null)).toBeNull()
+    expect(extractUsage({})).toBeNull()
+    expect(extractUsage({ usage: null })).toBeNull()
+    expect(extractUsage({ usage: {} })).toBeNull()
+  })
+
+  it('passes through model/promptTokens/completionTokens/totalTokens', () => {
+    expect(extractUsage({
+      usage: { model: 'openai/gpt-4o-mini', promptTokens: 100, completionTokens: 20, totalTokens: 120 },
+    })).toEqual({
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+    })
+  })
+
+  it('derives totalTokens when the task result omits it', () => {
+    expect(extractUsage({
+      usage: { model: 'openai/gpt-4o-mini', promptTokens: 100, completionTokens: 20 },
+    })).toEqual({
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+    })
+  })
+
+  it('is still meterable with just a model and no token counts', () => {
+    expect(extractUsage({ usage: { model: 'openai/gpt-4o-mini' } })).toEqual({
+      model: 'openai/gpt-4o-mini',
+      promptTokens: null,
+      completionTokens: null,
+      totalTokens: null,
+    })
+  })
+})

package/src/audit/task-run-service.js

@@ -11,6 +11,7 @@ import {
   summarizeError,
   summarizeInputs,
   summarizeResult,
+  extractUsage,
 } from './audit-helpers.js'
 import { rejectOnAbort } from '../request-diagnostics.js'
 
@@ -109,6 +110,7 @@ export const TaskRunService = {
         inputs: summarizeInputs(context.inputs),
       })
       recordTaskMetrics(taskId, durationMs)
+      const usage = extractUsage(result)
       await MeteringService.record({
         kind: 'task',
         actionId: context.actionId ?? null,
@@ -121,6 +123,7 @@ export const TaskRunService = {
         actionInvocationId: context.actionInvocationId ?? null,
         taskRunId: runId,
         trigger,
+        ...(usage ?? {}),
       })
       return result
     } catch (error) {

package/src/metering/assert-llm-usage-budget.js

@@ -0,0 +1,83 @@
+import { Aggregate, getProjection } from '@ossy/event-store'
+import { Workspace } from '@ossy/workspaces/server'
+import { LlmUsageProjection, currentUsageMonth } from './llm-usage.aggregate.js'
+
+/** Platform-wide default monthly token budget per workspace, used when a workspace has no override. */
+export const DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP = 2_000_000
+
+/**
+ * @returns {number}
+ */
+export function llmWorkspaceMonthlyTokenCap () {
+  const raw = process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+  const parsed = raw != null ? Number(raw) : NaN
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+}
+
+/**
+ * Effective monthly token limit for a workspace — its own
+ * `llmMonthlyTokenLimit` override (set via
+ * `@ossy/workspaces/actions/set-llm-monthly-token-limit`) when
+ * present, else the platform-wide default.
+ *
+ * @param {string | null | undefined} workspaceId
+ * @returns {Promise<number>}
+ */
+export async function resolveLlmMonthlyTokenLimit (workspaceId) {
+  const platformDefault = llmWorkspaceMonthlyTokenCap()
+  if (!workspaceId) return platformDefault
+
+  const workspace = await Aggregate.Of(Workspace, workspaceId).then(Aggregate.View())
+  const override = workspace?.llmMonthlyTokenLimit
+  return typeof override === 'number' && override > 0 ? override : platformDefault
+}
+
+/**
+ * Best-effort workspace id resolution from a task `run()` context — same
+ * precedence as `TaskRunService`'s `resolveWorkspaceId` (`payload`/`req`),
+ * plus the raw dispatch `event` for callers that invoke this before the
+ * task context's `payload.workspaceId` has been set.
+ *
+ * @param {object} context
+ * @returns {string | null}
+ */
+export function resolveWorkspaceIdForBudget (context = {}) {
+  return context.workspaceId
+    ?? context.payload?.workspaceId
+    ?? context.req?.workspaceId
+    ?? context.event?.payload?.belongsTo
+    ?? context.event?.belongsTo
+    ?? null
+}
+
+/**
+ * Fail-closed monthly token budget check for LLM-backed tasks (today: the
+ * OpenRouter integration; named generically so switching providers later
+ * needs no rename here).
+ * No-op when there is no workspace in context (e.g. a system/dev run) —
+ * nothing to attribute the cap to.
+ *
+ * @param {{ workspaceId?: string | null, month?: string }} args
+ * @throws {Error & { status: 402, code: 'LLM_TOKEN_QUOTA_EXCEEDED', workspaceId: string, limit: number, used: number }}
+ */
+export async function assertLlmUsageBudget ({ workspaceId, month } = {}) {
+  if (!workspaceId) return
+
+  const limit = await resolveLlmMonthlyTokenLimit(workspaceId)
+  const usageMonth = currentUsageMonth(month)
+  const state = await getProjection(workspaceId, LlmUsageProjection.ProjectionId)
+  const used = state?.byMonth?.[usageMonth]?.totalTokens ?? 0
+
+  if (used >= limit) {
+    throw Object.assign(
+      new Error(`LLM monthly token budget exceeded for workspace ${workspaceId}`),
+      {
+        status: 402,
+        code: 'LLM_TOKEN_QUOTA_EXCEEDED',
+        workspaceId,
+        limit,
+        used,
+      },
+    )
+  }
+}

package/src/metering/assert-llm-usage-budget.spec.js

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const getProjectionMock = jest.fn()
+const ofMock = jest.fn()
+const viewMock = jest.fn(() => (state) => state)
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  getProjection: getProjectionMock,
+  Aggregate: { Of: ofMock, View: viewMock },
+}))
+
+jest.unstable_mockModule('@ossy/workspaces/server', () => ({
+  Workspace: {},
+}))
+
+const {
+  DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP,
+  assertLlmUsageBudget,
+  llmWorkspaceMonthlyTokenCap,
+  resolveLlmMonthlyTokenLimit,
+  resolveWorkspaceIdForBudget,
+} = await import('./assert-llm-usage-budget.js')
+
+describe('resolveWorkspaceIdForBudget', () => {
+  it('prefers explicit workspaceId, then payload, then req, then the dispatch event', () => {
+    expect(resolveWorkspaceIdForBudget({ workspaceId: 'ws-a', payload: { workspaceId: 'ws-b' } })).toBe('ws-a')
+    expect(resolveWorkspaceIdForBudget({ payload: { workspaceId: 'ws-b' } })).toBe('ws-b')
+    expect(resolveWorkspaceIdForBudget({ req: { workspaceId: 'ws-c' } })).toBe('ws-c')
+    expect(resolveWorkspaceIdForBudget({ event: { payload: { belongsTo: 'ws-d' } } })).toBe('ws-d')
+    expect(resolveWorkspaceIdForBudget({ event: { belongsTo: 'ws-e' } })).toBe('ws-e')
+    expect(resolveWorkspaceIdForBudget({})).toBeNull()
+  })
+})
+
+describe('llmWorkspaceMonthlyTokenCap', () => {
+  const originalEnv = process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+
+  afterEach(() => {
+    process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP = originalEnv
+  })
+
+  it('falls back to the default when unset or invalid', () => {
+    delete process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+    expect(llmWorkspaceMonthlyTokenCap()).toBe(DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP)
+    process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP = 'not-a-number'
+    expect(llmWorkspaceMonthlyTokenCap()).toBe(DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP)
+    process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP = '0'
+    expect(llmWorkspaceMonthlyTokenCap()).toBe(DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP)
+  })
+
+  it('reads a positive override from the environment', () => {
+    process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP = '500000'
+    expect(llmWorkspaceMonthlyTokenCap()).toBe(500000)
+  })
+})
+
+describe('resolveLlmMonthlyTokenLimit', () => {
+  beforeEach(() => {
+    ofMock.mockReset()
+    delete process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+  })
+
+  it('uses the platform default without a workspaceId', async () => {
+    expect(await resolveLlmMonthlyTokenLimit(null)).toBe(DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP)
+    expect(ofMock).not.toHaveBeenCalled()
+  })
+
+  it('uses the platform default when the workspace has no override', async () => {
+    ofMock.mockResolvedValue({ id: 'ws-1' })
+    expect(await resolveLlmMonthlyTokenLimit('ws-1')).toBe(DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP)
+  })
+
+  it('prefers the workspace-specific override', async () => {
+    ofMock.mockResolvedValue({ id: 'ws-1', llmMonthlyTokenLimit: 500000 })
+    expect(await resolveLlmMonthlyTokenLimit('ws-1')).toBe(500000)
+  })
+
+  it('ignores an invalid (zero/negative) override', async () => {
+    ofMock.mockResolvedValue({ id: 'ws-1', llmMonthlyTokenLimit: 0 })
+    expect(await resolveLlmMonthlyTokenLimit('ws-1')).toBe(DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP)
+  })
+})
+
+describe('assertLlmUsageBudget', () => {
+  beforeEach(() => {
+    getProjectionMock.mockReset()
+    ofMock.mockReset()
+    ofMock.mockResolvedValue({})
+    delete process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+  })
+
+  it('is a no-op without a workspace in context', async () => {
+    await expect(assertLlmUsageBudget({})).resolves.toBeUndefined()
+    expect(getProjectionMock).not.toHaveBeenCalled()
+  })
+
+  it('allows the run when usage is under the cap', async () => {
+    getProjectionMock.mockResolvedValue({ byMonth: { '2026-09': { totalTokens: 100 } } })
+    await expect(assertLlmUsageBudget({ workspaceId: 'ws-1', month: '2026-09' })).resolves.toBeUndefined()
+  })
+
+  it('allows the run when there is no usage recorded yet', async () => {
+    getProjectionMock.mockResolvedValue(null)
+    await expect(assertLlmUsageBudget({ workspaceId: 'ws-1' })).resolves.toBeUndefined()
+  })
+
+  it('fails closed with a 402 once the monthly cap is reached', async () => {
+    process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP = '1000'
+    getProjectionMock.mockResolvedValue({ byMonth: { '2026-09': { totalTokens: 1000 } } })
+
+    await expect(assertLlmUsageBudget({ workspaceId: 'ws-1', month: '2026-09' }))
+      .rejects.toMatchObject({
+        status: 402,
+        code: 'LLM_TOKEN_QUOTA_EXCEEDED',
+        workspaceId: 'ws-1',
+        limit: 1000,
+        used: 1000,
+      })
+  })
+
+  it('fails closed against the workspace-specific override, not the platform default', async () => {
+    process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP = '2000000'
+    ofMock.mockResolvedValue({ llmMonthlyTokenLimit: 100 })
+    getProjectionMock.mockResolvedValue({ byMonth: { '2026-09': { totalTokens: 100 } } })
+
+    await expect(assertLlmUsageBudget({ workspaceId: 'ws-1', month: '2026-09' }))
+      .rejects.toMatchObject({ code: 'LLM_TOKEN_QUOTA_EXCEEDED', limit: 100, used: 100 })
+  })
+})

package/src/metering/get-workspace-llm-usage.action.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/platform/actions/get-workspace-llm-usage',
+  access: 'workspace',
+  audit: false,
+}

package/src/metering/get-workspace-llm-usage.task.js

@@ -0,0 +1,31 @@
+import { getProjection } from '@ossy/event-store'
+import { LlmUsageProjection, currentUsageMonth } from './llm-usage.aggregate.js'
+import { resolveLlmMonthlyTokenLimit } from './assert-llm-usage-budget.js'
+
+export const metadata = {
+  id: '@ossy/platform/tasks/get-workspace-llm-usage',
+  audit: false,
+}
+
+/** @returns {{ requests: number, promptTokens: number, completionTokens: number, totalTokens: number, byModel: object }} */
+function emptyMonth () {
+  return { requests: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0, byModel: {} }
+}
+
+export async function run ({ payload, req }) {
+  const workspaceId = payload?.workspaceId ?? req?.workspaceId
+  if (!workspaceId) {
+    throw Object.assign(new Error('workspaceId required'), { status: 400 })
+  }
+
+  const month = currentUsageMonth(payload?.month)
+  const state = await getProjection(workspaceId, LlmUsageProjection.ProjectionId)
+  const bucket = state?.byMonth?.[month] ?? emptyMonth()
+
+  return {
+    workspaceId,
+    month,
+    ...bucket,
+    limit: await resolveLlmMonthlyTokenLimit(workspaceId),
+  }
+}

package/src/metering/get-workspace-llm-usage.task.spec.js

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const getProjectionMock = jest.fn()
+const ofMock = jest.fn(() => Promise.resolve({}))
+const viewMock = jest.fn(() => (state) => state)
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  getProjection: getProjectionMock,
+  Aggregate: { Of: ofMock, View: viewMock },
+}))
+
+jest.unstable_mockModule('@ossy/workspaces/server', () => ({
+  Workspace: {},
+}))
+
+const { run } = await import('./get-workspace-llm-usage.task.js')
+
+describe('get-workspace-llm-usage task', () => {
+  beforeEach(() => {
+    getProjectionMock.mockReset()
+    ofMock.mockReset()
+    ofMock.mockResolvedValue({})
+    delete process.env.LLM_WORKSPACE_MONTHLY_TOKEN_CAP
+  })
+
+  it('requires a workspaceId', async () => {
+    await expect(run({ payload: {} })).rejects.toMatchObject({ status: 400 })
+  })
+
+  it('returns a zeroed bucket for a workspace with no usage yet', async () => {
+    getProjectionMock.mockResolvedValue(null)
+    const result = await run({ payload: { workspaceId: 'ws-1', month: '2026-09' } })
+    expect(result).toMatchObject({
+      workspaceId: 'ws-1',
+      month: '2026-09',
+      requests: 0,
+      promptTokens: 0,
+      completionTokens: 0,
+      totalTokens: 0,
+      byModel: {},
+    })
+    expect(result.limit).toBeGreaterThan(0)
+  })
+
+  it('returns the current month bucket from the projection', async () => {
+    getProjectionMock.mockResolvedValue({
+      byMonth: {
+        '2026-09': {
+          requests: 3,
+          promptTokens: 300,
+          completionTokens: 60,
+          totalTokens: 360,
+          byModel: { 'openai/gpt-4o-mini': { requests: 3, promptTokens: 300, completionTokens: 60 } },
+        },
+      },
+    })
+
+    const result = await run({ req: { workspaceId: 'ws-1' }, payload: { month: '2026-09' } })
+    expect(result).toMatchObject({
+      workspaceId: 'ws-1',
+      month: '2026-09',
+      requests: 3,
+      totalTokens: 360,
+    })
+  })
+
+  it('reports the workspace-specific limit override when set', async () => {
+    getProjectionMock.mockResolvedValue(null)
+    ofMock.mockResolvedValue({ llmMonthlyTokenLimit: 750000 })
+
+    const result = await run({ payload: { workspaceId: 'ws-1' } })
+    expect(result.limit).toBe(750000)
+  })
+})

package/src/metering/get-workspace-task-metering.action.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/platform/actions/get-workspace-task-metering',
+  access: 'workspace',
+  audit: false,
+}

package/src/metering/get-workspace-task-metering.task.js

@@ -0,0 +1,30 @@
+import { getProjection } from '@ossy/event-store'
+import { TaskMeteringProjection } from './task-metering.aggregate.js'
+import { currentUsageMonth } from './usage-month.js'
+
+export const metadata = {
+  id: '@ossy/platform/tasks/get-workspace-task-metering',
+  audit: false,
+}
+
+/** @returns {{ requests: number, failures: number, durationMs: number, byModule: object }} */
+function emptyMonth () {
+  return { requests: 0, failures: 0, durationMs: 0, byModule: {} }
+}
+
+export async function run ({ payload, req }) {
+  const workspaceId = payload?.workspaceId ?? req?.workspaceId
+  if (!workspaceId) {
+    throw Object.assign(new Error('workspaceId required'), { status: 400 })
+  }
+
+  const month = currentUsageMonth(payload?.month)
+  const state = await getProjection(workspaceId, TaskMeteringProjection.ProjectionId)
+  const bucket = state?.byMonth?.[month] ?? emptyMonth()
+
+  return {
+    workspaceId,
+    month,
+    ...bucket,
+  }
+}

package/src/metering/get-workspace-task-metering.task.spec.js

@@ -0,0 +1,43 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const getProjectionMock = jest.fn()
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  getProjection: getProjectionMock,
+}))
+
+const { run } = await import('./get-workspace-task-metering.task.js')
+
+describe('get-workspace-task-metering task', () => {
+  beforeEach(() => {
+    getProjectionMock.mockReset()
+  })
+
+  it('requires a workspaceId', async () => {
+    await expect(run({ payload: {} })).rejects.toMatchObject({ status: 400 })
+  })
+
+  it('returns a zeroed bucket for a workspace with no task runs yet', async () => {
+    getProjectionMock.mockResolvedValue(null)
+    const result = await run({ payload: { workspaceId: 'ws-1', month: '2026-09' } })
+    expect(result).toEqual({
+      workspaceId: 'ws-1',
+      month: '2026-09',
+      requests: 0,
+      failures: 0,
+      durationMs: 0,
+      byModule: {},
+    })
+  })
+
+  it('returns the current month bucket from the projection', async () => {
+    getProjectionMock.mockResolvedValue({
+      byMonth: {
+        '2026-09': { requests: 12, failures: 1, durationMs: 4500, byModule: { '@ossy/media-tasks': { requests: 12, durationMs: 4500 } } },
+      },
+    })
+
+    const result = await run({ req: { workspaceId: 'ws-1' }, payload: { month: '2026-09' } })
+    expect(result).toMatchObject({ workspaceId: 'ws-1', month: '2026-09', requests: 12, durationMs: 4500 })
+  })
+})

package/src/metering/index.js

@@ -0,0 +1,11 @@
+export { MeteringService } from './metering-service.js'
+export { currentUsageMonth } from './usage-month.js'
+export { LlmUsageProjection } from './llm-usage.aggregate.js'
+export { TaskMeteringProjection } from './task-metering.aggregate.js'
+export {
+  DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP,
+  assertLlmUsageBudget,
+  llmWorkspaceMonthlyTokenCap,
+  resolveLlmMonthlyTokenLimit,
+  resolveWorkspaceIdForBudget,
+} from './assert-llm-usage-budget.js'

package/src/metering/llm-usage.aggregate.js

@@ -0,0 +1,127 @@
+import { currentUsageMonth } from './usage-month.js'
+
+export { currentUsageMonth }
+
+/**
+ * ADR 0017 — per-workspace LLM token usage, folded at write.
+ *
+ * Bounded, time-bucketed projection over `@ossy/platform/schema/meter-event`
+ * `Recorded` events. Only events carrying LLM usage (`promptTokens` /
+ * `completionTokens`, set via `TaskRunService` → `MeteringService.record()`
+ * when a task result includes `usage`) affect state — everything else is a
+ * no-op `Apply` (durationMs/success-only meter events for non-LLM tasks).
+ *
+ * Named generically (not after a specific provider) — today's LLM tasks
+ * (`run-prompt`, `visual-content-descriptors`) call OpenRouter, but nothing
+ * in this metering layer assumes that; swapping the provider integration
+ * later needs no rename here.
+ *
+ * Scope: one document per workspace. Snapshot size is bounded by
+ * months × distinct models, not one row per request — mirrors
+ * `@ossy/analytics`'s `PageViewLocationProjection` day-bucket shape.
+ *
+ * Read via `getProjection(workspaceId, LlmUsageProjection.ProjectionId)`
+ * (`@ossy/event-store`). This is the same data backing both the workspace
+ * settings dashboard stat and `assertLlmUsageBudget`'s hard cap check.
+ *
+ * See `TaskMeteringProjection` (`./task-metering.aggregate.js`) for the
+ * general, all-tasks count/duration counterpart to this LLM-specific one.
+ */
+export class LlmUsageProjection {
+
+  static kind = 'projection'
+  static ProjectionId = '@ossy/platform/data/llm-usage'
+
+  static sources = [
+    { type: '@ossy/platform/schema/meter-event', event: 'Recorded' },
+  ]
+
+  /**
+   * @param {object} event
+   * @returns {string | null}
+   */
+  static scopeFromEvent (event) {
+    const workspaceId = event.payload?.belongsTo ?? event.payload?.workspaceId
+    return typeof workspaceId === 'string' && workspaceId ? workspaceId : null
+  }
+
+  static cacheKeys (scopeId) {
+    return [
+      `projection:${LlmUsageProjection.ProjectionId}:${scopeId}`,
+      'action:@ossy/platform/actions/get-workspace-llm-usage',
+    ]
+  }
+
+  /**
+   * @param {string} scopeId workspaceId
+   */
+  static initialState (scopeId) {
+    return { workspaceId: scopeId, byMonth: {} }
+  }
+
+  /**
+   * @param {object} event
+   * @param {{ workspaceId?: string, byMonth?: Record<string, MonthBucket> }} state
+   * @returns {{ workspaceId: string, byMonth: Record<string, MonthBucket> }}
+   */
+  static Apply (event, state) {
+    const payload = event.payload ?? {}
+    const promptTokens = typeof payload.promptTokens === 'number' ? payload.promptTokens : null
+    const completionTokens = typeof payload.completionTokens === 'number' ? payload.completionTokens : null
+    if (promptTokens == null && completionTokens == null) {
+      // Not an LLM-usage meter event (e.g. a plain task/action record) — no-op.
+      return { workspaceId: state.workspaceId, byMonth: state.byMonth ?? {} }
+    }
+
+    const totalTokens = typeof payload.totalTokens === 'number'
+      ? payload.totalTokens
+      : (promptTokens ?? 0) + (completionTokens ?? 0)
+
+    const at = Number(event.created)
+    const month = new Date(Number.isFinite(at) && at > 0 ? at : Date.now()).toISOString().slice(0, 7)
+
+    const byMonth = { ...(state.byMonth ?? {}) }
+    const bucket = byMonth[month] ?? emptyBucket()
+    const modelKey = typeof payload.model === 'string' && payload.model ? payload.model : 'unknown'
+    const modelBucket = bucket.byModel[modelKey] ?? emptyModelBucket()
+
+    byMonth[month] = {
+      requests: bucket.requests + 1,
+      promptTokens: bucket.promptTokens + (promptTokens ?? 0),
+      completionTokens: bucket.completionTokens + (completionTokens ?? 0),
+      totalTokens: bucket.totalTokens + totalTokens,
+      byModel: {
+        ...bucket.byModel,
+        [modelKey]: {
+          requests: modelBucket.requests + 1,
+          promptTokens: modelBucket.promptTokens + (promptTokens ?? 0),
+          completionTokens: modelBucket.completionTokens + (completionTokens ?? 0),
+        },
+      },
+    }
+
+    return { workspaceId: state.workspaceId, byMonth }
+  }
+}
+
+/** @returns {MonthBucket} */
+function emptyBucket () {
+  return { requests: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0, byModel: {} }
+}
+
+function emptyModelBucket () {
+  return { requests: 0, promptTokens: 0, completionTokens: 0 }
+}
+
+/**
+ * @typedef {{
+ *   requests: number,
+ *   promptTokens: number,
+ *   completionTokens: number,
+ *   totalTokens: number,
+ *   byModel: Record<string, { requests: number, promptTokens: number, completionTokens: number }>,
+ * }} MonthBucket
+ */
+
+export { LlmUsageProjection as Aggregate }
+export const id = 'platform/data/llm-usage'

package/src/metering/llm-usage.aggregate.spec.js

@@ -0,0 +1,95 @@
+import { describe, expect, it } from '@jest/globals'
+import { LlmUsageProjection, currentUsageMonth } from './llm-usage.aggregate.js'
+
+describe('LlmUsageProjection', () => {
+  it('scopes by workspaceId (belongsTo)', () => {
+    expect(LlmUsageProjection.scopeFromEvent({ payload: { belongsTo: 'ws-1' } })).toBe('ws-1')
+    expect(LlmUsageProjection.scopeFromEvent({ payload: {} })).toBeNull()
+  })
+
+  it('is a no-op for meter events without token usage (non-LLM tasks)', () => {
+    const state = LlmUsageProjection.initialState('ws-1')
+    const next = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { kind: 'task', taskId: '@ossy/booking/tasks/confirm', durationMs: 12, success: true },
+    }, state)
+    expect(next).toEqual({ workspaceId: 'ws-1', byMonth: {} })
+  })
+
+  it('folds prompt/completion tokens into the event month, keyed by model', () => {
+    const state = LlmUsageProjection.initialState('ws-1')
+    const next = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: {
+        belongsTo: 'ws-1',
+        model: 'openai/gpt-4o-mini',
+        promptTokens: 100,
+        completionTokens: 20,
+        totalTokens: 120,
+      },
+    }, state)
+
+    expect(next.byMonth['2026-09']).toEqual({
+      requests: 1,
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+      byModel: {
+        'openai/gpt-4o-mini': { requests: 1, promptTokens: 100, completionTokens: 20 },
+      },
+    })
+  })
+
+  it('accumulates across requests and models within the same month', () => {
+    const first = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'openai/gpt-4o-mini', promptTokens: 100, completionTokens: 20 },
+    }, LlmUsageProjection.initialState('ws-1'))
+
+    const second = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-20T08:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'google/gemini-2.5-flash-lite', promptTokens: 50, completionTokens: 10 },
+    }, first)
+
+    expect(second.byMonth['2026-09']).toEqual({
+      requests: 2,
+      promptTokens: 150,
+      completionTokens: 30,
+      totalTokens: 180,
+      byModel: {
+        'openai/gpt-4o-mini': { requests: 1, promptTokens: 100, completionTokens: 20 },
+        'google/gemini-2.5-flash-lite': { requests: 1, promptTokens: 50, completionTokens: 10 },
+      },
+    })
+  })
+
+  it('buckets separately across months', () => {
+    const first = LlmUsageProjection.Apply({
+      created: Date.parse('2026-08-31T23:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'openai/gpt-4o-mini', promptTokens: 100, completionTokens: 20 },
+    }, LlmUsageProjection.initialState('ws-1'))
+
+    const second = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-01T01:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'openai/gpt-4o-mini', promptTokens: 5, completionTokens: 1 },
+    }, first)
+
+    expect(Object.keys(second.byMonth).sort()).toEqual(['2026-08', '2026-09'])
+    expect(second.byMonth['2026-08'].totalTokens).toBe(120)
+    expect(second.byMonth['2026-09'].totalTokens).toBe(6)
+  })
+
+  it('invalidates the workspace usage action cache', () => {
+    expect(LlmUsageProjection.cacheKeys('ws-1')).toEqual([
+      'projection:@ossy/platform/data/llm-usage:ws-1',
+      'action:@ossy/platform/actions/get-workspace-llm-usage',
+    ])
+  })
+})
+
+describe('currentUsageMonth', () => {
+  it('passes through an explicit month, else defaults to the current UTC month', () => {
+    expect(currentUsageMonth('2026-01')).toBe('2026-01')
+    expect(currentUsageMonth()).toBe(new Date().toISOString().slice(0, 7))
+  })
+})

package/src/metering/metering-service.js

@@ -23,6 +23,10 @@ export const MeteringService = {
    *   actionInvocationId?: string | null,
    *   taskRunId?: string | null,
    *   trigger?: string | null,
+   *   model?: string | null,
+   *   promptTokens?: number | null,
+   *   completionTokens?: number | null,
+   *   totalTokens?: number | null,
    * }} record
    */
   async record (record) {
@@ -38,6 +42,10 @@ export const MeteringService = {
       actionInvocationId = null,
       taskRunId = null,
       trigger = null,
+      model = null,
+      promptTokens = null,
+      completionTokens = null,
+      totalTokens = null,
     } = record
 
     const moduleId = taskId
@@ -59,6 +67,11 @@ export const MeteringService = {
       actionInvocationId,
       taskRunId,
       trigger,
+      // ADR 0017 — optional LLM/usage-metering fields; null for non-metered runs.
+      model,
+      promptTokens,
+      completionTokens,
+      totalTokens,
       recordedAt: Date.now(),
     }
 

package/src/metering/metering-service.spec.js

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const appendResourceEventMock = jest.fn().mockResolvedValue(undefined)
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  EventStore: { AppendResourceEvent: appendResourceEventMock },
+}))
+
+jest.unstable_mockModule('@ossy/observability', () => ({
+  createLogger: () => ({ debug () {}, info () {}, warn () {}, error () {} }),
+  metrics: { increment () {}, timing () {} },
+}))
+
+const { MeteringService } = await import('./metering-service.js')
+
+describe('MeteringService.record', () => {
+  beforeEach(() => {
+    appendResourceEventMock.mockClear()
+  })
+
+  it('defaults usage fields to null for a plain task/action record', async () => {
+    await MeteringService.record({
+      kind: 'task',
+      taskId: '@ossy/booking/tasks/confirm',
+      workspaceId: 'ws-1',
+      durationMs: 12,
+      success: true,
+    })
+
+    expect(appendResourceEventMock).toHaveBeenCalledTimes(1)
+    const [{ payload }] = appendResourceEventMock.mock.calls[0]
+    expect(payload).toMatchObject({
+      model: null,
+      promptTokens: null,
+      completionTokens: null,
+      totalTokens: null,
+    })
+  })
+
+  it('carries model/token usage onto the meter-event payload', async () => {
+    await MeteringService.record({
+      kind: 'task',
+      taskId: '@ossy/media-tasks/tasks/run-prompt',
+      workspaceId: 'ws-1',
+      durationMs: 800,
+      success: true,
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+    })
+
+    const [{ payload }] = appendResourceEventMock.mock.calls[0]
+    expect(payload).toMatchObject({
+      belongsTo: 'ws-1',
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+    })
+  })
+})

package/src/metering/task-metering.aggregate.js

@@ -0,0 +1,108 @@
+import { currentUsageMonth } from './usage-month.js'
+
+export { currentUsageMonth }
+
+/**
+ * ADR 0017 (amendment) — general, all-tasks execution volume per workspace,
+ * folded at write. Where `LlmUsageProjection` only folds meter events
+ * carrying LLM token usage, this folds **every** `kind: 'task'` meter event
+ * `MeteringService.record()` writes — regardless of whether the task used
+ * an LLM — into a bounded, monthly-bucketed count + total execution
+ * time. Intended as a second, non-token billing dimension ("how much
+ * automation did this workspace run") independent of AI usage.
+ *
+ * Snapshot size is bounded by months × distinct modules, mirroring
+ * `LlmUsageProjection` / `@ossy/analytics`'s day-bucket shape.
+ */
+export class TaskMeteringProjection {
+
+  static kind = 'projection'
+  static ProjectionId = '@ossy/platform/data/task-metering'
+
+  static sources = [
+    { type: '@ossy/platform/schema/meter-event', event: 'Recorded' },
+  ]
+
+  /**
+   * @param {object} event
+   * @returns {string | null}
+   */
+  static scopeFromEvent (event) {
+    const workspaceId = event.payload?.belongsTo ?? event.payload?.workspaceId
+    return typeof workspaceId === 'string' && workspaceId ? workspaceId : null
+  }
+
+  static cacheKeys (scopeId) {
+    return [
+      `projection:${TaskMeteringProjection.ProjectionId}:${scopeId}`,
+      'action:@ossy/platform/actions/get-workspace-task-metering',
+    ]
+  }
+
+  /**
+   * @param {string} scopeId workspaceId
+   */
+  static initialState (scopeId) {
+    return { workspaceId: scopeId, byMonth: {} }
+  }
+
+  /**
+   * @param {object} event
+   * @param {{ workspaceId?: string, byMonth?: Record<string, TaskMonthBucket> }} state
+   * @returns {{ workspaceId: string, byMonth: Record<string, TaskMonthBucket> }}
+   */
+  static Apply (event, state) {
+    const payload = event.payload ?? {}
+    if (payload.kind !== 'task') {
+      // Action invocations are metered too, but this dimension is task
+      // execution volume only.
+      return { workspaceId: state.workspaceId, byMonth: state.byMonth ?? {} }
+    }
+
+    const at = Number(event.created)
+    const month = new Date(Number.isFinite(at) && at > 0 ? at : Date.now()).toISOString().slice(0, 7)
+
+    const byMonth = { ...(state.byMonth ?? {}) }
+    const bucket = byMonth[month] ?? emptyBucket()
+    const moduleKey = typeof payload.moduleId === 'string' && payload.moduleId ? payload.moduleId : 'unknown'
+    const moduleBucket = bucket.byModule[moduleKey] ?? emptyModuleBucket()
+    const durationMs = typeof payload.durationMs === 'number' ? payload.durationMs : 0
+    const failed = payload.success === false
+
+    byMonth[month] = {
+      requests: bucket.requests + 1,
+      failures: bucket.failures + (failed ? 1 : 0),
+      durationMs: bucket.durationMs + durationMs,
+      byModule: {
+        ...bucket.byModule,
+        [moduleKey]: {
+          requests: moduleBucket.requests + 1,
+          durationMs: moduleBucket.durationMs + durationMs,
+        },
+      },
+    }
+
+    return { workspaceId: state.workspaceId, byMonth }
+  }
+}
+
+/** @returns {TaskMonthBucket} */
+function emptyBucket () {
+  return { requests: 0, failures: 0, durationMs: 0, byModule: {} }
+}
+
+function emptyModuleBucket () {
+  return { requests: 0, durationMs: 0 }
+}
+
+/**
+ * @typedef {{
+ *   requests: number,
+ *   failures: number,
+ *   durationMs: number,
+ *   byModule: Record<string, { requests: number, durationMs: number }>,
+ * }} TaskMonthBucket
+ */
+
+export { TaskMeteringProjection as Aggregate }
+export const id = 'platform/data/task-metering'

package/src/metering/task-metering.aggregate.spec.js

@@ -0,0 +1,71 @@
+import { describe, expect, it } from '@jest/globals'
+import { TaskMeteringProjection } from './task-metering.aggregate.js'
+import { currentUsageMonth } from './usage-month.js'
+
+describe('TaskMeteringProjection', () => {
+  it('scopes by workspaceId (belongsTo)', () => {
+    expect(TaskMeteringProjection.scopeFromEvent({ payload: { belongsTo: 'ws-1' } })).toBe('ws-1')
+    expect(TaskMeteringProjection.scopeFromEvent({ payload: {} })).toBeNull()
+  })
+
+  it('is a no-op for action-kind meter events (task execution volume only)', () => {
+    const state = TaskMeteringProjection.initialState('ws-1')
+    const next = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { kind: 'action', actionId: '@ossy/booking/actions/create', durationMs: 12 },
+    }, state)
+    expect(next).toEqual({ workspaceId: 'ws-1', byMonth: {} })
+  })
+
+  it('counts every task run and sums duration, regardless of success', () => {
+    const first = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { kind: 'task', taskId: '@ossy/media-tasks/tasks/run-prompt', moduleId: '@ossy/media-tasks', durationMs: 800, success: true },
+    }, TaskMeteringProjection.initialState('ws-1'))
+
+    const second = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-20T08:00:00.000Z'),
+      payload: { kind: 'task', taskId: '@ossy/booking/tasks/confirm', moduleId: '@ossy/booking', durationMs: 50, success: false },
+    }, first)
+
+    expect(second.byMonth['2026-09']).toEqual({
+      requests: 2,
+      failures: 1,
+      durationMs: 850,
+      byModule: {
+        '@ossy/media-tasks': { requests: 1, durationMs: 800 },
+        '@ossy/booking': { requests: 1, durationMs: 50 },
+      },
+    })
+  })
+
+  it('buckets separately across months', () => {
+    const first = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-08-31T23:00:00.000Z'),
+      payload: { kind: 'task', moduleId: '@ossy/media-tasks', durationMs: 100, success: true },
+    }, TaskMeteringProjection.initialState('ws-1'))
+
+    const second = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-01T01:00:00.000Z'),
+      payload: { kind: 'task', moduleId: '@ossy/media-tasks', durationMs: 20, success: true },
+    }, first)
+
+    expect(Object.keys(second.byMonth).sort()).toEqual(['2026-08', '2026-09'])
+    expect(second.byMonth['2026-08'].durationMs).toBe(100)
+    expect(second.byMonth['2026-09'].durationMs).toBe(20)
+  })
+
+  it('invalidates the workspace task-metering action cache', () => {
+    expect(TaskMeteringProjection.cacheKeys('ws-1')).toEqual([
+      'projection:@ossy/platform/data/task-metering:ws-1',
+      'action:@ossy/platform/actions/get-workspace-task-metering',
+    ])
+  })
+})
+
+describe('currentUsageMonth (re-exported)', () => {
+  it('passes through an explicit month, else defaults to the current UTC month', () => {
+    expect(currentUsageMonth('2026-01')).toBe('2026-01')
+    expect(currentUsageMonth()).toBe(new Date().toISOString().slice(0, 7))
+  })
+})

package/src/metering/usage-month.js

@@ -0,0 +1,7 @@
+/**
+ * @param {string} [month] `YYYY-MM`; defaults to the current UTC month.
+ * @returns {string}
+ */
+export function currentUsageMonth (month) {
+  return typeof month === 'string' && month ? month : new Date().toISOString().slice(0, 7)
+}

package/src/runtime.js

@@ -12,6 +12,7 @@ import { loadSite, invalidateSite } from './site-loader.js'
 import { createLogger } from '@ossy/observability'
 import { mountHealthEndpoint } from './health.js'
 import { readWorkspaceIdFromCookies } from './user-app-settings.js'
+import { detectMobileDevice } from './ssr/detect-mobile-device.js'
 
 const log = createLogger('platform')
 
@@ -214,6 +215,7 @@ export async function startRuntime ({ port } = {}) {
         taskGraphEdges: cloneSerializable(manifest.taskGraphEdges || []),
         url: requestUrl,
         isAuthenticated: !!req.isAuthenticated,
+        isMobileDevice: detectMobileDevice(req),
         language,
         messages: cloneSerializable(messages),
         ...(fallbackMessages ? { fallbackMessages: cloneSerializable(fallbackMessages) } : {}),

package/src/server.js

@@ -37,6 +37,7 @@ import {
   withTimeout,
 } from './request-diagnostics.js'
 import { mergeWorkspaceSchemas } from '@ossy/workspaces/merge-workspace-schemas'
+import { detectMobileDevice } from './ssr/detect-mobile-device.js'
 import {
   buildEnableablePackageSet,
   setEnableablePackages,
@@ -578,6 +579,7 @@ export async function startServer (options = {}) {
           taskGraphEdges: cloneSerializable(manifest.taskGraphEdges || []),
           url: requestUrl,
           isAuthenticated: !!req.isAuthenticated,
+          isMobileDevice: detectMobileDevice(req),
           language,
           messages: cloneSerializable(messages),
           ...(fallbackMessages ? { fallbackMessages: cloneSerializable(fallbackMessages) } : {}),

package/src/ssr/detect-mobile-device.js

@@ -0,0 +1,39 @@
+/**
+ * SSR device detection for the app shell (fixes #871 — desktop sidenav
+ * flashing on mobile because SSR always assumed a desktop viewport).
+ *
+ * Primary signal: the `Sec-CH-UA-Mobile` client hint (Chromium browsers
+ * send it on every request once `Accept-CH` opts in, no round trip needed).
+ * It is a structured boolean: `?1` (mobile) or `?0` (desktop).
+ *
+ * Fallback: a `User-Agent` regex for browsers that don't send the client
+ * hint (Safari, Firefox). This is a best-effort guess only — the client
+ * still re-resolves the real value via `matchMedia` after mount.
+ */
+
+const MOBILE_USER_AGENT_PATTERN = /Mobi|Android|iPhone|iPad|iPod/i
+
+/**
+ * @param {string | undefined | null} headerValue raw `Sec-CH-UA-Mobile` header value
+ * @returns {boolean | null} `true`/`false` when the hint is present, `null` when absent/malformed
+ */
+export function parseSecChUaMobile (headerValue) {
+  if (typeof headerValue !== 'string') return null
+  const trimmed = headerValue.trim()
+  if (trimmed === '?1') return true
+  if (trimmed === '?0') return false
+  return null
+}
+
+/**
+ * @param {import('express').Request | undefined} req
+ * @returns {boolean} best-effort guess of whether the request came from a mobile device
+ */
+export function detectMobileDevice (req) {
+  const secChUaMobile = req?.headers?.['sec-ch-ua-mobile'] ?? req?.get?.('Sec-CH-UA-Mobile')
+  const hinted = parseSecChUaMobile(secChUaMobile)
+  if (hinted !== null) return hinted
+
+  const userAgent = req?.headers?.['user-agent'] ?? req?.get?.('User-Agent') ?? ''
+  return MOBILE_USER_AGENT_PATTERN.test(userAgent)
+}

package/src/ssr/detect-mobile-device.spec.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from '@jest/globals'
+import { detectMobileDevice, parseSecChUaMobile } from './detect-mobile-device.js'
+
+describe('parseSecChUaMobile', () => {
+  it('returns true for the mobile client hint', () => {
+    expect(parseSecChUaMobile('?1')).toBe(true)
+  })
+
+  it('returns false for the desktop client hint', () => {
+    expect(parseSecChUaMobile('?0')).toBe(false)
+  })
+
+  it('returns null when the header is missing or malformed', () => {
+    expect(parseSecChUaMobile(undefined)).toBeNull()
+    expect(parseSecChUaMobile(null)).toBeNull()
+    expect(parseSecChUaMobile('')).toBeNull()
+    expect(parseSecChUaMobile('mobile')).toBeNull()
+  })
+
+  it('tolerates surrounding whitespace', () => {
+    expect(parseSecChUaMobile(' ?1 ')).toBe(true)
+  })
+})
+
+describe('detectMobileDevice', () => {
+  it('prefers the Sec-CH-UA-Mobile client hint when present', () => {
+    const req = { headers: { 'sec-ch-ua-mobile': '?1', 'user-agent': 'Mozilla/5.0 (Windows NT 10.0)' } }
+    expect(detectMobileDevice(req)).toBe(true)
+  })
+
+  it('falls back to sniffing User-Agent when the client hint is absent (e.g. Safari/Firefox)', () => {
+    const req = { headers: { 'user-agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit' } }
+    expect(detectMobileDevice(req)).toBe(true)
+  })
+
+  it('treats desktop User-Agents as non-mobile when the client hint is absent', () => {
+    const req = { headers: { 'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit' } }
+    expect(detectMobileDevice(req)).toBe(false)
+  })
+
+  it('supports Express-style req.get(...) as a fallback lookup', () => {
+    const req = { headers: {}, get: (name) => (name === 'Sec-CH-UA-Mobile' ? '?1' : undefined) }
+    expect(detectMobileDevice(req)).toBe(true)
+  })
+
+  it('defaults to false when no request or headers are available', () => {
+    expect(detectMobileDevice(undefined)).toBe(false)
+    expect(detectMobileDevice({})).toBe(false)
+  })
+})

package/src/text-completion.schema.js

@@ -0,0 +1,37 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
+/**
+ * Platform schema for freeform text/Markdown LLM completion artifacts.
+ *
+ * Any task that produces unstructured prose (a chat completion, a
+ * generated summary, …) placed as a document should declare this schema
+ * as its output `schemaId` instead of inventing a feature-specific one.
+ * Structured JSON results (e.g. `{ title, tags, alt }`) still get their
+ * own feature schema — this one is only for the "freeform text/md" shape.
+ *
+ * See `docs/concepts/TaskOutput.md`.
+ */
+export default {
+  id: '@ossy/platform/schema/text-completion',
+  name: 'Text completion',
+  categoryName: 'Platform',
+  icon: 'comment',
+  fields: [
+    {
+      name: 'text',
+      type: 'textarea',
+      description: 'Model completion (freeform text/Markdown)',
+    },
+    {
+      name: 'model',
+      type: 'text',
+      description: 'Model slug that produced the completion',
+    },
+    {
+      name: 'prompt',
+      type: 'textarea',
+      description: 'Prompt that was sent, before resource context',
+    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
+  ],
+}