windmill-components 1.687.0 → 1.695.1

package/package/components/copilot/chat/app/core.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { getAppTools } from './core';
+import { getAppTools, prepareAppUserMessage } from './core';
 vi.mock('../shared', () => ({
     createToolDef: (_schema, name, description) => ({
         type: 'function',
@@ -52,9 +52,6 @@ vi.mock('../AIChatManager.svelte', () => ({
         }
     }
 }));
-vi.mock('$system_prompts', () => ({
-    getDatatableSdkReference: () => 'Datatable SDK reference'
-}));
 const EMPTY_LINT_RESULT = {
     errorCount: 0,
     warningCount: 0,
@@ -80,11 +77,12 @@ function createHelpers(overrides = {}) {
         setBackendRunnable: async () => EMPTY_LINT_RESULT,
         deleteBackendRunnable: () => undefined,
         getFiles: () => ({ frontend: {}, backend: {} }),
-        getSelectedContext: () => ({ type: 'none' }),
+        getSelectedContext: () => ({}),
         snapshot: () => 1,
         revertToSnapshot: () => undefined,
         lint: () => EMPTY_LINT_RESULT,
-        getDatatables: async () => [],
+        listDatatableTables: async () => [],
+        getDatatableTableSchema: async () => ({}),
         getAvailableDatatableNames: () => [],
         execDatatableSql: async () => ({ success: true }),
         addTableToWhitelist: () => undefined,
@@ -97,13 +95,139 @@ function createToolCallbacks() {
         removeToolStatus: vi.fn()
     };
 }
-function getPatchFileTool() {
-    const tool = getAppTools().find((entry) => entry.def.function.name === 'patch_file');
+function getTool(name) {
+    const tool = getAppTools().find((entry) => entry.def.function.name === name);
     if (!tool) {
-        throw new Error('patch_file tool not found');
+        throw new Error(`${name} tool not found`);
     }
     return tool;
 }
+function getListFilesTool() {
+    return getTool('list_files');
+}
+function getPatchFileTool() {
+    return getTool('patch_file');
+}
+describe('app list_files tool', () => {
+    it('returns lightweight metadata without file or runnable contents', async () => {
+        const tool = getListFilesTool();
+        const result = await tool.fn({
+            args: {},
+            workspace: 'test-workspace',
+            helpers: createHelpers({
+                getFiles: () => ({
+                    frontend: {
+                        '/index.tsx': 'const secretFrontendContent = true',
+                        '/styles.css': '.secret-class { color: red; }'
+                    },
+                    backend: {
+                        loadUsers: {
+                            name: 'Load users',
+                            type: 'inline',
+                            staticInputs: { admin: true },
+                            inlineScript: {
+                                language: 'bun',
+                                content: 'export async function main() { return "secretBackendContent" }'
+                            }
+                        },
+                        workspaceFlow: {
+                            name: 'Workspace flow',
+                            type: 'flow',
+                            path: 'f/flows/workspace_flow'
+                        }
+                    }
+                })
+            }),
+            toolCallbacks: createToolCallbacks(),
+            toolId: 'tool-list-files'
+        });
+        const parsed = JSON.parse(result);
+        expect(parsed).toEqual({
+            frontend: [
+                { path: '/index.tsx', size: 34, kind: 'tsx' },
+                { path: '/styles.css', size: 29, kind: 'css' }
+            ],
+            backend: [
+                {
+                    key: 'loadUsers',
+                    name: 'Load users',
+                    type: 'inline',
+                    language: 'bun',
+                    contentSize: 62,
+                    staticInputKeys: ['admin']
+                },
+                {
+                    key: 'workspaceFlow',
+                    name: 'Workspace flow',
+                    type: 'flow',
+                    path: 'f/flows/workspace_flow'
+                }
+            ]
+        });
+        expect(result).not.toContain('secretFrontendContent');
+        expect(result).not.toContain('secretBackendContent');
+    });
+});
+describe('app datatable tools', () => {
+    it('lists datatable metadata without column definitions', async () => {
+        const tool = getTool('list_datatables');
+        const result = await tool.fn({
+            args: {},
+            workspace: 'test-workspace',
+            helpers: createHelpers({
+                listDatatableTables: async () => [
+                    {
+                        datatable_name: 'main',
+                        schemas: {
+                            public: ['users', 'orders'],
+                            analytics: ['events']
+                        },
+                        tableCount: 3
+                    }
+                ]
+            }),
+            toolCallbacks: createToolCallbacks(),
+            toolId: 'tool-list-datatables'
+        });
+        const parsed = JSON.parse(result);
+        expect(parsed).toEqual([
+            {
+                datatable_name: 'main',
+                schemas: {
+                    public: ['users', 'orders'],
+                    analytics: ['events']
+                },
+                tableCount: 3
+            }
+        ]);
+        expect(result).not.toContain('email');
+        expect(result).not.toContain('jsonb');
+    });
+    it('gets one datatable table schema', async () => {
+        const tool = getTool('get_datatable_table_schema');
+        const result = await tool.fn({
+            args: {
+                datatable_name: 'main',
+                schema_name: 'public',
+                table_name: 'users'
+            },
+            workspace: 'test-workspace',
+            helpers: createHelpers({
+                getDatatableTableSchema: async () => ({ id: 'int4', email: 'text' })
+            }),
+            toolCallbacks: createToolCallbacks(),
+            toolId: 'tool-get-table-schema'
+        });
+        const parsed = JSON.parse(result);
+        expect(parsed).toEqual({
+            datatable_name: 'main',
+            schema_name: 'public',
+            table_name: 'users',
+            columns: { id: 'int4', email: 'text' }
+        });
+        expect(result).not.toContain('total');
+    });
+});
 describe('app patch_file tool', () => {
     it('patches frontend files with an exact replacement', async () => {
         const setFrontendFile = vi.fn(() => EMPTY_LINT_RESULT);
@@ -141,6 +265,26 @@ describe('app patch_file tool', () => {
             toolId: 'tool-2'
         })).rejects.toThrow('old_string matched 2 locations');
     });
+    it('treats leading /backend paths as frontend files', async () => {
+        const setFrontendFile = vi.fn(() => EMPTY_LINT_RESULT);
+        const tool = getPatchFileTool();
+        const result = await tool.fn({
+            args: {
+                path: '/backend/deleteRecipe/main.ts',
+                old_string: 'frontend route',
+                new_string: 'frontend page'
+            },
+            workspace: 'test-workspace',
+            helpers: createHelpers({
+                getFrontendFile: () => 'export const title = "frontend route"\n',
+                setFrontendFile
+            }),
+            toolCallbacks: createToolCallbacks(),
+            toolId: 'tool-leading-backend-path'
+        });
+        expect(setFrontendFile).toHaveBeenCalledWith('/backend/deleteRecipe/main.ts', 'export const title = "frontend page"\n');
+        expect(result).toContain("Patched '/backend/deleteRecipe/main.ts' successfully.");
+    });
     it('patches inline backend runnables through backend/<key>/main.ts paths', async () => {
         const runnable = {
             name: 'Delete recipe',
@@ -190,3 +334,84 @@ describe('app patch_file tool', () => {
         })).rejects.toThrow('generated automatically');
     });
 });
+describe('prepareAppUserMessage app context', () => {
+    it('still serializes inspector and code selections', () => {
+        const selectedContext = {
+            type: 'frontend',
+            frontendPath: '/index.tsx',
+            inspectorElement: {
+                path: 'body > button.primary',
+                tagName: 'button',
+                id: 'save',
+                className: 'primary action',
+                rect: { top: 10, left: 20, width: 120, height: 40 },
+                html: '<button id="save" class="primary action">Save</button>',
+                textContent: 'Save',
+                styles: {}
+            },
+            codeSelection: {
+                type: 'app_code_selection',
+                source: '/index.tsx',
+                sourceType: 'frontend',
+                title: '/index.tsx:3-4',
+                content: 'const selectedCode = true',
+                startLine: 3,
+                endLine: 4,
+                startColumn: 1,
+                endColumn: 25
+            }
+        };
+        const message = prepareAppUserMessage('Change this selected area', selectedContext);
+        const content = message.content;
+        expect(content).toContain('The user has selected an element in the app preview');
+        expect(content).toContain('body > button.primary');
+        expect(content).toContain('### CODE SELECTION:');
+        expect(content).toContain('const selectedCode = true');
+    });
+    it('serializes explicit mentions with lightweight file context', () => {
+        const additionalContext = [
+            {
+                type: 'app_frontend_file',
+                path: '/index.tsx',
+                title: '/index.tsx',
+                content: 'const fullFrontendContent = true'
+            },
+            {
+                type: 'app_backend_runnable',
+                key: 'loadUsers',
+                title: 'loadUsers',
+                runnable: {
+                    name: 'Load users',
+                    type: 'inline',
+                    staticInputs: { admin: true },
+                    inlineScript: {
+                        language: 'bun',
+                        content: 'export async function main() { return "secret" }'
+                    }
+                }
+            },
+            {
+                type: 'app_datatable',
+                datatableName: 'main',
+                schemaName: 'public',
+                tableName: 'users',
+                title: 'main/users',
+                columns: {
+                    id: 'int4',
+                    email: 'text'
+                }
+            }
+        ];
+        const message = prepareAppUserMessage('Wire these together', undefined, additionalContext);
+        const content = message.content;
+        expect(content).toContain('- Frontend file: /index.tsx');
+        expect(content).toContain('- Backend runnable: loadUsers');
+        expect(content).not.toContain('fullFrontendContent');
+        expect(content).not.toContain('export async function main');
+        expect(content).not.toContain('Static inputs');
+        expect(content).not.toContain('Load users');
+        expect(content).toContain('**Table: main/users**');
+        expect(content).toContain('"id": "int4"');
+        expect(content).toContain('"email": "text"');
+    });
+});

package/package/components/copilot/chat/context.js

@@ -16,3 +16,47 @@ export const ContextIconMap = {
     workspace_flow: BarsStaggered
     // flow_module type is handled with FlowModuleIcon
 };
+export function createAppSelectedContext(options = {}) {
+    return {
+        ...options
+    };
+}
+export function createAppFrontendFileContextElement(path, content) {
+    return {
+        type: 'app_frontend_file',
+        path,
+        title: path,
+        content
+    };
+}
+export function createAppBackendRunnableContextElement(key, runnable) {
+    return {
+        type: 'app_backend_runnable',
+        key,
+        title: key,
+        runnable
+    };
+}
+export function formatAppDatatableContextTitle(datatableName, schemaName, tableName) {
+    return schemaName === 'public'
+        ? `${datatableName}/${tableName}`
+        : `${datatableName}/${schemaName}:${tableName}`;
+}
+export function createAppDatatableContextElement(datatableName, schemaName, tableName, columns) {
+    return {
+        type: 'app_datatable',
+        datatableName,
+        schemaName,
+        tableName,
+        title: formatAppDatatableContextTitle(datatableName, schemaName, tableName),
+        columns
+    };
+}
+export function flattenDatatablesToAppContextElements(datatables) {
+    return datatables.flatMap((datatable) => {
+        if (datatable.error) {
+            return [];
+        }
+        return Object.entries(datatable.schemas).flatMap(([schemaName, tables]) => tables.map((tableName) => createAppDatatableContextElement(datatable.datatable_name, schemaName, tableName)));
+    });
+}

package/package/components/copilot/chat/flow/FlowAIChat.svelte

@@ -142,12 +142,13 @@ const flowHelpers = {
         }
         return { errorCount: 0, warningCount: 0, errors: [], warnings: [] };
     },
-    setFlowJson: async ({ modules, schema, preprocessorModule, failureModule }) => {
+    setFlowJson: async ({ modules, schema, preprocessorModule, failureModule, groups }) => {
         try {
             if (modules !== undefined ||
                 schema !== undefined ||
                 preprocessorModule !== undefined ||
-                failureModule !== undefined) {
+                failureModule !== undefined ||
+                groups !== undefined) {
                 // Take snapshot of current flowStore and set as beforeFlow
                 if (!diffManager?.hasPendingChanges) {
                     const snapshot = $state.snapshot(flowStore).val;
@@ -159,7 +160,8 @@ const flowHelpers = {
                 modules,
                 schema,
                 preprocessorModule,
-                failureModule
+                failureModule,
+                groups
             });
             // Refresh the state store to update UI
             refreshStateStore(flowStore);

package/package/components/copilot/chat/flow/core.d.ts

@@ -4,12 +4,13 @@ import { type Tool, type ScriptLintResult } from '../shared';
 import type { ContextElement } from '../context';
 import type { ExtendedOpenFlow } from '../../../flows/types';
 import { type InlineScriptSession } from './inlineScriptsUtils';
-import type { FlowJsonUpdateResult } from './helperUtils';
+import { type FlowGroup, type FlowJsonUpdateResult } from './helperUtils';
 type FlowJsonUpdate = {
     modules?: FlowModule[];
     schema?: Record<string, any> | null;
     preprocessorModule?: FlowModule | null;
     failureModule?: FlowModule | null;
+    groups?: FlowGroup[] | null;
 };
 /**
  * Helper interface for AI chat flow operations

package/package/components/copilot/chat/flow/core.js

@@ -2,9 +2,11 @@ import { ScriptService, JobService } from '../../../../gen';
 import { z } from 'zod';
 import { createDbSchemaTool, getFormattedResourceTypes, getLangContext, SUPPORTED_CHAT_SCRIPT_LANGUAGES } from '../script/core';
 import { createSearchHubScriptsTool, createToolDef, executeTestRun, buildSchemaForTool, buildTestRunArgs, buildContextString, applyCodePiecesToFlowModules, SPECIAL_MODULE_IDS, formatScriptLintResult, createSearchWorkspaceTool, createGetRunnableDetailsTool } from '../shared';
+import { createWorkspaceMutationTools } from '../workspaceTools';
 import { findModuleInFlow, findModuleInModules } from '../../../flows/flowTree';
 import { createInlineScriptSession } from './inlineScriptsUtils';
-import { flowModuleSchema, flowModulesSchema } from './openFlowZod';
+import { validateFlowGroups } from './helperUtils';
+import { flowModuleSchema, flowModulesSchema } from './openFlowZod.gen';
 import { collectAllFlowModuleIdsFromModules } from '../../../flows/flowTree';
 import { FLOW_CHAT_SPECIAL_MODULES, getFlowPrompt } from '../../../../system_prompts';
 /**
@@ -280,11 +282,14 @@ function validateEditableFlowJson(rawFlow) {
     const schema = validateFlowSchema(flow.schema);
     const preprocessorModule = validateOptionalFlowModule(flow.preprocessor_module, 'preprocessor_module');
     const failureModule = validateOptionalFlowModule(flow.failure_module, 'failure_module');
+    const groupModuleIds = new Set(collectAllFlowModuleIdsFromModules(modules));
+    const groups = validateFlowGroups(flow.groups, groupModuleIds);
     if (preprocessorModule) {
         if (preprocessorModule.id !== SPECIAL_MODULE_IDS.PREPROCESSOR) {
             throw new Error(`Invalid preprocessor_module: id must be "${SPECIAL_MODULE_IDS.PREPROCESSOR}"`);
         }
-        if (preprocessorModule.value.type !== 'rawscript' && preprocessorModule.value.type !== 'script') {
+        if (preprocessorModule.value.type !== 'rawscript' &&
+            preprocessorModule.value.type !== 'script') {
             throw new Error('Invalid preprocessor_module: only "rawscript" and "script" modules are supported');
         }
     }
@@ -310,7 +315,8 @@ function validateEditableFlowJson(rawFlow) {
         modules,
         schema,
         preprocessor_module: preprocessorModule,
-        failure_module: failureModule
+        failure_module: failureModule,
+        groups
     };
 }
 function buildEditableFlowJson(flow, inlineScriptSession, selectedContext = []) {
@@ -333,7 +339,9 @@ function buildEditableFlowJson(flow, inlineScriptSession, selectedContext = [])
         };
     }
     let failureModule = flow.value.failure_module;
-    if (failureModule?.value?.type === 'rawscript' && failureModule.value.content && inlineScriptSession) {
+    if (failureModule?.value?.type === 'rawscript' &&
+        failureModule.value.content &&
+        inlineScriptSession) {
         inlineScriptSession.set(failureModule.id, failureModule.value.content);
         failureModule = {
             ...failureModule,
@@ -347,7 +355,8 @@ function buildEditableFlowJson(flow, inlineScriptSession, selectedContext = [])
         modules,
         schema: flow.schema ?? null,
         preprocessor_module: preprocessorModule ?? null,
-        failure_module: failureModule ?? null
+        failure_module: failureModule ?? null,
+        groups: flow.value.groups ?? null
     };
 }
 const langSchema = z.enum(SUPPORTED_CHAT_SCRIPT_LANGUAGES);
@@ -377,9 +386,14 @@ const setFlowJsonToolSchema = z.object({
         .string()
         .optional()
         .nullable()
-        .describe('JSON string containing the optional failure module')
+        .describe('JSON string containing the optional failure module'),
+    groups: z
+        .string()
+        .optional()
+        .nullable()
+        .describe('JSON string containing the optional array of semantic flow groups (summary, note, autocollapse, start_id, end_id, color). Pass null to clear groups.')
 });
-const setFlowJsonToolDef = createToolDef(setFlowJsonToolSchema, 'set_flow_json', 'Set the complete flow modules array and optionally the flow input schema, preprocessor module, and failure module.', { strict: false });
+const setFlowJsonToolDef = createToolDef(setFlowJsonToolSchema, 'set_flow_json', 'Set the complete flow modules array and optionally the flow input schema, preprocessor module, failure module, and semantic groups.', { strict: false });
 const setPreprocessorModuleToolSchema = z.object({
     module: specialModuleToolArgSchema
 });
@@ -427,10 +441,7 @@ function validateSpecialFlowModule(module, field) {
     return parsedModule;
 }
 const patchFlowJsonSchema = z.object({
-    old_string: z
-        .string()
-        .min(1)
-        .describe('Exact text to find in the current compact flow JSON'),
+    old_string: z.string().min(1).describe('Exact text to find in the current compact flow JSON'),
     new_string: z.string().describe('Replacement JSON text'),
     replace_all: z
         .boolean()
@@ -475,6 +486,7 @@ export const flowTools = [
     createDbSchemaTool(),
     createSearchWorkspaceTool(),
     createGetRunnableDetailsTool(),
+    ...createWorkspaceMutationTools(),
     {
         def: resourceTypeToolDef,
         fn: async ({ args, toolId, workspace, toolCallbacks }) => {
@@ -726,7 +738,8 @@ export const flowTools = [
                 modules: parsedFlow.modules,
                 schema: parsedFlow.schema,
                 preprocessorModule: parsedFlow.preprocessor_module,
-                failureModule: parsedFlow.failure_module
+                failureModule: parsedFlow.failure_module,
+                groups: parsedFlow.groups
             });
             const warning = formatEmptyInlineScriptWarning(updateResult);
             const selectedModule = findModuleInFlow(parsedFlow, selectedId) ?? undefined;
@@ -751,7 +764,9 @@ export const flowTools = [
             const parsedArgs = setPreprocessorModuleToolSchema.parse(args);
             const parsedModule = validateSpecialFlowModule(parseOptionalJsonArg(parsedArgs.module, 'module'), 'preprocessor_module');
             toolCallbacks.setToolStatus(toolId, {
-                content: parsedModule === null ? 'Removing preprocessor module...' : 'Setting preprocessor module...'
+                content: parsedModule === null
+                    ? 'Removing preprocessor module...'
+                    : 'Setting preprocessor module...'
             });
             const updateResult = await helpers.setFlowJson({ preprocessorModule: parsedModule });
             const warning = formatEmptyInlineScriptWarning(updateResult);
@@ -804,16 +819,18 @@ export const flowTools = [
         showDetails: true,
         showFade: true,
         fn: async ({ args, helpers, toolId, toolCallbacks }) => {
-            const { modules, schema, preprocessor_module, failure_module } = args;
+            const { modules, schema, preprocessor_module, failure_module, groups } = args;
             let parsedModules;
             let parsedSchema;
             let parsedPreprocessorModule;
             let parsedFailureModule;
+            let parsedGroups;
             // Parse JSON strings
             parsedModules = parseOptionalJsonArg(modules, 'modules');
             parsedSchema = parseOptionalJsonArg(schema, 'schema');
             parsedPreprocessorModule = parseOptionalJsonArg(preprocessor_module, 'preprocessor_module');
             parsedFailureModule = parseOptionalJsonArg(failure_module, 'failure_module');
+            parsedGroups = parseOptionalJsonArg(groups, 'groups');
             if (parsedModules === null) {
                 parsedModules = undefined;
             }
@@ -832,10 +849,16 @@ export const flowTools = [
             }
             parsedPreprocessorModule = validateSpecialFlowModule(parsedPreprocessorModule, 'preprocessor_module');
             parsedFailureModule = validateSpecialFlowModule(parsedFailureModule, 'failure_module');
+            if (parsedGroups !== undefined) {
+                const effectiveModules = parsedModules ?? helpers.getFlowAndSelectedId().flow.value.modules ?? [];
+                const moduleIdsForGroups = new Set(collectAllFlowModuleIdsFromModules(effectiveModules));
+                parsedGroups = validateFlowGroups(parsedGroups, moduleIdsForGroups);
+            }
             const ids = [
                 ...(parsedModules ? collectAllFlowModuleIdsFromModules(parsedModules) : []),
-                ...([parsedPreprocessorModule, parsedFailureModule].filter((module) => module !== undefined && module !== null)
-                    .map((module) => module.id))
+                ...[parsedPreprocessorModule, parsedFailureModule]
+                    .filter((module) => module !== undefined && module !== null)
+                    .map((module) => module.id)
             ];
             if (ids.length !== new Set(ids).size) {
                 throw new Error('Duplicate module IDs found in flow');
@@ -849,7 +872,8 @@ export const flowTools = [
                 ...(parsedPreprocessorModule !== undefined
                     ? { preprocessorModule: parsedPreprocessorModule }
                     : {}),
-                ...(parsedFailureModule !== undefined ? { failureModule: parsedFailureModule } : {})
+                ...(parsedFailureModule !== undefined ? { failureModule: parsedFailureModule } : {}),
+                ...(parsedGroups !== undefined ? { groups: parsedGroups } : {})
             });
             const warning = formatEmptyInlineScriptWarning(updateResult);
             // Update exprsToSet if the selected module has input_transforms
@@ -858,9 +882,9 @@ export const flowTools = [
                 parsedFailureModule !== undefined) {
                 const { selectedId } = helpers.getFlowAndSelectedId();
                 const selectedModule = selectedId === SPECIAL_MODULE_IDS.PREPROCESSOR
-                    ? parsedPreprocessorModule ?? undefined
+                    ? (parsedPreprocessorModule ?? undefined)
                     : selectedId === SPECIAL_MODULE_IDS.FAILURE
-                        ? parsedFailureModule ?? undefined
+                        ? (parsedFailureModule ?? undefined)
                         : parsedModules
                             ? findModuleInModules(parsedModules, selectedId)
                             : undefined;
@@ -928,13 +952,15 @@ export function prepareFlowSystemMessage(customPrompt) {
 **Resources & Schema:**
 - **Search resource types** → \`resource_type\`
 - **Get database schema** → \`get_db_schema\`
+- **Create a schedule for the current flow** → \`create_schedule\`
+- **Create a trigger for the current flow** → \`create_trigger\`
 
 ## Quick Edits with patch_flow_json
 
 Use \`patch_flow_json\` for small, localized changes when you can target an exact snippet from the \`CURRENT FLOW JSON COMPACT\` block below.
 
 Always copy the exact search text from the \`CURRENT FLOW JSON COMPACT\` block below.
-The compact JSON is a single object with \`modules\`, \`schema\`, \`preprocessor_module\`, and \`failure_module\` keys.
+The compact JSON is a single object with \`modules\`, \`schema\`, \`preprocessor_module\`, \`failure_module\`, and \`groups\` keys.
 
 **Parameters:**
 - \`old_string\`: Exact JSON text to find
@@ -955,13 +981,14 @@ ${FLOW_CHAT_SPECIAL_MODULES}
 
 ## Flow Modification with set_flow_json
 
-Use the \`set_flow_json\` tool to set the entire flow structure at once. Provide the complete modules array and optionally the flow input schema, \`preprocessor_module\`, and \`failure_module\`.
+Use the \`set_flow_json\` tool to set the entire flow structure at once. Provide the complete modules array and optionally the flow input schema, \`preprocessor_module\`, \`failure_module\`, and \`groups\`.
 
 **Parameters:**
 - \`modules\`: Array of flow modules (required)
 - \`schema\`: Flow input schema in JSON Schema format (optional)
 - \`preprocessor_module\`: Special module that runs before \`modules\` (optional, separate from \`modules\`)
 - \`failure_module\`: Special module that runs on failure (optional, separate from \`modules\`)
+- \`groups\`: Array of semantic groups for organizing modules in the editor (optional). Each group has \`summary\` (display name), \`note\` (markdown description shown below the group header — attached directly to the group, not a separate sticky note), \`autocollapse\`, \`start_id\`, \`end_id\`, and \`color\`. \`start_id\` and \`end_id\` must reference existing module IDs in the flow (not \`preprocessor\` or \`failure\`). Groups do not affect execution — they provide naming and collapsibility in the editor. Pass \`null\` to clear existing groups.
 
 **Example - Simple flow:**
 \`\`\`javascript

package/package/components/copilot/chat/flow/helperUtils.d.ts

@@ -1,13 +1,15 @@
-import type { FlowModule, OpenFlow, RawScript } from '../../../../gen';
+import type { FlowModule, FlowValue, OpenFlow, RawScript } from '../../../../gen';
 import type { InlineScriptSession } from './inlineScriptsUtils';
 type FlowLike = Pick<OpenFlow, 'value'> & {
     schema?: Record<string, any>;
 };
+export type FlowGroup = NonNullable<FlowValue['groups']>[number];
 export interface FlowJsonUpdate {
     modules?: FlowModule[];
     schema?: Record<string, any> | null;
     preprocessorModule?: FlowModule | null;
     failureModule?: FlowModule | null;
+    groups?: FlowGroup[] | null;
 }
 export interface FlowJsonUpdateResult {
     emptyInlineScriptModuleIds: string[];
@@ -15,5 +17,6 @@ export interface FlowJsonUpdateResult {
 export declare function updateRawScriptModuleContent(flow: FlowLike, id: string, code: string): (FlowModule & {
     value: RawScript;
 }) | undefined;
-export declare function applyFlowJsonUpdate(flow: FlowLike, inlineScriptSession: InlineScriptSession, { modules, schema, preprocessorModule, failureModule }: FlowJsonUpdate): FlowJsonUpdateResult;
+export declare function validateFlowGroups(rawGroups: unknown, moduleIds?: Set<string>): FlowGroup[] | null;
+export declare function applyFlowJsonUpdate(flow: FlowLike, inlineScriptSession: InlineScriptSession, { modules, schema, preprocessorModule, failureModule, groups }: FlowJsonUpdate): FlowJsonUpdateResult;
 export {};

package/package/components/copilot/chat/flow/helperUtils.js

@@ -9,7 +9,36 @@ export function updateRawScriptModuleContent(flow, id, code) {
     rawScriptModule.value.content = code;
     return rawScriptModule;
 }
-export function applyFlowJsonUpdate(flow, inlineScriptSession, { modules, schema, preprocessorModule, failureModule }) {
+export function validateFlowGroups(rawGroups, moduleIds) {
+    if (rawGroups == null) {
+        return null;
+    }
+    if (!Array.isArray(rawGroups)) {
+        throw new Error('Flow groups must be an array');
+    }
+    return rawGroups.map((group, index) => {
+        if (!group || typeof group !== 'object' || Array.isArray(group)) {
+            throw new Error(`Invalid group at index ${index}: must be an object`);
+        }
+        const g = group;
+        if (typeof g.start_id !== 'string' || !g.start_id) {
+            throw new Error(`Invalid group at index ${index}: start_id must be a non-empty string`);
+        }
+        if (typeof g.end_id !== 'string' || !g.end_id) {
+            throw new Error(`Invalid group at index ${index}: end_id must be a non-empty string`);
+        }
+        if (moduleIds) {
+            if (!moduleIds.has(g.start_id)) {
+                throw new Error(`Invalid group at index ${index}: start_id "${g.start_id}" does not match any flow module`);
+            }
+            if (!moduleIds.has(g.end_id)) {
+                throw new Error(`Invalid group at index ${index}: end_id "${g.end_id}" does not match any flow module`);
+            }
+        }
+        return g;
+    });
+}
+export function applyFlowJsonUpdate(flow, inlineScriptSession, { modules, schema, preprocessorModule, failureModule, groups }) {
     const emptyInlineScriptModuleIds = new Set();
     if (modules !== undefined) {
         flow.value.modules = restoreFlowModules(modules, inlineScriptSession, emptyInlineScriptModuleIds);
@@ -29,6 +58,9 @@ export function applyFlowJsonUpdate(flow, inlineScriptSession, { modules, schema
                 ? undefined
                 : restoreFlowModule(failureModule, inlineScriptSession, emptyInlineScriptModuleIds);
     }
+    if (groups !== undefined) {
+        flow.value.groups = groups == null || groups.length === 0 ? undefined : groups;
+    }
     return {
         emptyInlineScriptModuleIds: Array.from(emptyInlineScriptModuleIds)
     };