feat(automation): declarative screen-flow completion/error messages + action errorMessage (#1990)

- FlowSchema gains `successMessage` / `errorMessage`; the engine attaches them to
  the terminal AutomationResult (success → successMessage, failure → errorMessage)
  so a screen-flow runner shows a meaningful toast instead of "Done"/raw error.
- AutomationResult contract gains `successMessage` / `errorMessage`.
- UI Action schema gains `errorMessage` (runtime already honoured it — closes a
  spec↔runtime gap).
- CRM convert-lead wizard declares a friendly completion + error message.

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

Author: os-zhuang

.changeset/flow-action-messages.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": minor
+---
+
+feat(automation): declarative screen-flow completion/error messages + action `errorMessage`
+
+A screen flow can now declare `successMessage` / `errorMessage` (FlowSchema). The
+engine surfaces them on the terminal `AutomationResult` (`successMessage` on
+success, `errorMessage` on failure), so the UI flow-runner shows a meaningful
+toast instead of a generic "Done" / the raw error — no manual "success screen"
+node needed. The CRM convert-lead wizard sets a friendly completion message.
+
+Also exposes `errorMessage` on the UI Action schema. The runtime (ActionRunner)
+already honoured it; it just wasn't declarable in the spec — closing a
+spec↔runtime gap so authors can set a friendly failure toast.

examples/app-crm/src/flows/convert-lead.flow.ts

@@ -30,6 +30,11 @@ export const ConvertLeadScreenFlow = defineFlow({
   status: 'active',
   runAs: 'user',
 
+  // Friendly terminal toasts — the flow-runner shows these instead of a generic
+  // "Done" / the raw error when the wizard finishes.
+  successMessage: '🎉 Lead converted — customer and opportunity created.',
+  errorMessage: 'Lead conversion did not finish — review the lead and try again.',
+
   variables: [
     // ── input (from the action trigger) ───────────────────────────────────
     { name: 'recordId',       type: 'text',   isInput: true,  isOutput: false },

packages/services/service-automation/src/engine.ts

@@ -1287,7 +1287,9 @@ export class AutomationEngine implements IAutomationService {
                     await this.bubbleToParent(run, output);
                 }
 
-                return { success: true, output, durationMs };
+                // Surface the flow's friendly completion message so a screen-flow
+                // runner shows it instead of a generic "Done".
+                return { success: true, output, durationMs, successMessage: flow.successMessage };
             } catch (err: unknown) {
                 // Re-suspended at a downstream node: persist a fresh continuation.
                 if (isSuspendSignal(err)) {
@@ -1341,7 +1343,9 @@ export class AutomationEngine implements IAutomationService {
                 if (!skipBubble) {
                     await this.failAncestors(run.context, errorMessage);
                 }
-                return { success: false, error: errorMessage, durationMs };
+                // Surface the flow's friendly error message (the raw error stays
+                // in `error` for logs/diagnostics).
+                return { success: false, error: errorMessage, durationMs, errorMessage: flow.errorMessage };
             }
         } finally {
             this.resuming.delete(runId);

packages/spec/src/automation/flow.zod.ts

@@ -234,7 +234,17 @@ export const FlowSchema = lazySchema(() => z.object({
   name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name'),
   label: z.string().describe('Flow label'),
   description: z.string().optional(),
-  
+
+  /**
+   * Terminal messages for `screen`-flow runs. When the run reaches a terminal
+   * state, the UI flow-runner shows `successMessage` instead of a generic
+   * "Done" toast, and `errorMessage` instead of the raw error. Both are
+   * surfaced on the terminal {@link AutomationResult} (`successMessage` /
+   * `errorMessage`). Plain strings; `{var}` is NOT interpolated here.
+   */
+  successMessage: z.string().optional().describe('Toast shown when a screen flow completes (defaults to a generic "Done").'),
+  errorMessage: z.string().optional().describe('Toast shown when a screen flow fails (defaults to the raw error).'),
+
   /** Metadata & Versioning */
   version: z.number().int().default(1).describe('Version number'),
   status: z.enum(['draft', 'active', 'obsolete', 'invalid']).default('draft').describe('Deployment status'),

packages/spec/src/contracts/automation-service.ts

@@ -119,6 +119,14 @@ export interface AutomationResult {
      * `signal.variables`.
      */
     screen?: ScreenSpec;
+    /**
+     * Friendly terminal messages copied from the flow definition
+     * (`flow.successMessage` / `flow.errorMessage`) so a screen-flow runner can
+     * show a meaningful toast instead of a generic "Done" / the raw error.
+     * `successMessage` is set on terminal success, `errorMessage` on failure.
+     */
+    successMessage?: string;
+    errorMessage?: string;
 }
 
 /** Signal payload used to resume a paused run (ADR-0019). */

packages/spec/src/ui/action.zod.ts

@@ -312,6 +312,9 @@ export const ActionSchema = lazySchema(() => z.object({
   /** UX Behavior */
   confirmText: I18nLabelSchema.optional().describe('Confirmation message before execution'),
   successMessage: I18nLabelSchema.optional().describe('Success message to show after execution'),
+  // Runtime (ActionRunner) already honours this — declared here so authors can
+  // set a friendly failure toast instead of surfacing the raw error string.
+  errorMessage: I18nLabelSchema.optional().describe('Error message to show when the action fails (overrides the raw error).'),
   refreshAfter: z.boolean().default(false).describe('Refresh view after execution'),
 
   /**