fix(actions): dispatch on the declared action type over REST (#3915) (#3919)

The REST `/actions/:object/:action` route had no action-type branching — every
action went to the script-handler registry, while the MCP `run_action` bridge
implemented the `flow` branch. A spec-faithful caller invoking a `type: 'flow'`
action got `Action '' on object '*' not found`.

Both headless surfaces now share one dispatch: `flow` runs on the automation
service (via the extracted `dispatchFlowAction`, with the caller's identity
forwarded so `runAs: 'user'` enforces RLS as the invoker), `script` keeps the
registry path, and `url`/`modal`/`form`/`api` return a 400 naming the type and
what to call instead. The route also resolves standalone `defineAction`
artifacts and Studio-authored `action` rows, which additionally closes a
declared-but-unenforced ADR-0066 D4 gate on that path.

Author: os-zhuang

.changeset/rest-actions-type-dispatch.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/runtime": minor
+---
+
+fix(actions): dispatch on the declared action `type` over REST — flow actions are no longer MCP-only (#3915)
+
+`POST /api/v1/actions/:object/:action` had **no action-type branching at all**.
+Whatever an action declared, the route went straight to `ql.executeAction` — the
+script-handler registry — while the MCP `run_action` bridge had implemented the
+`flow` branch since #2849. The spec is unambiguous that every non-`script` type
+dispatches on `target` (`packages/spec/src/ui/action.zod.ts`), so a REST/SDK
+caller who followed it and invoked a `type: 'flow'` action got
+
+```
+Action '' on object '*' not found
+```
+
+and had to know, out of band, to call `POST /api/v1/automation/:target/trigger`
+itself. Worse for the Studio-authored case: `resyncAuthoredActions` deliberately
+registers **no** handler for a flow-typed action ("no body (target/flow/url
+action)"), so there was never anything for the registry to find.
+
+The two headless surfaces now share one dispatch:
+
+- **`flow`** → `automation.execute(action.target, …)` via the new
+  `dispatchFlowAction`, which the MCP path now calls too. The caller's identity
+  (`userId` / `positions` / `permissions` / `tenantId`) is forwarded, so a
+  `runAs: 'user'` flow enforces RLS as the invoker instead of falling into the
+  user-less UNSCOPED path (ADR-0049). A flow action on a kernel with no
+  automation service reports **503**, not a `{ success: false }` body.
+- **`script`** → the handler registry, unchanged. An action with no resolvable
+  declaration is handler-only by definition and keeps that path.
+- **`url` / `modal` / `form` / `api`** → **400** naming the type and the
+  prescription (for `api`, the `target` endpoint to call directly) instead of a
+  registry miss that reads like the action does not exist.
+
+The route also resolves **standalone declarations** now — `defineAction`
+artifacts in the ObjectQL registry and Studio-authored `action` metadata rows,
+neither of which appears inside any object's `actions[]`. They were invisible
+to this route before, which is why a flow-typed one could not be dispatched —
+and, separately, why its `requiredPermissions` were declared-but-unenforced on
+REST while MCP honoured them. The ADR-0066 D4 gate still runs **before** the
+type check, so an unauthorized caller learns nothing about how an action
+dispatches.
+
+**Migration:** a caller invoking a `url`/`modal`/`form`/`api` action through
+this endpoint used to receive `{ success: false, error: "Action '' on object
+'*' not found" }` (HTTP 200) and now receives a 400 that says what to call
+instead. No spec-faithful action changes behavior.

content/docs/ui/actions.mdx

@@ -233,6 +233,16 @@ curl -b cookies.txt -X POST \
 Global (object-less) actions post to `/api/v1/actions/global/:action`. For
 credentials, see [API Authentication](/docs/api#authentication).
 
+The endpoint dispatches on the **declared `type`**, exactly like the MCP
+`run_action` tool — so the same URL invokes a script handler or a flow:
+
+| `type` | Over REST |
+|:---|:---|
+| `script` | Runs the registered handler / inline body. |
+| `flow` | Runs `target` on the automation engine, with your identity forwarded (a `runAs: 'user'` flow enforces RLS as you). Equivalent to `POST /api/v1/automation/:target/trigger`, without having to know the flow name. |
+| `api` | **400** — it dispatches on `target`; call that endpoint directly. |
+| `url` / `modal` / `form` | **400** — client-side navigation; there is nothing for the server to run. |
+
 ## Expose it to AI (MCP)
 
 Actions are **not** AI-visible by default. Opting in takes two fields — and
@@ -256,6 +266,7 @@ and [Connect an MCP Client](/docs/ai/connect-mcp).
 |:---|:---|
 | Button doesn't appear | `locations` doesn't include the surface; or the `visible` CEL throws (e.g. a bare, unprefixed field name) and fail-closed hides it; or the user fails `requiredPermissions` |
 | Click → `Action 'x' … not found` | `target`-style script with no registered handler — add the `registerAction` call in `onEnable` (Path B above) |
+| REST → 400 naming the action's `type` | The type has no server dispatch (`url`/`modal`/`form`/`api`) — open its `target` in the client, or call that endpoint directly |
 | Appears in UI, missing from `list_actions` (MCP) | `ai.exposed` not `true`, `ai.description` under 40 characters, or the type isn't headless-callable |
 | Runs but the list looks stale | Add `refreshAfter: true` |
 

packages/runtime/src/action-execution.ts

@@ -260,6 +260,114 @@ export function isHeadlessInvokableAction(deps: ActionExecutionDeps, action: any
     return false;
 }
 
+/**
+ * The action types a headless caller can actually invoke through a server
+ * dispatch — the two {@link isHeadlessInvokableAction} accepts. Kept next to
+ * it so the predicate and the explanation below can never drift apart.
+ */
+const SERVER_DISPATCHED_ACTION_TYPES: ReadonlySet<string> = new Set(['script', 'flow']);
+
+/**
+ * Explain why a declared action has NO server-side dispatch — `null` when it
+ * does have one (`script` / `flow`).
+ *
+ * The spec is explicit (`packages/spec/src/ui/action.zod.ts`): every
+ * non-`script` type dispatches on `target`, and only `flow` has a server-side
+ * runner (the automation engine). `url` / `modal` / `form` are renderer
+ * navigation and `api` names a *different* endpoint the client calls itself —
+ * none of them is the script-handler registry. Pre-#3915 the REST route had
+ * no type branching at all, so every one of them fell through to
+ * `executeAction` and came back as the misleading
+ * `Action '' on object '*' not found`. Naming the type and the prescription
+ * turns that dead end into an actionable 400.
+ */
+export function headlessActionTypeError(deps: ActionExecutionDeps, action: any, objectName?: string): string | null {
+    const type: string = action?.type ?? 'script';
+    if (SERVER_DISPATCHED_ACTION_TYPES.has(type)) return null;
+    const name: string = action?.name ?? 'unknown';
+    const on = objectName ? ` on '${objectName}'` : '';
+    const target: string | undefined = typeof action?.target === 'string' ? action.target : undefined;
+    if (type === 'api') {
+        return (
+            `Action '${name}'${on} is \`type: 'api'\` — it dispatches on \`target\`, ` +
+            `not through the action registry. Call ${target ? `\`${target}\`` : 'its `target` endpoint'} directly` +
+            `${typeof action?.method === 'string' ? ` (${action.method})` : ''}.`
+        );
+    }
+    return (
+        `Action '${name}'${on} is \`type: '${type}'\` — a client-side action with no server dispatch. ` +
+        `The renderer opens its \`target\`${target ? ` ('${target}')` : ''}; there is nothing for the server to run.`
+    );
+}
+
+/**
+ * The automation service when this kernel has a usable one, else `null` —
+ * the single availability probe behind `type: 'flow'` dispatch (both the
+ * headless-invokability filter and the two invoke paths ask through it).
+ */
+export async function resolveAutomationService(deps: ActionExecutionDeps, envId?: string): Promise<any | null> {
+    try {
+        const svc: any = await deps.resolveService('automation', envId);
+        return svc && typeof svc.execute === 'function' ? svc : null;
+    } catch {
+        return null; // no automation service on this kernel
+    }
+}
+
+/** Message for a flow action on a kernel with no automation service (a 503-shaped condition). */
+export function flowActionUnavailableError(action: any): string {
+    return `Action '${action?.name ?? 'unknown'}' is a flow but no automation service is available`;
+}
+
+/**
+ * Dispatch a `type: 'flow'` action through the automation service.
+ *
+ * The ONE implementation both headless surfaces share — the MCP `run_action`
+ * tool and the REST `/actions/:object/:action` route (#3915, which is exactly
+ * the asymmetry that let this branch exist on only one of them). Throws on a
+ * missing automation service and converts a `{ success: false }` engine result
+ * into a throw so both callers report failure the same way; returns the raw
+ * automation result otherwise.
+ *
+ * Forwarding the caller's identity (rather than just executing the flow) is
+ * what lets a `runAs: 'user'` flow enforce RLS as the invoker instead of
+ * falling into the user-less UNSCOPED path (#2849, ADR-0049 / #1888; mirrors
+ * the record-change trigger's context shape).
+ */
+export async function dispatchFlowAction(deps: ActionExecutionDeps,
+    action: any,
+    wiring: {
+        objectName: string;
+        record: Record<string, unknown>;
+        params: Record<string, unknown>;
+        ec: any;
+        envId?: string;
+    },
+): Promise<any> {
+    const { objectName, record, params, ec, envId } = wiring;
+    const automation = await resolveAutomationService(deps, envId);
+    if (!automation) {
+        throw new Error(flowActionUnavailableError(action));
+    }
+    // Pass a proper AutomationContext (the engine never read the former
+    // `triggerData` envelope).
+    const result: any = await automation.execute(action.target, {
+        record,
+        ...(objectName !== 'global' ? { object: objectName } : {}),
+        userId: ec?.userId,
+        ...(Array.isArray(ec?.positions) && ec.positions.length ? { positions: ec.positions } : {}),
+        ...(Array.isArray(ec?.permissions) && ec.permissions.length ? { permissions: ec.permissions } : {}),
+        ...(ec?.tenantId ? { tenantId: ec.tenantId } : {}),
+        // Record fields seed flows' named `isInput` variables (like the
+        // record-change trigger); explicit action params win on clash.
+        params: { ...record, ...params },
+    });
+    if (result && typeof result === 'object' && 'success' in result && result.success === false) {
+        throw new Error(`Flow '${action.target}' failed: ${result.error ?? 'unknown error'}`);
+    }
+    return result ?? null;
+}
+
 export function actionLooksDestructive(deps: ActionExecutionDeps, action: any): boolean {
     if (action?.ai?.requiresConfirmation !== undefined) return Boolean(action.ai.requiresConfirmation);
     return Boolean(action?.confirmText || action?.mode === 'delete' || action?.variant === 'danger');
@@ -486,7 +594,7 @@ export async function invokeBusinessAction(deps: ActionExecutionDeps,
     if (isSystemObjectName(objectName)) {
         throw new Error(`Action '${name}' is on a system object and is not exposed via MCP`);
     }
-    const hasAutomation = Boolean(await deps.resolveService('automation', envId).catch(() => null));
+    const hasAutomation = Boolean(await resolveAutomationService(deps, envId));
     if (!isHeadlessInvokableAction(deps, action, hasAutomation)) {
         throw new Error(
             `Action '${name}' (type='${action?.type ?? 'script'}') cannot be invoked via MCP`,
@@ -535,32 +643,10 @@ export async function invokeBusinessAction(deps: ActionExecutionDeps,
           }
         : { id: 'system', name: 'system' };
 
-    // ── flow dispatch ──
+    // ── flow dispatch ── (shared with the REST /actions route, #3915)
     if (action.type === 'flow') {
-        const automation: any = await deps.resolveService('automation', envId).catch(() => null);
-        if (!automation || typeof automation.execute !== 'function') {
-            throw new Error(`Action '${name}' is a flow but no automation service is available`);
-        }
-        // Pass a proper AutomationContext (the engine never read the former
-        // `triggerData` envelope). Forwarding the caller's identity is what
-        // lets a `runAs:'user'` flow enforce RLS as the invoker instead of
-        // falling into the user-less UNSCOPED path (#2849, ADR-0049 / #1888;
-        // mirrors the record-change trigger's context shape).
-        const result: any = await automation.execute(action.target, {
-            record,
-            ...(objectName !== 'global' ? { object: objectName } : {}),
-            userId: ec?.userId,
-            ...(Array.isArray(ec?.positions) && ec.positions.length ? { positions: ec.positions } : {}),
-            ...(Array.isArray(ec?.permissions) && ec.permissions.length ? { permissions: ec.permissions } : {}),
-            ...(ec?.tenantId ? { tenantId: ec.tenantId } : {}),
-            // Record fields seed flows' named `isInput` variables (like the
-            // record-change trigger); explicit action params win on clash.
-            params: { ...record, ...params },
-        });
-        if (result && typeof result === 'object' && 'success' in result && result.success === false) {
-            throw new Error(`Flow '${action.target}' failed: ${result.error ?? 'unknown error'}`);
-        }
-        return { ok: true, action: action.name, objectName, ...(recordId ? { recordId } : {}), result: result ?? null };
+        const result = await dispatchFlowAction(deps, action, { objectName, record, params, ec, envId });
+        return { ok: true, action: action.name, objectName, ...(recordId ? { recordId } : {}), result };
     }
 
     // ── script/body dispatch via the engine's executeAction ──
@@ -696,3 +782,67 @@ export function standaloneActionObjectName(deps: ActionExecutionDeps, action: an
     if (typeof action?.object === 'string' && action.object.length > 0) return action.object;
     return 'global';
 }
+
+/**
+ * Resolve the DECLARATION behind a `<object>/<action>` route pair — the
+ * single source the REST `/actions` route reads for the ADR-0066 D4
+ * permission gate, the ADR-0104 param contract, and (since #3915) the action
+ * TYPE it must dispatch on.
+ *
+ * Three sources, in the same precedence the execution layer uses:
+ *  1. the object's own `actions[]` (bundle/artifact objects + authored object
+ *     rows) — object-embedded wins, mirroring `collectActionDeclarations`;
+ *  2. the ObjectQL registry's standalone `action` items — `defineAction`
+ *     artifacts and rehydrated authored rows, which never appear inside any
+ *     object definition;
+ *  3. the metadata service's standalone `action` rows — the env-scoped
+ *     kernels where the registry carries no copy.
+ *
+ * Sources 2 and 3 are what the route was missing: a Studio-authored or
+ * standalone `defineAction` declaration was invisible here, so its declared
+ * `type` (and its `requiredPermissions`) were never read on the REST path
+ * even though the MCP path honoured both. A standalone declaration is
+ * accepted only when it belongs to the routed object or to the `'global'`
+ * wildcard — the same `<object>:<name>` / `'*'` key rotation the handler
+ * lookup performs.
+ */
+export async function resolveRouteActionDeclaration(deps: ActionExecutionDeps,
+    args: { ql: any; objectName: string; actionName: string; envId?: string },
+): Promise<{ action: any; obj: any } | undefined> {
+    const { ql, objectName, actionName, envId } = args;
+
+    let obj: any;
+    try {
+        obj =
+            (typeof ql?.getSchema === 'function' ? ql.getSchema(objectName) : undefined) ??
+            ql?.registry?.getObject?.(objectName);
+    } catch {
+        obj = undefined; // schema unresolved → handler-only action
+    }
+    const embedded = Array.isArray(obj?.actions)
+        ? obj.actions.find((a: any) => a?.name === actionName)
+        : undefined;
+    if (embedded) return { action: embedded, obj };
+
+    const ownsRoute = (action: any): boolean => {
+        const owner = standaloneActionObjectName(deps, action);
+        return owner === objectName || owner === 'global';
+    };
+
+    try {
+        const fromRegistry: any = ql?.registry?.getItem?.('action', actionName);
+        if (fromRegistry && ownsRoute(fromRegistry)) return { action: fromRegistry, obj };
+    } catch {
+        /* registry without an item lookup → fall through to the metadata service */
+    }
+
+    try {
+        const meta: any = await deps.resolveService('metadata', envId);
+        const fromMeta: any = await meta?.load?.('action', actionName);
+        if (fromMeta && ownsRoute(fromMeta)) return { action: fromMeta, obj };
+    } catch {
+        /* no metadata service on this kernel → no declaration to resolve */
+    }
+
+    return obj ? { action: undefined, obj } : undefined;
+}