@ossy/platform 3.15.0 → 3.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.15.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.15.0",
+    "@ossy/manifest": "^3.17.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/router": "^3.0.9",
-    "@ossy/schema": "^3.15.0",
-    "@ossy/sdk": "^3.12.0",
+    "@ossy/schema": "^3.17.0",
+    "@ossy/sdk": "^3.17.0",
     "@ossy/tokens": "^3.11.1",
-    "@ossy/users": "^3.15.0",
-    "@ossy/workspaces": "^3.15.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": "23517232ddc4f2c64ca0062faa3cad84ceaa34a7"
+  "gitHead": "91ff7dffe9b0bddcb823daee67213d2008eb64e9"
 }

package/src/audit/audit-helpers.js

@@ -19,14 +19,68 @@ export function hashPayload (payload) {
 /** Keep event payloads small — full task results stay outside the audit stream. */
 export function summarizeResult (result) {
   if (result == null) return null
-  if (typeof result !== 'object') {
-    return { kind: typeof result, preview: String(result).slice(0, 200) }
+  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.
+ *
+ * @param {unknown} inputs
+ * @returns {object | undefined}
+ */
+export function summarizeInputs (inputs) {
+  if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) return undefined
+  if (!Object.keys(inputs).length) return undefined
+  const preview = previewValue(inputs, 0)
+  if (!preview || typeof preview !== 'object' || Array.isArray(preview)) return undefined
+  if (!Object.keys(preview).length) return undefined
+  return preview
+}
+
+function previewValue (value, depth) {
+  if (value == null || typeof value !== 'object') {
+    if (typeof value === 'string' && value.length > 240) return `${value.slice(0, 240)}…`
+    return value
+  }
+  if (depth >= 4) {
+    return Array.isArray(value)
+      ? { kind: 'array', length: value.length }
+      : { kind: 'object', keyCount: Object.keys(value).length }
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 12).map((item) => previewValue(item, depth + 1))
   }
-  if (Array.isArray(result)) {
-    return { kind: 'array', length: result.length }
+  const preview = {}
+  for (const key of Object.keys(value).slice(0, 24)) {
+    preview[key] = previewValue(value[key], depth + 1)
   }
-  const keys = Object.keys(result)
-  return { kind: 'object', keys: keys.slice(0, 20), keyCount: keys.length }
+  return preview
 }
 
 /** @param {Error | { message?: string, code?: string }} error */

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-list.aggregate.js

@@ -42,6 +42,7 @@ export class TaskRunListProjection {
     if (event.event === 'Started') {
       entry.status = 'in progress'
       entry.startedAt = event.created
+      entry.triggeredBy = event.payload.triggeredBy ?? null
       runs.unshift(entry)
       return { workspaceId, runs: runs.slice(0, 200) }
     }
@@ -54,6 +55,7 @@ export class TaskRunListProjection {
         startedAt: event.created,
         completedAt: event.created,
         durationMs: event.payload.durationMs,
+        ...(event.payload.inputs ? { inputs: event.payload.inputs } : {}),
       })
       return { workspaceId, runs: runs.slice(0, 200) }
     }
@@ -66,6 +68,7 @@ export class TaskRunListProjection {
       durationMs: event.payload.durationMs,
       error: event.event === 'Failed' ? event.payload.error : undefined,
       resultSummary: event.event === 'Completed' ? event.payload.resultSummary : undefined,
+      ...(event.payload.inputs ? { inputs: event.payload.inputs } : {}),
     }
 
     return { workspaceId, runs }

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

@@ -9,7 +9,9 @@ import {
   resolveActorId,
   resolveWorkspaceId,
   summarizeError,
+  summarizeInputs,
   summarizeResult,
+  extractUsage,
 } from './audit-helpers.js'
 import { rejectOnAbort } from '../request-diagnostics.js'
 
@@ -105,8 +107,10 @@ export const TaskRunService = {
         actorId,
         durationMs,
         resultSummary: summarizeResult(result),
+        inputs: summarizeInputs(context.inputs),
       })
       recordTaskMetrics(taskId, durationMs)
+      const usage = extractUsage(result)
       await MeteringService.record({
         kind: 'task',
         actionId: context.actionId ?? null,
@@ -119,6 +123,7 @@ export const TaskRunService = {
         actionInvocationId: context.actionInvocationId ?? null,
         taskRunId: runId,
         trigger,
+        ...(usage ?? {}),
       })
       return result
     } catch (error) {
@@ -130,6 +135,7 @@ export const TaskRunService = {
         actorId,
         durationMs,
         error: summarizeError(error),
+        inputs: summarizeInputs(context.inputs),
       })
       recordTaskMetrics(taskId, durationMs)
       await MeteringService.record({
@@ -193,7 +199,7 @@ export const TaskRunService = {
     }
   },
 
-  async _appendCompleted ({ runId, taskId, workspaceId, actorId, durationMs, resultSummary }) {
+  async _appendCompleted ({ runId, taskId, workspaceId, actorId, durationMs, resultSummary, inputs }) {
     try {
       await Aggregate.Of(TaskRun, runId)
         .then(Aggregate.Add({
@@ -202,6 +208,7 @@ export const TaskRunService = {
           payload: {
             durationMs,
             resultSummary,
+            ...(inputs ? { inputs } : {}),
             ...taskRunScopePayload({ taskId, workspaceId }),
           },
         }))
@@ -210,7 +217,7 @@ export const TaskRunService = {
     }
   },
 
-  async _appendFailed ({ runId, taskId, workspaceId, actorId, durationMs, error }) {
+  async _appendFailed ({ runId, taskId, workspaceId, actorId, durationMs, error, inputs }) {
     try {
       await Aggregate.Of(TaskRun, runId)
         .then(Aggregate.Add({
@@ -219,6 +226,7 @@ export const TaskRunService = {
           payload: {
             durationMs,
             error,
+            ...(inputs ? { inputs } : {}),
             ...taskRunScopePayload({ taskId, workspaceId }),
           },
         }))

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

@@ -36,6 +36,7 @@ export class TaskRun {
             completedAt: event.created,
             durationMs: event.payload.durationMs,
             resultSummary: event.payload.resultSummary ?? null,
+            ...(event.payload.inputs ? { inputs: event.payload.inputs } : {}),
           }
 
         case 'Failed':
@@ -45,6 +46,7 @@ export class TaskRun {
             completedAt: event.created,
             durationMs: event.payload.durationMs,
             error: event.payload.error ?? null,
+            ...(event.payload.inputs ? { inputs: event.payload.inputs } : {}),
           }
 
         default:

package/src/file.schema.js

@@ -7,9 +7,5 @@ export default {
     { name: 'Key', type: 'text' },
     { name: 'ContentLength', type: 'number' },
     { name: 'ContentType', type: 'text' },
-    // Populated async by @ossy/media-tasks/tasks/resize-common-web
-    { name: 'blurhash', type: 'text' },
-    { name: 'width', type: 'number' },
-    { name: 'height', type: 'number' },
   ],
 }

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,
+  }
+}