feat: add experimental global AI assistant option (#4567)

* feat: add global chat streaming endpoint and routing

- Add global_chat_stream/2 to ApolloClient for /services/global_chat/stream
- Add global_chat?/1 and process_global_message/2 to MessageProcessor
- Route to global_chat when use_global_assistant is in session meta
- Pass use_global_assistant and page through channel message_options
- Add experimental_features_enabled to workflow channel get_context

* feat: add query_global_stream and build_global_message

- Add query_global_stream/3 using process_stream with build_global_message
- build_global_message extracts code from attachments (job_code or workflow_yaml)
- Context-aware: on job step prefers job_code, on overview prefers workflow_yaml
- Resolves job_id from job_key in attachment by matching against workflow jobs

* feat: add experimental features flag to frontend session context

- Add experimental_features_enabled to SessionContextResponseSchema
- Map to experimentalFeaturesEnabled in SessionContextStore
- Add useExperimentalFeaturesEnabled hook
- Add use_global_assistant and page to MessageOptions type

* feat: add global assistant checkbox and UI wiring

- Add Global assistant (experimental) checkbox to ChatInput with
  localStorage persistence and onGlobalAssistantChange callback
- Pass use_global_assistant and page through AIChannelRegistry buildJoinParams
- Wire checkbox through AIAssistantPanel with showGlobalAssistantOption,
  isGlobalAssistantActive, and onGlobalAssistantChange props
- AIAssistantPanelWrapper includes workflow YAML and page when global
  assistant is active, derives page from workflow/job context
- Badge shows "Global (experimental)" in amber when active

* chore: add changelog entry for global AI assistant (#4532)

* test: add experimental_features_enabled to session context test fixture

The Zod schema adds a default value for the new optional field,
so the parsed output includes it. Update the test fixture to match.

* refactor: extract_global_code_and_job to reduce cyclomatic complexity

Split build_global_message into smaller functions to satisfy
credo's complexity threshold.

* test: add coverage for global chat integration

- ApolloClient: global_chat_stream payload, nil filtering, error handling
- AiAssistant: query_global_stream SSE processing, job_code vs workflow_yaml
  extraction, job resolution from job_key, error handling
- MessageProcessor: global_chat routing when use_global_assistant is set
- AiAssistantChannel: session options and message options with global assistant
- WorkflowChannel: experimental_features_enabled in get_context

* test: add coverage for edge cases in build_global_message

Cover workflow_yaml fallback on overview pages, nil job_key handling
in resolve_job_from_key, and non-list attachments.

* test: cover resolve_job_from_key with nil workflow_id

* test: cover normalize_job_name catch-all with non-string job_key

* feat: use job_key from global chat to identify job code messages

When the global chat routes to job_code_agent and the job can't be
resolved to a DB record, store the job_key in message meta as
from_global_job_code so the frontend can render "Generated Job Code"
with a diff view instead of a generic workflow card.

Author: elias-ba

CHANGELOG.md

@@ -39,6 +39,8 @@ and this project adheres to
   snapshots are also cleaned up after expired requests are removed.
   [#4504](https://github.com/OpenFn/lightning/issues/4504)
 - AI assistant responses now stream in real-time
+- Add experimental global AI assistant option for users with experimental
+  features enabled [#4532](https://github.com/OpenFn/lightning/issues/4532)
   [#4517](https://github.com/OpenFn/lightning/pull/4517)
 - Allow users to export all collection items as a JSON file.
   [#4527](https://github.com/OpenFn/lightning/issues/4527)

assets/js/collaborative-editor/components/AIAssistantPanel.tsx

@@ -62,13 +62,20 @@ interface AIAssistantPanelProps {
    * AI assistant limit information
    */
   aiLimit?: { allowed: boolean; message: string | null } | null;
+  /** Show the experimental global assistant toggle */
+  showGlobalAssistantOption?: boolean;
+  /** Whether the global assistant checkbox is currently checked */
+  isGlobalAssistantActive?: boolean;
+  /** Callback when global assistant checkbox changes */
+  onGlobalAssistantChange?: (active: boolean) => void;
 }
 
 interface MessageOptions {
   attach_code?: boolean;
   attach_logs?: boolean;
   attach_io_data?: boolean;
   step_id?: string;
+  use_global_assistant?: boolean;
 }
 
 /**
@@ -103,6 +110,9 @@ export function AIAssistantPanel({
   onAcceptDisclaimer,
   connectionState = 'connected',
   aiLimit = null,
+  showGlobalAssistantOption = false,
+  isGlobalAssistantActive = false,
+  onGlobalAssistantChange,
 }: AIAssistantPanelProps) {
   const [view, setView] = useState<'chat' | 'sessions'>(
     sessionId ? 'chat' : 'sessions'
@@ -267,12 +277,18 @@ export function AIAssistantPanel({
                   <span
                     className={cn(
                       'inline-flex items-center px-2 py-0.5 rounded text-xs font-medium',
-                      page === 'job_code'
-                        ? 'bg-blue-100 text-blue-800'
-                        : 'bg-purple-100 text-purple-800'
+                      isGlobalAssistantActive
+                        ? 'bg-amber-100 text-amber-800'
+                        : page === 'job_code'
+                          ? 'bg-blue-100 text-blue-800'
+                          : 'bg-purple-100 text-purple-800'
                     )}
                   >
-                    {page === 'job_code' ? 'Job' : 'Workflow'}
+                    {isGlobalAssistantActive
+                      ? 'Global (experimental)'
+                      : page === 'job_code'
+                        ? 'Job'
+                        : 'Workflow'}
                   </span>
                 )}
               </div>
@@ -433,6 +449,8 @@ export function AIAssistantPanel({
             (!hasSessionContext || !hasCompletedSessionLoad))
         }
         showJobControls={page === 'job_code'}
+        showGlobalAssistantOption={showGlobalAssistantOption}
+        onGlobalAssistantChange={onGlobalAssistantChange}
         storageKey={storageKey}
         enableAutoFocus={
           isOpen &&

assets/js/collaborative-editor/components/AIAssistantPanelWrapper.tsx

@@ -27,6 +27,7 @@ import { useAIWorkflowApplications } from '../hooks/useAIWorkflowApplications';
 import { useAutoPreview } from '../hooks/useAutoPreview';
 import { useResizablePanel } from '../hooks/useResizablePanel';
 import {
+  useExperimentalFeaturesEnabled,
   useHasReadAIDisclaimer,
   useIsNewWorkflow,
   useLimits,
@@ -133,6 +134,8 @@ export function AIAssistantPanelWrapper({
   const connectionState = useAIConnectionState();
   const sessionContextLoaded = useSessionContextLoaded();
   const hasReadDisclaimer = useHasReadAIDisclaimer();
+  const experimentalFeaturesEnabled = useExperimentalFeaturesEnabled();
+  const [isGlobalAssistantActive, setIsGlobalAssistantActive] = useState(false);
   const markAIDisclaimerRead = useMarkAIDisclaimerRead();
   const workflowTemplateContext = useAIWorkflowTemplateContext();
   const project = useProject();
@@ -309,6 +312,7 @@ export function AIAssistantPanelWrapper({
         attach_logs?: boolean;
         attach_io_data?: boolean;
         step_id?: string;
+        use_global_assistant?: boolean;
       }
     ) => {
       const currentState = aiStore.getSnapshot();
@@ -355,10 +359,16 @@ export function AIAssistantPanelWrapper({
           ...(messageOptions?.attach_logs && { attach_logs: true }),
           ...(messageOptions?.attach_io_data && { attach_io_data: true }),
           ...(messageOptions?.step_id && { step_id: messageOptions.step_id }),
+          ...(messageOptions?.use_global_assistant && {
+            use_global_assistant: true,
+          }),
         };
 
-        // Add workflow YAML if in workflow mode
-        if (page === 'workflow_template') {
+        // Add workflow YAML if in workflow mode or global assistant
+        if (
+          page === 'workflow_template' ||
+          messageOptions?.use_global_assistant
+        ) {
           const workflowData = prepareWorkflowForSerialization(
             workflow,
             jobs,
@@ -372,6 +382,18 @@ export function AIAssistantPanelWrapper({
               finalContext = { ...finalContext, code: workflowYAML };
             }
           }
+
+          // Derive page for global assistant routing
+          if (messageOptions?.use_global_assistant) {
+            const jobName = (context as JobCodeContext)?.job_name;
+            const workflowName = workflow?.name || 'workflow';
+            finalContext = {
+              ...finalContext,
+              page: jobName
+                ? `workflows/${workflowName}/${jobName}`
+                : `workflows/${workflowName}`,
+            };
+          }
         }
 
         // Initialize store with context including content
@@ -398,12 +420,17 @@ export function AIAssistantPanelWrapper({
             attach_io_data?: boolean;
             step_id?: string;
             code?: string;
+            use_global_assistant?: boolean;
+            page?: string;
           }
         | undefined = {
         ...messageOptions, // Include attach_code, attach_logs, attach_io_data, step_id
       };
 
-      if (aiMode?.page === 'workflow_template') {
+      if (
+        aiMode?.page === 'workflow_template' ||
+        messageOptions?.use_global_assistant
+      ) {
         const workflowData = prepareWorkflowForSerialization(
           workflow,
           jobs,
@@ -418,6 +445,15 @@ export function AIAssistantPanelWrapper({
         if (workflowYAML) {
           options = { ...options, code: workflowYAML };
         }
+
+        // Derive page for global assistant routing
+        if (messageOptions?.use_global_assistant) {
+          const jobName = (aiMode?.context as JobCodeContext)?.job_name;
+          const workflowName = workflow?.name || 'workflow';
+          options.page = jobName
+            ? `workflows/${workflowName}/${jobName}`
+            : `workflows/${workflowName}`;
+        }
       } else {
         // important: determines what ai to be used
         options = { ...aiMode?.context, ...options };
@@ -449,6 +485,10 @@ export function AIAssistantPanelWrapper({
     [aiStore, retryMessageViaChannel]
   );
 
+  const handleGlobalAssistantChange = useCallback((active: boolean) => {
+    setIsGlobalAssistantActive(active);
+  }, []);
+
   const handleMarkDisclaimerRead = useCallback(() => {
     // Persist to backend via workflow channel and update local state
     markAIDisclaimerRead();
@@ -642,6 +682,9 @@ export function AIAssistantPanelWrapper({
               showDisclaimer={sessionContextLoaded && !hasReadDisclaimer}
               onAcceptDisclaimer={handleMarkDisclaimerRead}
               aiLimit={limits.ai_assistant ?? null}
+              showGlobalAssistantOption={experimentalFeaturesEnabled}
+              isGlobalAssistantActive={isGlobalAssistantActive}
+              onGlobalAssistantChange={handleGlobalAssistantChange}
             >
               <MessageList
                 messages={messages}

assets/js/collaborative-editor/components/ChatInput.tsx

@@ -13,6 +13,10 @@ interface ChatInputProps {
   isDisabled?: boolean | undefined;
   /** Show job-specific controls (attach code, attach logs) */
   showJobControls?: boolean | undefined;
+  /** Show the experimental global assistant toggle */
+  showGlobalAssistantOption?: boolean | undefined;
+  /** Callback when global assistant checkbox changes */
+  onGlobalAssistantChange?: ((active: boolean) => void) | undefined;
   /** Storage key for persisting checkbox preferences */
   storageKey?: string | undefined;
   /** Enable automatic focus management for the input */
@@ -36,6 +40,7 @@ interface MessageOptions {
   attach_logs?: boolean;
   attach_io_data?: boolean;
   step_id?: string;
+  use_global_assistant?: boolean;
 }
 
 const MIN_TEXTAREA_HEIGHT = 52;
@@ -46,6 +51,8 @@ export function ChatInput({
   isLoading = false,
   isDisabled = false,
   showJobControls = false,
+  showGlobalAssistantOption = false,
+  onGlobalAssistantChange,
   storageKey,
   enableAutoFocus = false,
   focusTrigger,
@@ -96,6 +103,17 @@ export function ChatInput({
     }
   });
 
+  const [useGlobalAssistant, setUseGlobalAssistant] = useState(() => {
+    if (!storageKey) return false;
+    try {
+      return (
+        localStorage.getItem(`${storageKey}:use-global-assistant`) === 'true'
+      );
+    } catch {
+      return false;
+    }
+  });
+
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const isLoadingFromStorageRef = useRef(false);
 
@@ -143,6 +161,14 @@ export function ChatInput({
       // Ignore localStorage errors
     }
 
+    try {
+      const globalValue =
+        localStorage.getItem(`${storageKey}:use-global-assistant`) === 'true';
+      setUseGlobalAssistant(globalValue);
+    } catch {
+      // Ignore localStorage errors
+    }
+
     setTimeout(() => {
       isLoadingFromStorageRef.current = false;
     }, 0);
@@ -181,6 +207,23 @@ export function ChatInput({
     }
   }, [attachIoData, storageKey]);
 
+  useEffect(() => {
+    if (!storageKey) return;
+    if (isLoadingFromStorageRef.current) return;
+    try {
+      localStorage.setItem(
+        `${storageKey}:use-global-assistant`,
+        String(useGlobalAssistant)
+      );
+    } catch {
+      // Ignore localStorage errors
+    }
+  }, [useGlobalAssistant, storageKey]);
+
+  useEffect(() => {
+    onGlobalAssistantChange?.(useGlobalAssistant);
+  }, [useGlobalAssistant, onGlobalAssistantChange]);
+
   useEffect(() => {
     if (enableAutoFocus && textareaRef.current) {
       const timeoutId = setTimeout(() => {
@@ -216,6 +259,10 @@ export function ChatInput({
       }
     }
 
+    if (showGlobalAssistantOption && useGlobalAssistant) {
+      options.use_global_assistant = true;
+    }
+
     onSendMessage?.(input.trim(), options);
     setInput('');
   };
@@ -422,6 +469,31 @@ export function ChatInput({
                         </span>
                       </div>
                     )}
+
+                    {showGlobalAssistantOption && (
+                      <Tooltip
+                        content="Route messages to the experimental global assistant"
+                        side="top"
+                      >
+                        <label className="flex items-center gap-1.5 group cursor-pointer">
+                          <input
+                            type="checkbox"
+                            checked={useGlobalAssistant}
+                            onChange={e =>
+                              setUseGlobalAssistant(e.target.checked)
+                            }
+                            className={cn(
+                              'w-3.5 h-3.5 rounded border-amber-400 text-amber-600',
+                              'focus:ring-amber-500 focus:ring-offset-0',
+                              'cursor-pointer'
+                            )}
+                          />
+                          <span className="text-[11px] font-medium text-amber-600 group-hover:text-amber-700">
+                            Global assistant (experimental)
+                          </span>
+                        </label>
+                      </Tooltip>
+                    )}
                   </div>
 
                   <button

assets/js/collaborative-editor/hooks/useSessionContext.ts

@@ -305,6 +305,22 @@ export const useHasReadAIDisclaimer = (): boolean => {
   );
 };
 
+/**
+ * Hook to check if the user has experimental features enabled
+ */
+export const useExperimentalFeaturesEnabled = (): boolean => {
+  const sessionContextStore = useSessionContextStore();
+
+  const selectExperimentalFeaturesEnabled = sessionContextStore.withSelector(
+    state => state.experimentalFeaturesEnabled
+  );
+
+  return useSyncExternalStore(
+    sessionContextStore.subscribe,
+    selectExperimentalFeaturesEnabled
+  );
+};
+
 /**
  * Hook to get setHasReadAIDisclaimer action
  * Returns function to update AI disclaimer read status (local state only)

assets/js/collaborative-editor/lib/AIChannelRegistry.ts

@@ -915,6 +915,14 @@ export class AIChannelRegistry {
       }
     }
 
+    // Global assistant flags (applicable to both session types)
+    if ('use_global_assistant' in context && context.use_global_assistant) {
+      params['use_global_assistant'] = true;
+    }
+    if ('page' in context && context.page) {
+      params['page'] = context.page as string;
+    }
+
     return params;
   }
 }

assets/js/collaborative-editor/stores/createSessionContextStore.ts

@@ -122,6 +122,7 @@ export const createSessionContextStore = (
       versionsError: null,
       workflow_template: null,
       hasReadAIDisclaimer: false,
+      experimentalFeaturesEnabled: false,
       limits: {},
       isNewWorkflow,
       isLoading: false,
@@ -189,6 +190,8 @@ export const createSessionContextStore = (
         draft.webhookAuthMethods = sessionContext.webhook_auth_methods;
         draft.workflow_template = sessionContext.workflow_template;
         draft.hasReadAIDisclaimer = sessionContext.has_read_ai_disclaimer;
+        draft.experimentalFeaturesEnabled =
+          sessionContext.experimental_features_enabled;
         draft.limits = sessionContext.limits;
         draft.isLoading = false;
         draft.error = null;

assets/js/collaborative-editor/types/ai-assistant.ts

@@ -216,6 +216,9 @@ export interface MessageOptions {
 
   code?: string;
   errors?: string;
+
+  use_global_assistant?: boolean;
+  page?: string;
 }
 
 /**

assets/js/collaborative-editor/types/sessionContext.ts

@@ -104,6 +104,7 @@ export const SessionContextResponseSchema = z.object({
   webhook_auth_methods: z.array(WebhookAuthMethodSchema),
   workflow_template: WorkflowTemplateSchema.nullable(),
   has_read_ai_disclaimer: z.boolean(),
+  experimental_features_enabled: z.boolean().optional().default(false),
   limits: LimitsSchema.optional(),
   workflow: BaseWorkflowSchema.optional(),
 });
@@ -127,6 +128,7 @@ export interface SessionContextState {
   versionsError: string | null;
   workflow_template: WorkflowTemplate | null;
   hasReadAIDisclaimer: boolean;
+  experimentalFeaturesEnabled: boolean;
   limits: Limits;
   isNewWorkflow: boolean;
   isLoading: boolean;