@ossy/media-tasks 3.15.0 → 3.17.0

package/src/resolve-configured-placement.js

@@ -0,0 +1,44 @@
+/**
+ * Resolve workspace-configured placement folders for a task output.
+ * Uses `@ossy/automation/actions/get-task-instance` (string id — no package import).
+ *
+ * @param {{ invoke: Function }} sdk
+ * @param {string} taskId
+ * @param {string} outputName
+ * @returns {Promise<string[]>}
+ */
+export async function resolveConfiguredPlacements (sdk, taskId, outputName) {
+  if (!sdk?.invoke || !taskId || !outputName) return []
+  try {
+    const instance = await sdk.invoke('@ossy/automation/actions/get-task-instance', { taskId })
+    const config = instance?.outputs?.[outputName]
+    const fromList = Array.isArray(config?.placementLocations)
+      ? config.placementLocations
+      : null
+    const raw = fromList ?? config?.placementLocation
+    const list = Array.isArray(raw) ? raw : (typeof raw === 'string' ? [raw] : [])
+    const seen = new Set()
+    const result = []
+    for (const entry of list) {
+      const trimmed = typeof entry === 'string' ? entry.trim() : ''
+      if (!trimmed || seen.has(trimmed)) continue
+      seen.add(trimmed)
+      result.push(trimmed)
+    }
+    return result
+  } catch {
+    return []
+  }
+}
+
+/**
+ * @deprecated Use {@link resolveConfiguredPlacements}
+ * @param {{ invoke: Function }} sdk
+ * @param {string} taskId
+ * @param {string} outputName
+ * @returns {Promise<string | null>}
+ */
+export async function resolveConfiguredPlacement (sdk, taskId, outputName) {
+  const locations = await resolveConfiguredPlacements(sdk, taskId, outputName)
+  return locations[0] ?? null
+}

package/src/resolve-configured-placement.spec.js

@@ -0,0 +1,58 @@
+import {
+  resolveConfiguredPlacement,
+  resolveConfiguredPlacements,
+} from './resolve-configured-placement.js'
+
+describe('resolveConfiguredPlacements', () => {
+  it('returns empty without sdk or ids', async () => {
+    expect(await resolveConfiguredPlacements(null, 't', 'o')).toEqual([])
+    expect(await resolveConfiguredPlacements({ invoke: async () => ({}) }, '', 'o')).toEqual([])
+  })
+
+  it('reads placementLocations from get-task-instance', async () => {
+    const calls = []
+    const sdk = {
+      invoke: async (action, payload) => {
+        calls.push([action, payload])
+        return {
+          outputs: {
+            palette: { placementLocations: ['/derived/colors/', ' /also/ ', '/derived/colors/'] },
+          },
+        }
+      },
+    }
+    await expect(resolveConfiguredPlacements(sdk, 'task-1', 'palette')).resolves.toEqual([
+      '/derived/colors/',
+      '/also/',
+    ])
+    expect(calls).toEqual([
+      ['@ossy/automation/actions/get-task-instance', { taskId: 'task-1' }],
+    ])
+  })
+
+  it('falls back to singular placementLocation', async () => {
+    await expect(resolveConfiguredPlacements({
+      invoke: async () => ({ outputs: { palette: { placementLocation: '/one/' } } }),
+    }, 't', 'palette')).resolves.toEqual(['/one/'])
+  })
+
+  it('returns empty when invoke fails or locations empty', async () => {
+    await expect(resolveConfiguredPlacements({
+      invoke: async () => { throw new Error('missing') },
+    }, 't', 'palette')).resolves.toEqual([])
+
+    await expect(resolveConfiguredPlacements({
+      invoke: async () => ({ outputs: { palette: { placementLocations: ['  '] } } }),
+    }, 't', 'palette')).resolves.toEqual([])
+  })
+})
+
+describe('resolveConfiguredPlacement', () => {
+  it('returns the first location', async () => {
+    await expect(resolveConfiguredPlacement({
+      invoke: async () => ({
+        outputs: { palette: { placementLocations: ['/a/', '/b/'] } },
+      }),
+    }, 't', 'palette')).resolves.toBe('/a/')
+  })
+})

package/src/run-prompt.action.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/media-tasks/actions/run-prompt',
+  access: 'workspace',
+  label: 'automation.task.run-prompt.title',
+}

package/src/run-prompt.js

@@ -0,0 +1,126 @@
+import { usageFromResponse } from './llm-usage.js'
+
+/** Default OpenRouter model for freeform completions. */
+export const DEFAULT_RUN_PROMPT_MODEL = 'openai/gpt-4o-mini'
+
+/** Document schema whose `content.body` is the prompt context. */
+export const MARKDOWN_DOCUMENT_TYPE = '@ossy/resources/schema/markdown'
+
+/** Cap resource text included beside the prompt so one file cannot fill the context. */
+export const MAX_PROMPT_CONTEXT_CHARS = 12_000
+
+/**
+ * @param {string} [contentType]
+ * @returns {boolean}
+ */
+export function isTextContentType (contentType) {
+  const mime = String(contentType || '').split(';')[0].trim().toLowerCase()
+  if (!mime) return false
+  return mime.startsWith('text/')
+    || mime === 'application/json'
+    || mime === 'application/xml'
+    || mime.endsWith('+json')
+    || mime.endsWith('+xml')
+}
+
+/**
+ * @param {unknown} temperature
+ * @returns {number | undefined}
+ */
+export function clampTemperature (temperature) {
+  if (temperature == null || temperature === '') return undefined
+  const n = typeof temperature === 'number' ? temperature : Number(temperature)
+  if (!Number.isFinite(n)) return undefined
+  return Math.min(2, Math.max(0, n))
+}
+
+/**
+ * True for a Markdown document (text in `content.body`, not a stored file).
+ *
+ * @param {object | null | undefined} resource
+ * @returns {boolean}
+ */
+export function isMarkdownDocument (resource) {
+  return resource?.type === MARKDOWN_DOCUMENT_TYPE
+}
+
+/**
+ * @param {object | null | undefined} resource
+ * @returns {string}
+ */
+export function markdownDocumentBody (resource) {
+  const body = resource?.content?.body
+  return typeof body === 'string' ? body : ''
+}
+
+/**
+ * Short context block prepended under the workspace prompt.
+ *
+ * @param {{ name?: string, contentType?: string, text?: string }} resource
+ * @returns {string}
+ */
+export function resourceContextText ({ name, contentType, text } = {}) {
+  const lines = []
+  if (name) lines.push(`Name: ${name}`)
+  if (contentType) lines.push(`Content type: ${contentType}`)
+  const body = typeof text === 'string' ? text.trim() : ''
+  if (body) {
+    const clipped = body.length > MAX_PROMPT_CONTEXT_CHARS
+      ? `${body.slice(0, MAX_PROMPT_CONTEXT_CHARS)}…`
+      : body
+    lines.push('', clipped)
+  }
+  return lines.join('\n').trim()
+}
+
+/**
+ * @param {import('openai').OpenAI} client
+ * @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) {
+    throw new Error('openrouter client is required')
+  }
+  const prompt = typeof opts.prompt === 'string' ? opts.prompt.trim() : ''
+  if (!prompt) {
+    throw new Error('prompt is required')
+  }
+
+  const model = opts.model || DEFAULT_RUN_PROMPT_MODEL
+  const temperature = clampTemperature(opts.temperature)
+  const contextText = typeof opts.contextText === 'string' ? opts.contextText.trim() : ''
+  const text = contextText ? `${prompt}\n\n---\n${contextText}` : prompt
+  const imageUrl = typeof opts.imageUrl === 'string' && opts.imageUrl ? opts.imageUrl : ''
+
+  /** @type {string | Array<{ type: string, text?: string, image_url?: { url: string } }>} */
+  const content = imageUrl
+    ? [
+      { type: 'text', text },
+      { type: 'image_url', image_url: { url: imageUrl } },
+    ]
+    : text
+
+  const response = await client.chat.completions.create({
+    model,
+    ...(temperature != null ? { temperature } : {}),
+    messages: [{ role: 'user', content }],
+  })
+
+  const completion = response?.choices?.[0]?.message?.content
+  if (typeof completion !== 'string' || !completion.trim()) {
+    throw new Error('run-prompt: model returned an empty completion')
+  }
+
+  const usage = usageFromResponse(response, model)
+
+  return {
+    text: completion,
+    model: usage.model,
+    usage,
+  }
+}

package/src/run-prompt.spec.js

@@ -0,0 +1,144 @@
+import {
+  DEFAULT_RUN_PROMPT_MODEL,
+  MARKDOWN_DOCUMENT_TYPE,
+  clampTemperature,
+  isMarkdownDocument,
+  isTextContentType,
+  markdownDocumentBody,
+  resourceContextText,
+  runOpenRouterPrompt,
+} from './run-prompt.js'
+
+describe('isTextContentType', () => {
+  it('accepts text, json, and xml', () => {
+    expect(isTextContentType('text/plain')).toBe(true)
+    expect(isTextContentType('text/markdown; charset=utf-8')).toBe(true)
+    expect(isTextContentType('application/json')).toBe(true)
+    expect(isTextContentType('application/ld+json')).toBe(true)
+    expect(isTextContentType('image/png')).toBe(false)
+  })
+})
+
+describe('isMarkdownDocument', () => {
+  it('recognises the markdown schema and reads its body', () => {
+    const resource = {
+      type: MARKDOWN_DOCUMENT_TYPE,
+      name: 'notes',
+      content: { body: '# Hello' },
+    }
+    expect(isMarkdownDocument(resource)).toBe(true)
+    expect(markdownDocumentBody(resource)).toBe('# Hello')
+    expect(isMarkdownDocument({
+      type: '@ossy/platform/schema/file',
+      content: { ContentType: 'text/plain', Key: 'abc' },
+    })).toBe(false)
+  })
+})
+
+describe('resourceContextText', () => {
+  it('includes name, type, and clipped body', () => {
+    const text = resourceContextText({
+      name: 'notes.md',
+      contentType: 'text/markdown',
+      text: 'hello',
+    })
+    expect(text).toContain('Name: notes.md')
+    expect(text).toContain('hello')
+  })
+})
+
+describe('clampTemperature', () => {
+  it('keeps 0 and clamps the range', () => {
+    expect(clampTemperature(0)).toBe(0)
+    expect(clampTemperature(3)).toBe(2)
+    expect(clampTemperature(-1)).toBe(0)
+    expect(clampTemperature(undefined)).toBeUndefined()
+  })
+})
+
+describe('runOpenRouterPrompt', () => {
+  it('sends the prompt and optional temperature, and returns the completion', async () => {
+    const calls = []
+    const client = {
+      chat: {
+        completions: {
+          create: async (args) => {
+            calls.push(args)
+            return {
+              model: 'openai/gpt-4o-mini',
+              choices: [{ message: { content: 'A short title' } }],
+            }
+          },
+        },
+      },
+    }
+
+    const result = await runOpenRouterPrompt(client, {
+      prompt: 'Name this file',
+      temperature: 0.2,
+      contextText: 'Name: a.png',
+    })
+
+    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 = {
+      chat: {
+        completions: {
+          create: async (args) => {
+            calls.push(args)
+            return { choices: [{ message: { content: 'ok' } }] }
+          },
+        },
+      },
+    }
+
+    await runOpenRouterPrompt(client, {
+      prompt: 'Describe',
+      model: 'google/gemini-2.5-flash-lite',
+      imageUrl: 'data:image/png;base64,aaaa',
+    })
+
+    expect(calls[0].model).toBe('google/gemini-2.5-flash-lite')
+    expect(calls[0].temperature).toBeUndefined()
+    expect(calls[0].messages[0].content[1].image_url.url).toBe('data:image/png;base64,aaaa')
+  })
+
+  it('rejects an empty prompt', async () => {
+    const client = { chat: { completions: { create: async () => ({}) } } }
+    await expect(runOpenRouterPrompt(client, { prompt: '  ' })).rejects.toThrow(/prompt/)
+  })
+})

package/src/run-prompt.task.js

@@ -0,0 +1,197 @@
+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'
+import {
+  DEFAULT_RUN_PROMPT_MODEL,
+  MARKDOWN_DOCUMENT_TYPE,
+  isMarkdownDocument,
+  isTextContentType,
+  markdownDocumentBody,
+  resourceContextText,
+  runOpenRouterPrompt,
+} from './run-prompt.js'
+import { resolveConfiguredPlacements } from './resolve-configured-placement.js'
+
+const log = createLogger('media-tasks')
+
+const TASK_ID = '@ossy/media-tasks/tasks/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',
+  kind: 'location',
+  schemaId: SCHEMA_ID,
+  contentType: 'application/json',
+}
+
+export const metadata = {
+  id: TASK_ID,
+  triggers: [
+    {
+      type: '@ossy/platform/schema/file',
+      event: 'Created',
+      match: { 'content.ContentType': 'text/*' },
+    },
+    {
+      type: '@ossy/platform/schema/file',
+      event: 'Created',
+      match: { 'content.ContentType': 'image/*' },
+    },
+    {
+      type: '@ossy/platform/schema/file',
+      event: 'Created',
+      match: { 'content.ContentType': 'application/json' },
+    },
+    {
+      type: MARKDOWN_DOCUMENT_TYPE,
+      event: 'Created',
+    },
+  ],
+  outputs: [OUTPUT],
+  inputs: [
+    {
+      name: 'prompt',
+      type: 'text',
+      multiline: true,
+      sources: ['payload', 'config'],
+      required: true,
+      description: 'Instructions for the model',
+    },
+    {
+      name: 'model',
+      type: 'text',
+      default: DEFAULT_RUN_PROMPT_MODEL,
+      sources: ['payload', 'config'],
+      description: 'OpenRouter model slug',
+    },
+    {
+      name: 'temperature',
+      type: 'number',
+      sources: ['payload', 'config'],
+      description: 'Sampling temperature from 0 to 2. Leave empty for the provider default.',
+    },
+  ],
+  configurable: true,
+}
+
+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')
+    throw Object.assign(new Error('OpenRouter integration not available'), { status: 503 })
+  }
+
+  const prompt = typeof inputs?.prompt === 'string' ? inputs.prompt : ''
+  const resourceId = event?.resourceId || payload?.resourceId || null
+  log.info(`[media-tasks/tasks/run-prompt] starting${resourceId ? ` for resource ${resourceId}` : ''}`)
+
+  let resource = null
+  let contextText = ''
+  let imageUrl
+  if (resourceId) {
+    resource = await sdk.invoke(GetResource, { resourceId })
+    const loaded = await loadResourceContext(resource)
+    contextText = loaded.contextText
+    imageUrl = loaded.imageUrl
+  }
+
+  const completion = await runOpenRouterPrompt(openrouter, {
+    prompt,
+    model: inputs?.model,
+    temperature: inputs?.temperature,
+    contextText,
+    imageUrl,
+  })
+  const body = {
+    text: completion.text,
+    model: completion.model,
+    prompt,
+  }
+
+  if (!resource?.id) {
+    return { output: OUTPUT.name, completion: body, placedResourceIds: [], usage: completion.usage }
+  }
+
+  const objectKey = taskArtifactObjectKey(resource.id, CONCEPT, OUTPUT.name)
+  await StorageClient.save(objectKey, Buffer.from(JSON.stringify(body), 'utf8'))
+  log.info(`[media-tasks/tasks/run-prompt] saved ${objectKey}`)
+
+  const placementLocations = await resolveConfiguredPlacements(sdk, TASK_ID, OUTPUT.name)
+  const placed = await placeTaskArtifacts({
+    sdk,
+    sourceResource: resource,
+    taskId: TASK_ID,
+    output: OUTPUT,
+    body,
+    artifactKey: objectKey,
+    placementLocations,
+  })
+  if (placed.length) {
+    log.info(`[media-tasks/tasks/run-prompt] placed ${placed.length} resource(s)`)
+  }
+
+  return {
+    output: OUTPUT.name,
+    key: objectKey,
+    completion: body,
+    placedResourceIds: placed.map((item) => item.id),
+    placedResourceId: placed[0]?.id ?? null,
+    usage: completion.usage,
+  }
+}
+
+/**
+ * @param {object | null | undefined} resource
+ * @returns {Promise<{ contextText: string, imageUrl?: string }>}
+ */
+async function loadResourceContext (resource) {
+  const name = resource?.name
+  if (isMarkdownDocument(resource)) {
+    return {
+      contextText: resourceContextText({
+        name,
+        contentType: MARKDOWN_DOCUMENT_TYPE,
+        text: markdownDocumentBody(resource),
+      }),
+    }
+  }
+
+  const contentType = resource?.content?.ContentType || ''
+  const key = resource?.content?.Key
+  if (!key) {
+    return { contextText: resourceContextText({ name, contentType }) }
+  }
+
+  if (String(contentType).startsWith('image/')) {
+    const buffer = await loadSourceBuffer(key)
+    return {
+      contextText: resourceContextText({ name, contentType }),
+      ...(buffer ? { imageUrl: toImageDataUrl(buffer, contentType) } : {}),
+    }
+  }
+
+  if (isTextContentType(contentType)) {
+    const buffer = await loadSourceBuffer(key)
+    return {
+      contextText: resourceContextText({
+        name,
+        contentType,
+        text: buffer ? buffer.toString('utf8') : '',
+      }),
+    }
+  }
+
+  return { contextText: resourceContextText({ name, contentType }) }
+}

package/src/visual-content-descriptors.js

@@ -0,0 +1,79 @@
+import { usageFromResponse } from './llm-usage.js'
+
+/** Default OpenRouter model slug (vision-capable). */
+export const DEFAULT_VCD_MODEL = 'openai/gpt-4o-mini'
+
+const SYSTEM_PROMPT = `You will be provided with images, and your task is to create a json object including the following properties:
+- title: Short attention grabbing title that describes the image
+- description: A short text describing the image, suitable for SEO purposes
+- tags: an array of tags describing the image that will be used for categorization and SEO purposes
+- alt: A short text that describes the image, suitable for alt text`
+
+/**
+ * Build a data URL so the model provider can read the image without fetching
+ * our storage URL (localhost / auth-gated URLs fail with OpenRouter 400).
+ *
+ * @param {Buffer} buffer
+ * @param {string} [contentType]
+ * @returns {string}
+ */
+export function toImageDataUrl (buffer, contentType = 'application/octet-stream') {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) {
+    throw new Error('image buffer is required')
+  }
+  const mime = String(contentType || 'application/octet-stream').split(';')[0].trim() || 'application/octet-stream'
+  return `data:${mime};base64,${buffer.toString('base64')}`
+}
+
+/**
+ * Ask an OpenRouter (OpenAI-compatible) client for SEO descriptors of an image.
+ *
+ * @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,
+ *   usage: { model: string, promptTokens: number | null, completionTokens: number | null, totalTokens: number | null },
+ * }>}
+ */
+export async function getVisualContentDescriptors (client, imageUrl, opts = {}) {
+  if (!client?.chat?.completions?.create) {
+    throw new Error('openrouter client is required')
+  }
+  if (!imageUrl) {
+    throw new Error('imageUrl is required')
+  }
+
+  const model = opts.model || DEFAULT_VCD_MODEL
+  const response = await client.chat.completions.create({
+    model,
+    max_tokens: 4000,
+    response_format: { type: 'json_object' },
+    messages: [
+      { role: 'system', content: SYSTEM_PROMPT },
+      {
+        role: 'user',
+        content: [{ type: 'image_url', image_url: { url: imageUrl } }],
+      },
+    ],
+  })
+
+  const raw = response?.choices?.[0]?.message?.content ?? '{}'
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('visual-content-descriptors: model returned non-JSON content')
+  }
+
+  return {
+    title: typeof parsed.title === 'string' ? parsed.title : null,
+    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,20 +1,31 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
 export default {
   name: 'Visual Content Descriptors',
   id: '@ossy/media-tasks/schema/visual-content-descriptors',
   categoryName: 'Media processing',
-  icon: 'attribution',
+  icon: 'details-more',
   fields: [
     {
-      name: 'resourceId',
+      name: 'title',
       type: 'text',
+      description: 'Suggested resource name',
     },
     {
-      name: 'status',
-      type: 'text',
+      name: 'description',
+      type: 'textarea',
+      description: 'Suggested SEO description',
     },
     {
-      name: 'result',
+      name: 'tags',
       type: 'textarea',
+      description: 'Suggested tags',
+    },
+    {
+      name: 'alt',
+      type: 'text',
+      description: 'Suggested alt text',
     },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
   ],
 }