@ossy/media-tasks 3.16.0 → 3.17.0

package/README.md

@@ -25,7 +25,7 @@ All four set **`configurable: true`**. Workspaces arm them on `/automation` with
 | extract-colors | `palette` | `@ossy/media-tasks/schema/extract-colors` |
 | resize-common-web | `sizes` (+ binary keys) | `@ossy/media-tasks/schema/resize-common-web` (JSON meta placed; binaries via URL) |
 | visual-content-descriptors | `descriptors` | `@ossy/media-tasks/schema/visual-content-descriptors` |
-| run-prompt | `completion` | `@ossy/media-tasks/schema/run-prompt` |
+| run-prompt | `completion` | `@ossy/platform/schema/text-completion` (freeform text/md — a platform schema, not feature-owned) |
 
 See [TaskOutput.md](../../docs/concepts/TaskOutput.md).
 
@@ -61,6 +61,12 @@ OpenRouter is OpenAI-compatible (`baseURL` `https://openrouter.ai/api/v1`). The
 
 `run-prompt` sends the resolved prompt as the user message. A matching file is appended as context (text/JSON excerpt, or an image data URL). A Markdown document (`@ossy/resources/schema/markdown`) sends `content.body` instead. The completion is stored at `{resourceId}:task-run-prompt-completion` and placed only when the workspace set a folder. **Run now** invokes `@ossy/media-tasks/actions/run-prompt` with the editor values; without a resource id the completion is returned on the task run and not stored.
 
+## Usage metering and a monthly token cap (ADR 0017)
+
+Both OpenRouter tasks read `response.usage` and return it as `result.usage = { model, promptTokens, completionTokens, totalTokens }`. `TaskRunService` forwards this onto `MeteringService.record()` automatically (any task returning `result.usage` in this shape gets metered — no per-task wiring needed).
+
+Before calling OpenRouter, each task calls `assertLlmUsageBudget()` (`@ossy/platform/metering`) — a **hard, fail-closed** monthly token cap **per workspace** (`LLM_WORKSPACE_MONTHLY_TOKEN_CAP` env var default `2_000_000`, overridable per workspace via `@ossy/workspaces/actions/set-llm-monthly-token-limit`). Once a workspace crosses its effective limit, further runs throw `{ status: 402, code: 'LLM_TOKEN_QUOTA_EXCEEDED' }` — no OpenRouter call made, no tokens spent. Named generically, not after OpenRouter specifically, so swapping the provider later needs no rename. See `docs/adr/0017-llm-usage-metering-and-quota.md`.
+
 ## Dependencies
 
 - **`sharp`** (peer) — image resizing + metadata

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/media-tasks",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Changestream-triggered media processing tasks (image resize, AI descriptors, prompts)",
   "type": "module",
   "main": "./src/index.js",
@@ -17,7 +17,9 @@
   },
   "dependencies": {
     "@ossy/observability": "^3.0.9",
-    "@ossy/resources": "^3.16.0",
+    "@ossy/platform": "^3.17.0",
+    "@ossy/resources": "^3.17.0",
+    "@ossy/schema": "^3.17.0",
     "blurhash": "^2.0.5"
   },
   "peerDependencies": {
@@ -34,5 +36,5 @@
   ],
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
   "license": "MIT",
-  "gitHead": "1872fb1467bf656284aae35881c34960c3860807"
+  "gitHead": "91ff7dffe9b0bddcb823daee67213d2008eb64e9"
 }

package/src/extract-colors.schema.js

@@ -1,3 +1,5 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
 export default {
   name: 'Extract Colors',
   id: '@ossy/media-tasks/schema/extract-colors',
@@ -14,30 +16,6 @@ export default {
       type: 'textarea',
       description: 'Palette entries as JSON ({ hex, ratio }[])',
     },
-    {
-      name: 'derivedFrom',
-      type: 'text',
-      description: 'Source resource id this output was derived from',
-    },
-    {
-      name: 'taskId',
-      type: 'text',
-      description: 'Task that produced this resource',
-    },
-    {
-      name: 'artifactName',
-      type: 'text',
-      description: 'Named task output',
-    },
-    {
-      name: 'artifactKey',
-      type: 'text',
-      description: 'Storage key for the artifact bytes/JSON',
-    },
-    {
-      name: 'artifactHref',
-      type: 'text',
-      description: 'Stable /r/…/tasks/… read path',
-    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
   ],
 }

package/src/llm-usage.js

@@ -0,0 +1,21 @@
+/**
+ * OpenRouter (OpenAI-compatible) chat completions return token usage as
+ * `response.usage = { prompt_tokens, completion_tokens, total_tokens }`.
+ * Callers echo this back on their result as `usage` so it flows through
+ * `TaskRunService` → `MeteringService` generically (see ADR 0017).
+ *
+ * @param {{ usage?: { prompt_tokens?: number, completion_tokens?: number, total_tokens?: number }, model?: string } | null | undefined} response
+ * @param {string} fallbackModel Model slug requested, used when the response omits `model`.
+ * @returns {{ model: string, promptTokens: number | null, completionTokens: number | null, totalTokens: number | null }}
+ */
+export function usageFromResponse (response, fallbackModel) {
+  const model = typeof response?.model === 'string' && response.model ? response.model : fallbackModel
+  const usage = response?.usage
+  const promptTokens = typeof usage?.prompt_tokens === 'number' ? usage.prompt_tokens : null
+  const completionTokens = typeof usage?.completion_tokens === 'number' ? usage.completion_tokens : null
+  const totalTokens = typeof usage?.total_tokens === 'number'
+    ? usage.total_tokens
+    : (promptTokens != null || completionTokens != null ? (promptTokens ?? 0) + (completionTokens ?? 0) : null)
+
+  return { model, promptTokens, completionTokens, totalTokens }
+}

package/src/llm-usage.spec.js

@@ -0,0 +1,41 @@
+import { usageFromResponse } from './llm-usage.js'
+
+describe('usageFromResponse', () => {
+  it('reads prompt/completion/total tokens and the model that answered', () => {
+    expect(usageFromResponse({
+      model: 'openai/gpt-4o-mini-2024-07-18',
+      usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+    }, 'openai/gpt-4o-mini')).toEqual({
+      model: 'openai/gpt-4o-mini-2024-07-18',
+      promptTokens: 10,
+      completionTokens: 5,
+      totalTokens: 15,
+    })
+  })
+
+  it('derives totalTokens when the response omits it', () => {
+    expect(usageFromResponse({
+      usage: { prompt_tokens: 10, completion_tokens: 5 },
+    }, 'openai/gpt-4o-mini')).toEqual({
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 10,
+      completionTokens: 5,
+      totalTokens: 15,
+    })
+  })
+
+  it('falls back to the requested model and nulls when usage is missing', () => {
+    expect(usageFromResponse({}, 'openai/gpt-4o-mini')).toEqual({
+      model: 'openai/gpt-4o-mini',
+      promptTokens: null,
+      completionTokens: null,
+      totalTokens: null,
+    })
+    expect(usageFromResponse(null, 'openai/gpt-4o-mini')).toEqual({
+      model: 'openai/gpt-4o-mini',
+      promptTokens: null,
+      completionTokens: null,
+      totalTokens: null,
+    })
+  })
+})

package/src/resize-common-web.schema.js

@@ -1,3 +1,5 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
 export default {
   name: 'Resize Common Web',
   id: '@ossy/media-tasks/schema/resize-common-web',
@@ -24,30 +26,6 @@ export default {
       type: 'textarea',
       description: 'Named derivative artifacts (thumbnail/gallery sizes)',
     },
-    {
-      name: 'derivedFrom',
-      type: 'text',
-      description: 'Source resource id this output was derived from',
-    },
-    {
-      name: 'taskId',
-      type: 'text',
-      description: 'Task that produced this resource',
-    },
-    {
-      name: 'artifactName',
-      type: 'text',
-      description: 'Named task output',
-    },
-    {
-      name: 'artifactKey',
-      type: 'text',
-      description: 'Storage key for the artifact bytes/JSON',
-    },
-    {
-      name: 'artifactHref',
-      type: 'text',
-      description: 'Stable /r/…/tasks/… read path',
-    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
   ],
 }

package/src/run-prompt.js

@@ -1,3 +1,5 @@
+import { usageFromResponse } from './llm-usage.js'
+
 /** Default OpenRouter model for freeform completions. */
 export const DEFAULT_RUN_PROMPT_MODEL = 'openai/gpt-4o-mini'
 
@@ -73,14 +75,12 @@ export function resourceContextText ({ name, contentType, text } = {}) {
 
 /**
  * @param {import('openai').OpenAI} client
- * @param {{
- *   prompt: string,
- *   model?: string,
- *   temperature?: number,
- *   contextText?: string,
- *   imageUrl?: string,
- * }} opts
- * @returns {Promise<{ text: string, model: string }>}
+ * @param {{ prompt: string, model?: string, temperature?: number, contextText?: string, imageUrl?: string }} opts
+ * @returns {Promise<{
+ *   text: string,
+ *   model: string,
+ *   usage: { model: string, promptTokens: number | null, completionTokens: number | null, totalTokens: number | null },
+ * }>}
  */
 export async function runOpenRouterPrompt (client, opts = {}) {
   if (!client?.chat?.completions?.create) {
@@ -116,8 +116,11 @@ export async function runOpenRouterPrompt (client, opts = {}) {
     throw new Error('run-prompt: model returned an empty completion')
   }
 
+  const usage = usageFromResponse(response, model)
+
   return {
     text: completion,
-    model: typeof response?.model === 'string' && response.model ? response.model : model,
+    model: usage.model,
+    usage,
   }
 }

package/src/run-prompt.spec.js

@@ -79,13 +79,40 @@ describe('runOpenRouterPrompt', () => {
       contextText: 'Name: a.png',
     })
 
-    expect(result).toEqual({ text: 'A short title', model: 'openai/gpt-4o-mini' })
+    expect(result).toEqual({
+      text: 'A short title',
+      model: 'openai/gpt-4o-mini',
+      usage: { model: 'openai/gpt-4o-mini', promptTokens: null, completionTokens: null, totalTokens: null },
+    })
     expect(calls[0].model).toBe(DEFAULT_RUN_PROMPT_MODEL)
     expect(calls[0].temperature).toBe(0.2)
     expect(calls[0].messages[0].content).toContain('Name this file')
     expect(calls[0].messages[0].content).toContain('Name: a.png')
   })
 
+  it('captures token usage from the OpenRouter response', async () => {
+    const client = {
+      chat: {
+        completions: {
+          create: async () => ({
+            model: 'openai/gpt-4o-mini-2024-07-18',
+            usage: { prompt_tokens: 42, completion_tokens: 8, total_tokens: 50 },
+            choices: [{ message: { content: 'ok' } }],
+          }),
+        },
+      },
+    }
+
+    const result = await runOpenRouterPrompt(client, { prompt: 'Name this file' })
+
+    expect(result.usage).toEqual({
+      model: 'openai/gpt-4o-mini-2024-07-18',
+      promptTokens: 42,
+      completionTokens: 8,
+      totalTokens: 50,
+    })
+  })
+
   it('attaches an image as a content part', async () => {
     const calls = []
     const client = {

package/src/run-prompt.task.js

@@ -1,6 +1,7 @@
 import { createLogger } from '@ossy/observability'
 import { StorageClient } from '@ossy/platform'
 import { taskArtifactObjectKey } from '@ossy/platform/storage-keys'
+import { assertLlmUsageBudget, resolveWorkspaceIdForBudget } from '@ossy/platform/metering'
 import { GetResource, placeTaskArtifacts } from '@ossy/resources'
 import { loadSourceBuffer } from './load-source-buffer.js'
 import { toImageDataUrl } from './visual-content-descriptors.js'
@@ -18,7 +19,10 @@ import { resolveConfiguredPlacements } from './resolve-configured-placement.js'
 const log = createLogger('media-tasks')
 
 const TASK_ID = '@ossy/media-tasks/tasks/run-prompt'
-const SCHEMA_ID = '@ossy/media-tasks/schema/run-prompt'
+// Freeform text/md completion → platform schema (see docs/concepts/TaskOutput.md),
+// not a feature-owned one. Structured JSON outputs (e.g. visual-content-descriptors)
+// still declare their own schema.
+const SCHEMA_ID = '@ossy/platform/schema/text-completion'
 const CONCEPT = 'run-prompt'
 const OUTPUT = {
   name: 'completion',
@@ -77,7 +81,12 @@ export const metadata = {
   configurable: true,
 }
 
-export async function run ({ event, payload, sdk, integrations, inputs }) {
+export async function run ({ event, payload, req, sdk, integrations, inputs }) {
+  // Fail closed before spending anything — ADR 0017's first QuotaPolicy.
+  await assertLlmUsageBudget({
+    workspaceId: resolveWorkspaceIdForBudget({ event, payload, req }),
+  })
+
   const openrouter = integrations?.get?.('openrouter')
   if (!openrouter) {
     log.warn('[media-tasks/tasks/run-prompt] openrouter integration not connected')
@@ -112,7 +121,7 @@ export async function run ({ event, payload, sdk, integrations, inputs }) {
   }
 
   if (!resource?.id) {
-    return { output: OUTPUT.name, completion: body, placedResourceIds: [] }
+    return { output: OUTPUT.name, completion: body, placedResourceIds: [], usage: completion.usage }
   }
 
   const objectKey = taskArtifactObjectKey(resource.id, CONCEPT, OUTPUT.name)
@@ -139,6 +148,7 @@ export async function run ({ event, payload, sdk, integrations, inputs }) {
     completion: body,
     placedResourceIds: placed.map((item) => item.id),
     placedResourceId: placed[0]?.id ?? null,
+    usage: completion.usage,
   }
 }
 

package/src/visual-content-descriptors.js

@@ -1,3 +1,5 @@
+import { usageFromResponse } from './llm-usage.js'
+
 /** Default OpenRouter model slug (vision-capable). */
 export const DEFAULT_VCD_MODEL = 'openai/gpt-4o-mini'
 
@@ -29,7 +31,13 @@ export function toImageDataUrl (buffer, contentType = 'application/octet-stream'
  * @param {import('openai').OpenAI} client
  * @param {string} imageUrl Absolute http(s) URL or data: URL of the image
  * @param {{ model?: string }} [opts]
- * @returns {Promise<{ title: string | null, description: string | null, tags: string[], alt: string | null }>}
+ * @returns {Promise<{
+ *   title: string | null,
+ *   description: string | null,
+ *   tags: string[],
+ *   alt: string | null,
+ *   usage: { model: string, promptTokens: number | null, completionTokens: number | null, totalTokens: number | null },
+ * }>}
  */
 export async function getVisualContentDescriptors (client, imageUrl, opts = {}) {
   if (!client?.chat?.completions?.create) {
@@ -66,5 +74,6 @@ export async function getVisualContentDescriptors (client, imageUrl, opts = {})
     description: typeof parsed.description === 'string' ? parsed.description : null,
     tags: Array.isArray(parsed.tags) ? parsed.tags.filter((t) => typeof t === 'string') : [],
     alt: typeof parsed.alt === 'string' ? parsed.alt : null,
+    usage: usageFromResponse(response, model),
   }
 }

package/src/visual-content-descriptors.schema.js

@@ -1,3 +1,5 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
 export default {
   name: 'Visual Content Descriptors',
   id: '@ossy/media-tasks/schema/visual-content-descriptors',
@@ -24,30 +26,6 @@ export default {
       type: 'text',
       description: 'Suggested alt text',
     },
-    {
-      name: 'derivedFrom',
-      type: 'text',
-      description: 'Source resource id this output was derived from',
-    },
-    {
-      name: 'taskId',
-      type: 'text',
-      description: 'Task that produced this resource',
-    },
-    {
-      name: 'artifactName',
-      type: 'text',
-      description: 'Named task output',
-    },
-    {
-      name: 'artifactKey',
-      type: 'text',
-      description: 'Storage key for the artifact bytes/JSON',
-    },
-    {
-      name: 'artifactHref',
-      type: 'text',
-      description: 'Stable /r/…/tasks/… read path',
-    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
   ],
 }

package/src/visual-content-descriptors.spec.js

@@ -49,6 +49,7 @@ describe('getVisualContentDescriptors', () => {
         description: 'Orange sky over water',
         tags: ['sunset', 'nature'],
         alt: 'Sunset over water',
+        usage: { model: DEFAULT_VCD_MODEL, promptTokens: null, completionTokens: null, totalTokens: null },
       })
 
     expect(calls).toHaveLength(1)
@@ -81,6 +82,30 @@ describe('getVisualContentDescriptors', () => {
         description: null,
         tags: ['ok'],
         alt: null,
+        usage: { model: DEFAULT_VCD_MODEL, promptTokens: null, completionTokens: null, totalTokens: null },
+      })
+  })
+
+  it('captures token usage and the model that actually answered', async () => {
+    const client = {
+      chat: {
+        completions: {
+          create: async () => ({
+            model: 'openai/gpt-4o-mini-2024-07-18',
+            usage: { prompt_tokens: 120, completion_tokens: 40, total_tokens: 160 },
+            choices: [{ message: { content: '{"title":"Sunset"}' } }],
+          }),
+        },
+      },
+    }
+    await expect(getVisualContentDescriptors(client, 'data:image/png;base64,x'))
+      .resolves.toMatchObject({
+        usage: {
+          model: 'openai/gpt-4o-mini-2024-07-18',
+          promptTokens: 120,
+          completionTokens: 40,
+          totalTokens: 160,
+        },
       })
   })
 

package/src/visual-content-descriptors.task.js

@@ -1,6 +1,7 @@
 import { createLogger } from '@ossy/observability'
 import { StorageClient } from '@ossy/platform'
 import { taskArtifactObjectKey } from '@ossy/platform/storage-keys'
+import { assertLlmUsageBudget, resolveWorkspaceIdForBudget } from '@ossy/platform/metering'
 import { GetResource, placeTaskArtifacts } from '@ossy/resources'
 import { loadSourceBuffer } from './load-source-buffer.js'
 import {
@@ -49,11 +50,16 @@ export const metadata = {
   configurable: true,
 }
 
-export async function run ({ event, sdk, integrations, inputs }) {
+export async function run ({ event, payload, req, sdk, integrations, inputs }) {
   const resourceId = event.resourceId
 
   log.info(`[media-tasks/tasks/visual-content-descriptors] starting for resource ${resourceId}`)
 
+  // Fail closed before spending anything — ADR 0017's first QuotaPolicy.
+  await assertLlmUsageBudget({
+    workspaceId: resolveWorkspaceIdForBudget({ event, payload, req }),
+  })
+
   const openrouter = integrations?.get?.('openrouter')
   if (!openrouter) {
     log.warn('[media-tasks/tasks/visual-content-descriptors] openrouter integration not connected')
@@ -80,7 +86,8 @@ export async function run ({ event, sdk, integrations, inputs }) {
 
   // Inline bytes — OpenRouter cannot fetch localhost / auth-gated storage URLs.
   const imageUrl = toImageDataUrl(sourceBuffer, contentType)
-  const body = await getVisualContentDescriptors(openrouter, imageUrl, {
+  // `usage` is metering-only — never persisted on the artifact/placed document.
+  const { usage, ...body } = await getVisualContentDescriptors(openrouter, imageUrl, {
     model: inputs?.model,
   })
   const objectKey = taskArtifactObjectKey(resourceId, CONCEPT, OUTPUT.name)
@@ -108,5 +115,6 @@ export async function run ({ event, sdk, integrations, inputs }) {
     descriptors: body,
     placedResourceIds: placed.map((r) => r.id),
     placedResourceId: placed[0]?.id ?? null,
+    usage,
   }
 }

package/src/run-prompt.schema.js

@@ -1,48 +0,0 @@
-export default {
-  name: 'Prompt completion',
-  id: '@ossy/media-tasks/schema/run-prompt',
-  categoryName: 'Media processing',
-  icon: 'comment',
-  fields: [
-    {
-      name: 'text',
-      type: 'textarea',
-      description: 'Model completion',
-    },
-    {
-      name: 'model',
-      type: 'text',
-      description: 'OpenRouter model that produced the completion',
-    },
-    {
-      name: 'prompt',
-      type: 'textarea',
-      description: 'Prompt that was sent, before resource context',
-    },
-    {
-      name: 'derivedFrom',
-      type: 'text',
-      description: 'Source resource id this output was derived from',
-    },
-    {
-      name: 'taskId',
-      type: 'text',
-      description: 'Task that produced this resource',
-    },
-    {
-      name: 'artifactName',
-      type: 'text',
-      description: 'Named task output',
-    },
-    {
-      name: 'artifactKey',
-      type: 'text',
-      description: 'Storage key for the artifact bytes/JSON',
-    },
-    {
-      name: 'artifactHref',
-      type: 'text',
-      description: 'Stable /r/…/tasks/… read path',
-    },
-  ],
-}