From e89d5c48bcd64df726da7a74164a4d4297ac2697 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 08:47:48 +0000 Subject: [PATCH] docs(spec): FlowSchema terminal messages are every-terminal-run, not screen-flow-only (#9512) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since #9414, AutomationResult.successMessage/errorMessage are carried on EVERY terminal flow run — execute()'s exit, both retryExecution() exits, and the resume exit — not only screen-flow runs. Rewrite the JSDoc and describe() text above FlowSchema.successMessage/errorMessage to say so explicitly and to kill the screen-flow-only reading, which was the premise of a route considered and rejected at #9414's triage (narrowing the contract to screen-flow-only). Regenerate the two mirrored reference pages. Text-only: authorable-surface.base.json is unchanged (re-verified via check:generated, not inherited from the filer's claim). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Fs18A2DdXLVN2h8PaaFBcP --- .../flow-terminal-messages-every-run-doc.md | 16 +++++++++++++ .../docs/references/api/automation-api.mdx | 4 ++-- content/docs/references/automation/flow.mdx | 4 ++-- packages/spec/src/automation/flow.zod.ts | 23 +++++++++++++------ 4 files changed, 36 insertions(+), 11 deletions(-) create mode 100644 .changeset/flow-terminal-messages-every-run-doc.md diff --git a/.changeset/flow-terminal-messages-every-run-doc.md b/.changeset/flow-terminal-messages-every-run-doc.md new file mode 100644 index 0000000000..6474c797c0 --- /dev/null +++ b/.changeset/flow-terminal-messages-every-run-doc.md @@ -0,0 +1,16 @@ +--- +"@objectstack/spec": patch +--- + +docs(spec): `FlowSchema.successMessage`/`errorMessage` describe themselves as carried on every terminal flow run, not screen-flow-only (#9512) + +Since #9414, the pair is set on `AutomationResult` for every terminal run — +`execute()`'s exit, both `retryExecution()` exits, and the resume exit — not +only on `screen`-flow runs. The JSDoc and `describe()` text above +`successMessage`/`errorMessage` in `packages/spec/src/automation/flow.zod.ts` +previously said "Terminal messages for `screen`-flow runs", which stayed the +premise of a route considered and rejected at #9414's triage (narrowing the +contract to screen-flow-only). Text-only: no schema shape, validation, or +`authorable-surface.base.json` change. The two mirrored reference pages +(`content/docs/references/automation/flow.mdx`, +`content/docs/references/api/automation-api.mdx`) are regenerated to match. diff --git a/content/docs/references/api/automation-api.mdx b/content/docs/references/api/automation-api.mdx index 9f72408047..d73a63befb 100644 --- a/content/docs/references/api/automation-api.mdx +++ b/content/docs/references/api/automation-api.mdx @@ -88,8 +88,8 @@ const result = AutomationApiErrorCode.parse(data); | **name** | `string` | ✅ | Machine name | | **label** | `string` | ✅ | Flow label | | **description** | `string` | optional | | -| **successMessage** | `string` | optional | Toast shown when a screen flow completes (defaults to a generic "Done"). | -| **errorMessage** | `string` | optional | Toast shown when a screen flow fails (defaults to the raw error). | +| **successMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done". | +| **errorMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error. | | **version** | `integer` | optional (default: `1`) | Version number | | **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional (default: `"draft"`) | Deployment status | | **template** | `never` | optional | [REMOVED] `flow.template` was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — no designer or engine path ever read it, so flagging a flow as a template/subflow did nothing. Delete the key. Shared logic is invoked via a subflow NODE referencing the flow by name. Run `os migrate meta --from 16` to rewrite existing sources automatically. | diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx index 40a51d1464..6f6a21bf9c 100644 --- a/content/docs/references/automation/flow.mdx +++ b/content/docs/references/automation/flow.mdx @@ -42,8 +42,8 @@ const result = FlowSchema.parse(data); | **name** | `string` | ✅ | Machine name | | **label** | `string` | ✅ | Flow label | | **description** | `string` | optional | | -| **successMessage** | `string` | optional | Toast shown when a screen flow completes (defaults to a generic "Done"). | -| **errorMessage** | `string` | optional | Toast shown when a screen flow fails (defaults to the raw error). | +| **successMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done". | +| **errorMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error. | | **version** | `integer` | optional (default: `1`) | Version number | | **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional (default: `"draft"`) | Deployment status | | **template** | `never` | optional | [REMOVED] `flow.template` was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — no designer or engine path ever read it, so flagging a flow as a template/subflow did nothing. Delete the key. Shared logic is invoked via a subflow NODE referencing the flow by name. Run `os migrate meta --from 16` to rewrite existing sources automatically. | diff --git a/packages/spec/src/automation/flow.zod.ts b/packages/spec/src/automation/flow.zod.ts index e71a8882b6..22d0f751f6 100644 --- a/packages/spec/src/automation/flow.zod.ts +++ b/packages/spec/src/automation/flow.zod.ts @@ -616,14 +616,23 @@ export const FlowSchema = lazySchema(() => strictObject( 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. + * Terminal messages for the flow. Since #9414, carried on EVERY terminal + * run — `execute()`'s exit, both `retryExecution()` exits, and the resume + * exit — not only on `screen`-flow runs. The pair is set on the terminal + * {@link AutomationResult} (`successMessage` on success, `errorMessage` on + * failure) returned by any trigger route (e.g. + * `POST /api/v1/automation/:name/trigger`), whether or not a UI is + * listening; a `screen`-flow run additionally has the UI flow-runner show + * `successMessage` as a toast instead of a generic "Done", and + * `errorMessage` instead of the raw error. Reading this pair as + * screen-flow-only was the alternative considered and rejected at #9414's + * triage — narrowing the text would delete a declared, documented, + * console-consumed capability to make a bug disappear — so treat the + * screen-flow toast as one consumer, not the whole contract. 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).'), + successMessage: z.string().optional().describe('Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done".'), + errorMessage: z.string().optional().describe('Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error.'), /** Metadata & Versioning */ version: z.number().int().default(1).describe('Version number'),