spine-framework 0.3.145 → 0.4.1

package/.framework/src/pages/admin/cil/CILAgentPage.tsx

@@ -1,18 +1,13 @@
-// CIL[BEGIN chunk_id="cilagentpage_module_header_1784193942" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies and icons for the CIL agent page"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provides module imports and icon references used by the page"]
-// CIL[DOC-CONTEXT module="cortex:cil-agent" layer="presentation" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Sets up React hooks, router, apiFetch, app path hook, UI components, and lucide icons" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Chat interface for the CIL agent that answers natural-language questions about indexed code"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide a React page that lets users ask the CIL agent questions and view grounded answers with source chunk references"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="project_id from URL and user question" outputs="Rendered chat UI with messages and source links" errors="API request failures render error message in chat" side_effects="Calls /api/cil-agent?action=prepare, /api/ai-agents?action=run, /api/admin-data?entity=messages, and /api/cil-project"]
+// CIL[DOC-MICRO logic_summary="Imports dependencies, defines message types, markdown rendering, message bubble, suggestions, and the main page component." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
 import { useState, useRef, useEffect, useCallback } from 'react'
 import { useParams } from 'react-router-dom'
 import { apiFetch } from '@core/lib/api'
@@ -37,48 +32,54 @@ import {
 
 
 import { PageInstructions } from '../../../components/admin/PageInstructions'
-// CIL[END chunk_id="cilagentpage_module_header_1784193942"]
-// CIL[BEGIN chunk_id="cilagentpage_message_1784193942" type="interface" identity="Message" parent="none"]
-// CIL[DOC-MACRO purpose="Define the shape of a chat message"]
-// CIL[DOC-RESPONSIBILITY responsibility="Declares the TypeScript interface for messages exchanged in the agent chat"]
-// CIL[DOC-CONTEXT module="cortex:cil-agent" layer="presentation" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Message type contract" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Describes id, role, content, optional sources, tool_calls_made, and loading flag" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/migrations/025_retype_threads_messages.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+
+// CIL[DOC-VECTOR type="context" content="purpose='Chat interface for the CIL agent that answers natural-language questions about indexed code'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/components/ui/button.tsx,.framework/src/components/ui/textarea.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:Message:interface" type="interface" identity="Message" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Message shape for CIL agent chat exchanges"]
+// CIL[DOC-RESPONSIBILITY responsibility="Describe the fields for a chat message including role, content, optional sources and tool calls"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/lib/api.ts,.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TypeScript interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines id, role, content, sources, tool_calls_made, and loading fields." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
 interface Message {
   id: string
   role: 'user' | 'assistant' | 'system'
   content: string
-  sources?: string[]
+  message_type?: string
+  tool?: string
+  sources?: { id: string; label: string }[]
   tool_calls_made?: string[]
   loading?: boolean
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Message shape for CIL agent chat exchanges'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/components/ui/button.tsx,.framework/src/components/ui/textarea.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:Message:interface"]
 
 
 
 
-// CIL[END chunk_id="cilagentpage_message_1784193942"]
-// CIL[BEGIN chunk_id="cilagentpage_rendermarkdown_1784193942" type="function" identity="renderMarkdown" parent="none"]
-// CIL[DOC-MACRO purpose="Render assistant message text with code blocks and inline formatting"]
-// CIL[DOC-RESPONSIBILITY responsibility="Convert plain text containing markdown-style formatting into React nodes"]
-// CIL[DOC-CONTEXT module="cortex:cil-agent" layer="presentation" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="React.ReactNode[]" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Splits on triple-backtick blocks, renders pre/code, then applies inline code, bold, and newline processing" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:renderMarkdown:function" type="function" identity="renderMarkdown" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Convert assistant answer text with markdown-like code and emphasis markers into React nodes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render inline code, bold text, code blocks, and line breaks safely for assistant messages"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/lib/api.ts,.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-CONTRACT inputs="text: string" outputs="Array of React nodes" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Splits text on code fences, then parses inline markers for code and bold." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/migrations/025_retype_threads_messages.sql, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
 function renderMarkdown(text: string): React.ReactNode[] {
   const parts: React.ReactNode[] = []
   let key = 0
@@ -98,45 +99,54 @@ function renderMarkdown(text: string): React.ReactNode[] {
       )
     } else {
       
+
+
       const inline = seg.split(/(`[^`]+`|\*\*[^*]+\*\*|\n)/g).map((chunk, i) => {
         if (chunk.startsWith('`') && chunk.endsWith('`')) {
           return <code key={i} className="bg-muted px-1 py-0.5 rounded text-xs font-mono">{chunk.slice(1, -1)}</code>
         }
+
         if (chunk.startsWith('**') && chunk.endsWith('**')) {
           return <strong key={i}>{chunk.slice(2, -2)}</strong>
         }
         if (chunk === '\n') return <br key={i} />
         return chunk
       })
+
       parts.push(<span key={key++}>{inline}</span>)
     }
+
   }
   return parts
 }
 
+// CIL[DOC-VECTOR type="context" content="purpose='Convert assistant answer text with markdown-like code and emphasis markers into React nodes'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/components/ui/button.tsx,.framework/src/components/ui/textarea.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:renderMarkdown:function"]
+
 
 
-// CIL[END chunk_id="cilagentpage_rendermarkdown_1784193942"]
-// CIL[BEGIN chunk_id="cilagentpage_messagebubble_1784193942" type="function" identity="MessageBubble" parent="none"]
-// CIL[DOC-MACRO purpose="Render a single chat message bubble with metadata chips"]
-// CIL[DOC-RESPONSIBILITY responsibility="Display a user or assistant message, loading skeleton, and source or tool chips"]
-// CIL[DOC-CONTEXT module="cortex:cil-agent" layer="presentation" related_files="[\".framework/migrations/025_retype_threads_messages.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="JSX.Element" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Determines user vs assistant layout, calls renderMarkdown for assistant content, and links to source chunks" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:MessageBubble:component" type="component" identity="MessageBubble" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Display a single chat message with avatar, markdown body, and optional tool and source chips"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render user or assistant message and link source chunks to the chunk detail page"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/lib/api.ts,.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-CONTRACT inputs="message, projectId, appPath" outputs="JSX message row" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Chooses avatar icon, renders markdown for assistant, and shows tool calls and source chips." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/025_retype_threads_messages.sql, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
 function MessageBubble({ message, projectId, appPath }: {
   message: Message
   projectId: string
   appPath: (p: string) => string
 }) {
   const isUser = message.role === 'user'
+  const mt = message.message_type
 
   if (message.loading) {
     return (
@@ -153,6 +163,39 @@ function MessageBubble({ message, projectId, appPath }: {
     )
   }
 
+  // Intermediate research steps render as a compact left-aligned trail rather
+  // than full chat bubbles so the plan/tool activity is visually distinct from
+  // the agent's actual replies.
+  if (!isUser && (mt === 'plan' || mt === 'thinking' || mt === 'tool_call' || mt === 'tool_result')) {
+    return (
+      <div className="flex items-start gap-2.5 pl-8">
+        <div className="flex-1 min-w-0 text-xs">
+          {mt === 'tool_call' && (
+            <span className="inline-flex items-center gap-1.5 bg-amber-50 border border-amber-200 text-amber-700 rounded-full px-2.5 py-1">
+              <Wrench className="h-3 w-3" /> {message.tool || 'tool'} — running
+            </span>
+          )}
+          {mt === 'tool_result' && (
+            <span className="inline-flex items-center gap-1.5 bg-emerald-50 border border-emerald-200 text-emerald-700 rounded-full px-2.5 py-1">
+              <Wrench className="h-3 w-3" /> {message.tool || 'tool'} — done
+            </span>
+          )}
+          {(mt === 'plan' || mt === 'thinking') && (
+            <div className="text-muted-foreground italic border-l-2 border-indigo-200 pl-3 py-0.5">
+              <span className="text-[10px] uppercase tracking-wide text-indigo-400 not-italic font-medium mr-1.5">
+                {mt === 'plan' ? 'plan' : 'thinking'}
+              </span>
+              {renderMarkdown(message.content)}
+            </div>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  const isAwaiting = mt === 'awaiting_input'
+  const isError = mt === 'error'
+
   return (
     <div className={`flex items-start gap-2.5 ${isUser ? 'flex-row-reverse' : ''}`}>
       <div className={`h-6 w-6 rounded-full flex items-center justify-center shrink-0 mt-0.5 ${isUser ? 'bg-slate-200' : 'bg-indigo-100'}`}>
@@ -160,14 +203,22 @@ function MessageBubble({ message, projectId, appPath }: {
           ? <User className="h-3.5 w-3.5 text-slate-600" />
           : <Bot className="h-3.5 w-3.5 text-indigo-600" />
         }
+
       </div>
 
       <div className={`flex-1 min-w-0 ${isUser ? 'items-end' : 'items-start'} flex flex-col`}>
         <div className={`rounded-xl px-3.5 py-2.5 max-w-[85%] text-sm leading-relaxed ${
           isUser
             ? 'bg-slate-900 text-white rounded-tr-sm'
-            : 'bg-muted rounded-tl-sm'
+            : isError
+              ? 'bg-red-50 border border-red-200 text-red-700 rounded-tl-sm'
+              : isAwaiting
+                ? 'bg-indigo-50 border border-indigo-200 rounded-tl-sm'
+                : 'bg-muted rounded-tl-sm'
         }`}>
+          {isAwaiting && (
+            <div className="text-[10px] uppercase tracking-wide text-indigo-500 font-medium mb-1">Needs your input</div>
+          )}
           {isUser
             ? <span className="whitespace-pre-wrap">{message.content}</span>
             : <div className="prose-sm">{renderMarkdown(message.content)}</div>
@@ -184,12 +235,12 @@ function MessageBubble({ message, projectId, appPath }: {
             ))}
             {(message.sources || []).map((src, i) => (
               <a
-                key={`src-${src}-${i}`}
-                href={appPath(projectId ? `/cil/${projectId}/chunks/${src}` : `/cil/chunks/${src}`)}
+                key={`src-${src.id}-${i}`}
+                href={appPath(projectId ? `/cil/${projectId}/chunks/${src.id}` : `/cil/chunks/${src.id}`)}
                 className="inline-flex items-center gap-1 text-xs bg-indigo-50 border border-indigo-200 text-indigo-700 rounded-full px-2 py-0.5 hover:bg-indigo-100 transition-colors"
-                title={`Open chunk: ${src}`}
+                title={`Open chunk: ${src.label}`}
               >
-                <Code2 className="h-2.5 w-2.5" /> {src}
+                <Code2 className="h-2.5 w-2.5" /> {src.label}
               </a>
             ))}
           </div>
@@ -199,23 +250,25 @@ function MessageBubble({ message, projectId, appPath }: {
   )
 }
 
+// CIL[DOC-VECTOR type="context" content="purpose='Display a single chat message with avatar, markdown body, and optional tool and source chips'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/components/ui/button.tsx,.framework/src/components/ui/textarea.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:MessageBubble:component"]
 
 
-// CIL[END chunk_id="cilagentpage_messagebubble_1784193942"]
-// CIL[BEGIN chunk_id="cilagentpage_suggestions_1784193942" type="constant" identity="SUGGESTIONS" parent="none"]
-// CIL[DOC-MACRO purpose="Provide default example questions for the CIL agent chat"]
-// CIL[DOC-RESPONSIBILITY responsibility="Supplies a constant list of sample user queries for the empty state"]
-// CIL[DOC-CONTEXT module="cortex:cil-agent" layer="presentation" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="readonly string[]" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Array of natural-language questions covering auth, embeddings, refactoring, and undocumented chunks" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:SUGGESTIONS:constant" type="constant" identity="SUGGESTIONS" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Preset example prompts for the CIL agent chat"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide ready-made questions users can click to start a conversation"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/lib/api.ts,.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of prompt strings" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Static list of questions covering authentication, embeddings, refactor safety, side effects, and undocumented chunks." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
 const SUGGESTIONS = [
   'What does the authentication middleware do?',
   'Which functions write to the embeddings table?',
@@ -225,23 +278,57 @@ const SUGGESTIONS = [
   'Show me undocumented chunks in this project',
 ]
 
-
-
-// CIL[END chunk_id="cilagentpage_suggestions_1784193942"]
-// CIL[BEGIN chunk_id="cilagentpage_cilagentpage_1784193942" type="component" identity="CILAgentPage" parent="none"]
-// CIL[DOC-MACRO purpose="Render the interactive CIL agent chat page"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage chat state, send questions to the CIL agent API, and render the conversation UI"]
-// CIL[DOC-CONTEXT module="cortex:cil-agent" layer="presentation" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="JSX.Element" errors="Displays API errors as assistant messages" side_effects="Calls /api/cil-agent and /api/cil-project; updates messages and input state"]
-// CIL[DOC-MICRO logic_summary="Loads project title, maintains messages/input/sending refs, sends messages via apiFetch, scrolls to bottom, and renders messages and input area" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Preset example prompts for the CIL agent chat'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/components/ui/button.tsx,.framework/src/components/ui/textarea.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:SUGGESTIONS:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:mapRecordToMessage:function" type="function" identity="mapRecordToMessage" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Map a persisted thread message record into the chat display Message shape"]
+// CIL[DOC-RESPONSIBILITY responsibility="Translate message_type, tool, and retrieved_sources fields from a messages row into a renderable Message"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-CONTRACT inputs="rec: messages record" outputs="Message" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Derives role from message_type, sources from retrieved_sources, and surfaces tool name for tool_call/tool_result rows." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function mapRecordToMessage(rec: any): Message {
+  const mt = rec?.data?.message_type || 'agent'
+  const role: Message['role'] = mt === 'human' ? 'user' : (mt === 'system' ? 'system' : 'assistant')
+  const rawSources = Array.isArray(rec?.data?.cited_sources) && rec.data.cited_sources.length
+    ? rec.data.cited_sources
+    : (rec?.data?.retrieved_sources || [])
+  const sources = rawSources
+    .map((s: any) => ({ id: s.document_id, label: s.chunk_name || s.title || s.document_id }))
+    .filter((s: any) => s.id)
+  return {
+    id: rec.id,
+    role,
+    content: rec.content || '',
+    message_type: mt,
+    tool: rec?.data?.tool,
+    sources,
+  }
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Map a persisted thread message record into the chat display Message shape'; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="Local impact only; used by CILAgentPage.loadMessages"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:mapRecordToMessage:function"]
+
+const TERMINAL_STATUSES = ['complete', 'awaiting_input', 'failed']
+const MAX_STEPS = 20
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:CILAgentPage:component" type="component" identity="CILAgentPage" parent="~/.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-MACRO purpose="Main admin page for the CIL agent chat"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage chat state, call the CIL agent API, render messages, suggestions, and input"]
+// CIL[DOC-CONTEXT module=".framework/src/pages/admin/cil" layer="admin-ui" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/lib/api.ts,.framework/src/pages/admin/cil/CILAgentPage.tsx"]
+// CIL[DOC-CONTRACT inputs="project_id from URL and user typed question" outputs="Rendered chat UI with message history and source links" errors="API request failures render error message in chat" side_effects="Calls /api/cil-agent?action=prepare, /api/ai-agents?action=run, /api/admin-data?entity=messages, and /api/cil-project"]
+// CIL[DOC-MICRO logic_summary="Fetches project title, scrolls to new messages, sends question to API, and renders conversation with suggestions." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export default function CILAgentPage() {
   const { id: projectId } = useParams<{ id: string }>()
   const appPath = (path: string) => '/spine-framework/admin' + (path.startsWith('/') ? path : '/' + path)
@@ -249,6 +336,12 @@ export default function CILAgentPage() {
   const [input, setInput] = useState('')
   const [sending, setSending] = useState(false)
   const [projectTitle, setProjectTitle] = useState('')
+  const [threadId, setThreadId] = useState<string | null>(null)
+  const conversationIdRef = useRef<string | null>(
+    (typeof localStorage !== 'undefined' && projectId)
+      ? localStorage.getItem(`cil-agent-conversation:${projectId}`)
+      : null
+  )
   const bottomRef = useRef<HTMLDivElement>(null)
   const textareaRef = useRef<HTMLTextAreaElement>(null)
 
@@ -269,54 +362,80 @@ export default function CILAgentPage() {
     bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
   }, [messages])
 
-  const sendMessage = useCallback(async (text: string) => {
-    if (!text.trim() || sending) return
-
-    const userMsg: Message = {
-      id: crypto.randomUUID(),
-      role: 'user',
-      content: text.trim(),
-    }
-    const loadingMsg: Message = {
-      id: crypto.randomUUID(),
-      role: 'assistant',
-      content: '',
-      loading: true,
+  const loadMessages = useCallback(async (tid: string) => {
+    const res = await apiFetch(`/api/admin-data?action=list&entity=messages&thread_id=${tid}&sort_field=created_at&sort_direction=asc&limit=200`)
+    const json = await res.json()
+    const recs = Array.isArray(json?.data) ? json.data : (Array.isArray(json) ? json : [])
+    setMessages(recs.map(mapRecordToMessage))
+  }, [])
+
+  const ensureThread = useCallback(async (): Promise<string> => {
+    if (!conversationIdRef.current) {
+      conversationIdRef.current = crypto.randomUUID()
+      if (projectId && typeof localStorage !== 'undefined') {
+        localStorage.setItem(`cil-agent-conversation:${projectId}`, conversationIdRef.current)
+      }
     }
+    const prep = await apiFetch('/api/cil-agent?action=prepare', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        project_id: projectId,
+        conversation_id: conversationIdRef.current,
+      }),
+    }).then(r => r.json())
+    const tid = prep?.thread_id || prep?.data?.thread_id
+    if (!tid) throw new Error('Failed to prepare CIL agent thread')
+    setThreadId(tid)
+    return tid
+  }, [projectId])
 
-    setMessages(prev => [...prev, userMsg, loadingMsg])
+  // Restore an existing conversation thread + history only when a persisted
+  // conversation_id already exists — a brand-new session stays lazy until the
+  // first message so we don't create empty threads.
+  useEffect(() => {
+    if (!projectId || threadId || !conversationIdRef.current) return
+    let cancelled = false
+    ensureThread()
+      .then(tid => { if (!cancelled) return loadMessages(tid) })
+      .catch(() => {})
+    return () => { cancelled = true }
+  }, [projectId, threadId, ensureThread, loadMessages])
+
+  const sendMessage = useCallback(async (text: string) => {
+    const trimmed = text.trim()
+    if (!trimmed || sending) return
+
+    setMessages(prev => [
+      ...prev,
+      { id: crypto.randomUUID(), role: 'user', content: trimmed },
+      { id: crypto.randomUUID(), role: 'assistant', content: '', loading: true },
+    ])
     setInput('')
     setSending(true)
 
     try {
-      const res = await apiFetch('/api/cil-agent?action=ask', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          question: text.trim(),
-          project_id: projectId,
-        }),
-      })
-      const data = await res.json()
-      const r = data?.data || data
-      const answer = r?.answer || 'Sorry, I could not generate a response.'
-
-      setMessages(prev => [
-        ...prev.slice(0, -1), 
-        {
-          id: crypto.randomUUID(),
-          role: 'assistant',
-          content: answer,
-          sources: r?.sources || [],
-          tool_calls_made: r?.tool_calls_made || [],
-        },
-      ])
+      const tid = threadId || (await ensureThread())
+
+      let userMessage: string = trimmed
+      for (let i = 0; i < MAX_STEPS; i++) {
+        const res = await apiFetch('/api/ai-agents?action=run', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ thread_id: tid, user_message: userMessage, mode: 'step' }),
+        }).then(r => r.json())
+        userMessage = ''
+        await loadMessages(tid)
+        const status = res?.status || res?.data?.status
+        if (TERMINAL_STATUSES.includes(status)) break
+      }
     } catch (err) {
       setMessages(prev => [
-        ...prev.slice(0, -1),
+        ...prev.filter(m => !m.loading),
         {
           id: crypto.randomUUID(),
           role: 'assistant',
+          message_type: 'error',
           content: `Error: ${err instanceof Error ? err.message : String(err)}`,
         },
       ])
@@ -324,7 +443,7 @@ export default function CILAgentPage() {
       setSending(false)
       setTimeout(() => textareaRef.current?.focus(), 50)
     }
-  }, [projectId, sending])
+  }, [projectId, sending, threadId, ensureThread, loadMessages])
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
     if (e.key === 'Enter' && !e.shiftKey) {
@@ -334,6 +453,11 @@ export default function CILAgentPage() {
   }
 
   const clearConversation = () => {
+    conversationIdRef.current = null
+    if (projectId && typeof localStorage !== 'undefined') {
+      localStorage.removeItem(`cil-agent-conversation:${projectId}`)
+    }
+    setThreadId(null)
     setMessages([])
     setInput('')
     textareaRef.current?.focus()
@@ -462,4 +586,10 @@ export default function CILAgentPage() {
   )
 }
 
-// CIL[END chunk_id="cilagentpage_cilagentpage_1784193942"]
+// CIL[DOC-VECTOR type="context" content="purpose='Main admin page for the CIL agent chat'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/components/ui/button.tsx,.framework/src/components/ui/textarea.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/pages/admin/cil/CILAgentPage.tsx:CILAgentPage:component"]