@ossy/platform 1.39.2 → 1.39.3

package/README.md

@@ -7,14 +7,18 @@ Express-based application server runtime for the Ossy platform. It reads the bui
 At startup `@ossy/platform`:
 
 1. Loads `build/manifest.json` produced by `@ossy/app build`.
-2. Registers and runs all **startup hooks** (`*.startup.js`) in order.
-3. Connects all **integrations** (`*.integration.js`) by calling `connect({ env })`.
-4. Registers all **tasks** (`*.task.js`) with `TaskService` and starts the cron scheduler.
-5. Registers all **resource templates** (`*.resource.js`) with `registerResourceTemplate`.
-6. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
-7. Registers all **actions** (`*.action.js`) with `ActionService`.
-8. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
-9. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
+2. Registers the manifest's toggleable packages with `@ossy/workspaces/entitlements` (`setEnableablePackages`) so workspace service toggles and action entitlement checks use scoped npm names (`@ossy/booking`, not slug-only keys).
+3. Registers and runs all **startup hooks** (`*.startup.js`) in order.
+4. Connects all **integrations** (`*.integration.js`) by calling `connect({ env })`.
+5. Registers all **tasks** (`*.task.js`) with `TaskService` and starts the cron scheduler.
+6. Registers all **schemas** (`*.schema.js`) with `registerSchema`.
+7. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
+8. Registers all **actions** (`*.action.js`) with `ActionService`.
+9. Mounts **MCP** at `POST /mcp` and serves `GET /capabilities.json`.
+10. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
+11. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
+
+Page SSR fills the `app:content` slot (see `PlatformShell` and `resolve-app-slots` in `@ossy/app`). App chrome uses namespaced keys such as `app:header` mapped from `export const slots` in `*.layout.jsx`.
 
 ## Quick start
 
@@ -69,9 +73,9 @@ import {
   StorageClient,
   S3Client,
   LocalStorageClient,
-  getSystemResourceTemplates,
-  normalizeAndValidateDocumentContent,
-  validateResourceTemplatesForImport,
+  getSystemSchemas,
+  schemaForWorkspace,
+  validateSchemasForImport,
 } from '@ossy/platform'
 ```
 
@@ -95,14 +99,14 @@ const action = ActionService.get('orders/create')  // { id, access, run } | null
 const all = ActionService.all()
 ```
 
-### `getSystemResourceTemplates`
+### `getSystemSchemas`
 
-Returns all resource templates registered from `*.resource.js` files.
+Returns all system schemas registered from `*.schema.js` files.
 
 ```js
-import { getSystemResourceTemplates } from '@ossy/platform'
+import { getSystemSchemas } from '@ossy/platform'
 
-const templates = getSystemResourceTemplates()
+const schemas = getSystemSchemas()
 // [{ id: '@ossy/tool/doc', name: 'Tool Doc', fields: [...] }, ...]
 ```
 
@@ -121,7 +125,7 @@ The platform is built around file conventions called **primitives**. Each primit
 | Integration | `*.integration.js` | Third-party client connected at startup |
 | Email | `*.email.jsx` | Transactional React email template |
 | Component | `*.component.jsx` | Injectable UI fragment |
-| Resource | `*.resource.js` | Custom document-type schema |
+| Resource | `*.schema.js` | Custom document-type schema |
 | Aggregate | `*.aggregate.js` | Event-sourced domain object |
 | Startup | `*.startup.js` | One-time boot hook |
 
@@ -130,7 +134,7 @@ The platform is built around file conventions called **primitives**. Each primit
 ```
 Incoming request
   │
-  ├─ POST /actions  ──► ActionService.invoke() ──► TaskService.invoke() ──► task.run({ payload, sdk, log, integrations, req })
+  ├─ POST /actions  ──► ActionService.invoke(actionId) ──► TaskService.invoke(taskIdFromActionId) ──► task.run(...)
   │
   ├─ Match API route    ──► api.handle(req, res)
   │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "1.39.2",
+  "version": "1.39.3",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -24,8 +24,11 @@
     "./test": "./src/test/index.js",
     "./test/jest.setup.js": "./src/test/jest.setup.js",
     "./test/e2e-runner.js": "./src/test/e2e-runner.js",
+    "./test/flow-runner.js": "./src/test/flow-runner.js",
     "./test/playwright.config.js": "./src/test/playwright.config.js",
-    "./locale": "./src/locale.js"
+    "./locale": "./src/locale.js",
+    "./storage-keys": "./src/storage/storage-keys.js",
+    "./mcp": "./src/mcp/mount-platform-mcp.js"
   },
   "scripts": {
     "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\"",
@@ -40,21 +43,27 @@
     "@aws-sdk/s3-request-presigner": "^3.1057.0",
     "@aws-sdk/util-create-request": "^3.972.26",
     "@aws-sdk/util-format-url": "^3.972.17",
-    "@ossy/event-store": "^1.8.2",
-    "@ossy/locale": "^1.40.2",
-    "@ossy/observability": "^1.8.2",
-    "@ossy/policies": "^1.13.2",
-    "@ossy/sdk": "^1.40.2",
-    "@ossy/tokens": "^1.13.2",
-    "@ossy/users": "^1.13.2",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@ossy/app": "^1.40.3",
+    "@ossy/event-store": "^1.8.3",
+    "@ossy/locale": "^1.40.3",
+    "@ossy/observability": "^1.8.3",
+    "@ossy/policies": "^1.13.3",
+    "@ossy/schema": "^1.0.1",
+    "@ossy/sdk": "^1.40.3",
+    "@ossy/tokens": "^1.13.3",
+    "@ossy/users": "^1.13.3",
+    "@ossy/workspaces": "^1.17.3",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
     "jsonwebtoken": "^9.0.0",
     "mongodb": "^7.2.0",
-    "morgan": ">=1.10.1 <2.0.0"
+    "morgan": ">=1.10.1 <2.0.0",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@faker-js/faker": "^9.9.0",
     "@jest/globals": "^30.2.0",
     "@playwright/test": ">=1.40.0",
     "casual": "^1.6.2",
@@ -64,5 +73,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "2b8745d57fee8b6c08787e2755b4df489291a5cd"
+  "gitHead": "a0d89185a17f8de8ce328c3a648c108ff1d61d8f"
 }

package/src/Definition.js

@@ -4,4 +4,5 @@ export const Definition = {
   description: 'Deployment platform configuration aligned with deployment-tools S3 platform-config.json.',
   icon: 'controller',
   statuses: ['beta'],
+  entitlementRequired: false,
 }

package/src/PlatformShell.jsx

@@ -14,23 +14,23 @@ import { ComponentSlotsProvider, Slot } from '@ossy/design-system'
  * provider shallow-merges on top.
  *
  * Slot regions rendered here (namespaced keys from app `export const slots`):
- *   shell:header           — top bar across full width
- *   shell:sidebar          — left column, full height
- *   shell:toolbar          — below header, above content (contextual actions)
- *   shell:notifications    — floating / bottom corner (toasts, badges)
- *   shell:system-messages  — banner above content (maintenance, errors)
+ *   app:header           — top bar across full width
+ *   app:sidebar          — left column, full height
+ *   app:toolbar          — below header, above content (contextual actions)
+ *   app:notifications    — floating / bottom corner (toasts, badges)
+ *   app:system-messages  — banner above content (maintenance, errors)
  *
  * @param {{ slots?: Record<string, import('react').ComponentType | null>, children: import('react').ReactNode }} props
  */
 export function PlatformShell({ slots = {}, children }) {
   return (
     <ComponentSlotsProvider slots={slots}>
-      <Slot name="shell:system-messages" />
-      <Slot name="shell:header" />
-      <Slot name="shell:sidebar" />
-      <Slot name="shell:toolbar" />
+      <Slot name="app:system-messages" />
+      <Slot name="app:header" />
+      <Slot name="app:sidebar" />
+      <Slot name="app:toolbar" />
       {children}
-      <Slot name="shell:notifications" />
+      <Slot name="app:notifications" />
     </ComponentSlotsProvider>
   )
 }

package/src/actions/action.service.js

@@ -1,5 +1,8 @@
 import { createLogger } from '@ossy/observability'
+import { taskIdFromActionId } from '@ossy/schema'
 import { TaskService } from '../tasks/task-service.js'
+import { ActionInvocationService } from '../audit/action-invocation-service.js'
+import { assertActionScoped } from '../auth/action-scopes.js'
 
 const log = createLogger('platform/actions')
 
@@ -9,8 +12,7 @@ const _actions = new Map()
 /**
  * Registry for action intent (`*.action.js` metadata only).
  *
- * Actions name what callers want: `{ id, access }`. Implementation lives in
- * a task with the same id — see `TaskService.invoke`.
+ * Implementation lives in `{feature}/tasks/{intent}` derived from the action id.
  */
 export const ActionService = {
   /**
@@ -19,7 +21,7 @@ export const ActionService = {
    * @param {{ metadata: { id: string, access?: string } }} mod
    */
   register (mod) {
-    const { id, access = 'authenticated' } = mod?.metadata ?? {}
+    const { id, access = 'authenticated', audit = true } = mod?.metadata ?? {}
 
     if (typeof id !== 'string' || id.trim() === '') {
       throw new Error(`[ActionService] Action module must export a non-empty string "metadata.id" (got ${JSON.stringify(id)})`)
@@ -29,7 +31,7 @@ export const ActionService = {
       log.warn(`[ActionService] Action "${id}" already registered — overwriting`)
     }
 
-    _actions.set(id, { id, access })
+    _actions.set(id, { id, access, audit })
     log.info(`[ActionService] Registered action "${id}" (access: ${access})`)
   },
 
@@ -49,7 +51,15 @@ export const ActionService = {
   },
 
   /**
-   * Invoke an action by id — enforces registration, delegates execution to TaskService.
+   * @param {string} actionId
+   * @returns {boolean}
+   */
+  hasHandler (actionId) {
+    return TaskService.hasTaskForAction(actionId)
+  },
+
+  /**
+   * Invoke an action by id — records audit, runs the derived primary task, dispatches on_action follow-ups.
    *
    * @param {string} id
    * @param {{ payload?: unknown, sdk?: unknown, log?: unknown, integrations?: unknown, req?: unknown }} context
@@ -58,6 +68,69 @@ export const ActionService = {
   async invoke (id, context = {}) {
     const action = _actions.get(id)
     if (!action) throw new Error(`[ActionService] Action not found: "${id}"`)
-    return TaskService.invoke(id, context)
+
+    const taskId = taskIdFromActionId(id)
+    if (!TaskService.has(taskId)) {
+      throw new Error(`[ActionService] No primary task for action "${id}" (expected "${taskId}")`)
+    }
+
+    if (context.req?.tokenScopes) {
+      assertActionScoped(id, context.req.tokenScopes)
+    }
+
+    const skipAudit = action.audit === false
+    const invocationId = skipAudit
+      ? null
+      : await ActionInvocationService.recordStart(id, context)
+
+    const invokeContext = {
+      ...context,
+      actionInvocationId: invocationId,
+      actionId: id,
+      audit: skipAudit ? false : undefined,
+    }
+
+    try {
+      const result = await TaskService.invoke(taskId, invokeContext)
+      const taskRunId = invokeContext.audit?.taskRunId ?? null
+
+      if (!skipAudit) {
+        await ActionInvocationService.recordSuccess(invocationId, context, {
+          taskRunId,
+        })
+
+        TaskService.dispatchOnAction({
+          actionId: id,
+          actionInvocationId: invocationId,
+          payload: context.payload,
+          result,
+          success: true,
+          req: context.req,
+          sdk: context.sdk,
+        })
+      }
+
+      return result
+    } catch (error) {
+      const taskRunId = invokeContext.audit?.taskRunId ?? null
+
+      if (!skipAudit) {
+        await ActionInvocationService.recordFailure(invocationId, context, error, {
+          taskRunId,
+        })
+
+        TaskService.dispatchOnAction({
+          actionId: id,
+          actionInvocationId: invocationId,
+          payload: context.payload,
+          success: false,
+          error,
+          req: context.req,
+          sdk: context.sdk,
+        })
+      }
+
+      throw error
+    }
   },
 }

package/src/audit/action-invocation-service.js

@@ -0,0 +1,144 @@
+import { nanoid } from 'nanoid'
+import { Aggregate } from '@ossy/event-store'
+import { createLogger } from '@ossy/observability'
+import { taskIdFromActionId } from '@ossy/schema'
+import { ActionInvocation } from './action-invocation.aggregate.js'
+import { PlatformSchema } from '../schema-ids.js'
+import { MeteringService } from '../metering/metering-service.js'
+import { detectChannel } from './detect-channel.js'
+import {
+  hashPayload,
+  moduleIdFromTaskId,
+  resolveActorId,
+  resolveWorkspaceId,
+  summarizeError,
+} from './audit-helpers.js'
+
+const log = createLogger('platform/action-invocation')
+
+/**
+ * Audit trail for action invocations (Wave 3 — agent trust / billing envelope).
+ */
+export const ActionInvocationService = {
+
+  /**
+   * @param {string} actionId
+   * @param {object} context
+   * @returns {Promise<string>} invocationId
+   */
+  async recordStart (actionId, context = {}) {
+    const invocationId = nanoid()
+    const workspaceId = resolveWorkspaceId(context)
+    const actorId = resolveActorId(context)
+    const channel = detectChannel(context.req)
+    const payloadHash = hashPayload(context.payload)
+
+    context.actionInvocationId = invocationId
+    context.audit = context.audit ?? {}
+    context.audit.invocationId = invocationId
+    context.audit.startedAt = Date.now()
+    context.audit.actionId = actionId
+
+    try {
+      await Aggregate.Of(ActionInvocation, {
+        resourceId: invocationId,
+        type: PlatformSchema.actionInvocation,
+        event: 'Invoked',
+        createdBy: actorId ?? undefined,
+        payload: {
+          actionId,
+          moduleId: moduleIdFromTaskId(actionId),
+          channel,
+          payloadHash,
+          actorId,
+          belongsTo: workspaceId,
+          location: '/@ossy/audit/actions/',
+        },
+      })
+    } catch (err) {
+      log.warn('[ActionInvocationService] Failed to record Invoked', { actionId, invocationId }, err)
+    }
+
+    return invocationId
+  },
+
+  /**
+   * @param {string} invocationId
+   * @param {object} context
+   * @param {{ taskRunId?: string | null }} meta
+   */
+  async recordSuccess (invocationId, context, meta = {}) {
+    const durationMs = Date.now() - (context.audit?.startedAt ?? Date.now())
+    const actorId = resolveActorId(context)
+
+    try {
+      await Aggregate.Of(ActionInvocation, invocationId)
+        .then(Aggregate.Add({
+          event: 'Completed',
+          createdBy: actorId ?? undefined,
+          payload: {
+            durationMs,
+            taskRunId: meta.taskRunId ?? context.audit?.taskRunId ?? null,
+          },
+        }))
+    } catch (err) {
+      log.warn('[ActionInvocationService] Failed to record Completed', { invocationId }, err)
+    }
+
+    const actionId = context.audit?.actionId
+    const taskId = actionId ? taskIdFromActionId(actionId) : null
+    await MeteringService.record({
+      kind: 'action',
+      actionId: actionId ?? null,
+      taskId,
+      channel: detectChannel(context.req),
+      workspaceId: resolveWorkspaceId(context),
+      actorId,
+      durationMs,
+      success: true,
+      actionInvocationId: invocationId,
+      taskRunId: meta.taskRunId ?? context.audit?.taskRunId ?? null,
+    })
+  },
+
+  /**
+   * @param {string} invocationId
+   * @param {object} context
+   * @param {Error} error
+   * @param {{ taskRunId?: string | null }} meta
+   */
+  async recordFailure (invocationId, context, error, meta = {}) {
+    const durationMs = Date.now() - (context.audit?.startedAt ?? Date.now())
+    const actorId = resolveActorId(context)
+
+    try {
+      await Aggregate.Of(ActionInvocation, invocationId)
+        .then(Aggregate.Add({
+          event: 'Failed',
+          createdBy: actorId ?? undefined,
+          payload: {
+            durationMs,
+            taskRunId: meta.taskRunId ?? context.audit?.taskRunId ?? null,
+            error: summarizeError(error),
+          },
+        }))
+    } catch (err) {
+      log.warn('[ActionInvocationService] Failed to record Failed', { invocationId }, err)
+    }
+
+    const actionId = context.audit?.actionId
+    const taskId = actionId ? taskIdFromActionId(actionId) : null
+    await MeteringService.record({
+      kind: 'action',
+      actionId: actionId ?? null,
+      taskId,
+      channel: detectChannel(context.req),
+      workspaceId: resolveWorkspaceId(context),
+      actorId,
+      durationMs,
+      success: false,
+      actionInvocationId: invocationId,
+      taskRunId: meta.taskRunId ?? context.audit?.taskRunId ?? null,
+    })
+  },
+}

package/src/audit/action-invocation.aggregate.js

@@ -0,0 +1,59 @@
+import { PlatformSchema } from '../schema-ids.js'
+
+/**
+ * ADR 0008 entity — audit record for each action invocation (POST /actions, MCP, SDK).
+ */
+export class ActionInvocation {
+
+  static kind = 'entity'
+  static SchemaId = PlatformSchema.actionInvocation
+  static AggregateType = 'ActionInvocation'
+
+  static View (events, state = {}) {
+    return events.reduce((invocation, event) => {
+      switch (event.event) {
+
+        case 'Invoked':
+          return {
+            ...invocation,
+            id: event.resourceId,
+            type: event.type,
+            actionId: event.payload.actionId,
+            moduleId: event.payload.moduleId,
+            channel: event.payload.channel,
+            payloadHash: event.payload.payloadHash,
+            actorId: event.payload.actorId ?? event.createdBy ?? null,
+            workspaceId: event.payload.belongsTo ?? null,
+            status: 'in progress',
+            startedAt: event.created,
+            created: event.created,
+          }
+
+        case 'Completed':
+          return {
+            ...invocation,
+            status: 'success',
+            completedAt: event.created,
+            durationMs: event.payload.durationMs,
+            taskRunId: event.payload.taskRunId ?? null,
+          }
+
+        case 'Failed':
+          return {
+            ...invocation,
+            status: 'failed',
+            completedAt: event.created,
+            durationMs: event.payload.durationMs,
+            taskRunId: event.payload.taskRunId ?? null,
+            error: event.payload.error ?? null,
+          }
+
+        default:
+          return invocation
+      }
+    }, state)
+  }
+}
+
+export { ActionInvocation as Aggregate }
+export const id = 'platform/schema/action-invocation'

package/src/audit/audit-helpers.js

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto'
+import { featureFromTaskId } from '@ossy/schema'
+
+/** @param {string} taskId e.g. `@ossy/booking/tasks/create` */
+export function moduleIdFromTaskId (taskId) {
+  return featureFromTaskId(taskId)
+}
+
+/** @param {unknown} payload */
+export function hashPayload (payload) {
+  try {
+    const json = JSON.stringify(payload ?? null)
+    return createHash('sha256').update(json).digest('hex')
+  } catch {
+    return createHash('sha256').update(String(payload)).digest('hex')
+  }
+}
+
+/** 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) }
+  }
+  if (Array.isArray(result)) {
+    return { kind: 'array', length: result.length }
+  }
+  const keys = Object.keys(result)
+  return { kind: 'object', keys: keys.slice(0, 20), keyCount: keys.length }
+}
+
+/** @param {Error | { message?: string, code?: string }} error */
+export function summarizeError (error) {
+  if (!error) return { message: 'Unknown error' }
+  return {
+    message: String(error.message ?? error).slice(0, 500),
+    code: error.code ?? undefined,
+  }
+}
+
+/**
+ * @param {object} context
+ * @returns {string | null}
+ */
+export function resolveWorkspaceId (context) {
+  return context.workspaceId
+    ?? context.payload?.workspaceId
+    ?? context.req?.workspaceId
+    ?? null
+}
+
+/**
+ * @param {object} context
+ * @returns {string | null}
+ */
+export function resolveActorId (context) {
+  return context.userId
+    ?? context.payload?.userId
+    ?? context.req?.userId
+    ?? null
+}

package/src/audit/detect-channel.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve billing/audit channel from an Express request (or similar).
+ *
+ * @param {import('express').Request | undefined} req
+ * @returns {'web_ui' | 'sdk' | 'api' | 'mcp' | 'cli'}
+ */
+export function detectChannel (req) {
+  if (!req) return 'api'
+
+  const url = req.originalUrl ?? req.url ?? ''
+  if (url.includes('/mcp')) return 'mcp'
+
+  const authHeader = req.get?.('Authorization') ?? req.headers?.authorization
+  if (authHeader && !req.signedCookies?.auth) return 'api'
+
+  if (req.signedCookies?.auth) return 'web_ui'
+
+  return 'api'
+}

package/src/audit/list-task-runs.action.js

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

package/src/audit/list-task-runs.task.js

@@ -0,0 +1,17 @@
+import { getProjection } from '@ossy/event-store'
+import { TaskRunListProjection } from '../audit/task-run-list.aggregate.js'
+
+export const metadata = {
+  id: '@ossy/platform/tasks/list-task-runs',
+  audit: false,
+}
+
+export async function run ({ payload, req }) {
+  const workspaceId = payload?.workspaceId ?? req?.workspaceId
+  if (!workspaceId) {
+    throw Object.assign(new Error('workspaceId required'), { status: 400 })
+  }
+
+  const projection = await getProjection(TaskRunListProjection.ProjectionId, workspaceId)
+  return projection?.state ?? TaskRunListProjection.initialState(workspaceId)
+}