@objectstack/service-automation 9.5.0 → 9.6.0

package/dist/index.d.cts

@@ -137,6 +137,36 @@ interface RegisteredConnector {
     readonly def: Connector;
     readonly handlers: Record<string, ConnectorActionHandler>;
 }
+/**
+ * Context handed to a named handler function invoked from a `script` node
+ * (#1870). Mirrors {@link ConnectorActionContext} but carries the node's mapped
+ * `input` so the function reads its arguments without reaching into the raw
+ * variable map. The function's return value becomes the node output.
+ */
+interface FlowFunctionContext {
+    /** Inputs mapped from the node's `config.inputs` (already in scope). */
+    readonly input: Record<string, unknown>;
+    /** Live flow variable map — read prior-node output / write results. */
+    readonly variables: Map<string, unknown>;
+    /** The flow execution / trigger context. */
+    readonly automation: AutomationContext;
+    readonly logger: Logger;
+}
+/**
+ * A named handler function callable from a `script` node. Returns the node's
+ * output (any JSON-serializable value); returning `undefined` yields an empty
+ * output. Authored packages contribute these via `defineStack({ functions })`,
+ * which the host bridges in through {@link AutomationEngine.setFunctionResolver}.
+ */
+type FlowFunctionHandler = (ctx: FlowFunctionContext) => unknown | Promise<unknown>;
+/**
+ * Resolves a function name to its handler. Injected by the host (the automation
+ * plugin bridges it to ObjectQL's `resolveFunction`, fed by `bundle.functions`),
+ * so the engine stays decoupled from any specific function registry. Returns
+ * `undefined` for an unknown name, letting the `script` node fail the step
+ * loudly instead of silently no-op'ing (#1870).
+ */
+type FlowFunctionResolver = (name: string) => FlowFunctionHandler | undefined;
 /**
  * A designer-facing view of one connector action — identity + its JSON-Schema
  * input/output. The runtime handler is intentionally omitted; this is metadata.
@@ -301,6 +331,8 @@ declare class AutomationEngine implements IAutomationService {
     private boundFlowTriggers;
     /** Connectors registered by integration plugins, keyed by connector name (ADR-0018 §Addendum). */
     private connectors;
+    /** Bridge to the host function registry for `script`-node calls (#1870), if wired. */
+    private functionResolver;
     private executionLogs;
     private readonly maxLogSize;
     private logger;
@@ -415,6 +447,20 @@ declare class AutomationEngine implements IAutomationService {
      * is not registered, so the node can fail the step with a clear error.
      */
     resolveConnectorAction(connectorId: string, actionId: string): ConnectorActionHandler | undefined;
+    /**
+     * Wire the engine to the host's named-function registry (#1870). The
+     * automation plugin calls this in `start()` with a resolver backed by
+     * ObjectQL's `resolveFunction` (populated from `bundle.functions` /
+     * `defineStack({ functions })`), so a `script` node can invoke an
+     * authored function by name. Passing `null` detaches the bridge.
+     */
+    setFunctionResolver(resolver: FlowFunctionResolver | null): void;
+    /**
+     * Resolve a named function for a `script` node. Returns `undefined` when no
+     * resolver is wired or the name is unregistered — the node then fails the
+     * step with a clear error rather than silently no-op'ing.
+     */
+    resolveFunction(name: string): FlowFunctionHandler | undefined;
     /** Get all registered connector names. */
     getRegisteredConnectors(): string[];
     /**
@@ -5009,22 +5055,6 @@ declare function registerLogicNodes(engine: AutomationEngine, ctx: PluginContext
  */
 declare function registerCrudNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
-/**
- * Screen / Script built-in nodes — 'screen' and 'script' executors.
- * Part of the core flow capability, so the {@link AutomationServicePlugin}
- * seeds them directly (ADR-0018) rather than shipping a separate plugin.
- *
- * - 'screen' nodes collect user input. A screen that declares `config.fields`
- *   (or sets `config.waitForInput === true`) suspends the run on entry via the
- *   engine's durable pause (ADR-0019), surfacing a `ScreenSpec` for the client
- *   to render; the run continues via `resume()` with the collected values (set
- *   as bare flow variables). A field-less screen — or one with
- *   `waitForInput === false` — stays a server pass-through (input vars, if any,
- *   are already injected from `context.params`).
- * - 'script' nodes dispatch by `config.actionType`. Currently only 'email'
- *   has a (logger-backed) implementation; unknown action types still succeed
- *   so flows can continue and downstream nodes can react.
- */
 declare function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
 declare function registerHttpNodes(engine: AutomationEngine, ctx: PluginContext): void;

package/dist/index.d.ts

@@ -137,6 +137,36 @@ interface RegisteredConnector {
     readonly def: Connector;
     readonly handlers: Record<string, ConnectorActionHandler>;
 }
+/**
+ * Context handed to a named handler function invoked from a `script` node
+ * (#1870). Mirrors {@link ConnectorActionContext} but carries the node's mapped
+ * `input` so the function reads its arguments without reaching into the raw
+ * variable map. The function's return value becomes the node output.
+ */
+interface FlowFunctionContext {
+    /** Inputs mapped from the node's `config.inputs` (already in scope). */
+    readonly input: Record<string, unknown>;
+    /** Live flow variable map — read prior-node output / write results. */
+    readonly variables: Map<string, unknown>;
+    /** The flow execution / trigger context. */
+    readonly automation: AutomationContext;
+    readonly logger: Logger;
+}
+/**
+ * A named handler function callable from a `script` node. Returns the node's
+ * output (any JSON-serializable value); returning `undefined` yields an empty
+ * output. Authored packages contribute these via `defineStack({ functions })`,
+ * which the host bridges in through {@link AutomationEngine.setFunctionResolver}.
+ */
+type FlowFunctionHandler = (ctx: FlowFunctionContext) => unknown | Promise<unknown>;
+/**
+ * Resolves a function name to its handler. Injected by the host (the automation
+ * plugin bridges it to ObjectQL's `resolveFunction`, fed by `bundle.functions`),
+ * so the engine stays decoupled from any specific function registry. Returns
+ * `undefined` for an unknown name, letting the `script` node fail the step
+ * loudly instead of silently no-op'ing (#1870).
+ */
+type FlowFunctionResolver = (name: string) => FlowFunctionHandler | undefined;
 /**
  * A designer-facing view of one connector action — identity + its JSON-Schema
  * input/output. The runtime handler is intentionally omitted; this is metadata.
@@ -301,6 +331,8 @@ declare class AutomationEngine implements IAutomationService {
     private boundFlowTriggers;
     /** Connectors registered by integration plugins, keyed by connector name (ADR-0018 §Addendum). */
     private connectors;
+    /** Bridge to the host function registry for `script`-node calls (#1870), if wired. */
+    private functionResolver;
     private executionLogs;
     private readonly maxLogSize;
     private logger;
@@ -415,6 +447,20 @@ declare class AutomationEngine implements IAutomationService {
      * is not registered, so the node can fail the step with a clear error.
      */
     resolveConnectorAction(connectorId: string, actionId: string): ConnectorActionHandler | undefined;
+    /**
+     * Wire the engine to the host's named-function registry (#1870). The
+     * automation plugin calls this in `start()` with a resolver backed by
+     * ObjectQL's `resolveFunction` (populated from `bundle.functions` /
+     * `defineStack({ functions })`), so a `script` node can invoke an
+     * authored function by name. Passing `null` detaches the bridge.
+     */
+    setFunctionResolver(resolver: FlowFunctionResolver | null): void;
+    /**
+     * Resolve a named function for a `script` node. Returns `undefined` when no
+     * resolver is wired or the name is unregistered — the node then fails the
+     * step with a clear error rather than silently no-op'ing.
+     */
+    resolveFunction(name: string): FlowFunctionHandler | undefined;
     /** Get all registered connector names. */
     getRegisteredConnectors(): string[];
     /**
@@ -5009,22 +5055,6 @@ declare function registerLogicNodes(engine: AutomationEngine, ctx: PluginContext
  */
 declare function registerCrudNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
-/**
- * Screen / Script built-in nodes — 'screen' and 'script' executors.
- * Part of the core flow capability, so the {@link AutomationServicePlugin}
- * seeds them directly (ADR-0018) rather than shipping a separate plugin.
- *
- * - 'screen' nodes collect user input. A screen that declares `config.fields`
- *   (or sets `config.waitForInput === true`) suspends the run on entry via the
- *   engine's durable pause (ADR-0019), surfacing a `ScreenSpec` for the client
- *   to render; the run continues via `resume()` with the collected values (set
- *   as bare flow variables). A field-less screen — or one with
- *   `waitForInput === false` — stays a server pass-through (input vars, if any,
- *   are already injected from `context.params`).
- * - 'script' nodes dispatch by `config.actionType`. Currently only 'email'
- *   has a (logger-backed) implementation; unknown action types still succeed
- *   so flows can continue and downstream nodes can react.
- */
 declare function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
 declare function registerHttpNodes(engine: AutomationEngine, ctx: PluginContext): void;

package/dist/index.js

@@ -30,6 +30,8 @@ var _AutomationEngine = class _AutomationEngine {
     this.boundFlowTriggers = /* @__PURE__ */ new Map();
     /** Connectors registered by integration plugins, keyed by connector name (ADR-0018 §Addendum). */
     this.connectors = /* @__PURE__ */ new Map();
+    /** Bridge to the host function registry for `script`-node calls (#1870), if wired. */
+    this.functionResolver = null;
     this.executionLogs = [];
     /**
      * Runs paused at a node, keyed by runId (ADR-0019). In-memory hot cache —
@@ -317,6 +319,24 @@ var _AutomationEngine = class _AutomationEngine {
   resolveConnectorAction(connectorId, actionId) {
     return this.connectors.get(connectorId)?.handlers[actionId];
   }
+  /**
+   * Wire the engine to the host's named-function registry (#1870). The
+   * automation plugin calls this in `start()` with a resolver backed by
+   * ObjectQL's `resolveFunction` (populated from `bundle.functions` /
+   * `defineStack({ functions })`), so a `script` node can invoke an
+   * authored function by name. Passing `null` detaches the bridge.
+   */
+  setFunctionResolver(resolver) {
+    this.functionResolver = resolver;
+  }
+  /**
+   * Resolve a named function for a `script` node. Returns `undefined` when no
+   * resolver is wired or the name is unregistered — the node then fails the
+   * step with a clear error rather than silently no-op'ing.
+   */
+  resolveFunction(name) {
+    return this.functionResolver?.(name) ?? void 0;
+  }
   /** Get all registered connector names. */
   getRegisteredConnectors() {
     return [...this.connectors.keys()];
@@ -1860,7 +1880,7 @@ function resolveToken(token, variables, context) {
     if (path[0] === "Email") return resolvePath(context.user, ["email", ...path.slice(1)]) ?? void 0;
     return resolvePath(context.user, path);
   }
-  if (/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(trimmed)) {
+  if (/^[A-Za-z_$][\w$]*(?:\.(?:[A-Za-z_$][\w$]*|\d+))*$/.test(trimmed)) {
     const segments = trimmed.split(".");
     const head = segments[0];
     if (variables.has(head)) {
@@ -2234,14 +2254,21 @@ function registerCrudNodes(engine, ctx) {
       const data = getData();
       if (!data) {
         ctx.logger.warn(`[create_record] no data engine; skipping ${objectName}`);
-        if (outputVariable) variables.set(outputVariable, `mock-${objectName}-${Date.now()}`);
-        return { success: true, output: { id: `mock-${objectName}-${Date.now()}`, object: objectName } };
+        const mockId = `mock-${objectName}-${Date.now()}`;
+        if (outputVariable) variables.set(outputVariable, { id: mockId });
+        return { success: true, output: { id: mockId, object: objectName } };
       }
       try {
         const created = await data.insert(objectName, fields);
-        const insertedId = Array.isArray(created) ? created[0]?.id : created?.id ?? created;
-        if (outputVariable) variables.set(outputVariable, insertedId);
-        return { success: true, output: { id: insertedId, record: created, object: objectName } };
+        const createdRecord = Array.isArray(created) ? created[0] : created;
+        const insertedId = createdRecord && typeof createdRecord === "object" ? createdRecord.id : createdRecord;
+        if (outputVariable) {
+          variables.set(
+            outputVariable,
+            createdRecord && typeof createdRecord === "object" ? createdRecord : { id: insertedId }
+          );
+        }
+        return { success: true, output: { id: insertedId, record: createdRecord, object: objectName } };
       } catch (err) {
         return { success: false, error: `create_record(${objectName}) failed: ${err.message}` };
       }
@@ -2308,6 +2335,7 @@ function registerCrudNodes(engine, ctx) {
 
 // src/builtin/screen-nodes.ts
 import { defineActionDescriptor as defineActionDescriptor7 } from "@objectstack/spec/automation";
+var SCRIPT_BUILTIN_ACTION_TYPES = /* @__PURE__ */ new Set(["email", "slack"]);
 function registerScreenNodes(engine, ctx) {
   engine.registerNodeExecutor({
     type: "screen",
@@ -2363,24 +2391,53 @@ function registerScreenNodes(engine, ctx) {
       category: "logic",
       source: "builtin"
     }),
-    async execute(node, _variables, _context) {
+    async execute(node, variables, context) {
       const cfg = node.config ?? {};
-      const actionType = cfg.actionType ?? "noop";
-      if (actionType === "email") {
+      const fnRaw = cfg.function ?? cfg.functionName;
+      const fnName = typeof fnRaw === "string" && fnRaw.trim() ? fnRaw.trim() : void 0;
+      const actionType = typeof cfg.actionType === "string" && cfg.actionType.trim() ? cfg.actionType.trim() : void 0;
+      if (!fnName && actionType && SCRIPT_BUILTIN_ACTION_TYPES.has(actionType)) {
         ctx.logger.info(
-          `[Script:email] template=${String(cfg.template)} recipients=${JSON.stringify(cfg.recipients)} vars=${JSON.stringify(cfg.variables)}`
+          `[Script:${actionType}] template=${String(cfg.template)} recipients=${JSON.stringify(cfg.recipients)} vars=${JSON.stringify(cfg.variables)}`
         );
         return {
           success: true,
-          output: {
-            actionType,
-            template: cfg.template,
-            recipients: cfg.recipients
-          }
+          output: { actionType, template: cfg.template, recipients: cfg.recipients }
+        };
+      }
+      const inlineScript = typeof cfg.script === "string" && cfg.script.trim() ? cfg.script : void 0;
+      if (!fnName && inlineScript) {
+        ctx.logger.warn(
+          `[Script] node '${node.id}': inline \`config.script\` is not executed by the built-in runtime (no server-side JS sandbox) \u2014 this node is a no-op. To run server logic, move it into a registered function and call it via \`config.function\` + \`defineStack({ functions })\`.`
+        );
+        return { success: true, output: { script: "not-executed" } };
+      }
+      const target = fnName ?? (actionType === "invoke_function" ? void 0 : actionType);
+      if (!target) {
+        return {
+          success: false,
+          error: 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\` \u2014 nothing to run.`
+        };
+      }
+      const handler = engine.resolveFunction(target);
+      if (!handler) {
+        return {
+          success: false,
+          error: `script node '${node.id}': '${target}' is not a built-in action (${[...SCRIPT_BUILTIN_ACTION_TYPES].join(", ")}) and no function named '${target}' is registered. Register it via \`defineStack({ functions: { '${target}': fn } })\`, or fix the name (#1870).`
+        };
+      }
+      const input = interpolate(cfg.inputs ?? cfg.input ?? {}, variables, context);
+      const outputVariable = typeof cfg.outputVariable === "string" && cfg.outputVariable.trim() ? cfg.outputVariable.trim() : void 0;
+      try {
+        const result = await handler({ input, variables, automation: context, logger: ctx.logger });
+        if (outputVariable) variables.set(outputVariable, result);
+        return { success: true, output: { function: target, result } };
+      } catch (err) {
+        return {
+          success: false,
+          error: `script function '${target}' (node '${node.id}') failed: ${err.message}`
         };
       }
-      ctx.logger.info(`[Script:${actionType}] node=${node.id} executed (no-op handler)`);
-      return { success: true, output: { actionType } };
     }
   });
   ctx.logger.info("[Screen/Script Nodes] 2 built-in node executors registered");
@@ -3030,6 +3087,18 @@ var AutomationServicePlugin = class {
         ctx.logger.info("[Automation] No ObjectQL engine \u2014 suspended runs kept in-memory only");
       }
     }
+    try {
+      const fnRegistry = ctx.getService("objectql");
+      if (fnRegistry && typeof fnRegistry.resolveFunction === "function") {
+        this.engine.setFunctionResolver((name) => {
+          const fn = fnRegistry.resolveFunction(name);
+          return typeof fn === "function" ? (fnCtx) => fn(fnCtx) : void 0;
+        });
+        ctx.logger.debug("[Automation] script-node function registry bridged to objectql.resolveFunction");
+      }
+    } catch {
+      ctx.logger.debug("[Automation] objectql not present \u2014 script-node function calls will fail loudly when used");
+    }
     try {
       const ql = ctx.getService("objectql");
       if (!ql) {