feat(automation): accept functionName alias + invoke_function marker on script nodes (#1870 DX) (#1925)

Found while evaluating objectstack-ai/templates with the authoring skills: the AI
templates emit `{ actionType: 'invoke_function', functionName: 'helpdesk.aiTriageStub' }`,
but the runtime only read `config.function` — so the call resolved nothing (my
#1870 fix would try to resolve a function literally named 'invoke_function').

Reduce the footgun (one fix, all future templates benefit):
- runtime (screen-nodes): `function ?? functionName`; `actionType: 'invoke_function'`
  is a marker — the name lives in function/functionName, not actionType.
- build (validate-expressions): recognize `functionName`; ERROR on
  `invoke_function` with no function/functionName (it names no callable).

Templates still must register the function via defineStack({ functions }); this
just makes the key/marker the AI guessed actually work + flags the missing-name
case at build. +2 runtime tests, +2 build tests; service-automation 201, cli 404.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

.changeset/script-function-alias.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/service-automation": patch
+"@objectstack/cli": patch
+---
+
+feat(automation): accept `functionName` alias + `invoke_function` marker on script nodes (#1870 DX)
+
+AI-authored templates commonly emit `config: { actionType: 'invoke_function', functionName: 'my_fn' }`,
+but the runtime only read `config.function`. Now:
+- `config.functionName` is accepted as an alias for `config.function` (runtime + build).
+- `actionType: 'invoke_function'` is treated as a MARKER ("call the named function") — the
+  name comes from `function`/`functionName`, not from actionType itself; it no longer
+  tries to resolve a function literally named `invoke_function`.
+- `objectstack build` errors on `actionType: 'invoke_function'` with no `function`/`functionName`
+  (it names no callable) instead of letting it fail at runtime.

packages/cli/src/utils/validate-expressions.test.ts

@@ -99,4 +99,34 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
     });
     expect(issues).toHaveLength(0);
   });
+
+  // #1870 DX — `functionName` is an accepted alias for `function`.
+  it('accepts a script node that names a callable via the functionName alias', () => {
+    const issues = validateStackExpressions({
+      flows: [{
+        name: 'helpdesk_flow',
+        nodes: [
+          { id: 'start', type: 'start', config: {} },
+          { id: 'triage', type: 'script', config: { actionType: 'invoke_function', functionName: 'helpdesk.aiTriageStub' } },
+        ],
+        edges: [],
+      }],
+    });
+    expect(issues).toHaveLength(0);
+  });
+
+  it('flags actionType invoke_function with no function/functionName', () => {
+    const issues = validateStackExpressions({
+      flows: [{
+        name: 'helpdesk_flow',
+        nodes: [
+          { id: 'start', type: 'start', config: {} },
+          { id: 'triage', type: 'script', config: { actionType: 'invoke_function', inputs: { x: 1 } } },
+        ],
+        edges: [],
+      }],
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toMatch(/invoke_function.*no .*function/i);
+  });
 });

packages/cli/src/utils/validate-expressions.ts

@@ -84,7 +84,10 @@ export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
       // not serialized into the artifact — so this is a structural check; the
       // runtime verifies the named function is actually registered.)
       if (node.type === 'script') {
-        const fn = typeof cfg.function === 'string' ? cfg.function.trim() : '';
+        // `function` is canonical; `functionName` is an accepted alias.
+        const fn =
+          (typeof cfg.function === 'string' ? cfg.function.trim() : '') ||
+          (typeof cfg.functionName === 'string' ? cfg.functionName.trim() : '');
         const action = typeof cfg.actionType === 'string' ? cfg.actionType.trim() : '';
         // Inline `config.script` (a JS body) is also a declared form — the
         // built-in runtime doesn't execute it (warned at run time), but the node
@@ -99,6 +102,16 @@ export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
               `(\`function: 'my_fn'\`, registered via \`defineStack({ functions })\`).`,
             source: JSON.stringify({ id: node.id, type: node.type, config: cfg }),
           });
+        } else if (action === 'invoke_function' && !fn) {
+          // `actionType: 'invoke_function'` is a marker that names no callable on
+          // its own — the function name must be in `function`/`functionName`.
+          issues.push({
+            where: `flow '${flowName}' · node '${node.id}' (script) callable`,
+            message:
+              `script node uses \`actionType: 'invoke_function'\` but no \`function\` (or \`functionName\`) — ` +
+              `it names no callable. Set \`function: 'my_fn'\` and register it via \`defineStack({ functions })\`.`,
+            source: JSON.stringify({ id: node.id, type: node.type, config: cfg }),
+          });
         }
       }
     }

packages/services/service-automation/src/builtin/screen-nodes.test.ts

@@ -107,4 +107,22 @@ describe('script node (#1870 — callable resolution)', () => {
         expect(result.success).toBe(false);
         expect(result.error).toMatch(/explode.*failed|failed.*boom|boom/i);
     });
+it('resolves config.functionName as an alias for function (#1870 DX)', async () => {
+        let calledWith: any;
+        engine.setFunctionResolver((name) =>
+            name === 'helpdesk.aiTriageStub' ? ((c: any) => { calledWith = c.input; return { triaged: true }; }) : undefined);
+        engine.registerFlow('script_flow', scriptFlow({ actionType: 'invoke_function', functionName: 'helpdesk.aiTriageStub', inputs: { ticketId: 't1' } }));
+        const r = await engine.execute('script_flow', {} as any);
+        expect(r.success).toBe(true);
+        expect(calledWith).toEqual({ ticketId: 't1' });
+    });
+
+    it('treats actionType invoke_function as a marker, not a function name', async () => {
+        // invoke_function alone (no function/functionName) must NOT try to resolve a
+        // function literally named 'invoke_function'; it fails with a clear message.
+        engine.registerFlow('script_flow', scriptFlow({ actionType: 'invoke_function' }));
+        const r = await engine.execute('script_flow', {} as any);
+        expect(r.success).toBe(false);
+        expect(r.error).toMatch(/invoke_function.*requires.*function/i);
+    });
 });

packages/services/service-automation/src/builtin/screen-nodes.ts

@@ -85,7 +85,10 @@ export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext
       }),
       async execute(node, variables, context) {
         const cfg = (node.config ?? {}) as Record<string, unknown>;
-        const fnName = typeof cfg.function === 'string' && cfg.function.trim() ? cfg.function.trim() : undefined;
+        // `function` is canonical; `functionName` is an accepted alias — AI/templates
+        // commonly emit it alongside `actionType: 'invoke_function'` (#1870 DX).
+        const fnRaw = cfg.function ?? cfg.functionName;
+        const fnName = typeof fnRaw === 'string' && fnRaw.trim() ? fnRaw.trim() : undefined;
         const actionType = typeof cfg.actionType === 'string' && cfg.actionType.trim() ? cfg.actionType.trim() : undefined;
 
         // Built-in side-effect actions keep their logger-backed behavior — but
@@ -118,18 +121,18 @@ export function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext
           return { success: true, output: { script: 'not-executed' } };
         }
 
-        // Otherwise the node names a function to invoke. `function` is canonical;
-        // a bare `actionType` that matched no built-in is accepted as a shorthand
-        // function name (so templates that point a node straight at e.g.
-        // `helpdesk.aiTriageStub` resolve).
-        const target = fnName ?? actionType;
+        // `actionType: 'invoke_function'` is a MARKER meaning "call the named
+        // function" — the name lives in `function`/`functionName`, not in actionType
+        // itself. A bare actionType that matched no built-in is still accepted as a
+        // function name (shorthand).
+        const target = fnName ?? (actionType === 'invoke_function' ? undefined : actionType);
         if (!target) {
-          // Defense in depth: registerFlow already rejects this structurally
-          // (#1870), so reaching here means a node bypassed registration.
           return {
             success: false,
             error:
-              `script node '${node.id}': declares neither \`actionType\` nor \`function\` — nothing to run.`,
+              actionType === 'invoke_function'
+                ? `script node '${node.id}': actionType 'invoke_function' requires \`config.function\` (or \`functionName\`) naming the function to call.`
+                : `script node '${node.id}': declares neither \`actionType\` nor \`function\` — nothing to run.`,
           };
         }