@ossy/platform 3.3.0 → 3.5.0

package/Dockerfile

@@ -13,11 +13,23 @@ COPY package.json ./
 RUN npm install --omit=dev --no-audit --no-fund --loglevel=error
 
 COPY src ./src
+COPY docker-healthcheck.js ./docker-healthcheck.js
+
+# ECS/ALB map container port 3000. `startRuntime` honors PORT (see runtime.js).
+ENV PORT=3000
+# Default label for `/health`; ECS task defs override with the service key.
+ENV OSSY_SERVICE_NAME=runtime
 
 EXPOSE 3000
 
+# Image-local Docker HEALTHCHECK (PORT + /health + 4s abort). ECS container
+# checks use the same probe shape via inline `node -e` fetch (ossy#589).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+  CMD ["node", "docker-healthcheck.js"]
+
 # Required env vars at runtime:
 #   OSSY_API_KEY   — Ossy API JWT for CMS reads
 #   OSSY_API_URL   — (optional) override API base, default https://api.ossy.se/api/v0
 #   PORT           — (optional) override listen port, default 3000
+#   OSSY_SERVICE_NAME — (optional) `/health` service label, default runtime
 CMD ["node", "src/runtime.js"]

package/README.md

@@ -60,7 +60,7 @@ Optional environment variables used by the platform itself:
 | Variable | Description |
 |---|---|
 | `DB_URL` | MongoDB connection string. Required for tasks and aggregates. |
-| `API_URL` + `OSSY_API_KEY` | SDK configuration. When set, tasks receive a pre-configured SDK instance. |
+| `API_URL` + `OSSY_API_KEY` | Optional HTTP bot SDK for tasks. When unset, tasks get an in-process SDK that calls `ActionService` / storage in the same process (local app-test and same-server changestream). |
 | `PORT` | HTTP port. |
 
 ## Health check
@@ -73,6 +73,8 @@ Both `startServer` (website / app images) and `startRuntime` (CMS multi-tenant i
 
 The route is mounted before auth and before CMS site loading, so ALB target groups and ECS container health checks can use path `/health` without cookies, API tokens, or a resolvable hostname.
 
+The runtime image `Dockerfile` sets `PORT` / `OSSY_SERVICE_NAME` and a Docker `HEALTHCHECK` via WORKDIR-root `docker-healthcheck.js` (same PORT + `/health` + 4s abort shape as ECS inline probes from `@ossy/deployment-tools`).
+
 ## Exported API
 
 ```js

package/docker-healthcheck.js

@@ -0,0 +1,32 @@
+/**
+ * Docker HEALTHCHECK entrypoint for the platform runtime image (WORKDIR root).
+ *
+ * ECS Fargate container checks use an inline Node `fetch` one-liner from
+ * `@ossy/deployment-tools` `ecsContainerHealthCheckCommand` (ossy#589) — they
+ * do not require this file. Keep the same PORT + `/health` +
+ * `HEALTHCHECK_FETCH_TIMEOUT_MS` probe shape so local `docker build` /
+ * `docker run` health matches ECS/ALB liveness.
+ *
+ * No curl/wget — `node:*-slim` only needs Node `fetch`.
+ */
+const DEFAULT_PORT = 3000
+const HEALTH_PATH = '/health'
+/** Match `src/health.js` / deployment-tools `HEALTHCHECK_FETCH_TIMEOUT_MS`. */
+const HEALTHCHECK_FETCH_TIMEOUT_MS = 4000
+
+function resolveProbePort () {
+  const parsed = Number.parseInt(String(process.env.PORT ?? ''), 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_PORT
+}
+
+const port = resolveProbePort()
+const url = `http://127.0.0.1:${port}${HEALTH_PATH}`
+
+try {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(HEALTHCHECK_FETCH_TIMEOUT_MS),
+  })
+  process.exit(response.ok ? 0 : 1)
+} catch {
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\"",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose"
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose && node --test docker-healthcheck.test.js"
   },
   "keywords": [],
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
@@ -45,16 +45,16 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.2.0",
-    "@ossy/locale": "^3.0.9",
-    "@ossy/manifest": "^3.0.9",
+    "@ossy/event-store": "^3.4.0",
+    "@ossy/locale": "^3.4.0",
+    "@ossy/manifest": "^3.5.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
-    "@ossy/schema": "^3.0.9",
-    "@ossy/sdk": "^3.3.0",
-    "@ossy/tokens": "^3.0.9",
-    "@ossy/users": "^3.2.0",
-    "@ossy/workspaces": "^3.2.0",
+    "@ossy/schema": "^3.5.0",
+    "@ossy/sdk": "^3.5.0",
+    "@ossy/tokens": "^3.5.0",
+    "@ossy/users": "^3.5.0",
+    "@ossy/workspaces": "^3.5.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -72,7 +72,8 @@
   },
   "files": [
     "src",
-    "Dockerfile"
+    "Dockerfile",
+    "docker-healthcheck.js"
   ],
-  "gitHead": "19e8bae4c1e9df79270218f28c0c9391f4f9871c"
+  "gitHead": "23167600f991596f122765a53f2b9df08314e115"
 }

package/src/file.schema.js

@@ -7,5 +7,9 @@ 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/health.js

@@ -6,16 +6,35 @@
  */
 export const HEALTH_PATH = '/health'
 
+/**
+ * Abort hung Node `fetch` probes under the usual 5s Docker/ECS check timeout.
+ * Mirrored by `@ossy/deployment-tools` `HEALTHCHECK_FETCH_TIMEOUT_MS`.
+ */
+export const HEALTHCHECK_FETCH_TIMEOUT_MS = 4000
+
+/**
+ * @param {string | undefined} explicit
+ * @returns {string}
+ */
+export function resolveHealthServiceName (explicit) {
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim()
+  const fromEnv = typeof process.env.OSSY_SERVICE_NAME === 'string'
+    ? process.env.OSSY_SERVICE_NAME.trim()
+    : ''
+  return fromEnv || 'ossy'
+}
+
 /**
  * @param {import('express').Express} app
  * @param {{ service?: string }} [options]
  */
-export function mountHealthEndpoint (app, { service = 'ossy' } = {}) {
+export function mountHealthEndpoint (app, { service } = {}) {
+  const resolvedService = resolveHealthServiceName(service)
   const handler = (_req, res) => {
     res.status(200).json({
       ok: true,
       status: 'ok',
-      service,
+      service: resolvedService,
     })
   }
 

package/src/health.spec.js

@@ -1,6 +1,11 @@
-import { describe, expect, it, jest } from '@jest/globals'
+import { afterEach, describe, expect, it, jest } from '@jest/globals'
 import express from 'express'
-import { HEALTH_PATH, mountHealthEndpoint } from './health.js'
+import {
+  HEALTH_PATH,
+  HEALTHCHECK_FETCH_TIMEOUT_MS,
+  mountHealthEndpoint,
+  resolveHealthServiceName,
+} from './health.js'
 
 function createMockRes () {
   const res = {
@@ -18,7 +23,38 @@ function createMockRes () {
   return res
 }
 
+describe('resolveHealthServiceName', () => {
+  const original = process.env.OSSY_SERVICE_NAME
+
+  afterEach(() => {
+    if (original === undefined) delete process.env.OSSY_SERVICE_NAME
+    else process.env.OSSY_SERVICE_NAME = original
+  })
+
+  it('prefers an explicit non-empty service', () => {
+    process.env.OSSY_SERVICE_NAME = 'from-env'
+    expect(resolveHealthServiceName('platform-runtime')).toBe('platform-runtime')
+  })
+
+  it('uses OSSY_SERVICE_NAME when explicit is omitted', () => {
+    process.env.OSSY_SERVICE_NAME = 'website-ossy'
+    expect(resolveHealthServiceName()).toBe('website-ossy')
+  })
+
+  it('defaults to ossy', () => {
+    delete process.env.OSSY_SERVICE_NAME
+    expect(resolveHealthServiceName()).toBe('ossy')
+  })
+})
+
 describe('mountHealthEndpoint', () => {
+  const original = process.env.OSSY_SERVICE_NAME
+
+  afterEach(() => {
+    if (original === undefined) delete process.env.OSSY_SERVICE_NAME
+    else process.env.OSSY_SERVICE_NAME = original
+  })
+
   it('registers GET /health that returns 200 without auth', () => {
     const app = express()
     const get = jest.spyOn(app, 'get')
@@ -42,6 +78,7 @@ describe('mountHealthEndpoint', () => {
   })
 
   it('defaults service name to ossy', () => {
+    delete process.env.OSSY_SERVICE_NAME
     const app = express()
     const get = jest.spyOn(app, 'get')
     mountHealthEndpoint(app)
@@ -50,4 +87,20 @@ describe('mountHealthEndpoint', () => {
     handler({}, res)
     expect(res.body.service).toBe('ossy')
   })
+
+  it('labels via OSSY_SERVICE_NAME when set', () => {
+    process.env.OSSY_SERVICE_NAME = 'website-ossy'
+    const app = express()
+    const get = jest.spyOn(app, 'get')
+    mountHealthEndpoint(app)
+    const handler = get.mock.calls[0][1]
+    const res = createMockRes()
+    handler({}, res)
+    expect(res.body.service).toBe('website-ossy')
+  })
+
+  it('exports HEALTHCHECK_FETCH_TIMEOUT_MS under the ECS check timeout', () => {
+    expect(HEALTHCHECK_FETCH_TIMEOUT_MS).toBe(4000)
+    expect(HEALTHCHECK_FETCH_TIMEOUT_MS).toBeLessThan(5000)
+  })
 })

package/src/index.js

@@ -1,4 +1,5 @@
 export { TaskService } from './tasks/task-service.js'
+export { createInProcessSdk } from './tasks/in-process-sdk.js'
 export { loadAndRegisterTasks } from './tasks/task-registry.js'
 export { ChangeStream } from './tasks/change-stream.js'
 export { registerSchema, getSystemSchemas } from './resources/schema.registry.js'

package/src/mcp/create-ossy-mcp-server.js

@@ -1,11 +1,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { jsonSchemaToZodShape } from './json-schema-to-zod.js'
+import { jsonSchemaToZod } from './json-schema-to-zod.js'
 import {
   TASK_TOPOLOGY_RESOURCE_URI,
   capabilitiesTaskTopologyResource,
 } from '@ossy/manifest/build-capabilities'
 
 /**
+ * Pass a full Zod object (with passthrough / record semantics) — not a raw shape.
+ * The MCP SDK wraps raw shapes with `z.object(shape)`, which strips unknown keys and
+ * defeats JSON Schema `additionalProperties: true` (e.g. timesheets `year` / `monthIndex`).
+ *
  * @param {{
  *   capabilities: { tools: Array<object>, tasks?: object[], graph?: object },
  *   invokeAction: (actionId: string, payload: object, req?: object) => Promise<unknown>,
@@ -44,12 +48,12 @@ export function createOssyMcpServer ({ capabilities, invokeAction, customTools =
   }
 
   for (const tool of capabilities.tools || []) {
-    const inputShape = jsonSchemaToZodShape(tool.inputSchema || { type: 'object' })
+    const inputSchema = jsonSchemaToZod(tool.inputSchema || { type: 'object' })
     server.registerTool(
       tool.name,
       {
         description: tool.description || tool.title || tool.actionId,
-        inputSchema: inputShape,
+        inputSchema,
       },
       async (args, extra) => {
         try {
@@ -68,14 +72,14 @@ export function createOssyMcpServer ({ capabilities, invokeAction, customTools =
   }
 
   for (const tool of customTools) {
-    const inputShape = tool.inputSchema
-      ? jsonSchemaToZodShape(tool.inputSchema)
+    const inputSchema = tool.inputSchema
+      ? jsonSchemaToZod(tool.inputSchema)
       : undefined
     server.registerTool(
       tool.name,
       {
         description: tool.description,
-        ...(inputShape ? { inputSchema: inputShape } : {}),
+        ...(inputSchema ? { inputSchema } : {}),
       },
       async (args, extra) => {
         try {

package/src/mcp/json-schema-to-zod.js

@@ -4,6 +4,11 @@ import { z } from 'zod'
  * Minimal JSON Schema → Zod conversion for MCP tool registration.
  * Supports the subset produced by build-capabilities.
  *
+ * JSON Schema default for `additionalProperties` is **true** (open objects).
+ * We only strip unknown keys when `additionalProperties` is explicitly `false`.
+ * That matters for envelopes like `import-schemas` (`items: { type: 'object' }`),
+ * which otherwise became `z.object({})` and dropped `id` / `fields`.
+ *
  * @param {object} schema
  * @returns {import('zod').ZodTypeAny}
  */
@@ -26,7 +31,14 @@ export function jsonSchemaToZod (schema) {
       shape[key] = field
     }
     const objectSchema = z.object(shape)
-    return schema.additionalProperties ? objectSchema.passthrough() : objectSchema
+    if (schema.additionalProperties === false) {
+      return objectSchema
+    }
+    // Open object with no declared properties → accept any keys.
+    if (Object.keys(shape).length === 0) {
+      return z.record(z.unknown())
+    }
+    return objectSchema.passthrough()
   }
 
   if (schema.type === 'array') {
@@ -52,6 +64,10 @@ export function jsonSchemaToZod (schema) {
 }
 
 /**
+ * Raw shape for callers that need ZodRawShape. Prefer {@link jsonSchemaToZod} when
+ * registering MCP tools — the MCP SDK rebuilds `z.object(shape)` without passthrough,
+ * which strips open-object fields.
+ *
  * @param {object} inputSchema JSON Schema object
  * @returns {import('zod').ZodRawShape}
  */

package/src/mcp/json-schema-to-zod.spec.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from '@jest/globals'
+import { z } from 'zod'
+import { jsonSchemaToZod, jsonSchemaToZodShape } from './json-schema-to-zod.js'
+import { normalizeMcpActionArgs } from './normalize-mcp-action-args.js'
+
+describe('jsonSchemaToZod', () => {
+  it('keeps unknown keys on open objects (JSON Schema default)', () => {
+    const schema = jsonSchemaToZod({ type: 'object' })
+    const parsed = schema.parse({
+      id: '@ossy/demo/schema/author',
+      fields: [{ name: 'n', type: 'text' }],
+    })
+    expect(parsed).toEqual({
+      id: '@ossy/demo/schema/author',
+      fields: [{ name: 'n', type: 'text' }],
+    })
+  })
+
+  it('strips unknown keys only when additionalProperties is false', () => {
+    const schema = jsonSchemaToZod({
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+      additionalProperties: false,
+    })
+    expect(schema.parse({ name: 'Ada', extra: true })).toEqual({ name: 'Ada' })
+  })
+
+  it('preserves schema items inside import-schemas-style arrays', () => {
+    const envelope = jsonSchemaToZod({
+      type: 'object',
+      required: ['schemas'],
+      properties: {
+        schemas: {
+          type: 'array',
+          items: { type: 'object' },
+        },
+      },
+    })
+    const input = {
+      schemas: [
+        {
+          id: '@ossy/demo/schema/author',
+          name: 'Author',
+          fields: [{ name: 'name', type: 'text', required: true }],
+        },
+      ],
+    }
+    expect(envelope.parse(input)).toEqual(input)
+  })
+
+  it('keeps timesheet generate fields when using the full Zod schema (MCP registration)', () => {
+    const capabilitySchema = {
+      type: 'object',
+      properties: {
+        workspaceId: { type: 'string' },
+        payload: { type: 'object', description: 'Action-specific payload' },
+      },
+      additionalProperties: true,
+    }
+    const full = jsonSchemaToZod(capabilitySchema)
+    expect(full.parse({ year: 2026, monthIndex: 7 })).toEqual({
+      year: 2026,
+      monthIndex: 7,
+    })
+
+    // MCP SDK wraps raw shapes with z.object(shape) — that path strips extras.
+    const stripped = z.object(jsonSchemaToZodShape(capabilitySchema)).parse({
+      year: 2026,
+      monthIndex: 7,
+      payload: {},
+    })
+    expect(stripped).toEqual({ payload: {} })
+    expect(stripped.year).toBeUndefined()
+  })
+})
+
+describe('normalizeMcpActionArgs', () => {
+  it('flattens nested payload bags used by default MCP envelopes', () => {
+    expect(normalizeMcpActionArgs(
+      { payload: { year: 2026, monthIndex: 7 } },
+      { workspaceId: 'ws-1', userId: 'u-1' },
+    )).toEqual({
+      workspaceId: 'ws-1',
+      user: undefined,
+      userId: 'u-1',
+      year: 2026,
+      monthIndex: 7,
+    })
+  })
+
+  it('keeps flat tool args (resources create style)', () => {
+    expect(normalizeMcpActionArgs(
+      { location: '/demo/', name: 'Ada', type: '@ossy/demo/schema/author' },
+      { workspaceId: 'ws-1' },
+    )).toMatchObject({
+      workspaceId: 'ws-1',
+      location: '/demo/',
+      name: 'Ada',
+      type: '@ossy/demo/schema/author',
+    })
+  })
+})

package/src/mcp/mount-platform-mcp.js

@@ -1,6 +1,7 @@
 import { buildCapabilities } from '@ossy/manifest/build-capabilities'
 import { mountOssyMcp } from './mount-ossy-mcp.js'
 import { uploadFileToolHandler, UPLOAD_FILE_TOOL } from './upload-file-tool.js'
+import { normalizeMcpActionArgs } from './normalize-mcp-action-args.js'
 import { ActionService } from '../actions/action.service.js'
 import { TaskService } from '../tasks/task-service.js'
 import { IntegrationService } from '../integration.service.js'
@@ -68,12 +69,7 @@ export function mountPlatformMcp (app, {
 
     const actionLog = createLogger(actionId)
     return ActionService.invoke(actionId, {
-      payload: {
-        workspaceId: payload?.workspaceId ?? req?.workspaceId,
-        user: req?.user,
-        userId: req?.userId,
-        ...payload,
-      },
+      payload: normalizeMcpActionArgs(payload, req),
       sdk: req?.sdk ?? null,
       log: actionLog,
       integrations: IntegrationService,

package/src/mcp/normalize-mcp-action-args.js

@@ -0,0 +1,30 @@
+/**
+ * Flatten MCP tool args into the action payload shape tasks expect.
+ *
+ * Default capability envelopes expose a nested `payload` bag. Agents often send
+ * `{ payload: { year, monthIndex } }`, but tasks read `payload.year` after
+ * ActionService spreads the tool args — without flattening that becomes
+ * `payload.payload.year`.
+ *
+ * @param {object} [args]
+ * @param {{ workspaceId?: string, user?: object, userId?: string }} [req]
+ * @returns {object}
+ */
+export function normalizeMcpActionArgs (args = {}, req = {}) {
+  const { workspaceId, payload: nestedPayload, ...rest } = args ?? {}
+  const fromNested = (
+    nestedPayload
+    && typeof nestedPayload === 'object'
+    && !Array.isArray(nestedPayload)
+  )
+    ? nestedPayload
+    : {}
+
+  return {
+    workspaceId: workspaceId ?? req?.workspaceId,
+    user: req?.user,
+    userId: req?.userId,
+    ...fromNested,
+    ...rest,
+  }
+}

package/src/mcp/upload-file-tool.js

@@ -1,4 +1,5 @@
 import { readFile, stat } from 'node:fs/promises'
+import { isLocalStorageUploadUrl } from '../storage/local-storage-url.js'
 
 /**
  * Composite upload: create binary resource + PUT file bytes.
@@ -29,11 +30,18 @@ export async function uploadFileToolHandler (invokeAction, args, req) {
     throw new Error('Storage is not configured or create did not return uploadUrl')
   }
 
-  const response = await fetch(uploadUrl, {
-    method: 'PUT',
-    headers: { 'Content-Type': type },
-    body,
-  })
+  /** @type {Record<string, string>} */
+  const headers = { 'Content-Type': type }
+  const init = { method: 'PUT', headers, body }
+  if (isLocalStorageUploadUrl(uploadUrl)) {
+    init.credentials = 'include'
+    const workspaceId = args.workspaceId || req?.workspaceId
+    if (workspaceId) headers.workspaceId = workspaceId
+    const auth = req?.get?.('Authorization') || req?.signedCookies?.auth
+    if (auth) headers.Authorization = auth
+  }
+
+  const response = await fetch(uploadUrl, init)
 
   if (!response.ok) {
     throw new Error(`Upload failed: HTTP ${response.status}`)

package/src/runtime.js

@@ -78,7 +78,8 @@ export async function startRuntime ({ port } = {}) {
 
   const app = express()
   // Liveness for ALB/ECS — before site loading so probes never depend on CMS/domain.
-  mountHealthEndpoint(app, { service: 'platform-runtime' })
+  // Prefer OSSY_SERVICE_NAME (ECS task env) when set.
+  mountHealthEndpoint(app)
   app.use(morgan('tiny'))
   app.use(express.json({ strict: false }))
   app.use(cookieParser(process.env.OSSY_COOKIE_SECRET || 'default_secret'))

package/src/server.js

@@ -276,11 +276,12 @@ export async function startServer (options = {}) {
   const layoutsById = await loadLayoutsById(layoutManifest, buildDir, log)
 
   // Register the SDK so all tasks receive it as `sdk`.
-  // Priority: explicit options.sdk → SDK.of() from env vars → null (direct-DB fallback in tasks).
+  // Priority: explicit options.sdk → HTTP bot SDK (API_URL + OSSY_API_KEY) → in-process ActionService SDK.
   const botSdk = (process.env.API_URL && process.env.OSSY_API_KEY)
     ? SDK.of({ apiUrl: process.env.API_URL, authorization: process.env.OSSY_API_KEY })
     : null
-  TaskService.setSdk(options.sdk ?? botSdk)
+  const { createInProcessSdk } = await import('./tasks/in-process-sdk.js')
+  TaskService.setSdk(options.sdk ?? botSdk ?? createInProcessSdk())
 
   TaskService.startScheduler()
 
@@ -322,7 +323,8 @@ export async function startServer (options = {}) {
 
   const app = express()
   // Liveness for ALB/ECS — before auth so probes never depend on cookies/Mongo.
-  mountHealthEndpoint(app, { service: 'platform' })
+  // Prefer OSSY_SERVICE_NAME (ECS task env) when set.
+  mountHealthEndpoint(app)
   app.use(morgan('tiny'))
   app.use(express.json({ strict: false }))
   app.use(cookieParser(ConfigService.TokenSecret))
@@ -342,6 +344,10 @@ export async function startServer (options = {}) {
     next()
   })
   app.use(WorkspacesMiddleware.ExtractWorkspaceId())
+  // App-authored Express middleware from `src/middleware.js` (bundled to
+  // build/public/static/middleware.js). Runs after auth/workspace so handlers
+  // can rely on req.userId / req.workspaceId when present.
+  for (const mw of await loadAppMiddleware(buildDir)) app.use(mw)
   app.use(createSlowRequestLogger(log))
   if (fs.existsSync(publicDir)) app.use(express.static(publicDir))
   app.use(ProxyInternal())
@@ -625,6 +631,32 @@ export async function startServer (options = {}) {
   return { app, server, port, close: closeServer, lifetime }
 }
 
+/**
+ * Load optional app middleware bundled from `src/middleware.js`.
+ * Accepts a default export that is either a middleware function or an array.
+ *
+ * @param {string} buildDir
+ * @returns {Promise<import('express').RequestHandler[]>}
+ */
+async function loadAppMiddleware (buildDir) {
+  const candidates = [
+    path.resolve(buildDir, 'public', 'static', 'middleware.js'),
+    path.resolve(buildDir, 'middleware.js'),
+  ]
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue
+    try {
+      const mod = await import(pathToFileURL(candidate).href)
+      const value = mod.default
+      if (Array.isArray(value)) return value
+      if (typeof value === 'function') return [value]
+    } catch (err) {
+      log.warn(`Failed to load app middleware from ${candidate}`, undefined, err)
+    }
+  }
+  return []
+}
+
 export default startServer
 export { loadLayoutsById, resolvePageLayoutRender }
 export { ConfigService } from './config.service.js'
@@ -632,6 +664,7 @@ export { ActionService } from './actions/action.service.js'
 export { IntegrationService } from './integration.service.js'
 export { StorageClient } from './storage/storage.client.js'
 export { originalObjectKey, derivativeObjectKey, assertStorageKey } from './storage/storage-keys.js'
+export { isLocalStorageUploadUrl } from './storage/local-storage-url.js'
 export { S3Client } from './storage/s3.client.js'
 export { LocalStorageClient } from './storage/local-storage.client.js'
 export { getSystemSchemas } from './resources/schema.registry.js'

package/src/storage/local-storage-url.js

@@ -0,0 +1,16 @@
+/**
+ * Detect filesystem-backend upload URLs (`/local-storage?key=…`).
+ * S3 presigned URLs must not receive session cookies or Authorization headers.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isLocalStorageUploadUrl (url) {
+  if (!url || typeof url !== 'string') return false
+  try {
+    const parsed = new URL(url, 'http://localhost')
+    return parsed.pathname === '/local-storage' || parsed.pathname.endsWith('/local-storage')
+  } catch {
+    return false
+  }
+}

package/src/storage/local-storage-url.spec.js

@@ -0,0 +1,17 @@
+import { describe, expect, it } from '@jest/globals'
+import { isLocalStorageUploadUrl } from './local-storage-url.js'
+
+describe('isLocalStorageUploadUrl', () => {
+  it('matches relative and absolute local-storage paths', () => {
+    expect(isLocalStorageUploadUrl('/local-storage?key=abc')).toBe(true)
+    expect(isLocalStorageUploadUrl('http://localhost:3006/local-storage?key=abc')).toBe(true)
+    expect(isLocalStorageUploadUrl('https://app.example.com/local-storage?key=id%3Athumb')).toBe(true)
+  })
+
+  it('rejects S3 and unrelated URLs', () => {
+    expect(isLocalStorageUploadUrl('https://bucket.s3.amazonaws.com/key?X-Amz-Signature=abc')).toBe(false)
+    expect(isLocalStorageUploadUrl('/r/abc')).toBe(false)
+    expect(isLocalStorageUploadUrl('')).toBe(false)
+    expect(isLocalStorageUploadUrl(null)).toBe(false)
+  })
+})

package/src/tasks/in-process-sdk.js

@@ -0,0 +1,107 @@
+import { resolveActionId } from '@ossy/sdk'
+import { ActionService } from '../actions/action.service.js'
+import { IntegrationService } from '../integration.service.js'
+import { StorageClient } from '../storage/storage.client.js'
+import { derivativeObjectKey } from '../storage/storage-keys.js'
+
+/**
+ * @param {unknown} file
+ * @returns {Promise<Buffer>}
+ */
+async function fileToBuffer (file) {
+  if (Buffer.isBuffer(file)) return file
+  if (file instanceof Uint8Array) return Buffer.from(file)
+  if (typeof file?.arrayBuffer === 'function') {
+    return Buffer.from(await file.arrayBuffer())
+  }
+  throw new Error('[InProcessSdk] uploadNamedVersion expects a File, Blob, Buffer, or Uint8Array')
+}
+
+/**
+ * Resolve actor/workspace from an eventstore document for nested action invokes.
+ *
+ * @param {object} [event]
+ * @returns {{ userId: string, workspaceId?: string }}
+ */
+function reqFromEvent (event) {
+  return {
+    userId: event?.createdBy
+      ?? event?.payload?.createdBy
+      ?? event?.payload?.userId
+      ?? 'system',
+    workspaceId: event?.payload?.belongsTo
+      ?? event?.belongsTo
+      ?? event?.payload?.workspaceId,
+  }
+}
+
+/**
+ * Same-process SDK for changestream / scheduled tasks when no HTTP bot
+ * credentials (`API_URL` + `OSSY_API_KEY`) are configured.
+ *
+ * Implements the surface media and follow-up tasks use: `invoke` and
+ * `resources.uploadNamedVersion`, via ActionService + StorageClient.
+ *
+ * @param {{ req?: { userId?: string, workspaceId?: string } }} [options]
+ */
+export function createInProcessSdk (options = {}) {
+  const req = options.req ?? { userId: 'system' }
+
+  const sdk = {
+    /**
+     * @param {import('@ossy/sdk').ActionRef} action
+     * @param {Record<string, unknown>} [payload]
+     */
+    invoke (action, payload = {}) {
+      const actionId = resolveActionId(action)
+      return ActionService.invoke(actionId, {
+        payload,
+        sdk,
+        integrations: IntegrationService,
+        req,
+      })
+    },
+
+    /**
+     * Bind actor/workspace from a triggering event for one dispatch.
+     * @param {object} event
+     */
+    withEventContext (event) {
+      return createInProcessSdk({ req: reqFromEvent(event) })
+    },
+
+    get resources () {
+      return {
+        /**
+         * Patch named derivative metadata, then write bytes to storage.
+         * @param {{ id: string, name: string, file: File | Blob | Buffer | Uint8Array }} args
+         */
+        async uploadNamedVersion ({ id, name, file }) {
+          if (!id) throw new Error('[InProcessSdk] uploadNamedVersion requires id')
+          if (!name) throw new Error('[InProcessSdk] uploadNamedVersion requires name')
+          if (!file) throw new Error('[InProcessSdk] uploadNamedVersion requires file')
+
+          const size = typeof file.size === 'number' ? file.size : undefined
+          const type = typeof file.type === 'string' ? file.type : undefined
+          const buffer = await fileToBuffer(file)
+
+          const resource = await sdk.invoke('@ossy/resources/actions/upload-named-version', {
+            id,
+            namedVersion: name,
+            // HTTP SDK historically sent `name`; accept either in the task.
+            name,
+            size: size ?? buffer.length,
+            type,
+          })
+
+          // Action response may rewrite `sizes` to read URLs via withResourceMedia;
+          // always persist with the canonical derivative key.
+          await StorageClient.save(derivativeObjectKey(id, name), buffer)
+          return resource
+        },
+      }
+    },
+  }
+
+  return sdk
+}

package/src/tasks/in-process-sdk.spec.js

@@ -0,0 +1,89 @@
+import { describe, expect, it, jest } from '@jest/globals'
+
+const invokeMock = jest.fn(async (_id, context) => ({
+  id: context.payload.id,
+  content: {
+    sizes: { [context.payload.namedVersion]: `${context.payload.id}:${context.payload.namedVersion}` },
+    uploadUrl: '/local-storage?key=unused',
+  },
+}))
+
+const saveMock = jest.fn(async () => {})
+
+jest.unstable_mockModule('../actions/action.service.js', () => ({
+  ActionService: { invoke: invokeMock },
+}))
+
+jest.unstable_mockModule('../integration.service.js', () => ({
+  IntegrationService: { get: () => null },
+}))
+
+jest.unstable_mockModule('../storage/storage.client.js', () => ({
+  StorageClient: { save: saveMock },
+}))
+
+const { createInProcessSdk } = await import('./in-process-sdk.js')
+
+describe('createInProcessSdk', () => {
+  it('invokes actions in-process with bound req', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk({
+      req: { userId: 'u1', workspaceId: 'ws1' },
+    })
+
+    await sdk.invoke({ id: '@ossy/resources/actions/get' }, { resourceId: 'r1' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/get',
+      expect.objectContaining({
+        payload: { resourceId: 'r1' },
+        req: { userId: 'u1', workspaceId: 'ws1' },
+      }),
+    )
+  })
+
+  it('binds event actor/workspace via withEventContext', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk().withEventContext({
+      createdBy: 'author',
+      payload: { belongsTo: 'workspace-a' },
+    })
+
+    await sdk.invoke('@ossy/resources/actions/get', { resourceId: 'r2' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/get',
+      expect.objectContaining({
+        req: { userId: 'author', workspaceId: 'workspace-a' },
+      }),
+    )
+  })
+
+  it('uploadNamedVersion patches then saves bytes', async () => {
+    invokeMock.mockClear()
+    saveMock.mockClear()
+    const sdk = createInProcessSdk()
+    const bytes = new Uint8Array([1, 2, 3, 4])
+
+    await sdk.resources.uploadNamedVersion({
+      id: 'file1',
+      name: 'thumbnailSmall',
+      file: new File([bytes], 'thumbnailSmall', { type: 'image/jpeg' }),
+    })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/upload-named-version',
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          id: 'file1',
+          namedVersion: 'thumbnailSmall',
+          type: 'image/jpeg',
+        }),
+      }),
+    )
+    expect(saveMock).toHaveBeenCalledWith(
+      'file1:thumbnailSmall',
+      expect.any(Buffer),
+    )
+  })
+})

package/src/tasks/task-service.js

@@ -147,7 +147,10 @@ export class TaskService {
   static dispatch(event, { sdk } = {}) {
     if (!event) return
 
-    const effectiveSdk = sdk ?? TaskService._sdk
+    const baseSdk = sdk ?? TaskService._sdk
+    const effectiveSdk = typeof baseSdk?.withEventContext === 'function'
+      ? baseSdk.withEventContext(event)
+      : baseSdk
 
     for (const { metadata, handler } of TaskService._tasks) {
       const triggers = metadata.triggers ?? []

package/src/test/flow-runner.js

@@ -246,10 +246,16 @@ export async function runFlow (flow, options = {}) {
       }
       const engine = schemaEngineFromManifest(manifest)
       const content = mockFormContent(engine, template, context)
+      const formTimeout = step.timeout ?? 15000
       const formRoot = formId ? page.locator(`form[id="${formId}"]`) : page
+      await formRoot.waitFor({ state: 'visible', timeout: formTimeout })
       for (const field of template.fields) {
         const value = content[field.name]
-        const locator = formRoot.locator(`[name="${field.name}"]`)
+        if (value === undefined || value === null) {
+          throw new Error(`mockFormContent produced no value for field "${field.name}"`)
+        }
+        const locator = formRoot.locator(`[name="${field.name}"]`).first()
+        await locator.waitFor({ state: 'visible', timeout: formTimeout })
         const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
         if (tag === 'select') {
           await locator.selectOption(String(value))
@@ -258,7 +264,18 @@ export async function runFlow (flow, options = {}) {
           if (inputType === 'checkbox') {
             if (value) await locator.check()
           } else {
-            await locator.fill(String(value))
+            // Retry fills: early hydration can accept DOM input then wipe on re-render.
+            const asText = String(value)
+            for (let attempt = 0; attempt < 3; attempt++) {
+              await locator.fill(asText)
+              try {
+                await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
+                break
+              } catch (err) {
+                if (attempt === 2) throw err
+                await page.waitForTimeout(150)
+              }
+            }
           }
         } else {
           await locator.fill(String(value))
@@ -271,10 +288,26 @@ export async function runFlow (flow, options = {}) {
       if (!page) throw new Error('action step requires a Playwright page')
       const actionId = resolveActionId(step.action)
       const service = resolveActionService(step.action, step.service)
-      const locator = page.locator(actionSelector(actionId, service)).first()
+      const matches = page.locator(actionSelector(actionId, service))
       const actionTimeout = step.timeout ?? 15000
-      await locator.waitFor({ state: 'visible', timeout: actionTimeout })
-      await locator.click()
+      await matches.first().waitFor({ state: 'attached', timeout: actionTimeout })
+      // Prefer an actionable match when duplicates exist (e.g. hero CTA under a page overlay).
+      const count = await matches.count()
+      let clicked = false
+      let lastError
+      for (let i = 0; i < count; i++) {
+        const candidate = matches.nth(i)
+        try {
+          await candidate.click({ timeout: Math.min(5000, actionTimeout) })
+          clicked = true
+          break
+        } catch (err) {
+          lastError = err
+        }
+      }
+      if (!clicked) {
+        throw lastError ?? new Error(`No actionable locator for ${actionSelector(actionId, service)}`)
+      }
       continue
     }
 

package/src/test/playwright.config.js

@@ -17,8 +17,16 @@
 /** @type {import('@playwright/test').PlaywrightTestConfig} */
 export default {
   retries: process.env.CI ? 1 : 0,
+  // Fail hung flow steps instead of sitting on the default 30s forever across many actions.
+  timeout: process.env.CI ? 60_000 : 30_000,
+  expect: {
+    timeout: process.env.CI ? 15_000 : 5_000,
+  },
   use: {
     baseURL: process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002',
+    trace: process.env.CI ? 'on-first-retry' : 'off',
+    actionTimeout: process.env.CI ? 15_000 : 0,
+    navigationTimeout: process.env.CI ? 30_000 : 0,
   },
   reporter: [['list']],
   env: {

package/src/token.service.js

@@ -24,7 +24,7 @@ export class TokenService {
 
       if (!token) {
         log.debug('[TokenService] No token to verify')
-        return reject(new Error('No token'))
+        return reject(Object.assign(new Error('No token'), { status: 401 }))
       }
 
       jwt.verify(token, ConfigService.TokenSecret, { algorithms: ['HS256'] }, (error, payload) => {
@@ -32,7 +32,12 @@ export class TokenService {
 
         if (errorType) {
           log.error('[TokenService]: Token invalid', undefined, error)
-          return reject()
+          // Callers (e.g. POST /actions) use `err.status ?? 500` — always attach 401
+          // so unverifiable auth tokens are not reported as internal errors (#494).
+          return reject(Object.assign(new Error('Invalid or expired token'), {
+            status: 401,
+            cause: error,
+          }))
         }
 
         log.info('[TokenService]: Token verified')

package/src/token.service.spec.js

@@ -0,0 +1,49 @@
+import { beforeAll, describe, expect, it } from '@jest/globals'
+import jwt from 'jsonwebtoken'
+import { TokenService } from './token.service.js'
+import { ConfigService } from './config.service.js'
+
+describe('TokenService.verify', () => {
+  beforeAll(() => {
+    process.env.TOKEN_SECRET = process.env.TOKEN_SECRET || 'test-token-secret-for-verify'
+  })
+
+  it('resolves a valid HS256 token payload', async () => {
+    const token = jwt.sign({ sub: 'user-1', type: 'WebAuth' }, ConfigService.TokenSecret, {
+      algorithm: 'HS256',
+      expiresIn: '1h',
+    })
+    await expect(TokenService.verify(token)).resolves.toMatchObject({
+      sub: 'user-1',
+      type: 'WebAuth',
+    })
+  })
+
+  it('rejects missing tokens with status 401', async () => {
+    await expect(TokenService.verify('')).rejects.toMatchObject({
+      message: 'No token',
+      status: 401,
+    })
+    await expect(TokenService.verify(null)).rejects.toMatchObject({
+      status: 401,
+    })
+  })
+
+  it('rejects garbage tokens with status 401 (not an empty rejection)', async () => {
+    await expect(TokenService.verify('not-a-jwt')).rejects.toMatchObject({
+      message: 'Invalid or expired token',
+      status: 401,
+    })
+  })
+
+  it('rejects expired tokens with status 401', async () => {
+    const token = jwt.sign({ sub: 'user-1' }, ConfigService.TokenSecret, {
+      algorithm: 'HS256',
+      expiresIn: -10,
+    })
+    await expect(TokenService.verify(token)).rejects.toMatchObject({
+      message: 'Invalid or expired token',
+      status: 401,
+    })
+  })
+})

package/src/users.middleware.js

@@ -26,21 +26,31 @@ function normalizeAuthToken (token) {
  */
 export class UsersMiddleware {
 
-  /** Reject revoked API tokens (JWT alone stays valid until expiry). */
-  static assertApiTokenActive(payload) {
-    if (payload.type !== 'Api' || !payload.jti) {
+  /**
+   * Reject revoked session/API tokens (JWT alone stays valid until expiry).
+   * WebAuth tokens with `jti` are checked after sign-out (#359); API tokens
+   * keep the same revoke path. Legacy WebAuth JWTs without `jti` skip this.
+   */
+  static assertAuthTokenActive(payload) {
+    if ((payload.type !== 'Api' && payload.type !== 'WebAuth') || !payload.jti) {
       return Promise.resolve(payload)
     }
     return Aggregate.Of(Token, payload.jti)
       .then(aggregate => {
         const view = Token.View(aggregate.events, aggregate.state)
         if (view.status === 'Revoked') {
-          return Promise.reject(new Error('Api token revoked'))
+          const label = payload.type === 'Api' ? 'Api token revoked' : 'Auth token revoked'
+          return Promise.reject(Object.assign(new Error(label), { status: 401 }))
         }
         return payload
       })
   }
 
+  /** @deprecated Use assertAuthTokenActive — kept for callers that still import the old name. */
+  static assertApiTokenActive(payload) {
+    return UsersMiddleware.assertAuthTokenActive(payload)
+  }
+
   /**
    * Resolves the caller to a real user (with workspaces and policies attached)
    * or to the anonymous principal. Authorization / role checks belong in a separate step.
@@ -74,7 +84,7 @@ export class UsersMiddleware {
 
     withTimeout(
       TokenService.verify(authToken)
-        .then(UsersMiddleware.assertApiTokenActive)
+        .then(UsersMiddleware.assertAuthTokenActive)
         .then(payload => {
           req.authPayload = payload
           req.tokenScopes = payload?.type === 'Api' ? (payload.scopes ?? ['*']) : null

package/src/users.middleware.spec.js

@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const ofMock = jest.fn()
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  Aggregate: {
+    Of: ofMock,
+  },
+}))
+
+jest.unstable_mockModule('@ossy/observability', () => ({
+  createLogger: () => ({
+    debug () {},
+    info () {},
+    warn () {},
+    error () {},
+  }),
+}))
+
+jest.unstable_mockModule('@ossy/users/server', () => ({
+  User: { name: 'User' },
+}))
+
+jest.unstable_mockModule('@ossy/tokens/server', () => ({
+  Token: {
+    View (events, state = {}) {
+      return events.reduce((token, event) => {
+        if (event.event === 'Created') {
+          return { ...event.payload, status: 'Active', id: event.resourceId }
+        }
+        if (event.event === 'Revoked') {
+          return { ...token, status: 'Revoked' }
+        }
+        return token
+      }, state)
+    },
+  },
+}))
+
+jest.unstable_mockModule('@ossy/policies/server', () => ({
+  PoliciesQueries: { GetPoliciesForUser: async () => [] },
+}))
+
+jest.unstable_mockModule('./config.service.js', () => ({
+  ConfigService: { AnonymousUserId: 'anonymous' },
+}))
+
+jest.unstable_mockModule('./token.service.js', () => ({
+  TokenService: { verify: async () => ({}) },
+}))
+
+jest.unstable_mockModule('./request-diagnostics.js', () => ({
+  OperationTimeoutError: class OperationTimeoutError extends Error {},
+  resolveTimeoutMs: () => 10_000,
+  withTimeout: (promise) => promise,
+}))
+
+const { UsersMiddleware } = await import('./users.middleware.js')
+
+describe('UsersMiddleware.assertAuthTokenActive', () => {
+  beforeEach(() => {
+    ofMock.mockReset()
+  })
+
+  it('allows payloads without jti (legacy WebAuth)', async () => {
+    await expect(UsersMiddleware.assertAuthTokenActive({
+      type: 'WebAuth',
+      sub: 'user-1',
+    })).resolves.toEqual({ type: 'WebAuth', sub: 'user-1' })
+    expect(ofMock).not.toHaveBeenCalled()
+  })
+
+  it('allows active WebAuth tokens', async () => {
+    ofMock.mockResolvedValue({
+      events: [{ event: 'Created', resourceId: 'sess-1', payload: { type: 'WebAuth' } }],
+      state: {},
+    })
+
+    await expect(UsersMiddleware.assertAuthTokenActive({
+      type: 'WebAuth',
+      jti: 'sess-1',
+      sub: 'user-1',
+    })).resolves.toMatchObject({ jti: 'sess-1' })
+  })
+
+  it('rejects revoked WebAuth tokens with status 401', async () => {
+    ofMock.mockResolvedValue({
+      events: [
+        { event: 'Created', resourceId: 'sess-2', payload: { type: 'WebAuth' } },
+        { event: 'Revoked', payload: {} },
+      ],
+      state: {},
+    })
+
+    await expect(UsersMiddleware.assertAuthTokenActive({
+      type: 'WebAuth',
+      jti: 'sess-2',
+      sub: 'user-1',
+    })).rejects.toMatchObject({
+      message: 'Auth token revoked',
+      status: 401,
+    })
+  })
+
+  it('rejects revoked API tokens', async () => {
+    ofMock.mockResolvedValue({
+      events: [
+        { event: 'Created', resourceId: 'api-1', payload: { type: 'Api' } },
+        { event: 'Revoked', payload: {} },
+      ],
+      state: {},
+    })
+
+    await expect(UsersMiddleware.assertAuthTokenActive({
+      type: 'Api',
+      jti: 'api-1',
+      sub: 'user-1',
+    })).rejects.toMatchObject({
+      message: 'Api token revoked',
+      status: 401,
+    })
+  })
+})